X 项目 Harness Engineering 全景架构设计
版本:v15.2.0
变更历史只住harness/CHANGELOG.md(文首不逐次叠写变更摘要——多会话共改同一行必然互相覆盖)
文档性质:长期架构真相源(非计划、非宪法)。宪法.claude/CLAUDE.md是最高法 + 导航;本文档是宪法之下的全套架构详图;.claude/plan/*.md是一次性施工计划(闭环验收后整份搬进归档、不再维护,本文档承接其中的长期设计结论)。
冲突裁决:本文档与宪法冲突时,以宪法为准,且该冲突本身是架构级 bug,必须立即消解。
更新纪律:见文末「十三、版本契约与更新触发」。本文档只写结构与机制(稳定),不写时点状态(规范数量、测试通过数、迁移进度等易腐数据按需用工具派生,禁止入档)。
一、这套体系解决什么问题
一个人(架构师/所有者)+ 一个 AI(执行者)开发四端系统。风险不是"恶意入侵",而是:
- AI 乱写:不读规范上来就写,写出多样性代码;
- 无意识漂移:规范改了、规则书没同步;检测器改了、没人发现它变哑了;
- 静默腐蚀:兜底逻辑、遗留代码、"先这样以后再改"一点点堆积。
应对哲学是类低代码:每种操作只有一种正确写法(零多样性),规范文档内嵌检测器(规范即检测),hook 在写入时刻物理拦截(写错就拦),最后一道人闸是用户的两次签字(签字一管做什么,验收完结管做成的东西,验收完结照他的代签设置由他本人或 X大脑 签);机器只把验收过的那一份按项目名提交进库,历史只增不改。
统一模型:四件套 + 两个裁判(ADR-67)。上面这句落到机器上是一个模型,本文其余各节都是它的展开:
| 角色 | 回答什么 | 落在哪 |
|---|---|---|
| 设计 | 为什么这样定、哪里守不到 | 架构页、业务架构文档、本文 |
| 条款 | 必须什么、禁止什么、为什么 | 规则书(条款书) |
| 判据 | 怎么判 | 规范(内嵌检测器) |
| 执法 | 在哪一刻把裁判叫来、裁判说不过时怎么办 | guard、工作流、定版脚本、发布出口 |
| 裁判一 · 检测 | 读代码:写得合不合规 | 语言层(编译检查,引擎自带)+ 规范层(判据) |
| 裁判二 · 测试 | 跑代码:行为对不对 | 床(唯一运行器、部署门入口) |
执法不是第三个裁判,它只做一件事:在四个时刻把两个裁判一起叫来 —— 开发中(向导:VERIFY 一条命令同时叫两个,没过回去改)、收尾(反馈:每轮一次,两栏分开报,说不清就拦)、定版(墙:三层同一个封版命令,检测与测试两个都是前置;本单元的代码没有测试覆盖时如实写 none 放行)、发布(墙:当场真跑,传上去的就是测过的那一份)。
两个裁判同构:都按内容记结论(检测记「这份内容查过是干净的」,测试记「这张床对这份内容跑过、过了」);结论都随上游作废(判据或检测引擎一变,干净结论作废;被测对象、床、夹具或运行器一变,跑过记录作废);都 fail-closed(工具没跑、判定出错、说不清,一律不算过);封版与发布都要两个都过。
裁判也被裁判:检测器有判据床守着;床有空壳对照守着(新建或改过的床,把被测对象换成空壳再跑,必须变红);空壳对照与判定模块有它们自己的床 —— 递归到框架自己为止。递归不是无限的:最底下那一层(守卫、运行器、判定模块)的床由收尾逼着跑,改它们的人亲眼看见红绿。
这套模型证明不了的:两个裁判都过,只证明「对当前内容查过、跑过、咬得住」,证明不了判据写得全、测试测得全 —— 那是设计里「测试守不到之处」要如实写下的东西,也是回归逐域复审要做的事(§十六诚实边界)。
二、威胁模型与安全边界
| 要素 | 事实 |
|---|---|
| 参与者 | 唯一人类 owner(用户)+ AI 执行者。AI 执行者有两种:owner 面前说话的主控会话(X大脑),和系统用官方后台会话自动发起、无人值守的常驻会话、各专项的产品经理会话与用时起的复盘经理会话(ADR-116;owner 在 agent view 里看,不盯着)。改动不都发生在 owner 眼前,但都落在仓里、过同一套守卫、记进账本,最后一道人闸仍是 owner 的两次签字 |
| 提交权 | 验收完结那一签(亲签,或照代签设置代签)同时授权这条需求的发布与提交;提交只经受信的提交命令(环收尾之后、按项目名、打项目标签、只推主干与这个标签、只许正常推);命令行里的 git 一律只读;钥匙石与代签设置只由用户亲手提交;退回、重置永远不做(铁律) |
| 保护性质 | 100% 软保护:hook 让"改核心机器"这件事变得刻意 + 可见,不追求物理不可绕 |
| 最后人闸 | 用户的两次签字(签字一管做什么,验收完结管做成的东西,代签照他的设置)加只增不改的历史:用户随时能按项目标签回看每一条需求的 diff(不设 git 层自动闸,见 ADR-05) |
| 钥匙石 | .claude/settings.json:hook 由它挂载,它被改坏则整套 hook 静默失效——机器提交从不带它(代签设置 .claude/sign-settings.json 同样),它与库里不一样时每次提交点一次名,由用户亲手看、亲手提交(可用「!」跑设置提交脚本;改它只有用户动手 —— 手动开闸、亲手编辑,或用「!」跑项目设置改法的脚本,后者只做代码里登记的闭集、改完核写前拦截的接线还在,§十五「要 BOSS 亲手做的事」) |
| 并发会话 | 多 AI 会话可并行,各自 working-tree 改动交织:非本会话引入的 rule/spec/hook/arch 变更属他会话在途,禁互相干涉——各会话只归档/只修自己引入的改动,不代修他会话漂移;全量检测报出的非本会话单元锁步告警(版本契约、specHash 等)静默跳过。判据 = 本会话是否引入(见宪法 §六.6);L4 按写证据机器判定(ADR-50):环2 记每个会话的写证据(内容指纹 / 命令时间窗),环3 只检查、只拦本会话的改动,分不清的两边都拦并注明,无主的不拦人只出结论、由部署门挡(§八、ADR-89;部署门只在它的待检范围里挡:治理站点、官网、手机网页版往线上放新内容时只数该站原料目录,静态托管的回滚与清理旧文件不看仓库状态,其余变更类调用照全仓) |
| 无人值守的后台会话(ADR-116) | 除 X大脑 窗口之外的会话都由受信脚本(体系守护技能的会话命令,§十五「常驻会话与会话命令」)用官方后台会话发起,免确认权限档、没人逐步点头,守卫的钩子是它们唯一的闸。防线三道:① 送进会话的话只许是一处常量里的固定句(发起首句、叫醒、恢复各一句;另有项目经理建定时巡检用的巡检句,同一处常量、同一待遇)—— 用户的话恰好等于固定句时守卫不把它记进原话账本、不认作签字(句子后面多一个字就照常记),握手内容、转话、叫醒的原因一律经会话之间的消息送(那不算用户说的话);② 任何会话不经受信脚本直接跑 claude 一律拦,不分是不是办理会话;③ 会话号与名字登记在会话登记册里,登记册目录进写保护名单、只许受信脚本写,会话命令只认登记册里的主控与项目经理(身份取自会话环境里的会话号)。常驻会话不是任何需求的办理会话、不写机器镜像 |
| 对话内容送到哪(ADR-130) | 会话把对话内容交给它的型号背后的那一家:走官方的送官方;设成 gpt 的会话会把对话内容(含仓里的代码与文档)经本机代理送到 ChatGPT 账号(代理是用户在本机起的 x-proxy/claude-code-proxy.exe;这样的会话派的执行体跟着它走,内容同样送过去)。哪些角色此刻走 Codex,看型号配置查看命令(harness.js --action=model-settings)印的逐行表,「路」那一栏写着本机代理的就是;不想让哪一摊的内容出去,就把那一行说回 Claude 型号(BOSS 在 X大脑 窗口说固定话,§十五「型号与推理档」)。守卫的钩子由本机的客户端跑、与型号背后是哪一家无关,走 Codex 的会话照样在岗 |
| 代签(ADR-116) | AI 在用户设置允许的范围里替用户签验收、授权发布与联调。设置是两个开关(产品专项、Harness专项),文件缺了、读不出或写坏一律按亲签;签字一(需求确认,同时是受保护文件放行的授权)与改设置从不代。代签只走受信的代签命令:它核调用者是登记册里的主控、设置此刻允许这一类、这条计划的「验收谁签」是代签,关口(三查全绿、独立复盘过、验收区有证据)与用户亲签时同一套;代授权的发布与联调在命令里显式带需求名与「代授权」标记,部署门与各条发布出口只核带标记的这条路。验收完结的代签连带这条需求的发布与提交,和亲签一样:提交命令核的是完结那一笔记着要提交与环收尾成立,不另问用户。代签、改代签设置、改型号配置、重建登记册、换主控这五条敏感命令,守卫按钩子输入里的 agent_id 拦执行体(只有主控本人的会话跑得了)。机制见 §十五「代签设置、验收谁签与代签命令」「型号与推理档」 |
| 签字放行(ADR-116) | 放行只给办理会话、只给签过的文件。受保护文件平时照拦(守卫、检测引擎承牙等);一条需求签了字一、在办、没作废,它的办理会话写落在它签字那一刻的落点表里的受保护格才放行(范围写死为守卫脊柱与检测引擎承牙两类),别的文件、别的会话、别的需求一律照拦;验收完结、归档、签字作废当场收回。永不放行名单(各本账、需求履历、各单元的锁清单、装配标记、射程缓存、代签设置文件、型号配置文件、会话登记册目录、项目设置)里的永不放;放行评估自己出任何错一律按不放行。写文件工具、命令行、换入帮手三条路认同一份放行(写文件工具与命令行只放行写,受保护文件的删除只经换入帮手标删)。手动开闸(把写前拦截那一行改名)只留作急救。机制见 §八 环1「签字放行」 |
| 定时任务冒充用户的话(ADR-116) | 机器话要和用户的话分得开,用户的签字只认在主控窗口里说。事实(恢复演练实测):说话钩子分不出「用户敲的字」和「定时任务触发时送进来的话」—— 平台的钩子输入里没有来源字段,官方文档还明写定时任务触发也走这个钩子;项目经理建的一个探针定时任务触发后,被原样记成了用户的原话。手里有定时任务工具(CronCreate、ScheduleWakeup)的会话,把提示词写成签字说法或那几句用户亲口说的固定话,触发时就是冒充用户。堵在送进去的那头,三层:① 说话只认主控 —— 会话登记册读得出而且登记了主控之后,签字说法与用户亲口说的「重建登记册」「改代签设置」「改型号配置」(型号配置按行认,多行消息里有一行是它也算)只认在主控会话里说的,别的会话里出现这样的话不记进原话账本、不认作签字,只回一句原因(「换主控」那句不受此限);② 环1 拦定时任务 —— 提示词里含签字说法或任一句用户亲口说的固定话(含换主控,整句或子串)的一律拦,登记着的非主控会话只许建提示词整句恰好等于巡检固定句的定时任务;③ 巡检句是固定句 —— 说话钩子遇到它与发起、叫醒、恢复同一待遇(不记、不认作签字),落盘的定时任务文件 .claude/scheduled_tasks.json 进写保护与永不放行名单。没堵的:定时任务送进来的普通话,在主控与没登记的会话里仍被记成原话;定时任务文件被 node 脚本直接写,守卫看不见;说话只认主控以登记册读得出、登记了主控为前提(新窗口没登记之前,用户的签字不记)。机制见 §八 环1「定时任务通道」与「签字记录只认两条路」 |
诚实边界:AI 被 hook 拦截后,可以刻意写 node 脚本绕过——但这个动作在会话里可见。绕过写下的改动不在任何一条需求的验收内容里:机器提交不带它,它留在工作树里、每次提交点一次名;落进验收内容里的,过了独立复盘与验收。"可见的绕过"是设计接受的残余,不是漏洞。澄清(不撞死命令原则6"禁依赖人工审查"):node 写逃逸的是环1/环3 的实时拦截,其内容仍被 check.js -m file-state 在 Stop/部署 VALIDATE 自动兜住(非靠人工审查执行规范);用户事后按项目标签抽看每条需求的 diff 是最后天花板,不是例行的一道,也非唯一执行手段。业务码 ad-hoc node=理论洞(协作 AI 非攻击者、能 node 者亦能直接写 git 绕本地闸),控制面 node 写=真风险(见 §八 分治 + ADR-14)。ADR-15 预注册的那一条(威胁模型升级 —— 多人写权限、远端 agent 持写权限 —— 时用服务端分支保护)不触发:参与者没变,还是用户与本机的 AI,推送用的是用户自己的凭据,提交这个动作由一条受信命令代用户做(ADR-118)。签字与开工分开的守不到:账本追加没有跨进程加锁,签字与开工、或两次开工恰好同一时刻判同一个单元,可能两条同占;不同单元的两条可以同时开工,先完结的那一条的发布要等另一条把它的单元封了版;排队久了的计划可能因为前面的项目改动而要重签(ADR-119;细目见 §八「签字与开工分开」)。
平台这一层的四条边界(ADR-99;钩子、会话、组队都是 Claude Code 平台给的能力,它们自己的规矩就是这套体系的边界。①②,以及 ③ 里平台怎么认收信策略,照平台官方文档写,本机没有实测;守卫怎么对待来信与 ④ 是本仓核过的事实):
① 钩子超时等于放行。平台对每个钩子有时限(钩子接线文件里写前、写后各 30 秒,收尾 120 秒),到点把钩子进程掐掉;被掐掉的写前钩子不拦这一次工具调用,被掐掉的收尾钩子不逼修。守卫自己的各段预算都设在这个时限之内、到点按没过算(§八 部署门的总预算、环3「收尾自身时限」),但平台抢在守卫出结论之前掐掉的那一次就是放行,而且不留拦截记录(§八「拦截出口」列的不记的几种)。所以写前拦截要短、要快,慢到被掐等于没拦。
② 收尾钩子连拦八次后放行。平台规定收尾钩子连续让会话接着做满八次,再下一次强制结束这一轮(上限由平台的环境变量 CLAUDE_CODE_STOP_HOOK_BLOCK_CAP 调,本仓没有设)。守卫自己放得更早 —— 被拦过的下一轮红项没减少就放(§八 环3);它不数平台这个次数。两头合起来:收尾逼修不是无限的,红项一直没清,这一轮最终会结束,没清的由下一轮收尾、封版与发布接着查。
③ 会话之间的消息。收信策略(平台的 crossSessionInbound 一项:接受、扣留、拒绝三种)不写进项目设置文件:平台只认项目文件里的扣留与拒绝,「接受」要写在用户设置里、由用户本人选。没设时平台按双方的权限模式决定,可能把来信扣下等人批、过时丢弃 —— 那是主控与各专项的产品经理会话之间「传话没到、只好人转」的一个来源;用户在自己的设置里选了接受,来信才直接送到。送得到也只是传话:来信批不了任何权限、改不了配置,也不算用户说的话 —— 守卫认出整段是别的会话或队友发来的消息就丢开,不进原话记录、不认签字(§八 需求对账;守卫主文件里用户说话那一支的开头)。守卫的钩子看不见会话之间的消息本身:送没送到、被没被扣、谁发给谁,不留任何账,用户设置里选的是哪一种它也读不到;握手、派工、回报因此全靠纪律(§十五「怎么派工」)。
④ 队友与领队同一个会话号。组队时队友的工具事件带执行体编号与名字,会话号却与领队相同(§八「组队与执行体」,零件 guard/team.js 文件头记着两次探针)。所以办理会话、顶层围栏、三查、越界记账都把队友算进领队那个会话:好处是队友的改动天然归这条需求;代价是主控若把一条需求线交给自己的队友办,账就全记在主控名下 —— 这是需求线要交给一位产品经理会话、不交给队友的原因(§十五「先分级、再选路」)。
后台会话、代签与签字放行的边界(ADR-116;守不到的照实写):① 实测只证明本机 Claude Code 2.1.310(会话号、会话列表字段、后台会话续上的行为……);官方升级后行为可能变,命令里留了字段自检,字段不在了就报错、不硬做;agent view 里卡住的会话显示成什么、循环任务真满 7 天到期的那一刻、免确认档以外的权限档遇到没批准的云端工具服务会怎样、托管设置里有没有免确认开关,都没测到或看不出。② 固定句(含巡检句)只防「机器话被认成用户的话」,防不了有人手打同一句固定句;定时任务触发的话也走说话钩子,钩子分不出它是不是用户敲的字(恢复演练实测),堵法与没堵的见上表「定时任务冒充用户的话」一行;说话只认主控以登记册读得出、登记了主控为前提。③ 常驻会话不是办理会话:三查归属、核准资格按会话号与「谁写过机器镜像」记账,对跨多条需求的常驻会话会串账,所以它们只写计划目录、不写任何需求的机器镜像,落笔的受治文件由办理会话(产品经理)派执行体写。④ X大脑 派出去的执行体与它是同一个会话号,在守卫眼里同样算主控 —— 五条敏感命令按 agent_id 拦执行体,防得住执行体,防不住主控会话本身被冒用;运维经理只认发件名是 X大脑 的消息当授权或代签中转,发件名是平台给的,认得出叫 X大脑,认不出是不是主控本人。⑤ 登记册被手改、会话号被冒用(命令里改写会话号守卫已拦,其余办法拦不全)、主控登记被冒用:机器挡不全,镜像只能发现单边改动;代签命令认 X大脑 靠登记册,所以登记册的口子同样是代签的口子,也是说话只认主控的口子。⑥ X大脑 代验时判断得对不对,机器判不了,证据留在看板验收区、用户随时抽查;用编辑器手改代签设置,账本里不留原话,只靠设置文件里「最后改动」一栏与账本对不上时提示一句,编辑器手改与脚本直写在文件上分不开;用户本人授权的发布与联调机器照旧不核,亲签只是关掉代授权这条路、不是门强制用户在场。⑦ 能改守卫的人就能改放行的判定;放行把范围收窄到签过字的几个文件、那一个会话,但办理会话往这几个文件里写了什么机器挡不住,靠标准、测试床、独立复盘把关。⑧ 手动开闸(急救)是整关:设置会热加载,开闸那一刻全部在跑的会话同时失去守卫,所以急救第一步先停常驻会话与各位产品经理;放行评估出错一律按不放行、吞掉、记一笔(受保护文件照拦,别的命令含恢复命令照放),守卫别的出错形态下恢复命令跑不跑得了,以两张设计页诚实边界里写明的为准。⑨ 权限确认不能代答:后台会话一律免确认模式(要用户设置里的开关开着),守卫的钩子才是真正的闸;后台会话的环境(含代理)以后台服务起来那一刻为准,脚本直接起的会话不经用户平时用的启动包装(agent view 头上写的新会话默认型号与推理档是本机用户设置,发起时显式带型号和推理档、值取自型号配置,不受它影响);在新目录或新克隆里起后台会话,得先由人信任一次(已信任目录底下单独建的 git 仓也算新工作区)。⑩ 恢复演过的是停掉后台会话再用恢复命令拉回(会话号全没变,答得出工具名,记得停之前的对话,不带参数续上之后仍能写主仓);真重启电脑的恢复没演过,用量上限把会话打断之后的拉回也没测过。⑪ 云端 MCP 开机可能超时,后台会话没人点 /mcp:运维经理头一次开机时项目级云端工具服务连接超时(30 秒),会话里一个云端工具都没有;stdio 方式的服务启动失败,官方没有自动重试,只有手动 /mcp reconnect。兜法靠定义与命令,不是硬控(§十五「运维经理的云端工具自愈」):会话命令核云端工具读的是会话记录文件里平台自己追加的条目(deferred_tools_delta 的 failedMcpServers 与 addedNames),格式官方没承诺,读不出就说「核不出」、不乱判,claude logs 里有没有这类提示官方文档没写;发起命令带的 MCP_TIMEOUT 在后台会话里生不生效,文档没写,本机六轮重启实测都连上了、没测出来;最后兜底是用户在 agent view 里发 /mcp reconnect cloudbase(官方文档写明,本机未实测)。
三、六层全景图
┌─ L0 宪法层 ──────────────────────────────────────────────────────────┐
│ .claude/CLAUDE.md(最高法+导航·每会话加载·有边界禁区) │
│ .claude/harness-engineering.md(本文件·架构详图·按需加载) │
│ .claude/rules/x-constitution-rule.md(16 死命令+核心哲学·按路径自动加载)│
├─ L1 元治理层 ────────────────────────────────────────────────────────┤
│ /x-meta-dev:spec↔rule 生命周期(审计漂移/同步/反向覆盖/幻影ID/安全删除) │
│ specHash 内容指纹物理闸:改 spec → 指纹变 → rule 强制重派生 │
│ 系统四件套锁步:条款↔判据双向对齐 · 派生区戳记 · 变更历史封版 │
│ 封版测试前置:测试面与覆盖床对当前内容全过才封,写「测试指纹」 │
│ 编号铁律:STD/NS 各自 0001 起 gapless,删中间号必 renumber 全链路传播 │
├─ L2 工作流层 ────────────────────────────────────────────────────────┤
│ /x-feature-dev(统一开发:增/改/删·四端 fan-out·Data 永远第一) │
│ /x-meta-dev(治理环) /x-deploy-dev(发布) /x-spec-checker(检测裁判) │
│ /x-harness-dev(六层体检 · 全体测试床=测试裁判) 两环+检测与测试两裁判 │
│ 另有受信命令:接力命令 · 十态 · 会话命令 · 代签设置与代签命令 · 提交命令│
│ VERIFY〈检测+按改动跑测试床〉 · ARCH-SYNC〈回看·升版·测试前置〉 │
├─ L3 规范能力层(四件套护城河)──────────────────────────────────────────┤
│ spec(.claude/skills/x-spec-checker/references/x-*-spec.md,内嵌 detector)│
│ rule(.claude/rules/x-*-rule.md,paths-scoped 规则书,携带 specHash) │
│ 引擎(check.js + check/ 模块树):-t 自测 / -v 验证 / -m 扫描 / 全量 / │
│ --changed 增量 + coverage-gate │
│ 测试守不到之处:架构页测试床一节(待补床可见)·业务域测试指纹 none │
├─ L4 强制层 ──────────────────────────────────────────────────────────┤
│ settings.json 挂载 guard.js 单分发器(八个时刻·启动壳 fail-closed· │
│ 零件用到才装;写前写后只挂守卫按工具名处理的工具,读文件、搜索不起守卫): │
│ SubagentStop 复盘者收尾:最后一行须为固定格式结论,认出即进需求账本; │
│ 他写的「遗留」一节随这一笔记下(认不出只说一声,不拦) │
│ 同一份说明结论相同的后一笔记成重复、不计 │
│ SessionStart 开工注入:写前拦截在不在岗、正在办与排队的需求(不拦) │
│ ConfigChange 钩子接线文件改动留痕(来源·文件·闸的状态,不拦) │
│ UserPromptSubmit 用户说话:逐字进需求账本;认三句固定的话(确认/验收完结/│
│ 不过)记签字、签字一记全部受治文件指纹;「正在办」那一行│
│ 列每条在办需求的进度:谁在办、走到哪、被拦几次(不拦) │
│ 签确认那一刻另过几道:认流程、算最低档、核条数上限, │
│ 哪一道不过都签不上;签上的那一笔记下车道、档与办理 │
│ 会话,再判开不开得了工(要占的单元、改判定代码、 │
│ 阶段六的关口):开得了当场开工,开不了记成排队、 │
│ 不拒签;像签字却没记上的当场 │
│ 说原因; │
│ 办得超了这一档的用时或复盘轮数,那一行里点名(不拦) │
│ 签字记录只认两条路:用户的原话、代签命令;用户说的话恰好 │
│ 等于固定句(发起、叫醒、恢复、巡检四句)的,不记、不认签字│
│ 登记了主控后,签字说法与三句固定话(改代签设置、 │
│ 改型号配置、重建登记册)只认主控会话里说的,别的会话 │
│ 里的不记不认、回原因 │
│ 环1 PreToolUse 写前硬闸(exit 2)——【防手滑,结构上不完备】 │
│ +需求对账:没有在办的需求不让写受治文件; │
│ 有在办需求时只放办理会话的写与命令 │
│ +顶层围栏:顶层四类版本单元的文件,不是办它的会话不让写 │
│ +签字放行:脊柱与引擎承牙两类受保护文件,对签过字的办理 │
│ 会话放行它签过的格(四样同时成立,永不放行名单不放); │
│ 手动开闸只在急救时用 │
│ +会话命令与敏感命令:不经受信脚本直接跑 claude 拦;代签、 │
│ 改代签设置、改型号配置、重建登记册、换主控五条拦执行体 │
│ +「!」脚本:项目设置改法、设置提交经命令行跑一律拦 │
│ +命令行里的 git 一律只读:提交与推送只经提交命令 │
│ +定时任务:CronCreate、ScheduleWakeup 的提示词含签字说法 │
│ 或固定话的拦;登记着的非主控会话只许建巡检固定句 │
│ +选项题:带着答案的、题目正文写了仓内相对路径的不让弹; │
│ 认成签字题的,弹出之前要过谁弹的、签哪几道(确认题可 │
│ 一题签几条)、认计划、题目正文带看板完整路径与「签字」│
│ 页签、签字区是最新的那一道,缺一样弹不出来 │
│ +派执行体:类型不在执行体名册里的派不出去,平台内置的通 │
│ 用类型也拦;复盘任务另过复盘派出那一道 │
│ +部署门:云端写入前当场跑床,上传须是测过的那份 │
│ 先判联调还是正式发布:联调只放本需求的单元施工中, │
│ 正式发布核验收完结(被在办需求的落点表盖住就拦) │
│ 代授权的发布与联调,只核带「代授权」标记的这一条路 │
│ +拦截留痕:每拦一次往会话台账记一笔(拦在哪、为什么) │
│ 环2 PostToolUse 写后记写证据(内容指纹;Bash 按时间窗) │
│ +云端写入与命令行发布的事后复判(收尾报红一次) │
│ +联调放行的云端写入成功后往会话台账记一笔(收尾写履历)│
│ +需求对账:写完一句「在哪条需求的哪一格 / 不在范围里」 │
│ PostToolUseFailure 失败的 Bash:照写后那一支记命令时间窗(只认 Bash) │
│ 环2.5 事后测量 git status 差集补测(Stop + 部署门两处消费)【完备记账】│
│ 环3 Stop 两个裁判同轮叫来:检测(写法)与测试(结果)分栏报 │
│ 说不清就拦(fail-closed);总时限到点没跑的按没过记 │
│ 被拦过的下一轮红项降了没清零继续拦,没降才放 │
│ +需求对账:对签字基线算改动面,范围只认本会话办理的需求;│
│ 范围外的拦一次,写进别的会话在办范围的同样拦一次 │
│ +写域点名:执行体写到它写域之外的文件,点名一次(不拦) │
│ +联调:这一轮记下的逐笔写进履历「联调」一格并点名一次 │
│ verify-harness.js 永久回归套件 + permissions.deny(只在开闸时多一层) │
├─ L5 代码层 ──────────────────────────────────────────────────────────┤
│ ★x-core(框架内核母本·非端·各端共享系统层的唯一一份)★ │
│ server/sys(服务端内核与运行时锚) + tools/{manifest,closure} │
│ mobile/backends/web(H5 backend·glass-easel 自建) + tools/mobile(装配器)│
│ mobile/core(@wowoway/core) + mobile/kits/{geo-lazy} + mobile/biz/{goods,goods-lazy}│
│ (业务域包 @wowoway/goods 主包 / @wowoway/goods-lazy 分包·只 x-client 消费)│
│ x-server(云函数·骨架复制 + 内核装配·sys/ 只读) │
│ x-admin(antd6+Pro3+Umi4) x-client / x-technician(小程序·消费母本包的端实例)│
│ x-data(MySQL 表 .md+.datasource.json 文档先行) │
│ x-website(官网站点·纯静态无构建·非端·挂主域名) │
│ x-harness(治理阅读站点·有构建·非端·产物 dist 不进仓) │
│ x-test(业务端与内核母本测试·按被测对象分桶·部署门入口·非端) │
│ 出包门:x-core/tools 出包前先跑部署门登记的床,没过不出包 │
│ 业务码内 X-RULE 标记 = 检测锚点(删改被环1 当场拦) │
└──────────────────────────────────────────────────────────────────────┘
控制哲学:工作流=向导(教你写对) · L4=传感器(写错就拦)
绕过工作流 ≠ 绕过检测与测试(两个裁判锚在文件、写入与发布动作上,不锚在流程上)
四、L0 宪法层
载体:.claude/CLAUDE.md。只定义:四端、第一最高律(一切开发穿工作流)、治理拓扑(part1/part2)与测试闭环的存在性声明(检测与测试两个共用裁判只在宪法 §二 定义一次)、六层模型、护城河定性、工作流目录、运作方式(宪法 §四 那一段:X大脑、常驻会话、各专项的产品经理会话与复盘经理怎么分工,只写定性,机制在本文 §十五)、工作流闭环、强制规则(含测试闭环铁律、禁止复杂化的取舍原则 —— 都只写定性,机制在本文 §十五)、宪法边界、相关文档导航。测试闭环在宪法里只写定性、执行点分层与义务;测试面划分、收床与记账、测试指纹算法、收尾执法强度及其切换状态都属下层,住本文 §十六(宪法 §七 禁区已点名)。
边界禁区(§七):L0 允许定性+存在性声明,禁止写任何下层机制细节(detector 算法、检测模式、死命令全文、具体 spec/rule 名等)。这就是本文档必须独立于 CLAUDE.md 存在的宪法级理由。
下沉文档(宪法体积控制的产物):
x-constitution-rule.md:16 死命令 + 系统四件套文档架构 + BFF/原子化/组件化哲学(按 frontmatter paths 自动加载,不是全域加载;是所有 spec/rule 的最高原则来源);x-standard-rule.md:元规范规则书("规范的规范",约束所有 spec 文件自身的结构);x-thirdparty-skill-rule.md:第三方 skill 登记 + 供应链安全基线。
L0 自身也被治理:x-governance spec 治理 CLAUDE.md(禁计数、禁状态快照——宪法必须去状态化,时点状态按需派生)。
宪法只留定性,机制各在哪(ADR-99;宪法只写定性加指向,机制的落点列在这里):
| 宪法里只留的定性 | 机制在本文哪里 |
|---|---|
| §六.8 需求闭环:先有计划与用户确认再动受治文件;需求确认(签字一)由用户签、从不代签,验收完结与线上写入的点头按用户的代签设置由用户本人或主控来;三查与一次独立复盘;完结之后清理归档;发布排在完结之后 | §八「需求对账」。计划看板的页签:需求、设计、步骤、用例、固化与验收、决策与遗留六个内容页签,加一个「签字」页签(模板住 x-feature-dev/assets/plan/)。签字区怎么勾、怎么贴回:「签字搬进看板签字区」。内容编号:同段开头(由机器记、不给用户看;签字只锁五样,锁住的五样一改签字作废,其余过程由主控核准,见同段「签字只锁五样、过程由主控核准」)。写前、写后、收尾三个时刻各对照什么:同段「四个时刻」与「守不到之处」开头那一句。封版之前先查的两项(办理会话零越界、自动用例闭环):「三查接关口」。两次签字各认什么:只有签字一可以打字说固定那句,签字二必须贴回带单子编号的结论(同段开头「签字只有两种形态」);签字记录只认两条路 —— 用户的原话、代签命令(§十五「签字机制」)。流水线整体怎么走在项目架构设计页 |
| §四 「不为每端单设入口」:开发流怎么用现成的数据表技能与删模块技能 | §六「结构约束」里「委托关系」 |
| §二 测试跟着被测对象安放、按内容记结论 | §十六(测试根、唯一运行器、按张记账、测试指纹) |
| §六.6 别的会话在途改动不代修:检测报出的非本会话单元的锁步告警怎么处置 | §二 表「并发会话」一行(静默跳过;L4 按写证据机器判归属,§八 环3) |
| §四 按落点分五条流程(每条三档、一共十五条车道;落点不归任何版本单元的按目录认)、会话身份怎么定(主控由 X大脑 执行体定义启动;常驻会话、各专项的产品经理会话与复盘经理会话由项目经理经会话命令自动发起、登记在会话登记册里) | §十五「先分级、再选路」车道表;§十七「五类需求入口表」「术语表」;§十五 角色表(主控一行写着启动方式)与「常驻会话与会话命令」「会话登记册与恢复」;签「确认」那一刻机器认流程见 §八「认车道」,不归任何版本单元的目录归哪条流程见 §十五「称呼对应与顶层的范围」 |
| §二、§三 五类架构是自上而下的五层、各答一个问题,agent 架构是其中一层(答「谁来做」),执行工件是它的内容(ADR-101;五层的说法 ADR-105) | §十三 单元表「agent 架构」一行(锁什么、怎么封);§十四(目录与写权);§十五(定位、治理规范、生命周期);设计本身在 agent 架构设计页 .claude/arch/agent/ARCH.html |
| §六.9 禁止复杂化:取舍只问最佳最合适,规模与成本不作为取舍的理由;只禁止复杂化 | §十五「取舍原则与复杂化审查官」(谁来判、三个时点、四种判断);两位架构师做设计的第一条要求是同一句,写在他们的执行体定义最前面 |
| §四 运作方式:常驻会话、每个专项一位产品经理会话端到端负责、会话由项目经理自动发起、每个专项验收完结之后由复盘经理复盘这一程、设计由两位架构师出、不动受治文件的小事由 X大脑 直接派执行体 | §十五 角色表、「常驻会话与会话命令」「会话登记册与恢复」「怎么派工」,以及「先分级、再选路」的车道表;复盘经理复盘什么、发现怎么定去向:§十五「遇到顶层问题的两种走法」、§八「过程复盘的耗时表与红旗」「后台收尾」 |
| §四、§六.8 验收完结与线上写入的点头按代签设置由用户本人或主控来;签字一不代、改设置不经立项 | §十五「签字机制」「代签设置、验收谁签与代签命令」「谁来发布、怎么授权」;§八「部署门认联调」⑮ |
异常 · harness-P-07 下沉文档里有一条收尾义务没有执行点(待复盘 · 只登记不修):x-constitution-rule.md 原则14 配套写着「删除后必须跑全 spec -m 静态检测」,而收尾环只对本会话改动跑增量检测,全量检测恒返回 0、只能读输出文本 —— 这条义务既不在任何工作流步骤里强制,也没有机器闸。会出什么事:删掉文件后结构强制类、废弃键类的违规要等下一次有人主动跑全量才现形。动不动钱:不动。依据:.claude/rules/x-constitution-rule.md(原则14 配套末段「收尾强制」);.claude/hooks/guard/stop-handler.js(收尾只跑 --changed)。状态:要修(把「删除之后跑全量」接进删除流程 x-module-del 的收尾一步,或在原则里写明它靠纪律)。由什么测试守着:不适用(义务的执行点问题)。
五、L1 元治理层
管"规范/规则/系统四件套/工作流自身"的生命周期,入口 /x-meta-dev。
核心机制——specHash 内容指纹物理闸:
改 x-{d}-spec.md ──→ spec 内容指纹(归一化 djb2)变化
↓
x-{d}-rule.md 头部 specHash 立即失配
↓
check.js -v x-{d} 爆 NS-COMMON-0027(spec↔rule 三件套失同步)
↓
L4 环3(Stop)对本轮触碰过的 spec/rule 自动跑 -v ──→ 失同步则逼修
指纹按内容而非版本号——版本号可以撒谎,内容指纹不能。元规范自身同受此治(框架递归治理自己)。
其余职责:反向覆盖检测(rule 声称的规则在 spec 里必须真实存在,防幻影 ID)、编号 gapless 检查、规范安全删除(退役必须全链路清理,不留死引用)。
系统四件套锁步:每个系统规范域 = 设计(arch/system/<规范>/ARCH.html 架构页 + CHANGELOG.md)+ 条款(规则书,frontmatter 声明 ruleFormat: "clauses-v1" 的条款书)+ 判据(规范,内嵌 detector,同前缀注册表计入指纹)+ 执法(guard)。原件(判据、条款、架构页原件区、变更历史条目)由 x-meta-governor 经 /x-meta-dev 撰写;派生件(条款书的标准写法与速查、架构页派生区、规则书 specHash 与 paths)只准脚本产出;变更历史的记录行与锁清单只准统一封版命令写(§十三)。锁步四道:① 对齐——规范指纹闸加条款格式分支(x-standard NS-COMMON-0027):每颗闸被条款认领、守护引用的「规范名:规则号」存在、无闸条款写理由、规则书派生区逐字等于从判据与注册表重新生成,改规范或规则书当轮报红;② 派生区戳记——架构页每个派生区带 data-v(引擎输出版本)/ data-out(产出指纹)/ data-src(来源指纹),直接改或来源变了即红(x-arch NS-COMMON-0008),写入端 validate 第 10 项逐字重新生成兜住「引擎改了输出没升号」;③ 版本锁步——版本契约(§十三):版本号只写在规范简介一处,变更历史第一节必须等于它并由统一封版命令封版;判据、条款、架构页原件封版后改过而没升版,改动当轮在那个文件上报红,整单元由 x-arch NS-COMMON-0009 在全量检测报出(改了变更历史或版本号,增量检测当轮整单元核);sync 只刷新派生区、从不封版;④ 成套——规范与 arch/system/ 目录一一对应(x-arch NS-COMMON-0007)。解析与规则书派生区生成只有一份引擎原子(parsers/tetrad-doc,检测端经 tools.tetradParser、写入端直接 require);架构页派生区引擎住 x-meta-dev(领域无关、显式输出版本号、同输入同字节)。
封版的测试前置(ADR-62;三层同一个封版命令):版本锁步管的是「设计、判据、条款、代码对齐」,管不到「证明这一版有效的测试跑过没有」。封版钉死一版之前先核测试 —— 系统规范域:规范面(连同覆盖它某颗闸的面外床)对当前内容全过、逐闸有床、架构页零待补床;业务域:本域代码所在的测试面(没有覆盖如实写 none);整个 HARNESS:守卫、检测引擎、技能三类测试面。钉死时在那一版写「测试指纹」。测试不单独发版本号,跟着单元定版。机制见 §十三「版本契约」与 §十六「封版的测试前置」。
封版的检测前置(ADR-67):定版处两个裁判都在 —— 封版前置把测试前置与检测前置合成一个结论(tetrad.combineSealGates):检测一侧是规范自测(-t:标准写法的示例符合自己的插槽模板)与结构验证(-v:判据文档符合元规范),两边都过才准封,原因两边都列;检测判不了(引擎缺席、没跑成)按不过算。「本版还没封版」不在 -v 的射程里(它是 x-arch 对注册表的判定),所以不会与封版互相等待(x-deploy 就在待同步状态下经这道前置封过版)。
元规范的条款书:元规范 x-standard 的规则书同样按条款书格式写(每颗闸各有条款认领),但它是框架三件套的一员——设计留在本文档(§五、§七),不建 arch/system/x-standard/(x-arch 成套闸臂B 把该目录的存在本身判红);版本随整个 HARNESS 升版与封版(它的判据是框架的内容、条款书是框架的设计),没有自己的系统架构变更历史。工具为此各留一个元规范分支:引擎解析器 clauseBookHead 给它的「设计」行指向本文档;x-meta-dev tetrad.refresh 对它免变更历史与架构页、只刷新条款书派生区;checkRegeneration(validate 第 10 项)对它只比对条款书。其余规范照常(四件套床、x-meta-dev 自测与框架独立性床验证)。references 下除元规范外每份规范都是四件套,成套闸处于严格态,新建规范只能经 /x-meta-dev tetrad 一次建整套。
四件套的长期约定:① 条款书的「标准写法」派生区是行号索引不是模板拷贝——模板本体只住判据(它本来就是真相源),条款书那一节只列「规则 · 段 · 判据行」一张表,写码时按行读判据、整块拷贝(条款书因此少背约 140 KB 自动加载体量;病历:逐字拷贝曾占自动加载量 11%)。② 迁移去向判据——改写条款书或搬迁内容时,写码当下要用的操作性内容(键名、取值、步骤、映射表、模板片段、位置表、命令、豁免名单)留条款,只有设计理由去架构页;来历只进变更历史与决策记录;「为什么」每条不超过三句、只留防的后果与判据边界(病历:一次迁移把 7 处写码必需内容搬进了不自动加载的架构页,抽查 221 条条款有 44 条与检测器口径不符)。③ 床点名验真两臂(x-arch NS-COMMON-0010;引擎令牌四种)——床的种类写实:不标 data-bed-kind 的床文件里必须真调用引擎(extractNsRuleDetector / check.js / buildDetectorTools / X-RULE-BEGIN-SLOT 任一,后两种对应手抠 SLOT 块喂引擎 tools 的写法),只守不变量、不跑判据的床在点名上写 data-bed-kind="invariant";data-guards 兼收「规范名:ARCH-条款号」,由床承接的无机器闸条款(资损域双分支逐字等值、两端注册行同值)有处登记(病历:只有一行头注也算「床点名属实」时,登记床比字面承诺弱一档)。④ 引擎原语的几处约定——架构页普查通配符认花括号且不配对即抛错(不静默 0 文件);detector 经 tools.ignoredDirs 取引擎忽略目录名册,判据里禁手抄跳过表(病历:x-marker 手抄表漏 .cache 致 772 处重复);两处解析器的 STANDARD 标签正则是「-X 后不许再跟字母数字或汉字」,规则名以大写 X 开头的模板段不被截断丢块;parseImports 认第七种变体(默认 + 具名混写 import A, { B } from;病历:漏认这一种时 50 处对五份判据结构性隐身);元规范 NS-COMMON-0021 的忽略目录名册同样取 tools.ignoredDirs(手抄本会漏 worktrees)。⑤ 子 agent 批量产出必须独立复核——病历:7 个只读复核 agent 抓出 44 条条款偏差、2 条误登、7 处搬丢内容,复核成本约为产出的三分之一,值;守卫开闸期间提示词纪律对子 agent 与总统筹都不可靠(多次管道过滤检测输出),物理闸关上前只能靠复核兜底。⑥ 存量清零的三分法——判据收紧后曝出的存量,处置只有三条路且必须逐处核验后再选:真违规改代码(改逻辑不改形态)、真渲染面显示兜底打条款认可的标记并自证、判据误判则改判据(升版 + 条款回看 + 反向样本床)。禁止第四条路:为了让闸变绿而换写法(拆中间变量、包一层函数、改成等价的别种形态),条款 x-fallback ARCH-D03 已把它写成明禁;判据误判的豁免必须按正向证据识别(如绑定关系树要同时满足「自定义弹窗形态」与「权限指向 -bind」),不能按「长得像」放行,否则真违规会跟着一起逃。
六、L2 工作流层
| 工作流 | 角色 | 轴 |
|---|---|---|
/x-feature-dev | 统一开发生命周期:PLAN→IMPLEMENT(四端内部阶段,Data 永远第一)→VERIFY〈检测 + 按改动跑测试床〉→ARCH-SYNC〈回看设计 · 升版 · 测试前置〉→独立复盘→验收完结→DEPLOY〈交运维经理〉;增/改/删是动词不是流程 | A 功能开发 |
/x-meta-dev | 规范/规则生命周期治理 | B 元治理 |
/x-deploy-dev | 发布(云函数 / 静态站点无空窗发布 / 回滚;预检→发布→核对) | 支撑 |
/x-spec-checker | 检测引擎入口(两环共用的检测裁判:判写得合不合规) | 横切 |
/x-harness-dev | 六层体检 BFF(聚合各层自检,不路由调度)+ 全体测试床的唯一运行器(两环共用的测试裁判:判行为对不对;每张床按对哪份内容跑过记账)+ 一条需求的接力命令、环的十态查询与办理会话改派(ADR-98:只把现成的程序按次序叫起来、读现成的账,自己不判、不新增闸;§八「接力命令」「环的十态」「办理会话改派」)+ 会话命令(九个子动作)、代签设置命令与代签命令(ADR-116:受信命令,身份取自会话环境,§十五「常驻会话与会话命令」「代签设置、验收谁签与代签命令」)+ 型号配置命令与两条要 BOSS 亲手做的事的「!」脚本(ADR-127:型号配置的 show 谁都能看、set 只有主控跑且核用户的新鲜原话;项目设置改法与设置提交只有 BOSS 用「!」跑得了,守卫拦模型经命令行跑;§十五「型号与推理档」「要 BOSS 亲手做的事」)+ 提交命令(ADR-118:环收尾之后把这条需求验收过的那一份提交进库、打项目标签、推主干与这个标签;受信命令,写 git 的唯一一条路,§八「提交命令」)+ 过程复盘的耗时表命令(ADR-120:对一条专项出耗时表与红旗,只读;§八「过程复盘的耗时表与红旗」) | 横切 |
五类需求各从哪进(ADR-99、ADR-101、ADR-105):上表是工作流;一条需求改的是哪一类东西(agent 架构、项目架构、框架、系统规范、业务),各落在哪个版本单元、从哪个入口进、谁写计划、谁动手、用哪条封版命令、往哪发,合成一张表 —— §十七「五类需求入口表」。前三类走 Harness 流程,系统规范走规范流程,业务走业务流程(宪法 §四;每条流程三档,车道表在 §十五「先分级、再选路」;三条主流程签「确认」那一刻守卫按落点认流程、算最低档,§八「认车道」);三条主流程走的是同一套闭环(计划、签字一、封版、独立复盘、三查、验收完结(签字二)、发布、清理归档,项目架构设计页),运维与分析两条辅助流程不立需求;改框架、改项目架构与改 agent 架构没有专属工作流,走 Harness 流程,封版用元治理的封版命令。发布排在验收完结之后:编排器的阶段仍是五段(见下「ARCH-SYNC 与发布出口的测试执行点」),ARCH-SYNC 封版之后先过独立复盘与验收完结(用户签,或照代签设置由主控代签),再交运维经理发布 —— 开发流自己不往线上放东西。开发期联调上线(建数据表、在控制台发布数据模型、联调时部署云函数)不是正式发布:它是运维经理在授权下(用户的单次授权,或照代签设置由 X大脑 代授权)做的一个动作。机器认得它(ADR-100):运维经理先跑联调开始带需求名(脚本通道在发布命令上带需求名与联调两个开关),放行面是那条需求签过字的落点表 —— 要上线的函数与表落在表里才按联调判,发布前版本比对只放过这条需求落点表里的单元施工中;没开联调、过了时限、需求不在办或落在范围外的,一律按正式发布判,正式发布由机器核验收完结(判法见 §八 环1「联调还是正式发布」与环3 需求对账里「部署门认联调」)。联调上线成功之后机器自动记进这条需求履历发布段的「联调」一格(经云端工具的当场只往会话台账记一笔、这一轮收尾时写进履历,经脚本通道的当场记;§八「收尾单与治理站点一格」里「联调是单独一种格」);这条需求该发的格在验收完结之后照旧要正式发一次才翻「已发布」—— 联调那一格只留痕,不顶替任何一格的正式发布。守不到:机器只认有没有有效的联调口径,授权与是哪个会话在发,除带「代授权」标记的那一条路(§八「部署门认联调」⑮)之外仍没有机器核(§十五「谁来发布、怎么授权」);控制台里用户亲手做的导入与发布机器看不见、不自动记。
四端编排:orchestrator.js VERBS.order 三个动词都含 client(缺了宪法第一最高律在 client 端物理不可满足——小程序开发只能绕流程直做):add = Data→Admin→Server→Client;modify = Data→Server→Admin→Client;delete = Client→Admin→Server→Data(逆序 prune,消费端先拆)。roadmap.js END_RULES.client 的口径 =「spec 含 STD/NS-MOBILE 规则」∪「rule 自声明 -m xxx x-client 验证」,排除元规范 x-standard。x-dev-rule.md 有 Client 端工作流章节(场景A/B + 步骤×规则映射表 + NS-DEV-0032~0038 禁令),编排器与规则书双真相源同步(order 以 orchestrator 为准,rule 文档载语义)。worker 层(shell scaffold --end=client)、END_DIR、dirsOf 都按端类多实例展开。
结构约束(官方实证):Skill 不能干净调 Skill,Workflow(JS)只能编排 subagent——所以四端知识是 /x-feature-dev 的内部阶段(bridge 委托既有 worker,零复制),不为每端单设入口。委托关系(宪法 §四 只留「不为每端单设入口」这句定性,做法写在这里):数据表与删模块两件事早有现成的技能 x-data-dev、x-module-del,开发流不抄它们的代码 —— x-feature-dev/scripts/data/bridge.js 与 x-feature-dev/scripts/delete/bridge.js 只认路、把命令转发给它们留在原位的脚本(零复制,不删不抄;只代理纯命令行脚本,云端调用与用户手工的步骤不经它)。(与 §十五 的关系:四端有两条正交编排路径并存 —— ① x-feature-dev 内部 skill 阶段/bridge〔手册化流程〕;② 领队(主控或产品经理在各自会话里的主线,§十五)直接派四端工程师执行体〔隔离化执行者,§十五〕。二者不冲突,按需选用;subagent 可调 skill,是工作流触达 skill 的干净适配器。) 闭环形态见宪法§五(治理环改规则与流程本身 —— 规范流程、Harness 流程;开发环是业务流程;检测与测试两个共用裁判;开发中发现规则或流程错/缺反向触发治理环)。
VERIFY 接上测试(ADR-63):VERIFY 的本次改动面一条命令跑两样 —— x-feature-dev/scripts/verify-feature.js --changed <改动文件…>:增量检测(check.js --changed … -d --wip,施工中只提示)+ 按改动跑测试床(唯一运行器 --changed --stale:只补跑对当前内容不新鲜的床,已经通过的沿用,与接力命令里跑床那一步同一个口径,机制见 §十六「只跑不新鲜的」;起床时不写死路数,吃命令行入口的缺省(按整机预算起池同时跑),机制见 §十六「跑床分道并发」;改动命中的测试面每张床对当前内容通过),两步都跑完再合并结论。它先用测试面判定模块算命中哪些面:命中了才交运行器(运行器按改动选床时一张都没选中按失败处理,防路径写错当通过);一个面都没命中是正常情况(改到的代码没有测试覆盖),如实告知、不判失败。编排器每端的「测试」一行与 x-dev-rule 各端增量那一步(「测试另走一条」)同口径;全量检测兜底不变。两个裁判的定义只在宪法 §二,x-dev-rule 的「检测只有两条命令」铁律照旧 —— 测试不是第三条检测命令。登记豁免的跳过(本机缺外部环境)不让运行器报红,但 VERIFY 把它单独列出、不说「全过」。
ARCH-SYNC 与发布出口的测试执行点(L2):宪法 §三 把「业务升版与发布出口」的测试执行点放在 L2。① ARCH-SYNC:编排器的阶段序列是五段(PLAN、IMPLEMENT、VERIFY、ARCH-SYNC、DEPLOY,「未 SYNC 禁入 DEPLOY」因此在计划里有处落地;阶段提示写明 ARCH-SYNC 与 DEPLOY 之间还隔着独立复盘与验收完结,DEPLOY 是交运维经理发布,见上「五类需求各从哪进」);业务域的封版入口 x-feature-dev/scripts/arch/seal.js --unit=domain:<域> --execute(转调统一封版命令)核检测零红、本域测试面对当前内容全过(没有测试覆盖如实写 none)、有标题有说明、日期是今天,过了按会话归属写三行指纹、改动清单与锁清单,机制见 §十三。② 发布出口:/x-deploy-dev 的脚本出口 gateFunctions 当场真跑部署门入口,并核对暂存目录与测过的目录指纹一致、内核母本与测过的一致;四个静态出口(后台、网页版、官网、治理站点)同样当场真跑。五个发布入口在这之前先只读查一遍部署门的待检清单(ADR-98),有没复核的改动就停在第一步,不走到跑床与上传(§九「发布之前先只读查部署门」)。跑哪些床由被发布物推导:发布的输入文件 → 它们所属的测试面 → 这些面的全部床,部署门注册表登记的床是「额外必跑」;不按网站种类写死、不只跑 @suite mobile 套件。结论写进发布档案 checks(推导出的每张床与结果、测试面、输入源码指纹),上传档案闸要每张床都是 PASS。没有跳过口(--skip-validate / --skip-beds 给了就拒)。发布不认 VERIFY 留下的记录。
异常 · harness-P-06 技能开发规范(已处置 · ADR-99):.claude/rules/x-dev-skill-workflow.md 是一页指针 —— 不点名不存在的标杆技能、不写没人查的要求,带按路径加载的文档头,不每次会话全局加载;写技能照现行几个自研技能的形态。五个自研技能的自测各有一条「说明对得上脚本」(技能说明里每条本技能的命令,脚本文件在、动作名在脚本的路由表里)。仍然守不到:它的文件名不是「x-…-rule.md」形态,检测引擎的规则书分类(check/constants/rule-books.js)不把它当规则书,没有任何判据查这一页指针的内容(它是整个 HARNESS 锁住的设计文件,改了收尾逼整个 HARNESS 升版,写得对不对仍归人审);「说明对得上脚本」守的是五份技能说明,不守这一页;体系守护技能的自测在床头点名了这一页(各处改口对表要读它),哪天把这份规则书删掉,要同批把床头那一行里的它去掉 —— 点名了不存在的路径,那张床算不出指纹。动不动钱:不动。
七、L3 规范能力层(四件套解剖:判据与条款)
x-{domain}-spec.md ──┬── STD 规则:唯一标准格式(STANDARD 模板·真实值)
(真相源+检测器一体) │ + 插槽检测格式(SLOT 模板·{{{中文插槽}}})
│ 双模板结构一致,引擎自动提取 SLOT 逐行比对
├── NS 规则:纯脚本 detector(内嵌 JS),堵 STD 装不下的负空间
│ 域感知视图:codeKeepMultiline(默认)/ commentStripped /
│ codeOnly·multilineStripped(抹块,须写理由)(禁裸 content 匹配)
└── X-RULE 标记体系:BEGIN/END 配对·SINGLE 单行·
MULTILINE(仅限业务逻辑/错误处理,须 category 声明)·
linelist(可变长同构列表,itempattern 逐行有牙)
│ specHash 派生
▼
x-{domain}-rule.md ── 开发者/AI 读的规则书,frontmatter paths 声明作用域
(paths-scoped) (写代码前自动加载 = "先读规则再写"的物理实现)
规则书写不写适用范围机器不拦(新建规则书漏写,就会被每个会话和执行体常驻装载,靠复盘发现)
**★视觉原语治理归属定案:留在 x-styles(治理版图第二半张图),数据独立成伴生注册表★**
Style 治理版图有两半:「档位体系」(11 轴 token 化,治值该取多少 —— 16 分块中行高 / 定位 / 尺寸 / 变换四类目**不建档、只守跨端镜像折半**(用户裁定),由 `NS-COMMON-0034` 第三臂「数字序列比较」承接,例外逐处登记 `numericExempt`;字族走零档位纯禁令 `NS-COMMON-0036`)与「组件原语治理」(结构性属性没有档位概念,
整块视觉写法封装成原语,业务方只能用不能拼)。后者的三颗闸(禁副本 / 逼用 / 消费契约)靠原语注册表驱动,原语注册表不放进轴注册表 `x-styles-axes.json`、另成伴生文件(见下「处置」)。
原语治理**留在 x-styles、不迁到 x-tools 域、不建新 spec**,四条依据:
① 逼用闸用轴 def 文件把 `var()` 解析成真值再判几何 —— 它是档位表的**消费者**;搬出 x-styles 会造成「改档位表不触发原语规范同步」的半把锁,
而 §十铁律禁止引擎依赖业务注册表,故它只能留在这里;② INV-06 纯净闸 / 规则引用闸 / schema↔闸双向闸对原语闸的看守随迁移丢失,
只能克隆 —— 克隆正是本体系立法反对的逐字复制体;③ 迁移要 gapless 重编 25 个规则号,床按 ID 静默换靶、镜像面业务注释集体失真,
效力增量为零;④ 治理版图自身把原语定为 Style 的第二半张图,「原语不是 style 的治理对象」只对一半原语成立(组件型本就在 xComponents,配方型就是 wxss)。
**处置**:原语数据独立成伴生文件 `x-styles-primitives.json`(同目录同前缀 ⇒ 自动入 x-styles specHash 与 Stop 环扇出,
改原语行只动本文件;detector 内变量名 `preg` 与轴注册表 `reg` 分名,`NS-COMMON-0019` 根键双向比对只针对轴表);
`NS-COMMON-0007` ⑧ 留墓碑(编号不复用防引用漂移)。**补的是牙不是户口**:`NS-COMMON-0039` 注册表自洽(声明或弃权 —— 什么都不填从合法变违规 /
canonical 逐根实存 / requireAttrs ↔ 本体 triggerEvent 与 props 对拍防第二真相源 / 前缀两两不互为前缀 / 弃权表 why 非空且目录实存);
`NS-MOBILE-0012` 配方类根认领(registries 每个类根须落在某原语前缀下 —— 一原语一前缀,活体 `.x-submit-btn` 归位为 `.x-submit-bar-btn`);
`NS-MOBILE-0013` 组件目录归类(新建组件第一个 json 就红,`--changed` 增量门可见);`0017` 端锚定 canonical(防子串豁免对任意端同名路径放行)+ 词边界
+ 镜像域 pairs 文件对 mobile 原语豁免(解 0017×0034 catch-22:复刻件沿用同名类名才能让对位闸拿到可比键);`NS-MOBILE-0005` 增 `requireAttrs`
(防 x-tab 缺 change 绑定;受控弹层缺 close 绑定 = 永远关不掉)+ 事件名归一 + 标签边界。三端 `-m x-styles` 0 红,
守着它的床 `.claude/skills/x-spec-checker/tests/x-styles/primitives-teeth.test.js`(含临时注册表反向注入,证明三颗闸读的是数据不是硬编码)。ADR-33。
**诚实边界**:伴生表的「行为字段 ↔ 闸读取」双向一致只由 `NS-COMMON-0039` 内的 KNOWN 字段白名单**单向**看守,`NS-COMMON-0019` 的双向比对只针对轴注册表,伴生表新增字段不被闸读取时无人报。
**★detector 的「视图」与「解析」都是引擎原子,禁在 detector 里自写★**
本层 NS detector 内嵌在 spec 里,天然诱导每颗闸自写「属性: 值」「自定义属性定义位」「长度值文法」这类正则。
x-styles 一本 spec 里实测积累了 **12+ 份**这样的副本,各自演化出不同的盲区(行首锚定 / 每行只 exec 一次 / 强制分号 /
字符类不含下划线 / 不认转义引号 / 单位闭集 / 无大小写标志)—— 描边轴 105 用例白盒台账判出 **57 个口子**,
最大一族的根因不是 57 个,是「副本数量」这一个。
**处置**:引擎 L4 parsers 层的原子 `css-decl.js`(经 `create-service.js` 脚手架建,受 `validate-jsdoc` 层清单校验):
整文声明迭代(字符串 / 括号 / url() / 注释感知,声明以 `;` 或 `}` 终止,同行多条、跨行)· 行内 style 解析(`{{ }}` 不透明)·
自定义属性 / LESS 变量定义表 · 长度值文法(CSS Values 4 全部单位 + rpx,`[+-]?`,`.5`,大小写不敏感)·
border 四边展开(简写 / 长写 / 逻辑属性 / 1–4 值归一)· 旋转判定(rotate / rotateZ / rotate3d / matrix / 独立 rotate 属性)。
经 `tools.cssParser` 注入 detector;`@serviceForbids` 明令 detector 禁自写这些正则。
**配套两条契约修正**:① detector 工具包构造是引擎导出 `buildDetectorTools`(`executors/phases`)——白盒测试床若
各自手抄一份 tools,引擎一加原子所有床同时脱契约;契约只有一份实现,`_getPreprocessed` 缓存带内容同一性校验
(白盒床同路径喂不同合成内容必重算)。② 元规范 `x-standard` NS-COMMON-0024 的 tools 有效键不用硬编码清单,取
`Object.keys(tools)`(detector 拿到的就是引擎给的那份)—— 清单与注入分家正是它要防的「副本各自演化」。
**detector 对缺失的原子注入一律 fail-loud**(返回 error 违规,不静默降级):手抄 tools 的床会整床红,这是设计。
**★视图契约:抹块视图与保块视图,以及 MULTILINE 块的抹块资格★**
引擎给 detector 的视图分两类,选错不报错、只会静默失明:① **保块视图** `codeKeepMultiline`(剥注释与字符串)与 `commentStripped`(只剥注释)与原文**等长**,MULTILINE 业务块里的代码照样看得见;② **抹块视图** `multilineStripped`(对全部文件类型)与 `codeOnly`(只在 TS/JS 上抹,CSS / 标记语言 / `.md` / `.json` 上不抹)把每一对 MULTILINE 标记之间的代码抹成空行 —— **只保行数、不保长度**,字符偏移只能在同一视图或等长视图之间换算。业务逻辑恰恰住在各标准写法的 MULTILINE 块里,所以「禁止某种写法」的闸默认读保块视图,抹块视图只在有意排除块时用、并在检测器注释里写明理由(x-standard ARCH-E02;把「代码标识符 → codeOnly、注释指令 → multilineStripped」当默认、不提保块视图的口径,照它写出的闸对块内整片失明)。读抹块视图的闸逐颗有审计结论;改读保块视图的闸,床里都有「违规写法放进 MULTILINE 块 ⇒ 必咬」,并做过反向验真(临时改回抹块视图当场变红)。
**MULTILINE 块是抹块许可,许可要有来处**:引擎按每一对标记抹块、不问来历,一对形态合法的游离标记就能让所有读抹块视图的闸对被包住的代码失明。x-marker NS-COMMON-0003 把资格收在判据登记处 —— STD 规则号的块必须落在同规范同规则号、已配对的 STANDARD 块里,插槽名是判据声明过的;NS 规则号的块由那条规则登记「族名 → 成员文件」;认定口径与引擎抹块同源并逐行对拍引擎视图,漂移即报。孤儿的身份是「规范 + 规则号 + 名字」:本仓编号按 gapless 重排,规则号被复用是常规操作,只按号判存活会让旧标记长期无人看见(病历:x-file 导入服务写法删掉后号给了导出仓储,两个导入服务的旧标记一直在宣称受保护);清理脚本 `orphan-marker-cleaner.js` 与孤儿闸同口径,扫描根与跳过表取引擎名册(缺失即报错,不手抄)。
**另三条喂料与解析契约**:① **目录模式喂料**:判据把某个根登记为目录模式时,引擎聚合只把目录喂给检测器、根下叶子整片去重 —— 按单文件写的检测器在那里「非某后缀即早退」就等于从没读过文件;常驻金丝雀 `.claude/skills/x-spec-checker/tests/x-structure/gates-dirmode-feed.test.js` 按引擎真实喂法调每一条这样的规则,不往目录里看又没登记为判目录名的即红。② **领域独占目录的共管**:L1.5 独占目录(`sys` / `xType` / `locales` / `xStyles` / `wechatpay` 等)的 owner 数组可以按**正交的治理轴**追加共管规范(标记可归属性轴、语言面闭集轴……),非 owner 的规则在聚合阶段被整片剔除 = 死规则,扩包含面前先查那张表。③ **导入语句的起点只在真代码里认**:`parsers/ts-statement.parseImports` 在剥注释与字符串的视图上找 `import` 起点、在原文上取值,字符串与模板串里写着的 `import … from` 不被当成导入(五份判据共用这一原子)。**探针纪律**:`buildDetectorTools` 按文件路径缓存预处理结果、路径还决定视图分流,探针与床喂样本必须用真实后缀的真路径 —— 在路径后拼 `#序号` 会改掉后缀、换掉视图,测出来的是另一种文件。
**代码围栏只有一份实现**:markdown 代码围栏(``` / ~~~)的识别收在引擎 `scanners/spec.js` 的 `buildFenceLineMask`,经 `tools.fenceLines` 注入检测器(逐行 `boolean[]`,含开闭围栏行),字符偏移版 `buildFenceMask` 由同一份逐行核心派生 —— **判据里禁止再手写围栏跟踪**,消费处缺席即抛。两类手写形态都坏在同一个地方:翻转式(遇围栏标记就取反)在「4 反引号外层套 3 反引号内层」时被内层开围栏关掉状态,把围栏里的演示内容当真;按长度配对但只匹配反引号的写法,对 `~~~` 围栏整类不可见。两者的症状都是判据文档里写给人看的**示例**被当成真规则,而这种假红没有任何迹象指向围栏。
**★引擎「规则没跑成」必须 fail-loud★**
本层的护城河是「detector 内嵌 spec」,其代价是**规则可能加载不出来** —— 而加载失败与
「programmatic NS(合法无 detector)」在调用方眼里**都只是 null,不可区分**。遇 null 若静默跳过,
而适用性已先记 `APPLICABLE` ⇒ 状态机按「已检测且零违规」判定,该规则显示 **✅ 通过、总违规 0、退出码 0**。
**这就是假绿**:闸看似在,其实一次都没跑;hook 与 CI 全部放行。
判定为**遗漏而非取舍**的三条硬证据:① `violations/types.js` 早已写明设计意图「宪法要求"禁止隐藏",
所有 detector 内部异常通过此类型转为违规」并建了 `DETECTOR_INTERNAL_ERROR`(detector **执行**异常);
② STD 侧同类问题(模板提取失败)早有 `TEMPLATE_EXTRACT_FAILED` **报违规**;
③ 同一条链上三个环节,前两个有牙、第三个(NS detector **加载**失败)没有。
**处置**:`DETECTOR_LOAD_FAILED` 违规类型 + `getNsDetectorLoadFailure()` 伴生查询(区分两种 null)
+ 适用性第 5 态 `LOAD_FAILED`(统计行渲染 🚨「detector 未加载(规则未执行)」,**优先级高于其余全部状态**——
规则没跑成时「通过 / 不适用」两种说法都是谎报)+ 进程级 once 去重(加载失败是 **spec 的问题**不是被检测文件的问题,
而 checker 是 per-file 调用,不去重会让一个洞刷满全部适用文件)。
`extractNsRuleDetector` 全库**只有一个调用点**,`-t`/`-v`/`-m`/并行 worker 全部汇聚于此 ⇒ **修一处即全通道覆盖**。
**★上面这句是【会漂移的前提】,已给它装机器锚★**
「只有一个调用点」是本处方案成立的**支点**——多出一个不查 failure 的调用点,那条路径就退回假绿。
同理,「消费点真的调用了 `getNsDetectorLoadFailure`」也**不被既有断言覆盖**:回归床 L1–L4 查的是
违规类型在不在、状态枚举在不在、查询函数在不在、状态机优先级对不对,**没有一条查「有人用它」**。
**实测(真引擎)**:把消费点那句 failure 查询抽掉,**L1/L2/L3/L4 全部照常绿**,假绿原样复活。
⇒ 回归床用例 **`.claude/skills/x-spec-checker/tests/x-styles/axes-teeth.test.js` 的 L5** 双重锚定:
① 消费点必须同时在场三样(查 failure / 产 `DETECTOR_LOAD_FAILED` / 记 `LOAD_FAILED` 状态)且顺序正确
(查询在 `if (!detector)` 分支内、在 detector 执行之前);
② **反向枚举**全 `scripts/` 树的 `extractNsRuleDetector` 真调用点,多出一个即 fail-loud 逼人确认它也查了 failure。
**另一处活体实证**:在真 spec 内同时注入「一条 detector 语法错」+「另一条必报违规」,
实测坏 detector 报 `LOAD_FAILED`、**同文件另一条规则的真违规照常报出**、退出码 0→1 ——
即 detector 加载失败**不会**吞掉同文件其余规则的违规(该场景为 per-rule 调用,不存在跨规则污染)。
**渲染器的两条约定**:`buildMessage` 的
`String.replace(re, String(value))` **必须转义** —— 不转义,value 里的 `$&` / `$'` 被当替换变量展开
(value 是运行时数据——detector 抛的错误消息、正则片段、代码行,含 `$&` 极常见,消息被残片污染且无法察觉);
占位符**兼容 `{{key}}` 与 `{{{key}}}` 两种写法**(types.js 里并存;只认双花括号的话,三花括号渲染后残留一对花括号)。
**活体验证**:注入语法错的 detector,报「总违规 1 · 🚨 detector 未加载 · 退出码 1」(不报这一类时是「总违规 0 · ✅ 通过 · 退出码 0」),
且**只报 1 次**。
**诚实边界**:本闸只管「**加载**失败」。detector 能加载但**逻辑写错**(判据写反、射程写窄、空转假牙)仍不可自动发现,
归三件套的 `-t` 自测、反向注入与常驻对抗床 —— 那是另一类问题,本闸不承诺覆盖。
│ 被引擎消费
▼
check.js + check/ ── 单一检测引擎(唯一真相源,禁止并行检测器):
-t spec 自测(STANDARD↔SLOT 互证)
-v spec 结构验证(用元规范验 spec)+ specHash 闸
-m 代码扫描(spec×目标路径)
无参 全量(全部 spec 扫描 + OxLint/TypeScript 编译验证)
--changed 增量(变更文件×spec 交集,环3 消费;
全部规范的射程按指纹缓存复用,见 §八 收尾环)
exit:0 通过 / 1 违规 / 2 参数错误 / 3 零匹配(防假绿)
coverage-gate:业务新文件零 spec 认领且不在
coverage-inventory 登记 → 拦(堵"真空文件静默放行")
★注册表驱动的矩阵框架(L3 的第二种规范形态)★
三位一体的默认形态是「一条规则 = 一个内嵌 detector」,判据直接写死在 detector 里。当同一判据要在 N 个维度上重复表达时,该形态会产生同构缺陷——维度与判据的对应关系被二次硬编码进 detector,每加一个维度就要回去改一次正则。实测某 spec 同一缺陷连犯 5 次,五次修法完全相同(放宽正则前缀)、五次都没碰病根。
矩阵框架把「维度」从代码里抽出来变成数据:
x-{domain}-axes.json ── sidecar 注册表(spec/rule/code 之外的【第四类真相源】)
(唯一数据源) detector 经 require('fs') 直读(引擎 sandbox 白名单放行 path/fs)
│
▼
轴无关闸 ── 闸不认识任何具体维度,只认识注册表的 schema
铁律:加一个维度 = 往注册表追加一行声明,【闸代码零改动】
若必须改闸才能支持新维度 ⇒ 说明 schema 缺字段,补 schema 不改闸
│
▼
元闸族 ── 闸检查闸/注册表本身(否则整个框架建立在坏数据上):
① 注册表自洽(必填字段/枚举/正则可编译/命名空间正交/子结构校验)
② 闸实现纯净(闸体内禁出现任何维度前缀与端名字面量——维度真相只能来自注册表)
③ schema↔闸双向一致(下划线前缀=文档字段闸不读 · 无下划线=行为字段必须被读)
双向堵两个真实事故形态:隐形契约(闸读了、schema 没声明)+ 孤儿字段(声明了、没人读)
为什么这是架构性变更而非普通规则调整:① 引入了 spec 之外的第四类真相源(注册表),三位一体变为「注册表 + spec + rule + code」四方一致 ② 引入了元闸这一新层级(闸的判据对象不再是业务代码,而是闸自身与注册表)③ 检测能力的增删从「改 detector」变为「改数据」,变更成本与风险模型都变了。
诚实边界(三条):① 该形态目前只有 x-styles 采用,不是全局机制——其余 spec 仍是默认形态 ② 元闸「闸实现纯净」的射程只覆盖注册表 axisAgnosticGates 名册内的闸,未登记者逃出射程,且该逃逸方向零检测(反向臂以名册为迭代源,未登记者根本不进循环)③ 重构过渡期存在增量模式开关,未被任何维度认领的族静默——这是逐维度曝红的节奏控制机制,必须随全部维度回填完毕切为严格模式,否则它就是永久豁免。
三层路径排除体系:L1 IGNORED_DIRS(全局)→ L1.5 DOMAIN_SCOPED_DIRS(领域独占)→ L2 spec excludes(业务精细)。spec 禁止重复声明 L1 已覆盖目录(死代码检测)。
★L1 全局排除是"业务不变量的绝对盲区",禁用于含业务写入的目录(ADR-23)★:L1 在索引期过滤,所有 spec 永不可见,spec 层无法覆盖——目录一旦入 L1,其内代码对全库扫描物理隐身,连显式声明其完整路径的规则也会静默变成死规则。故 L1 只允许放纯产物/纯缓存(node_modules/dist/.umi/__pycache__);凡含业务写入(尤其钱域)的第三方/vendored 目录,一律走 L1.5 领域独占 + 结构类规范 spec 层显式排除的组合:业务不变量(SQL 契约/系统字段/镜像等值)照常覆盖,结构形态类规范显式豁免。诚实边界:引擎的 L1.5 owner 过滤在 -m 与全量两模式下表现不一致(实测 -m x-structure x-server/tools 检测目标不含 wechatpay、全量却计入并判未通过),故非 owner spec 的排除必须写进 spec **排除** 字段,不可依赖 L1.5 自动过滤。
路径级忽略(与目录名册并列的另一张表):上面三层之外,另有一张按仓根相对路径前缀跳过的表(检测引擎常量 IGNORED_PATH_PREFIXES,现有 .claude/tmp 与 x-test/zz-work 两条,后一条见 §八「项目自带」(ADR-112);索引读它,检测器自己走目录树的遍历(scanners/file.js 的 ignoredByPath)也读它)。它与 L1 的目录名册不是一回事:L1 按目录名排除、全仓同名一律跳过,这一张只跳指定的那一条路径、别处同名的目录照旧可见,所以单独一个常量、不混进目录名册(混进去会把全仓所有叫 tmp 的目录一起挡掉)。跳 .claude/tmp 的理由:守卫与运行器的账本、需求账、各会话的临时文件都住在里面,每个会话随时在增删;它们若进索引的文件清单,射程缓存的键(含「文件与目录清单」,§八 环3「射程复用」)就跟着天天变,全部规范的射程隔三差五重算一遍。跳过的前提是没有任何规范的射程落在那里:动手前对每份规范数过落在这条路径下的目标,全为零;一份适用面写 **/* 的诱饵规范证明跳过生效、真射程零差。目录遍历与索引共用一个跳过判断(scanners/walk-skip.js,ADR-114):目录名册(L1)、点开头(.claude 除外)、测试根、这张路径前缀表四条,再加工作区地图(§十八)里目录所在的区的「检测」属性;同一个目录在两种视图里一样,.claude/tmp 两边都看不见。诚实边界:① 遍历看不见点开头目录与测试根,这一类不在对拍台回放里,靠全量检测前后对比兜;② 没有闸盯着「哪份规范的射程落在这条路径下」:今天为零,所以没有可见的后果,将来若有判据要查这两条路径下的文件,经索引与遍历都取不到它们,也不会有东西报错,要先回头改这张表。
扫描后缀白名单是已知盲区:非白名单后缀不进扫描——新增文件类型时必须核对白名单,否则是伪检测。
测试守不到之处的登记位置:宪法 §六.7 要求测试守不到的地方必须在设计里写明,宪法 §三 把它定为 L3 的执行点。载体有三处,各管一面:① 系统规范——架构页「测试床」一节,每颗闸点名床,没床写 data-bed="待补床"(页面标红,x-arch NS-COMMON-0010 核点名属实;封版前置对待补床说不);条款书「无机器闸」的条款写明类别与兜底,落在架构页「诚实边界」一节;② 业务域——第七个视图「测试设计」(parts/test.html,ADR-66):谁在测本域的代码(测试面与床)、每个云函数有没有自己的测试(登记在部署门的发布前当场真跑)、哪里测不到、本视图的异常;页面事实从文档头 describes × 测试面判定 × 部署门注册表派生,只写结构、不写「此刻过没过」。封版时变更历史里写下的「测试指纹」一行是事后痕迹;「资金写函数要么有测试、要么写明不测」还没有闸(x-arch 架构页异常 x-arch-P-01 后半);③ 框架自身——本文 §十六 的诚实边界。
异常 · harness-P-05 技能目录里的脚本、模板、说明书没有任何判据认领(待复盘 · 只登记不修):改 .claude/skills/** 下的技能脚本(五个发布脚本除外)、assets/templates、SKILL.md、tests,没有任何判据认领它们的内容(它们是整个 HARNESS 锁住的文件,改了收尾当轮报「还没升版」;只有 tests 谁都不锁),写得对不对没人查。会出什么事:技能说明写错一条命令、脚本改坏一个参数,检测一侧不会有任何反应,只能靠技能自己的测试床(改了会让技能面的记录作废,收尾提示重跑)。动不动钱:不动。依据:各判据的「适用文件」没有覆盖这些路径(只点名了规范文档、同前缀注册表、x-deploy-dev 的发布脚本与 x-mobile-dev 的端壳模板)。状态:要修(先定哪些该有判据:技能说明的命令至少应核「指向的脚本存在」)。由什么测试守着:技能面的测试床(只守行为,不守说明文字)。
八、L4 强制层(guard 单分发器详图)
挂载:settings.json hooks 八个时刻。写前(PreToolUse)与写后(PostToolUse)只挂守卫真正按工具名分支处理的工具 —— 写前 ^(Agent|AskUserQuestion|Bash|CronCreate|ScheduleWakeup|Write|Edit|MultiEdit)$|^mcp__cloudbase__(CronCreate、ScheduleWakeup 是定时任务通道,ADR-116:守卫写前有这一支,名单里就得有这两个名字,否则这一支在平台上根本不起),写后 ^(Agent|AskUserQuestion|Bash|TaskStop|Write|Edit|MultiEdit)$|^mcp__cloudbase__(写后比写前只多 TaskStop —— 领队按名字停掉队友那一下要在写后记一笔,写前没有它的事;写后名单里有 Agent 与 TaskStop:派出去的执行体与停掉它都要记一笔。选项题写前写后都挂:写前,带着预先填好答案的一律不让弹,题目正文写了不带盘符的仓内相对路径的同样不让弹(ADR-98),被认成签字题的弹出之前要过「谁弹的、签哪几道(确认题可以一题签几条,验收题只签一道)、认计划、题目正文带看板完整路径与「签字」页签、签字区是最新的那一道」;写后认答案。判法见下环3「需求对账」里「签字题带地址」「带话的签字」「一题签几条、每道题都核地址」三段);读文件、搜索、别家 MCP 这类守卫什么都不做的工具不起守卫进程。名单必须带 ^ 和 $:里面有 cloudbase 前缀就得按正则写,而平台对不带锚点的正则按子串认、还连旧名一起认(会带上 NotebookEdit、TaskStop);写成不带正则符号的 Bash|Write|mcp__cloudbase__ 会被当成整名,cloudbase 工具一个都认不上、也不报错。这两个时刻用「直接起程序」的写法:"command": "node"、"args": ["${CLAUDE_PROJECT_DIR}/.claude/hooks/guard.js", "<事件>"](不经 shell,每次少起两层)—— command 只能写 node(多写一个字平台就起不来,写前起不来等于放行),项目目录必须带花括号。失败后(PostToolUseFailure)挂一条只认 ^Bash$ 的,照样起 guard.js PostToolUse:命令执行失败时平台不走写后那一刻,不挂它失败的命令就不记时间窗、它写出的文件到收尾算无主。其余时刻(Stop / SessionStart / ConfigChange / UserPromptSubmit / SubagentStop)是经 shell 的一行命令 node .claude/hooks/guard.js <Event>(收尾换写法实测基本打平,不换)。守卫里每加一个按工具名的分支,都要同批改这两份名单:回归套件从守卫源码里取出分支的名字、按平台的认法核名单(连同「command 只写 node」「失败后只认 Bash」),漏改当场红。共同失效点(守不到,写明):直接起程序的写法若在某一版平台上起不来,写前钩子不拦;而写后看到键名是 PreToolUse 就认定写前判过、不补判 —— 两头都没声音。所以每次换平台版本或改这三段接线,都要在真实会话里逐个时刻核一遍(写前拦一条、写后记一笔、失败后记一笔、收尾逼修)再离开。guard 异常一律 fail-closed(exit 2)—— 含启动壳:任一策略模块加载失败也退出码 2 并写明恢复办法(退出码 1 等于全部放行:平台规定退出码不是 2 就不拦)。SessionStart 只往上下文注入一段状态(写前拦截在不在岗、正在办的需求取自计划目录的 scope.json)并记一笔闸的状态 —— 没签字的计划那一行写明它最后改动的日期、「它自己还没签字,还不能照它动受治文件」「不是你手上的事就不用管它」(全新的会话分不出那是别人放了很久的旧计划,写成「还没签字,先别动受治文件」会被当成给自己的禁令;只是说法,拦不拦由写前拦截判);ConfigChange 与编辑工具写 settings.json 都往会话台账记一笔 cfg(来源、文件、此刻闸的状态)—— 开闸关闸各留一痕;两者都不拦。零件用到才装:守卫的零件(台账、命令判定、云端判定、需求对账、收尾、工作树测量)若启动时一次装齐,与这个事件不相干的零件坏了,说话、配置变更也一起退出码 2 —— 拦说话会吞掉用户原话,拦配置变更挡住的正是启动壳报文给的恢复办法。所以每个零件第一次被用到时才装,装不上照旧走启动壳那一段报文、退出码 2(直接结束进程,不抛异常:调用处「出错只提示」的 try 吞不掉它)。台账零件每个事件都装(会话身份一开头就要用),它坏了照样全部拦;需求零件坏了,用得到它的事件(开工、说话、写前与写后的编辑、写前 Bash、写前派子代理、写前的选项题〔整道题里有「确认」「验收完结」「全选执行」任何一个词的才装需求零件去判;三个词一个都没有的不装、直接放;带着预先填好答案的在这之前就拦了,那一样不用需求零件;题目正文写了不带盘符的仓内相对路径的同样在这之前就拦,不分是不是签字题〕、写后的选项题、子代理收尾、收尾)照样拦 —— 写前 Bash 也在内:没签字的闭集白名单每条命令都要问它「本会话是不是某条在办需求的办理会话」,直写落点还要过需求闸,命令判定经守卫的装载口取它,自己装不上也按拦处理,没有「装不上就放行」的分支。组队零件(guard/team.js)同一个约定(ADR-102):带执行体身份的事件、带名字派队友的写后、队友还活着的收尾、停任务要装它;写前派执行体那一下要过派发闸,所以领队派执行体这一下也要装它,装不上照样拦,判法见下环3「需求对账」里「派发闸」。回归套件按「事件 × 零件」逐格注入故障守着:这一格用得到的零件逐个坏掉必须拦并点名,用不到的全坏了必须照常且装的零件不变。工作区地图的读者入口同一个约定(ADR-126):守卫里按路径分类的判断都经唯一入口 guard/map-reader.js 问地图,入口与它要装的读取模块都只在第一次问的那一行才装,原话入账、会话开始、改配置、收尾记写证据这几条路一次都不装它;它也是失败矩阵里的一列 —— 它坏了,只有要问地图的事件退出码 2、点名出错的文件与行,用不到它的事件照常。判法、读不到地图时的做法见 §十八「守卫读地图与读坏了怎么办」。顶层围栏要问的版本契约同一个道理(ADR-94):写前的编辑与命令行直写,要写的路径先过一张路径预筛表(可能归顶层四类版本单元的路径只会落在表里那几处;不在表里的写 —— 业务代码、业务域的设计、计划与看板、运行时目录 —— 直接放),放掉的不装版本契约;过了预筛的才由需求零件去装版本契约、问单元名册,装不上或名册列不出,这一笔写被拦并写明判不了(它不走启动壳那一种:坏的是这一次判定,不是守卫)。判法见下环3 需求对账「顶层围栏」。「写业务文件不装版本契约」由那张「零件用到才装」的对照表守着。部署门的范围零件(guard/hosting-scope.js,ADR-89)同一个装法:只有带着站点信息的静态托管上传走到部署门时才装,装不上照旧走启动壳、退出码 2,不退回全仓(守卫主自测有一条场景守着;判法见下「部署门」)。
工具调用 ─→ 环1 PreToolUse(写前硬闸,exit 2 = 拦)
├─ Bash 通道:guard/command-policy.js 结构化分词
│ · 折叠引号拼接取真命令名(堵 'no''de' 式混淆)+ 续行/heredoc/{}
│ · 死命令:node -e / python -c 等 CODE_EXEC · 命令行里的 git 一律只读(见下「命令行里的 git 一律只读」)
│ (另有:python - 与 -m、pip 装包;
│ NODE_OPTIONS 预加载类开关 -r/--require/--import/--loader;
│ 生产构建 npm/pnpm/yarn/bun/max/umi 的 build 脚本与 node --run build)
│ · 写目标检测:重定向/cp/mv/sed -i 指向保护面 → 拦
│ (cp/mv 按「目录+源文件名」算真实落点;mv 挪走硬保护目标拦;
│ rm/rimraf/del-cli 删硬保护目标拦,本地发布档案除外——作废的档案本来就该清)
│ (同一件事只留一个取法:① 包管理器跑哪个脚本 —— 选项写在子命令前面也认得,
│ run 的别名同认;取出的脚本名不是起服务器的名字时再看其余词,只对查询、安装类子命令
│ 免拦(npm ls start 这类不误拦,别的写法一律不少拦);② cp / mv 先定目标与源
│ (-t 与带值选项按 GNU 规则取,-t 没有值不算写了 -t),只判一遍真实落点;这份取法与
│ python 一族的名单各只有一份,判落点与没签字的闭集白名单共用;③ 包着的命令
│ 写前拦截与写后复判同一个取法,照各家 shell 自己的参数文法走:bash 类把选项(连同它的值)
│ 走完、剩下的整串就是命令或脚本文件(多字母选项的名单只此一处);cmd 在每个词里找
│ 「斜杠加 c / k / r」(开关粘在前面的也认);powershell 的开关按参数顺序认(斜杠与长横
│ 开头的开关同认);「跑脚本文件」放行之前判不了就拦 —— 走过认不出的开关词、表里认而
│ 5.1 不认的开关或位置上的 .ps1 后面有语句记号(分号、竖线、圆括号、大于号)、参数里有
│ bash 会改写的记号又有执行开关,都不算跑脚本文件;另按「每个参数去首尾空白、空词只在
│ 开关位置跳过」再取一遍(powershell 自己的取参办法),几种读法写前有一种取得出就拦。
│ 写后记账另有第二种读法,任一种认出发布就记;cmd 每一处「斜杠加
│ c / k / r」后面的整串、圆括号里的命令、从第一个拿不准的开关词起的整串各认一遍;
│ 剥包裹词时 then / do / else / elif 与 cmd 的 call、@ 前缀一并剥掉(只用在拦的方向:没签字的
│ 闭集白名单与命令名混淆闸不多剥这几个)。cmd / powershell 带执行开关词、整条命令里又有
│ 管道或输入重定向喂标准输入 → 拦(标准输入会从外层继承,按整条命令看)。mv 的源是保护
│ 目录本身(检测引擎那棵树、空壳桩目录、sys / templates / .umi、装配产物目录)→ 拦。
│ eval / source / . / iex 后面的整串写后也向内再判一层。
│ 守不到:powershell 的编码命令(-EncodedCommand)写前照拦、写后看不出里面包的是不是发布;
│ 文法只照 bash、cmd、Windows PowerShell 5.1 实测过,pwsh / zsh / ksh 没验证;
│ cmd /\c(反斜杠写法)、if / while / until / case 后面直接跟的命令认不出;
│ 不带执行开关词的 cmd / powershell 被管道喂命令、here-doc 起始行后面的管道、|& 接 bash、
│ rm 删挪保护目录本身同样拦不住)
├─ 会话命令与敏感命令(ADR-116;这一支管两样:不经受信脚本直接跑 claude,与代签、改代签设置、改型号配置、重建登记册、换主控这五条敏感命令。固定句不记不认签字、写保护名单、签字记录只认两条路、代授权的标记、签字放行、说话只认主控、定时任务通道这几处判法按所在的环分开写):
│ · 任何会话不经受信脚本(体系守护技能的 harness.js)直接跑 claude 一律拦,不分是不是办理会话
│ (会话命令自己用参数数组起 claude,
│ 走的是脚本内部,不经这道命令判定)
│ · 会话命令起 claude 子进程前洗掉继承来的四个环境变量(ADR-127):`CLAUDE_CODE_SUBAGENT_MODEL`、`CLAUDE_CODE_SUBAGENT_MODEL_FORCE`
│ (子代理型号与强制开关)、`CLAUDE_CODE_SUBAGENT_EFFORT`、`CLAUDE_CODE_EFFORT_LEVEL`(推理档只许型号配置定);名单是 `core/session-ctl.js` 里的
│ 一份 `SCRUBBED_ENV`、小函数 `cleanEnv` 洗,Windows 上变量名不分大小写,别的变量一个不动;`spawnClaude` 是仓里起 claude 子进程的唯一口,
│ 发起、叫醒、恢复、停、删、列表、改名与读横幅日志都经它。为什么要洗:后台作业的环境取自起它那条进程的环境、存进作业的状态文件,
│ 起新会话时用、叫醒旧作业时原样重放 —— 某个会话的环境里带着这几个变量,就会顺着它的 Bash 子进程、会话命令起的 claude 子进程、新作业
│ 一路带进新会话与它派的执行体(后台服务自己的环境会把这几个键剥掉,所以重启电脑或停后台服务都解决不了;设置里删键只管以后读设置的进程、
│ 不撤已应用的变量)。守不到:已经带着这几个变量的旧作业(会话命令洗不到它们身上)叫醒时仍重放旧值;已在跑的会话(含 X大脑 的窗口,
│ 按新启动命令重开才干净)自己派的执行体仍被强制,要换新只能删了再发起;平台以后再有别的会把型号或推理档带进新会话的变量,名字要补进
│ 那份名单;这一条没有真环境的实测,只有床里用假 claude 看环境
│ · 代签(`--action=sign`)、改代签设置(`--action=sign-settings` 带 `--do=set`)、改型号配置(`--action=model-settings` 带 `--do=set`,
│ ADR-127)、重建登记册与换主控(`--action=session` 带 `--do=rebuild` 或 `--do=register-main`)
│ 这五条敏感命令,发出者带执行体编号(钩子输入里的 agent_id 不空)的一律拦:X大脑 派出去的执行体与它同一个会话号,
│ 所以认执行体编号、不认会话号;只有主控本人的会话跑得了(型号配置命令不带 `--do=set` 的 show 谁都能看)。
│ 命令判定读环1 传进来的「是不是执行体」一栏,不自己去认
│ · 两条要 BOSS 亲手做的事的「!」脚本(`--action=project-settings`、`--action=settings-commit`,ADR-127)经 Bash 工具跑一律拦,
│ 含预览,不分主控、常驻会话还是执行体,报文写「这条只给 BOSS 在 X大脑 窗口用「!」跑」:「!」不经写前钩子,所以只有 BOSS 跑得了;
│ 守不到:用脚本转一道去跑守卫看不见,两条命令都是代码里登记的闭集,绕过去也无害(§十五「要 BOSS 亲手做的事」)
├─ Write/Edit/MultiEdit 通道(写保护的六个判断条件,谓词住 command-policy 的 isProtectedWriteTarget、名单不抄在守卫里 —— 问工作区地图的视图,见 §十八「守卫读地图与读坏了怎么办」):
│ · isSpineTarget 脊柱只读:整个 .claude/hooks/(分发器·策略模块·回归床)
│ +settings(.local).json+.mcp.json+runtime-registry.js
│ +.claude/tmp/ledger/ 写证据台账+装配面新鲜度戳+各单元锁清单
│ +唯一运行器与空壳桩+部署门入口
│ +两条封版命令(x-meta-dev core/seal.js·x-feature-dev arch/seal.js)
│ +两个发布出口(deployer.js·publish-tests.js)+x-core/tools/manifest.js
│ +.claude/agents/*.md(复盘者与执行体定义)
│ +检测引擎的射程缓存目录 .claude/tmp/.scope-cache
│ +会话登记册目录 .claude/tmp/sessions/ 与代签设置文件 .claude/sign-settings.json(ADR-116;都在永不放行名单里)
│ +型号配置文件 .claude/model-settings.json(ADR-127;在永不放行名单里)
│ +定时任务文件 .claude/scheduled_tasks.json(ADR-116;CronCreate 带 durable 时平台写它,在永不放行名单里)
│ +会话命令与代签命令的判决模块 session-*.js、sign-*.js(体系守护技能 core/ 下;和对账命令、核准命令同列)
│ +型号配置命令与两条「!」脚本 model-settings.js、project-settings.js、settings-commit.js(体系守护技能 core/ 下,ADR-127;它们决定谁能改配置、改哪个文件、提交哪几份)
│ 只锁名单上的文件本身,不锁整棵目录:分发脚本、脚手架、部署门登记表不锁
│ (写即卸墙;正当变更走签字放行 —— 脊柱与引擎承牙这两类对签过字的办理会话放行它签过的文件,见下「签字放行」;手动开闸只在急救时用)
│ · isEngineTarget 引擎只读:check.js+check/ 整树(一次编辑即
│ 掏空任何闸;只锁写不锁跑)
│ · isProtectedArea 保护区只读:sys/ · templates/ · .umi
│ · isGeneratedArtifact 生成物只读:业务端目录下的 miniprogram_npm/、dist/web/、.cache/web-src/
│ (装配器产物,手改即被下次装配覆盖;正确入口是改母本后重新装配)
│ · isReleaseArchive 发布档案只读:x-release/ 整树(发布闸认的检查点记录与上传来源;
│ 只给静态托管下载落到 <档案>/backup/ 留一个口)
│ · isBizSource X-RULE 删除闸:业务码逐【具体标记】计数比对
│ (防诱饵标记平衡总数;Write 覆盖读盘对比)
│ · 前五类(脊柱、检测引擎、保护区、生成物、发布档案)编辑工具、命令行直写、云端工具三条路
│ 都直接拦;业务源码编辑工具走上面的 X-RULE 逐标记计数闸,命令行与云端工具的裸写直接拦
│ · 风险标记里说的「写保护文件」只取前三类(脊柱、检测引擎、保护区),扣掉各单元的变更历史
│ 与锁清单、守卫的运行账本与生成物(.claude/tmp 下的写证据台账、需求账本、装配标记、射程
│ 缓存,与保护区里的 .umi)、需求履历;另两类生成物与发布档案本来就不在这三类里(§十五
│ 「七个风险标记」)。扣除项写在守卫需求零件一处常量里,谓词本身照旧只住 command-policy
│ · 这六个判断条件之外另过需求零件的写前那一道(requirements.writeBlockWhy,命令行直写共用):
│ 没有开了工的在办需求不让写受治文件(排队的不算);有在办需求时只放本会话是某条在办或签字作废的
│ 需求的办理会话的写(ADR-98,见环3「需求对账」里「写前按办理会话判」);
│ 要写的文件归顶层四类版本单元(整个框架、
│ 某个系统规范域、项目架构、agent 架构)时再过顶层围栏(ADR-94;
│ agent 架构 ADR-101)—— 写的会话不是
│ 某条在办或签字作废、落点表列有该单元的需求的办理会话就拦。判法、回的话与
│ 守不到见环3「需求对账」里「顶层围栏」一段
├─ 签字放行(ADR-116;下面说的受保护文件只指上面前两类 —— 脊柱与检测引擎承牙):
│ · 为什么不靠手动开闸:手动开闸是把项目设置里写前拦截那一行改名,整个写前拦截就停了,设置又会热加载,那一刻全部在跑的会话
│ 同时失去守卫、关闸还得有人记着 —— 授权的范围(整个守卫、所有会话)比要做的事(一条需求改几个受保护文件)大得多。
│ 授权跟着签字一走,守卫不关
│ · 受保护格:计划落点表里凡是落在受保护文件上的格,由计划工具(立项命令、对账命令、签字题命令)自动标「受保护」,
│ 不靠人手标;路径里的通配符先展开成真实文件再逐个问保护名单,永不放行名单里的文件虽然受保护、但不在放行之内。
│ 受保护格不另存标记,由签字那一刻的落点表和保护名单现算,新旧签字一样。签字一的题与看板写一句人话:
│ 「这条要改受保护的文件(守卫 N 个、执行体目录……):签了就等于同意到时放行这些文件,不用你手动开闸」。
│ 授权永远出自用户:签字一只能用户本人签、从不代签,开闸的授权不会被代签带走
│ · 放行只有一个询问入口(`requirements.releaseOf(root, sid, rel, opts)`,返回 `{ allow, why }`;写文件工具与命令行
│ 两处调用口都带「记一笔」开关,放行时往这条需求的账本记一笔 `rel`)。写一个受保护文件,四样同时成立才放,否则照拦:
│ ① 写的人是这条需求的办理会话,而且只认三种:签字时记下的那个会话(owner)、会话登记册里登记为这条需求产品经理的会话、
│ 主控或项目经理指名改派的会话(`handoff --to=<完整会话号>`,账本里记 named);谁都能跑的自助改派 `handoff --take`
│ (记 self)照旧能把三查和写前拦截接过去,但不带走放行;常驻会话不写机器镜像,也不是办理会话
│ ② 路径落在这条需求签字那一刻的落点表算出来的受保护格里,并且核准之后的现行落点表里还有它
│ (签字之后经核准加进来的格不放行 —— 要放行得先核准、再请用户重签(重签只有签字作废时才有,没作废就只能请用户手动开闸换入,补签放行没做);核准减掉的格也不放行;减格不用重签)
│ ③ 这条需求在办:签了字一、开了工、没完结、签字没作废(排队的开工之后才放行;不另设「正在实施」一种态)
│ ④ 路径不在永不放行名单里
│ · 范围写死为脊柱与检测引擎承牙这两类;保护区、生成物、发布档案、业务端源码不在放行之内。写文件工具、命令行、
│ 换入帮手(`core/swap-in.js`)三条路认同一份放行(写文件工具与命令行只放行写、挪走与删除照拦;受保护文件的删除只经换入帮手标删,问的是同一份放行);别的文件、别的会话、别的需求一律照拦
│ · 永不放行名单(写在代码里、只许加严;和工作区地图的地板是两回事):各本账(需求账本、原话账本、会话台账)、需求履历、
│ 各单元的锁清单 `version-lock.json`、装配标记、检测引擎的射程缓存、版本库自己的忽略清单 `.git/info/exclude`、
│ 代签设置文件(只归用户)、型号配置文件(只归受信命令)、会话登记册目录(只归受信命令)、定时任务文件(`.claude/scheduled_tasks.json`)、项目设置与本机设置(`settings.json`、`settings.local.json`)、云端工具服务的定义文件(`.mcp.json`);
│ 唯一运行器、部署门入口和空壳桩不在名单里,列在签过字的落点里就放行
│ · 自动收回:验收完结、归档、签字作废任何一样发生,这条需求的放行当场收回,不需要谁记着关
│ · 放行评估自己出任何错(读不了账本、机器镜像坏了、抛异常)一律按不放行:吞掉、记一笔、不往外抛,
│ 受保护文件照拦,别的命令(含恢复命令)照放
│ · 留痕:放行时往账本记 `rel`;需求履历记下这条需求放行过哪些受保护文件、实际写了哪些(从写证据取)
│ · 急救开闸:新换上的守卫要是坏了、连恢复命令都被拦住,用户照旧可以手动改名停掉写前拦截来救(主控告诉用户什么时候开、
│ 救完提醒关,关闸可以由主控代关)。设置会热加载,开闸那一刻全部在跑的会话同时失去守卫,所以急救第一步先停掉常驻会话
│ 和各位产品经理。放行评估出错已按不放行处理;守卫别的出错形态下恢复命令跑不跑得了,以两张设计页诚实边界与急救步骤里写明的为准
│ · 守不到:能改守卫的人就能改放行的判定;办理会话往这几个文件里写了什么,机器挡不住(靠标准、测试床、独立复盘);
│ 放行只看路径与会话、不看写进去的内容;指名改派与登记册的口子见 §二 与下面「办理会话改派」。
│ 受保护格与放行是两份名单:受保护格宽(守卫、检测引擎、执行体目录、保护区、项目设置……),放行窄(只脊柱与引擎承牙,
│ 且不在永不放行名单里)。落在保护区(`sys/`、`templates/` 等)或项目设置上的受保护格不放行 —— 签字一那句「签了就
│ 等于同意到时放行这些文件」对它们说过头了,要改它们仍得用户手动开闸(项目设置本来只归用户)
│ 守着它的床:`.claude/hooks/tests/signed-gate.test.js`(起真守卫逐项断言放行与各种拦,含手动开闸照样有效、
│ 放行评估出错时受保护文件照拦而恢复命令照放)
├─ 选项题通道(AskUserQuestion · ADR-92 · ADR-98):
│ · 整次先看带没带答案:工具输入里答案一栏不是空的 → 拦,不分是不是签字题
│ (答案只能由平台在用户点了之后填;报文以「环1 选项题:」打头)
│ · 每道题都核地址:题目正文里出现不带盘符的仓内相对路径 → 拦,要求写成
│ 完整路径,不分是不是签字题
│ · 整道题里「确认」「验收完结」「全选执行」三个词一个都没有 → 不装需求零件,直接放
│ · 其余交需求零件 guard/requirements.js 的 askGateWhy,一次弹题有几问就逐问各自判;
│ 先碰到哪一样不过就拦在哪一样(被认成签字题而不过的,报文以「环1 签字题:」打头;
│ 两问以上报文前加「第 N 问:」):
│ 封口(选项标签以「全选执行」打头却不是固定写法 → 拦;认没认成签字题都生效)
│ → 是不是签字题(只认两种写法:选项标签恰好是固定写法;题里写着「确认 <名>」
│ 「验收完结 <名>」而 <名> 是一条没完结的计划;认不出的那一问直接放;
│ 认法与答完之后认打字的同一套,动词与名字连着写的也认)
│ → 谁弹的(带执行体身份的签字题 → 拦)
│ → 签几道(验收题必须单选、一问只签一份计划的一道;确认题可以多选:
│ 每个选项各是一条固定写法「全选执行:确认 <名>」、各对得上一份没完结的计划;
│ 几个选项的落点单元有重叠、或有一条此刻签不了 → 拦并点名)
│ → 认计划(名字对上恰好一份;已完结、账本被改过、机器镜像读不了 → 拦;
│ 多选的确认题逐份认)
│ → 题目正文两样(先核看板的完整路径,再核「签字」与「页签」挨着出现;
│ 多选的确认题要有每一份看板的完整路径)
│ → 签字区(读得到;内容编号、开着的是哪一道、验收题另比结果单编号;
│ 多选的确认题逐份核,各自是最新的那一道)
│ · 只比现成的记号,不重算三查;判法、被拦时回的话与守不到见环3「需求对账」里
│ 「签字题带地址」与「一题签几条、每道题都核地址」两段
│ · 写后认答案另过「说话只认主控」一道(ADR-116):登记了主控、而弹题的会话不是主控 ⇒
│ 答案里的签字不认、原话不记,回话写明原因(判法见环3「需求对账」里「签字记录只认两条路」)
├─ 定时任务通道(CronCreate、ScheduleWakeup · ADR-116;提示词都在 prompt 里,触发时送进会话的就是这一句话):
│ · 为什么:说话钩子分不出用户敲的字和定时任务触发时送进来的话(官方的钩子输入里没有来源字段,官方文档明写
│ 定时任务触发也走这个钩子;恢复演练实测,项目经理建的探针定时任务触发后被原样记成了用户原话),所以堵在建的那一刻
│ · 提示词里含签字说法(`requirements.signLikeText` 认得出的)或用户亲口说的任一句固定话(含换主控;整句相等或作为
│ 子串出现都算;型号配置那一句认前缀「型号配置:」,含前缀的不管后面写得对不对都拦)⇒ 拦,不分哪个会话、单次还是重复、带不带 durable;报文以「环1 定时任务:」打头,写明原因与出路
│ · 会话登记册 sessions 里有这个会话号的非主控会话(常驻会话、各专项产品经理、复盘经理)只许建提示词整句恰好等于巡检固定句
│ (`FIXED_SENTENCES.patrol`,首尾空白不算字)的 ⇒ 别的一律拦;主控与没有登记的会话只受上一条约束;读登记册失败按没登记算,上一条照判
│ · 提示词不是一段文字 ⇒ 判不了里面有什么,按拦;零件装不上走启动壳(退出码 2),判定出错走顶层 fail-closed,没有「判不了就放」
│ · 落盘的定时任务文件 `.claude/scheduled_tasks.json` 是脊柱写保护(编辑工具与命令行直写都拦),并进永不放行名单
│ · 守不到:只拦建的那一刻;定时任务送进来的普通话(不含签字说法的)在主控与没登记的会话里仍被记成用户原话;平台自己写落盘文件
│ 不经本闸,node 脚本直接写那个文件守卫看不见;手动开闸期间这一支(挂在写前)不在岗,触发那一刻的说话钩子那一道仍在。
│ 守着它的床:`.claude/hooks/tests/scheduled-prompt.test.js`
├─ 派执行体通道(Agent;两道,先后固定 —— 先复盘派出那一道、再派发闸):
│ · 复盘派出那一道(报文以「环1 复盘:」打头):只管提示词里带复盘任务说明标记的那一次派发 ——
│ 复盘者不许带名字派、只能派对抗审查官、提示词必须逐字是程序生成的派发表头
│ (说明全文不进提示词,复盘者自己读;抄全文、改字、加减一句都拦)、
│ 连着三次不过而用户没在派它的那个会话里发话就不让再派。这一道不判型号与推理档:复盘者和别的执行体一样,
│ 由下面的派发闸判(ADR-127)。
│ 判法见环3「需求对账」里「复盘进关口」
│ · 派发闸(ADR-102;报文以「环1 派发:」打头):每一次派执行体都判,两样 ——
│ ① 类型:平台自带的两个工具型放;平台内置的那几种拦(ADR-103:先认这张内置名单、不分大小写,
│ 再查名册:名册里有同名的一行、目录里也有同名定义文件,照样拦);在名册里而且定义文件在的放;
│ 其余一律拦(不写类型、名册外的名字、名册读不到、名册里有行而定义文件不在);
│ ② 型号与推理档(ADR-127;类型与名册那一关过了才判,复盘者也走):入参里的 model 不写或写 inherit 放,写了别的一律拦;
│ effort 写了就只放等于型号配置里执行类推理档的;主控类会话派执行体必须带它;配置读不出时执行类会话不带参数的派发照放、其余拦;
│ 守卫只拦、不改写入参,里面没有任何型号字面量。排在复盘派出那一道之后:拿复盘任务派错了人、连着三次不过、
│ 带名字派,报的仍是复盘那几句原话。判法、回的话与守不到见环3「需求对账」里「派发闸」与「派发的型号与推理档」两段
├─ MCP 通道:guard/mcp-policy.js decideMcp
│ · 本地写通道(download*/init 类)落点危险 → 拦(.claude 与 .git 全树禁写;git 没设钩子目录,
│ 哪天设了要把它补进名单)
│ · callCloudApi 破坏动词 + sts/cam/ssm/kms(凭证、权限、机密值控制面)→ 硬拦
│ · auth 凭证外泄拦;只放查状态、发起登录、登出;set_env 与 login_by_api_key 核目标环境
│ = .mcp.json 声明环境(写了哪个环境字段就核哪个);认不出的动作、不带动作的一律拦
│ · 全量工具快照(READ/GATE/SPECIAL),快照外未知工具 fail-closed
│ · 数据库写分级:manageMysqlDatabase 与 queryMysqlDatabase.runQuery 先看语句 ——
│ DROP TABLE|DATABASE|INDEX|VIEW / TRUNCATE / ALTER TABLE…DROP / 无条件 DELETE|UPDATE
│ 一律拦(删表删列走五步破坏性迁移、由用户在控制台做);带条件的写照旧过部署门。
│ (PostgreSQL 的两个工具同一套分级;数据库实例销毁、取原始连接信息拦;
│ 运行时配置绕过闸连 callCloudApi 的 params 里带的超时与内存一起看)
│ · 部署门:变更类 MCP 且待检范围内存在「既非存量、又没有收尾环干净结论」的改动
│ → 拦(按写证据台账判;范围内不问是谁的)。待检范围按被发布物定
│ (ADR-89;下面 a、d 两种调用不照全仓,其余照 ADR-50 决策⑤ 的全仓):
│ a. 发布档案往线上放新内容的上传(assets / cutover),这一次调用恰好落在一个站点、
│ 且站点认得出种类(x-harness ⇒ 治理站点;x-website ⇒ 官网;站点在检测引擎端名册的
│ 手机端一栏里 ⇒ 手机网页版)⇒ 只数该站原料目录里的改动:治理站点 x-harness/,
│ 官网 x-website/,手机网页版 = 端目录 + x-core/mobile/ + x-core/tools/。原料目录
│ 不另写一份,取发布前测试的同一份定义(发布库 release/publish-tests.js 的
│ inputDirsOf);文件键与目录都经台账的同一个归一,按「目录 + /」从仓根开头比 ——
│ 路径中段带同名字样的(别的目录下的 x-harness/ 子目录)、只是前缀相同的
│ (x-website-old/)都不算。站点从这次调用要传到的托管目录认,不信发布档案自己
│ 记的种类,只拿它对一遍
│ b. 认不出就照全仓(只会更严):站点是后台(构建会把各端与云函数的权限声明编进包,
│ 原料不止 x-admin/)、站点不在手机端名册里、一次调用跨站点(涉及的站点不是恰好
│ 一个,两个手机端同传也算)、档案记的种类为空或与站点对不上、发布库装不上或抛错、
│ 原料目录为空、含空串或不含站点目录
│ c. 其余变更类调用(云函数、云存储、数据库、权限、网关路由与域名…)的判法:
│ 数全仓,不问是谁的 —— 推上生产的是仓库状态,更严不更松
│ d. 不往线上放新内容的静态托管调用(回滚上传、回滚删除 —— 首页换回已核对之后、
│ 清理清单内的删除)不看仓库状态:策略层放行时结论不带 gate,守卫里「看仓库状态」
│ 那一整段因此都不进 —— 不只待检清单与发布前版本比对两臂,这一段开头的量仓
│ (measureOrBlock 的三种 fail-closed 拦:git 故障、生产形态下仓根不是版本库、
│ 台账首次建立)与这一段的部署门总时限检查(量仓前、版本比对前各一次)也不发生。
│ 只由静态托管发布面物理闸把关(见下「环1 静态托管发布面物理闸」)
│ 谁算范围:守卫自己的范围零件 guard/hosting-scope.js(scopeOf 算范围、noteOf 出报文
│ 里那一句)—— 不触盘、不装别的零件。guard.js 的 gateScopeOf 把它要的两样装好交
│ 过去:手机端名册(检测引擎的端名册常量)与原料目录取法(发布库的 inputDirsOf),
│ 都按守卫自身位置取、各放在 try 里,装不上就交空的 —— 名册空了手机端一律认不出,
│ 取法空了哪个站点都认不出,认不出就照全仓(b)。
│ 装不上是因为工作区地图读不到的除外:端名册文件在加载时读地图,那一种原样往上抛
│ (部署门按拦、发布先查说「判不了」),不当成「没有手机端」。
│ 范围零件挂在「用到才装」上,只有带着站点信息的上传走到部署门才装;它自己装不上
│ 走守卫启动失败(GUARD-BOOT,退出码 2,这次调用被拦并点名坏的零件),不悄悄照全仓
│ —— 发布库是守卫之外的东西,坏了退回更严的判法;范围零件是守卫的一部分,坏了就是
│ 守卫坏了。其余变更类调用的结论不带站点信息,gateScopeOf 第一句就返回,一个零件
│ 都不多装。
│ 谁按范围数:台账的待检清单出口(session-ledger 的 pending)多一个可选的第三个参数
│ (范围目录数组),不传就是全仓,有版本库与没有版本库两种形态同一个判法;返回的
│ 数组上另挂 scoped(这一次是不是真按范围数的)与 outside(范围外另有几个没数)。
│ 范围写法台账认不出(不是数组、空数组、任一项不是规范的仓根相对目录)同样照全仓数、
│ scoped 为假 —— 守卫只在范围零件给出了范围、且台账真按它数了时才算收窄。
│ 收窄时拦截报文另加一句:只数了这次要发的哪个站点的哪些原料目录、范围外另有几个
│ 没复核的没数(前两句照常)。紧跟的发布前版本比对不随之收窄,核全部单元
│ (§十三 第 4 关;这一次判成联调时,只放过那条需求落点表里的单元
│ 施工中,见下「联调还是正式发布」)。
│ 守不到:① 这一臂只看得见工作区里还没存进版本库的改动,存进去之后一个都不数 ——
│ 它不是墙(拦截报文自称粗粒度),墙是发布前版本比对与发布前当场跑的测试;② 原料
│ 目录信的是发布库那一份定义,它写窄了待检范围跟着窄 —— 守着这一份定义的有两样:
│ 发布库受脊柱写保护、归整个 HARNESS 这个版本单元,改它要升版封版并跑技能面的床;
│ 守卫面有两张床(包着主自测的薄壳床、会话台账床)在床头 @covers 点名了发布库那
│ 一个文件 release/publish-tests.js,它一变这两张床的旧记录作废、守卫面要重跑,按
│ 改动选床时连守卫面一起选中(范围零件自己的床不读发布库,不在此列);③ 以后新增
│ 站点类顶层物默认不收窄(照全仓),要收窄得在范围零件的站点种类表里登记;④ 治理
│ 站点的取材面远大于 x-harness/,受治文档那一半不在待检范围里,交代与缺口见 §九
│ 「发布准备的公开内容扫描」
│ 当场重查(车道上机;只用在上面 a 那几种收窄到原料目录的站点上传,写后补判那一支
│ 不重查):待检清单里别的会话名下(有写证据的主人:在线的、满 24 小时的、不在线的
│ 都算;问清单的本会话自己的不算)、文件还在、此刻这份内容以前在任一判据组下查过
│ 干净、也没记过红的文件,当场按当前判据重查一次 —— 与收尾环替无主文件复核同一
│ 条增量检测,照同一种分批逐批起子进程、带 GIT_OPTIONAL_LOCKS=0;时限取部署门总预
│ 算剩下的、再给联调判定与版本比对留 6 秒(RECHECK_RESERVE_MS),不到 8 秒
│ (RECHECK_MIN_MS)不起子进程、这几个全按没跑完。一批退出码 0 整批过;有违规而报文
│ 点名了文件的,点名的没过、其余过;有违规却一个都没点名的整批没过;起不来、到点的
│ 算没跑完。过了的从清单里拿掉、这一次放行,记成无主的干净结论(此后谁收尾看到同
│ 一份内容都跳过它);没过的留在清单上、原因写「当场重查没过」,没跑完的写「当场重
│ 查没跑完」,两种都只拦、不记红;从没查干净过的、记过红的、没有写证据的照旧等它
│ 的主人或任一会话收尾。拦截报文多一行:当场重查了几个、过了几个(已记成无主的干
│ 净结论)、没过几个、没跑完几个;收窄时最后那一句改说这几个当场重查不了或没过、
│ 各自怎么办。后台与云函数按全仓数,不重查、照旧拦。判法住会话台账零件(待检条目
│ 多带 key、hash、abs 与能不能当场重查的 recheck 四栏)与部署门测量零件(recheck
│ 跑检测、recheckPending 是总入口,「只有收窄了才重查」只住这一处);记不记无主的
│ 干净结论由调用方给的开关定:部署门记,发布之前的只读先查只查不记(§九)。只给床
│ 用的开关 X_RECHECK_MS 只能把时限调短。守不到:它只省掉「叫醒主人」这一跳,替主
│ 人做的只是一次检测、不含测试;内容改过一个字就照旧等主人;一批约六七秒,部署门的
│ 总时限里一次最多跑两批左右,待检的多时剩下的照拦;重查会写检测引擎的射程缓存。
│ · 联调还是正式发布(ADR-100;排在待检清单之后、发布前版本比对之前;
│ 判法住守卫的联调零件 guard/trial.js,用到才装):这次调用要上线什么照现成的
│ 判定面取 —— 代码推送面命中 ⇒ 云函数(函数名;上传目录在仓里时连它一起算),
│ 建数据模型(mcp-policy 的 dataModelSurface 从图里认出表名)⇒ 数据表,带站点
│ 信息的上传 ⇒ 站点(原料目录与上面待检范围同一个取法),其余变更类调用不进
│ 这一道(没有联调,也不核完结)
│ a. 判成联调(四样同时成立:有效的联调标记、那条需求在办、要上线的全部东西都
│ 落在它签过字的落点表里、要上线的是云函数或数据表)⇒ 紧跟的版本比对只放过
│ 这条需求落点表里的单元处于施工中,这些单元别的毛病照拦,别的单元照旧
│ b. 其余一律按正式发布判:要发的云函数目录或站点源码目录被任一开了工的在办需求(签字
│ 作废的、计划不见了的也算在办)签过字的落点表盖住 ⇒ 拦,报文在「部署门:」
│ 后面是「正式发布核验收完结:」那一句,点名那条需求、带上联调开始的命令;
│ 有口径而联调没成立时,为什么没成立那一句拼进这一道与后面每一句拦截报文
│ c. 判不了(需求零件出错、联调标记在却读不出来、在办需求盖着哪里无从得知、
│ 账本目录或仓外镜像目录在却列不出来)按拦处理;这一道在本进程里同步读盘、
│ 截不断,开头先核一次部署门的剩余预算
│ 写后补判走同一段(只判、不跑床)。两条路、放行面、联调标记、写后记一笔与
│ 收尾写进履历、守不到,见环3「需求对账」里「部署门认联调」一段
│ · 部署门总预算(从守卫进程启动那一刻算):
│ git 测量、发布前版本比对、资损域回归床、忽略规则核对、内核核验共用一个预算,
│ 每一样只拿剩下的时间,剩不到一秒半当场拦(超时一律按没过算)。版本比对挪进子进程
│ 跑同一个函数(同进程里的同步调用到点截不断):超时、退出码不是 0、没出标记行、
│ 读不出数组,一律拦(这一次判成联调时,子进程多带一份「放过哪些单元
│ 的施工中」的名单,标记行不变)。预算常数写在守卫里,回归套件把它与 settings.json 里写前钩子的
│ 时限绑住(预算加余量必须小于钩子时限 —— 钩子先被平台掐掉等于放行),并在守卫副本里
│ 把预算、门槛与慢桩同比例缩小实跑「到点就拦」(云存储上传与推代码各走一遍)。截不断的是两步,
│ 都在本进程里同步跑、量都很小:读台账(它超出剩余预算时下一道当场拦)与推代码时排在
│ 各臂最后的上传内容核对(读测试账本、算上传目录与内核的指纹;它后面没有下一道预算检查)
│ · 被拦时先报最便宜的那一样:运行时配置绕过(不读盘)→ 待检范围内没复核的
│ 改动(范围见上)→ 联调还是正式发布(正式发布核验收完结)→
│ 版本比对 → 推代码那几臂;待检拦截的报文末尾提醒「清完还要过版本比对」。
│ 版本比对拦下时,问题清单里每一行(判不了那一行除外)末尾带着那个
│ 单元的封版命令,拦截那句的尾巴写明「每一行后面就是它的封版命令」
│ · 资损域回归床门:命中代码推送面(codePushSurface)→ 跑常驻床,红则拦
│ · ★运行时配置绕过闸:runtimeConfigBypass —— MCP 调用
│ 显式携带 timeout/memorySize 即拦。云函数超时是【平台侧参数】,
│ 唯一真相源在 runtime-registry.js;经 MCP 直改线上 ⇒ 仓库不知情、
│ 下次脚本发布又覆盖回去,值反复横跳。静态检测扫文件看不见线上态,
│ 只有 PreToolUse 拦得住。与代码推送面【正交】(配置绕过不推代码,
│ 故必须挂在 codePushSurface 判据【之前】,否则永不触发)
│ ★MCP 优先新建:guard 注入 runtime-registry 真值,携带的
│ timeout==真值 → 放行(真相源未被绕过,只是经 MCP 下发);不一致/取不到
│ 真值 → 拦;memorySize 无合法 MCP 携带方,恒拦
│ · ★vendor 双形态归一★:@cloudbase MCP 存在聚合(manageFunctions
│ {action})与扁平(createFunction/...)两代工具形态,mcp-policy normalizeFlat
│ 把扁平归一为聚合语义 —— 四判定面(decideMcp/推送面/装配面/配置闸)单真相源,
│ 任一形态出现都不绕闸不误拦(扁平读/变更/凭证面各归其类,login 等硬拦)
│ · ★内核装配闸:kernelAssemblySurface 包住代码推送面,
│ 对 X 形函数目录 spawn(绝不 require,框架不依赖材料)
│ `x-core/tools/manifest.js --verify` 双臂核验:①内容臂——上传目录
│ 内核与母本差集三元组非空即拦;②打包器剥离臂——MCP SDK 打包器
│ 【读 .gitignore 剥文件】(活体实证:直传源目录返回
│ success 而函数冷启动 MODULE_NOT_FOUND),故 `git check-ignore`
│ 判上传目录的 sys 命中忽略规则且目录本身在仓库内 → 拦,
│ 正解=--bundle 落仓库外装配后上传
│ (先按原样路径问、再按上传目录的真实路径问一次 —— 仓外的目录联接指回
│ 仓内函数的父目录同拦;上传目录是 UNC 路径一律拦 —— 管理共享指回仓内时原样与
│ 真实路径都是 UNC、git 一律答「不在仓里」,两问都判不出;正路出包落系统临时目录,
│ 是盘符路径,从不产生 UNC)
│ · ★牙B require 闭合在 --verify 里:bundle 级三合一——
│ 内核字节等值 + require 图闭合(断边/逃逸/动态 require 皆拦,
│ sys 子树虚拟解析到母本、与物化状态无关)+ bare 依赖对账
│ (闭包实测 externals ⊆ package.json deps ∪ busboy 懒加载白名单)。
│ 两条通道同点消费:guard MCP 闸 spawn 它,脚本通道 deployer
│ 装配后 require 它(verifyBundle),红即 fail 本次部署
│ · ★上传内容闸(ADR-61)★:床门跑的是【仓库里】的函数,传上去的可以是
│ 别处改过的副本。床门跑绿时部署门入口记下那份目录的上传指纹,本闸在内核各道
│ 检查之后对【实际上传目录】算同一个指纹比一次,对不上即拦。指纹只有一份定义
│ (guard/test-faces.js 的 fnDirFingerprint),出包工具、脚本发布出口、写后复判共用
└─ 拦截出口(ADR-93 · 拦截留痕):上面每一条「拦」,连同执行体停下那道关、复盘者收尾、收尾环的拦,
都从守卫主文件里同一个出口走 —— 往标准错误写一行原因、退出码 2;只在屏幕上留一行字的话,
事后问「这条需求被拦过几次、最近一次为什么」答不出,所以还要记账。
· 这个出口在退出之前往本会话的台账追加一笔拦截(事件 x,格式见环2):时刻;在哪一刻被拦(写前 / 执行体
停下那道关 / 复盘者收尾 / 收尾,记成 pre / agent-stop / review-stop / stop);工具名;拦在哪(编辑取文件的仓根
相对路径、仓外的写绝对路径,命令取开头一百二十个字,云端工具取动作名、带服务名的写成「服务名:动作名」,
派执行体取类型);原因的第一行(二百字以内);执行体发出的带上它的编号与名字
· 守卫自己运行出错而拦的那一种(文件末尾的总兜底)也尽力记一笔、标明是守卫出错;记不下不管
· 不改判、不拖慢:记账包在 try 里,记不下时原来的报文与退出码一个字不变;放行的调用不多读不多写,
被拦的那一次只多一次追加(台账零件本来每个事件都装,不多装零件)
· 写的时候不记「是哪条需求的」(不多读任何东西);归到需求是读的时候算 —— 按「这条需求的办理会话、
第一次签字之后」数,分三栏:写前、收尾、其它(执行体停下那道关与复盘者收尾归其它);只读那一个会话
自己那一份台账(见环3 需求对账「每次回话列进度」)
· **为什么不进需求账本**:那本账带链,追加是「读末行、再追加」两步、没有跨进程排队(环3 需求对账「记洞不改」里
讲往账本追加一笔的那一句);拦截是高频事件,并行的工具调用与几个会话同时落笔会把链撞断、整本账判成被改过、全仓写前都拦
· **守不到**:① 不经这个出口的,一笔不记 —— 守卫启动失败(台账零件可能就是坏的那个,会话号也还没算出);
钩子输入读不了、连会话号都没取到的那一次守卫出错;平台自己的禁止名单拦的、钩子超时被平台掐掉的;
写后复判判出的「本该拦」不是拦,照旧记 {u};封版命令拒封、签字没记成都不是守卫的拦,不在这本账里;
开闸期间写前那一道不在岗,那时没有拦、也就没有记录。② 会多数的 ——「写证据台账首次建立」那一次提示性的拦
也被数成被拦。③ 会少数的 —— 台账写不进去时照拦、少一笔、没有提示。④ 留在本机的 —— 被拦命令的开头
(前一百二十个字)原样留在本机的会话台账里,命令里带着密钥的话也留在那里(台账不进版本库,保留三十天);
台账在本机、脚本能改(与写证据同一条边界)。⑤ 今天读这类记录的只有「每次回话列进度」:没有单独的查询命令,
完结时也不汇总进需求履历
▼
写入成功 ─→ 环2 PostToolUse:按会话记写证据(guard/session-ledger.js · ADR-50)
· 台账 .claude/tmp/ledger/<会话id>.jsonl:每会话一份、只追加(Windows 多进程追加写
实测无损;禁「写临时再改名覆盖」,并发实测失败 42%);会话 id 取 hook 输入的
session_id(子代理与主会话同一个,--resume 不变,--fork-session 才换)
· Write/Edit/MultiEdit/MCP 下载 → {w, 文件键, 写后内容指纹}
· Bash → {b, 结束时刻, duration_ms}(PostToolUse 输入自带时长,开闸期 PreToolUse
关掉也不丢起点);命令类写入无 file_path,只能按时间窗归属
· 这份台账里不只有写证据:收尾红数、接线变更、写后复判等各有各的事件(见各段)。其中拦截 {x, 时刻, 在哪一刻被拦, 工具, 拦在哪, 原因首行[, 执行体编号与名字][, 守卫出错]}(环1 末「拦截出口」写)
没有文件键、不是写证据:判改动归谁时不看它。但它**算这个会话的动静**:环3 判「主人会话已结束」的那一处认任何带时刻的事件、不分种类 ——
被拦一次,就算这个会话还活着,它的改动因此晚些才轮到别的会话按无主复核(只会更晚放行,不会放松;
这说的是满 24 小时那一种认法 ——「主人已不在线」那一种不看台账里的动静,看平台的会话名册,见环3 分账 ②)
另有三种(ADR-100)—— 联调上线 {tr, 时刻, 需求的目录名, 标记是哪个会话开的, 上线了什么}(下面「联调放行之后自动记」写)、
联调已写进履历 {trf, 时刻, 各笔记上没有与发布登记怎么说的}(环3 收尾时把 {tr} 逐笔写进履历之后写)、
联调点名过 {tra, 时刻}(环3 收尾的附注真说出去那一刻写),见「部署门认联调」⑦。这三种同样没有文件键、不是写证据
另有一种(ADR-102)—— 写域已点名 {twd, 时刻, 点过名的那几个「文件键:内容指纹」}(环3 收尾的附注真说出去那一刻写,
见「写域点名」)。同样不是写证据,判改动归谁时不看它。收尾每一轮另记一笔计时 {rt, 时刻, 本轮总用时毫秒, 各段用时}(环3 收尾写,用进程退出钩子一处管所有出口;执行体停下那一支不记):
各段共十五个段名(boot、measure、attribute、trial、team、tests、seal、assembly、site、detect、side、audit、notes、record、other),各段之和恒等于总用时;
它没有文件键,归属、干净结论与拦不拦都不看它,记不进账时放行与拦截一个字不变;它的时刻同别的带时刻的事件一样,被「判主人会话已结束」当成这个会话最后一笔动静(只会让判断更晚、不会更松);被平台超时掐掉的那一轮没有走到退出,也就没有这一笔;按段取每一轮的用时用台账零件的 `roundTimings`,给以后决定收尾能不能并发做时定收益用
· 不阻塞——真检测延到 Stop,避免每写全量扫描
· ★cloudbase 工具 → 写后复判(ADR-61)★:执行完用写前策略 decideMcp 再判一次,
代码推送另比「传上去的就是测过的那一份」;判为本该拦的(认不出的工具、未测发布、没过检查的
发布档案…)记 {u};开闸期间这是云端写操作唯一还在岗的检查
· 写前另有的四类也补判:运行时配置绕过、没复核的改动、版本没封、上传目录缺内核
或会被剥掉 —— 与写前走同一份代码(现场信息只装一次),只判、不跑测试床;只在写前拦截不是
确定在岗时补(读不到设置也算不在岗),确定在岗时不补(写前已拿同一份输入判过同一套)。
「没复核的改动」这一类的范围与写前同一套(ADR-89):
三类静态站点往线上放新内容时只数该站原料目录,范围外的不记,范围内的记下与写前拦截
逐字相同的那一句;回滚与清理的结论不带 gate,「看仓库状态」那一整段写后同样不进,
没复核的改动与版本没封这两类都不补判。这一段里另有一样(ADR-100):联调还是正式发布
—— 正式发布被在办需求签过字的落点表盖住的,补判成本该拦;判成联调的,版本没封那一类只对
那条需求落点表之外的单元判(与写前同一段代码)
· ★联调放行之后自动记(ADR-100)★:cloudbase 工具这一支,在上面的写后复判之后 —— 这次调用是
代码推送或建数据模型、此刻照部署门的同一个判定是联调 ⇒ 当场只往本会话台账记一笔 {tr}
(哪条需求、标记是哪个会话开的、上线了什么:函数目录或表文档的路径,仓根相对),并在工具结果旁
说一句:这一次按联调放行、不算正式发布、这一笔什么时候进履历。**当场不调发布登记、不写任何
受治文件**:当场写出的发布段文件是一处没有干净结论的改动,同一轮紧接着的第二次联调上传会被
待检清单拦下 —— 云端工具通道一轮就只能传一个函数。写进那条需求履历发布段「联调」一格的那一步
在这一轮收尾时做(环3「部署门认联调」⑦)。只有联调标记文件在场时才装联调零件(说话、编辑、
普通命令这些路不因此多装零件);出任何错只在工具结果旁说一声(那一次没记进台账,收尾不会替它
写进履历,要留痕手跑联调记法),不影响别的记账、不拦
· 云存储、静态托管的单文件下载落进仓里同样记写证据;目录级下载枚举不了远端写了
哪些文件,不记,按无主由部署门挡(落在这次调用的待检范围里才挡得到,范围见环1「部署门」)
· 失败后时刻:命令执行失败时平台走 PostToolUseFailure、不走写后,接线文件把它挂到
同一支(只认 Bash)—— 失败的命令照记时间窗;失败的发布命令也记一笔「命令行直接发布」
(这一支不看命令成没成,收尾报红一次)。**守不到**:云端工具调用失败时平台同样不走写后,
而失败后时刻只挂了 Bash —— 开闸期间失败的云端调用一笔不记(失败的调用没有改到线上)
▼
补测记账 ─→ 环2.5 guard/worktree-probe.js(只做【测量】)
· 病根:Bash 通道(sed / node 脚本 / 任何工具)写的文件【三环全盲】——
环1 判据在词法层取命令串里的路径词,而真实路径由 shell 在 hook 看完
之后才展开(变量/$()/glob/cd 改 cwd);环2 无 file_path 进不了白名单。
实测 38 条改业务源命令逃 27 条,ex/ed/patch/git apply/truncate/install/
rsync/ln -sf/shred/unlink/touch/sponge/csplit 13 个写工具全逃。
活体:`sed -i ... "$F"`(路径装变量)改 6 处业务源,事后查队列——不在。
· 设计:不从命令串【预测】会写什么(静态分析 shell = 不可判定),
而在事后【测量】实际写了什么 → git status --porcelain -uall 得全仓脏文件。
变量/xargs/find -exec/node fs/未知工具全覆盖。
· ★测量与判定分离★:git 是仓库级(唯一能看见命令类写入的事实来源),
「是谁的、查过没有」交 session-ledger 按写证据判——不用全仓快照(它只有一根
指针,两个会话轮流推它,谁放行谁就吞掉另一个的差集)。
· 两处消费:Stop + MCP 部署门(measureOrBlock 同语义)。成本 ~1.1s,只挂这两个
低频点,绝不挂每次 Bash。
· 自指防护:.claude/tmp|worktrees 排除(台账自身未 gitignore 前会出现在 git status 里)。
· ★测量的四条约定★
G1 路径解码:git 对非 ASCII 路径【默认】C-quote(\ooo 八进制)。若用
JSON.parse——JSON 不认八进制,必抛→落 catch→带引号原串当路径→statSync
失败→入队【不存在的路径】⇒ 该文件静默逃出复核。所以按字节解码再整体
UTF-8 还原。射程:全仓 542 个 tracked 路径会被 quote(含受治 plan 文档)。
G2 忽略面:被 ignore 的业务源对本环全盲 —— 病历:一条从
Node 模板抄来的裸 `logs/` 吞了 6 个业务源(admin logs 模块 + 双语语言包,
且 routes.ts 已注册其路由)⇒ 既不在版本库也对本环全盲。
「被 ignore 的受治端源码」由回归床对拍防复发(运行时不加 git 调用)。
G3 写证据台账写保护:台账目录 .claude/tmp/ledger/。
往台账补一条假的干净结论 ⇒ 该文件从待检里凭空消失 ⇒ Stop 逼修与部署门
同时失明且都报绿。危害与 runtime-registry 同级,三通道全拦。
G4 降级语义归一:git 故障(degraded)/ 生产形态下无仓库(noRepo)/ 台账首建
三形态在 Stop 环与部署门共用 measureOrBlock 同语义拦截(禁同一字段两套失效语义)。
· 诚实边界:①归属靠写证据:内容指纹优先(复制保留修改时间的文件按时间会瞎,
指纹不会)、命令时间窗其次(两端 1.5s 余量)、都没有 = 无主;后台 Bash 的
写后事件在启动时触发,之后的写入无主;删除按父目录修改时间归属;
两会话时间窗重叠归「分不清」两边都拦(一次回放 43 份记录重叠合计 0.3 分钟)
②记账完备 ≠ 检测完备(--changed 对目录级规则结构性不可达)
③被 .gitignore 忽略的文件测不到——这是 git 视角的固有天花板,改不掉;
反例由回归床 IG 组对拍拦截。非 git 仓库 → noRepo,
两处消费方均 fail-closed(不静默当作「干净」);verify-harness 沙箱是
设计内的无仓库形态,按本会话台账自证
▼
回合结束 ─→ 环3 Stop:guard.js 归属 + guard/stop-handler.js 检测(按会话分账)
· ledger.attribute:对每个脏文件判 存量(台账首建时记为基线,只拦一次提示)/
本会话的(内容指纹或时间窗指向本会话)/ 分不清的(多个会话都指向)/ 他会话的 / 无主
· 只检查、只拦本会话的;分不清的两边都拦并注明;他会话的留给它自己收尾 —— **但主人会话已结束、或主人已不在线而内容曾查过干净的改动按无主处理**
(两种认法:满 24 小时那一种 ADR-82;主人已不在线那一种 ADR-102。都归无主、保留原主人供报文点名,由下面「无主」那条路接住。
① **满 24 小时**:一个改动的全部主人会话都已结束,即它们最后一笔台账事件都在 24 小时之前,本会话永远算活着。
为什么:干净结论按(文件、内容、判据指纹)记,判据或引擎一变旧结论作废,而已结束的会话不会再来收尾,不这样认,它留下的改动就永远挂在部署门上、只能开闸绕过 ——
病历:一个会话结束后留下的 21 个守卫文件改动就这样卡住过治理站点发布;24 小时是台账里唯一可观察的「还活着」信号(台账之外另有平台的会话名册,见 ②),
判成已结束的只是多被别人复核一次、按内容记结论、不拦人。
② **主人已不在线、内容曾查过干净**(零件 `guard/session-ledger.js`):补 ① 的一个死角 —— 封版一变判据组,旧的干净结论整组作废;
只按 ① 判时,文件的主人会话已经关掉、但最后一笔动静还不满 24 小时,既不算无主、又没有活着的主人来复核,发布被拦,只能请用户进那个旧会话结束一轮。
`classify` 另算一样「此刻的内容曾经查过干净」—— 台账里有同一个内容指纹的干净结论,不论是在哪个判据组下记的。判法:这个文件的主人都不在线或已结束、
而且此刻的内容曾经查过干净 ⇒ 归无主,带上原主人并标「主人已不在线」,任一会话收尾时照无主那条路替它复核、结论按内容记回。主人里有一位在线 ⇒ 照旧归别的会话;
此刻的内容从没查过干净 ⇒ 照旧等 24 小时;本会话永远算在线。
**「不在线」读平台的会话名册**(`readRoster`、`awayBy`):用户配置目录下的 sessions 目录,一份记录一个开着的会话,只用进程号、会话号、目录三样 —— 名册里没有这个会话号在线的记录,
或有记录而那个进程已经不在(`pidAlive`:不发信号地探一下,查无此进程才算不在,没权限探、别的错都按在),就是不在线。名册在哪由 `rosterDir` 定:
环境变量 X_GUARD_SESSIONS_DIR 指到哪就读哪(床里换成假的),否则读 CLAUDE_CONFIG_DIR 下的 sessions,再否则读用户目录下配置目录里的 sessions;
只碰名字是纯数字加 .json 的那几份(一个进程号一份),同目录别的文件不读、不列。
**名册「判得了」要四样齐**:目录读得了、而且至少有一份认得出的记录;活着的进程的记录都认得出格式(有一份活着的认不出,那位会话是谁不知道,可能正是主人);
有一份活着、而且就开在这个仓里的记录;给了本会话的会话号时名册里它在线。后两样是自证 —— 守卫能跑起来,就说明这个仓里至少有一个会话活着、而且就是本会话;
名册里看不出来,说明读到的不是此刻在用的那一份,或格式变了。任一样不成立 ⇒ 判不了,照旧只按 ① 判(只会更严、不会更松),并在收尾的附注里说一声:
有几个改动没法按主人不在线判、为什么。用到才读:只有碰到「归别的会话、而且此刻的内容曾查过干净」的文件才读名册,一次归属至多读一遍。
**两种各说各的话**:收尾时,① 照旧说「主人会话已结束的 N 个改动按无主复核……」;② 说「主人已不在线的 N 个改动按无主复核……不再等 24 小时,结论按内容记回,不拦本会话」。
部署门的待检清单(`pending`,有仓库与无仓库两种形态)用同一个判法,只是报文里那一句原因不同:② 写「未经收尾环复核;主人已不在线(本机的会话名册里没有它,或它的进程已经不在)、
这份内容曾经查过干净,按无主复核,任一会话收尾时顺带查」。问清单的是哪个会话由调用方给:守卫的部署门给本会话的;发布之前的只读先查(§九)不给,那一侧不核「名册里本会话在线」这一样。
**连带**:这类文件落在「无主」一栏,封版命令的认领开关可以认领它们(不带认领开关照旧保留旧指纹);三查那边按「别的会话」认。
**守不到**:(a) 平台依赖 —— 名册的位置、文件名与字段是平台此刻的样子,变了就判不了、退回 ①,这一种认法也就不再起作用(收尾的附注会说,只在真碰到这种文件时说);
(b) 只看得见本机、这一份配置目录下起的会话:别的用户、容器或子系统里起的会话(名册在别处)、平台没登记进名册的会话形态,都会被看成不在线;
(c) 进程号被别的进程重新用上时,已经关掉的会话看起来还在线(只会更严);名册里那一位的进程在、而会话号已经换了(清空重开),原来那个会话号算不在线;
(d) 被看成不在线的那一位其实还在的话,它自己收尾时这个文件仍算它的、照查照拦,别的会话替它做的只是一次真检测、结论按内容记;
(e) 替它复核的只是检测、不含测试;复核出红的照旧挂着;(f) 此刻的内容从没查过干净的照旧等 24 小时,出路照旧是恢复那个会话结束一轮。
守着它的床:`.claude/hooks/tests/session-ledger.test.js`、`.claude/hooks/tests/stop-ring.test.js`);
无主的做不拦人的检查(每轮至多 40 个),结论按内容指纹记回台账,红的由部署门挡
(ADR-89;只在待检范围内挡:三类静态站点往线上放新内容时,落在该站原料目录
之外的红项不挡这一次发布,回滚与清理一律不挡;其余变更类调用照全仓挡。收尾报文里
「有无主改动复核未过」的那一句附注不一概说部署门会挡,只说发布时
落在部署门待检范围里的会被挡)。无主的改动封版时照旧保留旧指纹、要带认领开关才封得进去;
其中没有任何写证据的删除另有一种自动认领(ADR-103)—— 落在这一版「为了」
那条在办需求此刻的落点表里、又在本单元锁清单里的照封(判法在封版命令,§十三 第 3 关)
· 「查过没有」按(文件键,内容指纹)记干净结论:同一内容只查一次,改了再查;
拦下时不记 —— 下一轮仍看得见这批文件,直到真正修干净(逼修语义)
· **联调写进履历(ADR-100)**:收尾里第一次量工作树与归属之后,本会话台账里上一笔「已写进履历」{trf} 之后的联调记录 {tr}
逐笔交给发布登记,写进那条需求履历发布段的「联调」一格(一笔调一次,次数才对得上上传的次数);写出的发布段文件
照编辑工具写文件那样给本会话记写证据;真写出了文件就重量一次工作树、重算归属,它在同一次收尾被复核、拿到干净结论;
排在量工作树之后而不是之前:待写的记录要从台账里找,而量工作树那一步会把这一轮读进来的台账丢掉重读 —— 排在前面,每一次收尾都要多整读一遍全部会话台账(下面「台账一轮只整读一次」);排在后面,没有待写记录的收尾一次都不多读;
全部写完记一笔 {trf}。它排在「被拦之后接着的那一次、没有上一轮红数可比就直接放行」那一支之后(那一轮不量不查,写出来的文件没人复核)。
为什么不在写后当场写、记不上怎么办、会话没走到收尾怎么办,见下「部署门认联调」⑦
· **需求对账(`guard/requirements.js`)**:一条需求 = 计划目录(`.claude/plan/` 下的一个目录),
人读 `PLAN.html`、机器读 `scope.json`(签字只锁五样:需求那一句话、要用户亲手验的清单、动钱与动权限与身份与改已发布表字段类型或删功能三个自报、档、流程;标准的措辞与条数、自动用例、落点表里的目录与格这些过程不锁,见下「签字只锁五样、过程由主控核准」);
内容编号 = 前四样的指纹前四位(盖的是需求、三个自报、档和亲手验的清单;机器镜像里「档」一栏没写或写小事的不进编号,见下「定档与上限」),**不进用户看的话**:他点「确认 <名>」那一刻钩子记下此刻的编号,之后锁住的内容一改编号就对不上、签字作废;
「验收完结 <名>」同理,钩子拿他看过的那张结果单(= 他从看板签字区复制出来的结论末尾带的那张单子的编号,必须就是账本目录里落盘的那张)
与当场重算的比。签字只有两种形态(ADR-78,见本段末「签字搬进看板签字区」):
打字说固定的那一句(「确认 <名>」算签字一;「验收完结 <名>」不带单子编号按「没给他看过单子」记账、不完结),或把看板签字区「复制结论」生成的整段贴回 ——
首行是那一句,中间每样一行「<名目>:对 / 不对[。意见:…]」,可有一行总意见,末行〔内容 XXXX〕或〔结果单 XXXX · 内容 XXXX〕;全「对」= 签字,有「不对」= 不过(他写的意见就是原因),
少一样 = 不算,夹着别的行 = 只记成他的话;编号由守卫核、不给用户看。官方选项里的多选题不是签字(多选的确认题另认一种 —— 选中的每一项恰好是固定写法「全选执行:确认 <名>」的,各记一笔,见下「一题签几条、每道题都核地址」,ADR-98)。选项题的答案今天只有三种认成签字:单选题「其他」输入位里粘的签字区结论、打的固定句「确认 <名>」(见本段末「贴回经对话框」);整段恰好等于固定写法的那个选项(「对话框一键签」);单选题「其他」里他自己打的、以「全选执行」那一句开头、后面跟着话的(「带话的签字」)。不是签字、但也不只是记成话的:与在对话里说的一样会记一笔不过的那几种(比如单选题「其他」里他自己打的「不过 <名> 原因」)。其余才只记成他说过的话。多选题的答案、认不出属于哪一问的答案,签字只留中间那一种(多选的确认题按选中的选项逐个比,每个恰好是固定写法的各算一笔);以一个不是恰好固定写法的选项标签打头、后面多出一截的答案,整句只记成话,哪一种签字都不认。需求账本
`.claude/tmp/requirements/`(脊柱写保护):`says.jsonl` 用户每句原话;`<名>.jsonl` confirm / accept / reject / oos(confirm 那一笔另有两栏:当时按哪一档核的 tier、办理会话 owner;另有事件 handoff:办理会话改派那一笔,记跑命令的会话、从谁到谁、几点;开工那一笔 start(时刻、谁开的、占的单元、开工基线)与提交那一笔 commit(提交号、标签、推没推成);confirm 那一笔带「排队」标就是签了字、没开工;oos 那一笔记的是「本会话写进别的会话在办范围」时多一栏 into,记写进了哪条需求的范围);
`<名>.baseline.json` 开工那一刻(当场开工的就是签字一那一刻)全部受治文件的指纹(只记第一次;清理归档时清掉仓内这一份,见下「清理归档」⑤)。四个时刻:用户说话(UserPromptSubmit,认三句、记账、
塞提醒 ——「正在办」那一行给每条在办的需求列一段进度,见下「每次回话列进度」;对每一份已完结、还留在计划目录的计划各点名一行,见下「清理归档」;出错只提示不拦)→ 动手之前(没有正在办的需求不让写受治文件;有在办的也只放办理会话,见下「写前按办理会话判」;不拦计划与看板、.claude/tmp、仓外,施工区不受治但另有一道隔离(见下「项目自带」);「本会话已写过的文件」那一条豁免只在仓里没有在办需求、只有签字作废的需求时管用 —— 有在办需求而本会话不是办理会话的,写过也照拦;要写的文件归顶层版本单元(四类)时另过顶层围栏,见下「顶层围栏」)
→ 写完之后(一句「在哪条需求的哪一格 / 不在范围里」放在工具结果旁)→ 收尾(现在的受治文件对基线算改动面,范围取本会话办理的在办
需求的并集(范围 = 签字时的目录加已核准的目录,在办的与它办理的签字作废的同样,签字之后新加、没核准的目录里的改动算范围外,见上「签字只锁五样、过程由主控核准」⑥),范围外的按收尾环算好的会话归属(内容指纹 → 命令时间窗):本会话写的与分不清的拦一次并记 oos、内容变了再拦,
本会话写进别的会话在办范围里的另算:同样拦一次、记进同一本账(多一栏 into)、同一种去重,回话单独一句点名落进了谁的范围并给出改派命令;别的会话与没有写证据的改动落在一条在办需求的范围里算有主、不列,
其余别的会话与没有写证据的只列并点名)。「正在办」由用户的确认加上开工写下,不由执行者声明 —— 确认可以提前签好几份,开得了工当场开、开不了记成排队(排队的不算正在办),开了工才算;几份需求同时在办是常态(并行会话各办一条;同一个版本单元上同一时刻只开工一条,落在不同单元的照旧并行,见下「签字与开工分开」「同一块排队」)。
**记洞不改**:命令行写出的文件按命令时间窗归属到会话 —— 命令跑得久、丢后台,或像封版命令那样由脚本在命令末尾才写出的文件,
修改时间落在窗口之外,收尾与三查记成「没有写证据」(需求闭环那份计划的结果单上变更历史与锁清单两份就是这样列的);只列不挡 —— 没有写证据的改动不拦完结,否则任何无关文件都能卡住完结。
**签字只锁五样、过程由主控核准**(ADR-111 · 少重签)。本节别处凡与本段不同的,以本段为准;宪法 §六.8 那一句「签过字的内容一改,签字作废」里「签过字的内容」指的就是下面锁住的五样。
① **锁住的五样**:需求那一句话;要用户亲手验的清单(tests 为空的那几条用例:哪几条、每条验什么、条数);动钱、动权限与身份、改已发布表字段类型或删功能三个自报;档(写了而且不是小事才进);流程(业务、Harness、规范认成哪条,机器从落点表算)。内容编号 = 前四样的指纹前四位(`requirements.substanceOf` / `contentHash`),不进用户看的话;流程不进编号:签字那一笔记下当时的流程(`flow` 一栏),之后每次判断(`planStates`)逐次拿它和此刻从落点表算出的比(`flowCheck`),不一样当场判签字作废,算不出来点名「流程判不了」(判成读不了)、不作废 —— 流程不放进编号,是因为它从落点表推出来,规则表一改、进了编号会让全部在途签字整批作废。锁住的任何一样改了(编号变,或流程比出差别),签字作废、要用户重签。**验收谁签**(ADR-116)一栏不在这五样里、单向锁住:放宽(亲签改代签)算实质、要用户重签,收紧(代签改亲签)走核准、不用重签(核准命令的重判里多一支),详 §十五「代签设置、验收谁签与代签命令」。
② **不锁的过程**(`requirements.processOf`):标准的措辞与条数;自动用例的一切(条数、预期、作证文字、点名的测试、对着哪条标准);亲手验用例的「在哪看、怎么验」;同一流程之内加或换的版本单元;落点表里的目录与格。签字之后它们和签字时(或上一次核准时)不一样,叫「待核准」(`pendingOf` 列清单,每一项旧到新:加或去掉目录、加或去掉版本单元、标准措辞改了或增删、自动用例增删与预期与对着的标准、点名的测试增减、作证文字改了;只改格名、不动目录的不追踪),签字照样有效、编号不变;用户每说一句话,「正在办」那一行点名待核准的条数和核准命令。
③ **核准**(`requirements.approveProcess`,命令 `harness.js --action=approve --plan=<名>`,实现住 `x-harness-dev/scripts/core/plan-approve.js`;该文件进脊柱写保护名单、算在判决依据的「三查」这一样里,不多出一样):不带 `--execute` 只预览 —— 列清单(旧到新)、新增覆盖多少个受治文件、重判过没过、一个清单指纹(盖清单全文加机器镜像此刻的指纹,不含时间),账本一个字不动;`--execute` 必须带同一个 `--fp`,对不上就拒绝(预览之后清单又变了;开关叫 `--fp`、不叫 `--print`,见下 ⑨)。执行记一笔 `approve`:核准者、时刻、当时的办理会话、改了什么(旧到新)、新增覆盖多少文件、此刻的过程(之后的待核准以它为底),和判资格用的事实(`sg` 最近一笔确认所在的会话、`hs` 当时的办理会话、`win` 自这份过程的底定下以来写过机器镜像的全部会话、`mh` 当时机器镜像的指纹、`mn` 核准那一刻登记的主控)。**核准者是会话登记册里此刻登记的主控**(与「说话只认主控」同一个认法:登记册读得出、而且登记了主控;读不出来或没登记主控时,是最近一笔确认所在的会话),**不是当时的办理会话**(含改派接手的),**不是自底定下以来写过这份机器镜像的任何会话**(先写的也不行,不只看最后一个写者),机器镜像此刻的内容还要**查得到写证据**(没变过,或写证据台账里有一笔把它写成此刻这份内容;脚本、拷贝、编辑器写的说不清是谁写的,不核准)。读账本的一端按这一笔里记的事实重算(`approvalHolds`;带 `mn` 的按它认核准者,不带的老写法只认签字会话),不合规的核准不算数(验收时单独点名);之后改派办理会话、或有人碰机器镜像,不追溯作废以前合规的核准。核准不是代签:签字一永远只有用户本人签,签字二按代签设置由用户本人或 X大脑 代签(代签命令,见下「签字记录只认两条路」)。
④ **核准那一刻机器重判**(`approveReasons`):碰到五样中任何一样就拒绝,报文按类写出路 —— 流程变了(认成另一条、混成一条:不走核准,逐次比对当场判签字作废,核准命令碰到已作废的计划直接拒)、风险标记新增(与签字时记下的比)、档的下限高于签的档、条数超了签的档的上限、改判定代码同一时刻只开工一条、新增的版本单元必须是版本契约认得的(含业务域)且没被别的需求占着、新增的目录归一个落点表里没列的单元也不行(单元被占与判定代码被占这两道只对开了工的需求查;排队的需求什么都没占、不查,开工那一刻整张落点表重判),新增的点名测试同样重判。另有四道拦悄悄改松:每条签字时有标准对着的需求(标准尾部「(对着需求 N)」)现在仍至少有一条标准对着、每条用例对着的标准都存在、自动用例或点名的测试变少(要显式带 `--accept-fewer`)、加业务域单元(要显式带 `--domain=<单元名>`:机器核不了它动不动钱动不动权限)—— 后两类在清单里置顶标红,独立复盘必须作答。重判不过的,**只有风险标记新增、档的下限升高两类要请用户重签**:带执行开关(并带对清单指纹)时账本另写一笔 `void` 标记(只绑当时的待核准清单,清单一变即失效;只对它前面那一笔确认有效,重签之后自动作废;还有别的拦着时先不写),签字随即作废;单元不认得、条数超了档的上限不写标记,判定代码被占、单元被占写等或并。
⑤ **没有核准路的需求**:办理会话就是签字会话(`handlerOf` 等于最近一笔确认所在的会话),或核准者自己写过机器镜像、写者查不到 —— 待核准的过程改动当作实质,签字作废(`noPathOf`),重签时一并带进新的签字(`carry`)。办理会话就是签字会话的,机器当场判(签字回话当场说明);另两种由核准者带执行开关跑核准命令时写上面那笔 `void` 标记,预览只报不写。机器认办理会话的办法是写证据里写过这份机器镜像的会话(签字会话自己的写不算办理,别的会话也写过的取其中最后一个),所以主控自己写机器镜像再自己签,就是没有核准路 —— 核准路必须是「另一个会话」的代价,也是机器镜像由产品经理写、主控签的由来。
⑥ **范围 = 签字时的目录和版本单元,加已核准的**(`effectiveDirsOf` / `effectiveUnitsOf`;`planStates` 把它挂在机器镜像上的 `__allow`,`cellOf` 只认这个集合里的目录),读者分两类。**放行类读窄**:顶层围栏、联调放行(放行面与放行的单元,`guard/trial.js`)、写后提醒、收尾对账、封版认领、封版命令把「为了」解析到一条需求时核本单元在不在、三查的第一查与第三查、签字作废的需求的范围、计划已搬走的完结需求的范围 —— 没核准的目录和单元里的改动算范围外。**拦人类读宽**:开工条件里的单元占用与判定代码占用、正式发布门读此刻整张落点表并上有效范围,还没核准的目录照拦;封版命令判哪些需求触及本单元同样读宽。车道判断(认流程、算档的下限)读此刻整张落点表:流程与档是锁住的五样,不是范围。核准一笔,在办的需求履历跟着刷新(发布登记按履历里的落点表推联调留痕)。重签:有核准路的需求重签只签锁住的五样,已核准的仍然算数、没核准的仍是待核准,不会被重签带进新的签字;没有核准路的需求重签,待核准的一并带进新的底。
⑦ **验收时逐条列给用户,核准一笔复盘作废**:三查结果单、复盘说明、验收区各单列一节「签字之后的过程改动」,每一笔核准写核准者(会话号前八位,标明是不是用户最近一笔签字所在的会话)、时刻、改了什么(旧到新)、新增覆盖多少个受治文件,节顶上写签字之后累计新增覆盖多少文件;还没核准的待核准清单出现在结果单与复盘说明里并让第一查红(`c1Red` 多一个键 `unapproved`,所以验收区开不出来时不会有它)。核准记录与待核准清单并入结果单编号,它的指纹(`processFactsPrint`)绑进复盘记录(`pf`,与范围指纹并列):核准一笔、或待核准的清单变了,最新一笔复盘就对不上,第一查回红、要再复盘。复盘说明多一节与第四条判法:核准过的标准与用例的改动逐条看,凡是把签字时的要求放松了的按没达标算,带红标的核准项必须逐项作答。有核准记录的需求,验收清单(亲手验的那几条)最后多一个必勾项「签字之后的过程改动我看过、认可」,没勾就是不过(一键签与复制结论都自动带上;各组的意见框与总体意见只记话,不判过不过)。完结时核准清单写进需求履历。确认区里「需求」「范围」两组各有一句导语,「需求」组里的标准与自动用例不是要用户逐条勾的明细、只当说明列出;标记引起的重签(风险标记新增、档的下限升高),横幅只写一句原因。
⑧ **老签字**:账本里那一笔没有 `lock` 一栏。留着底的只比底里有的项(`signHolds`),锁住的几样一样就仍是在办、沿用原来签的编号(复盘、结果单、签字区都绑着它),不用重签;没有留底的一律重签。老签字的底里有标准原文,但没有每条用例对着哪条标准、也没有落点表按格的行,这两样守不到。
⑨ **守不到**(照实写):办理会话就是签字会话的需求没有核准路,待核准的改动当作实质、要用户重签(主控自己写机器镜像再自己签,就是这种);换了主控窗口,核准跟着登记册走,不用重签;登记册读不出来或没登记主控时,只认最近一笔确认所在的会话,那时签字会话没了就没有核准路,要重签。机器核的是登记册里登记的主控,认不出是不是用户本人 —— 登记册与换主控由会话命令把关(列表里名叫 X大脑 的交互窗口;旧主控还活着要用户亲口说换主控),守卫写保护,经 node 直写登记册两处与镜像的,与别的账本同一条边界。读的一端信核准那一笔里记的 `mn`,与 `hs`、`win` 同一条边界(办理会话在自己的进程里冒用会话号调记账口,读的一端看不出);`void` 标记只在有人跑核准命令时才落下 —— 没人跑,待核准让验收前的三查第一查报红,不会悄悄放过;等用户重签期间别动待核准清单,动了的话标记会静默失效(标记绑的是清单);写证据只在机器镜像此刻的内容查不到时才认得出脚本、拷贝、编辑器写的,夹在两笔有证据的写中间的认不出;新增的目录有多宽只列文件数、不判;还没建出来的目录机器认不出归哪个单元;标准与用例的措辞放松了是不是把需求改松,机器判不了,靠独立复盘的必查项和用户验收时逐条看,机器只列旧到新并拦上面三道悄悄改松;指纹开关叫 `--fp`、不叫 `--print`:守卫查 node 的求值开关(`-e`、`--eval`、`-p`、`--print`)时连脚本后面的参数一起看,命令里带 `--print=<指纹>` 会被当成 node 求值当场拦下、执行那一步谁也跑不了;直接调函数测的床经不过守卫、发现不了这一类,所以另有一条床把预览打印的下一步命令原文交给守卫的命令判定、断言不被拦;守卫那道安全墙不放宽(放宽要另起一条认真审)。
**签字记录只认两条路**(ADR-116;宪法 §六.8 的签字规矩):需求账本里的签字记录 —— 签字一的 `confirm`、签字二的 `accept` 与随后的 `closed` —— 只认两条路:① 用户的原话(`says.jsonl` 里的话触发的,上面「签字只有两种形态」「签字搬进看板签字区」那一整套);② 代签命令(`harness.js --action=sign --plan=<名> --kind=验收完结 --as=代签`,实现住体系守护技能的 `core/sign-delegate.js`)经守卫自己的记账口写的那两笔 —— `accept` 带 `via:'delegate'`、签字人写「X大脑 代签」、带设置的指纹(`sfp`)与验收区证据的指纹(`ev`),`closed` 同样带 `via:'delegate'` 与签字人;其余栏与用户亲签的那两笔一样,履历里签字二那一行写「X大脑 代签」。手写进账本的一笔、写法不是这两条路的,本来就判成账本被直接改过(上面的链与镜像)。代签命令核三件事 —— 调用的会话是会话登记册里登记的主控、设置此刻允许这一类、这条计划的「验收谁签」是代签;三样都对,才走与用户亲签时同一套关口(三查全绿、独立复盘过、看板与机器镜像对得上、验收区有证据,同一段代码);代签只签签字二,**从不签签字一**,也不改代签设置;用户本人随时能签(就算定了代签,说「全选执行:验收完结 <短名>」照样算)。说话钩子一侧另有三处:① 用户说的话恰好等于固定句(会话命令送进会话的发起首句、叫醒、恢复三句,与项目经理建定时巡检用的巡检句,共四句,放在守卫目录 `guard/session-phrases.js` 一处常量里,守卫与受信命令共用)时,不记进原话账本、不认作签字,句子后面多一个字就照常记;② 用户亲口说的固定话(重建登记册、换主控、改代签设置)是另一组,照常记、按签字的认法认,而且要新鲜、一次一用(只认最近 10 分钟内说的,同一笔不能用第二次);③ **说话只认主控**:会话登记册读得出而且登记了主控之后,签字说法(`requirements.signLikeText` 认得出的:固定写法、贴回的看板结论、对话里打的「全选执行:…」、带话的签字)与用户亲口说的「重建登记册」「改代签设置」「改型号配置」三种(型号配置按行认,多行消息里有一行是它也算),只认在主控会话里说的 —— 别的会话里出现这样的话,说话钩子不记进原话账本、不认作签字,只回一句原因(写明不是登记的主控会话里说的、用户的签字只在 X大脑 窗口里说才算、新窗口还没登记就先登记主控);一键签、带话的签字、选项题答完各入口同样先过这一道(弹题的会话不是主控,答案里的签字不认、原话不记);原话账本核对(`requirements.bossPhraseHeard`)对这三种也只认主控那一笔;「会话登记册:换主控」不受此限(新窗口登记之前它是唯一的出口,会话命令另核调用者是名叫 X大脑 的交互会话);登记册读不出来、没有登记主控的仓照旧(老仓、床里的假仓、登记册两处都坏要重建的时候)。这一道只防「别的会话里出现这样的话」,防不了定时任务送进来的普通话,那一头见环1「定时任务通道」。守着③的床:`.claude/hooks/tests/main-only-says.test.js`。机制全貌与守不到见 §十五「签字机制」「代签设置、验收谁签与代签命令」。
**三查接关口**:核对命令 `x-harness-dev harness.js --action=reconcile` 出三查结果单(实施复盘 / 用例闭环 / 固化核对,
带编号 = 判定事实的指纹前四位,材料取需求对账、测试记账、版本契约三处不复刻);统一封版命令封之前要求这一版有 `> 为了:` 一行、
触及本单元的在办需求本会话零越界且自动用例闭环;签字二「验收完结 <名>」由钩子当场跑三查(不落盘;按这条需求的办理会话算、不按当场签字的会话,见下「办理会话」),就是执行者给用户看的那张且三查
全绿才记「已完结」,没通过的那几笔只记账、不改状态;签过字没完结的计划目录,直写路径的 rm / rimraf / git rm / mv / git mv 拦,
完结了的也拦、回话给出清理归档的命令(计划目录下的任何一份都删不了、挪不走,见下「清理归档」)—— 换目录、变量展开、find -exec 这类形态拦不住(命令行有无穷形态,写前拦截历来只挡常见直写),靠收尾点名兜底,
被脚本删掉的收尾点名一次(只点签过字没完结的;已完结的被脚本删掉没有人点名,见下「清理归档」的守不到 ①)。
**收尾与签字的几条约定**:收尾环的需求对账与计划目录核对提前算,无论哪条路退出都并进报文(排在检测 / 测试红项之后的话,
本会话只要有一个红项就永远跑不到);「验收完结」还要求给用户看的那张是绿的(编号用的事实含「判不了」的状态,红单绿单不同号);
第三查把范围里没有写证据的改动也算进本需求(只有明确归别的会话的才单列);签字前查模板占位没填与四个页签是否都在;
`.gitignore` 进受治名单(往里加一行能把新建的受治文件藏出改动面);签字时报范围重叠;「不过」之后必须有新的复盘才能完结;
复盘结论绑复盘者看的那张单子的范围指纹(任务说明生成时记下,复盘途中重跑核对命令换不掉);「没有用例的标准」机器判不了。
**复盘派发与受治范围的几条约定**:复盘者的第一条提示词必须逐字等于程序生成的派发表头(只核正文时,正文前面能塞进别的话),结论记说明生成时的
内容编号,派复盘者时提示词必须原样是命令印出来的那一段派发表头;scope.json 读不了与不见了同判;`git stash push -u` 带计划目录同删;
签字题选项必须是那几样;任何一层 `.gitignore` 与 `.git/info/exclude` 受治(后者进脊柱);结果单编号不含看板正文,范围外的改动里只有办理会话自己写的进编号,别的会话写的、没有写证据的、归别的在办需求范围的、不归任何版本单元的那份名单都只印在单子上(ADR-98,见下「复盘之后看板的状态列可以动」);版本契约读不了
第三查红;完结那条路与「老测试充数」分支有床守着。命令删计划只挡直写路径的形态(换目录、变量、find -exec 拦不住),靠收尾点名兜底。
**命令判定与复盘者的几条约定**:`git stash` 带未跟踪文件一律拦(不带路径的 -u 会把计划连同需求账本挪出工作区);`mv -t` 按来源判;
`claude -p / --print` 拦;受治判定大小写不敏感;列受治文件时关掉用户级全局忽略文件;复盘者派发时只能是对抗审查执行体,
收尾时别的执行体的结论标不可信;量仓出错三查按「判不了」红。按设计不改、记洞:没有写证据的改动只列不挡完结(否则任何无关文件都能卡住完结);
签字锁的是机器镜像,看板正文改字签字不作废;封版与复盘说明的会话身份来自环境变量;内容编号与结果单编号只取指纹前四位。
**直写命令与签字的几条约定**:直写路径的命令(重定向 / cp 与 mv 的落点 / tee / sed -i / dd of=)写受治文件与编辑工具走同一道需求闸(顶层围栏也是这两条路共用,见下「顶层围栏」);
删与挪按「有没有保护目标住在它下面」判上一级目录(.claude / .claude/plan / .claude/hooks / .claude/tmp 整目录挪走同样拦);unlink 与 rm 同判;
签字题必选项按动词分、动钱多一样;
第二查只认床文件本身变过;同一张结果单上的「过」盖不掉「不过」;计划恢复后再删再点名;跨会话消息不进原话记录;.stylelintrc.json 受治。
记洞不改:空壳对照的记账键不含被测代码(改它要动测试面判定、旧记录全作废)。
**两份计划触及同一单元**:核对命令的越界按并集(落在别的在办需求范围里的改动不算本需求越界、单列;收尾对账对这一类点名一次、记账,见下「写前按办理会话判」);封版前置每条需求按它自己的会话算(= 它的办理会话)、
它的会话没在本单元动过手的不拿它的用例闭环拦别人封版;它一旦动了手,它的用例没闭环照拦(共享单元不能在别人的改动没闭环时封)。同一个版本单元上已有别的需求占着时,后签的那一条开不了工、记成排队(见下「同一块排队」),所以这一段管的是已经同占的与单元不同而目录重叠的。
**命令行闭集**(黑名单枚举命令写法是开集):没有任何在办需求时命令行只放白名单(只读命令、shell 内建、git 只读子命令、
受治树里已有的脚本;重定向与写命令只准落仓外或免检目录的字面路径;仓外脚本也拦),有在办需求时只有办理会话不走白名单(ADR-98;不是任何在办需求的办理会话的照没有在办需求时那样只放白名单,见下「写前按办理会话判」;命令行里的 git 例外,办理会话那一支也只放只读子命令,见下「命令行里的 git 一律只读」);需求账本每笔带上一笔的指纹并同时进用户目录下的镜像,
链断 / 与镜像不符 / 镜像或账本不见 = 被改过 ⇒ 写前拦、签字不记、删不掉、派不了、收尾点名、拒封、第一查红;没有链也没有镜像的账本同判(不认领迁移前的旧账本,见下)。
**命令行里的 git 一律只读;提交与推送只经提交命令**(ADR-118):命令判定零件不分是不是办理会话、有没有签字,对命令行里的 git 只放只读子命令 ——
status、log、diff、show、ls-files 这一类,加列表形态的 branch、tag、stash、remote、config、worktree、reflog;`symbolic-ref` 只放读一个名字这一种
(可带 `-q`、`--short`、`--no-recurse`),带两个参数会改 HEAD、`-d` 会删引用、`-m` 也会写,都拦;commit、add、rm、mv、建与删 tag、push、pull、fetch、merge、rebase、
cherry-pick、am、stash(非列表形态)、switch、update-ref 一律拦,退回、重置这类恢复操作永远不做(死命令原则 12)。拦下的报文写明:提交与推送只经提交命令(印出命令全文,
带执行开关才做),退回、重置永远不做;没签字那一支那句「先建计划」的口径不用来回答 git。办理会话那一支里拦「git rm 删计划目录」的那句原因照旧排在这一道之前、原话不变;
`git -c alias.X=!shell`、`--config-env`、`--exec-path`、`git grep -O`、输出文件开关这些检查照常。受治树里已有的脚本照旧在任何会话里都跑得起来,
所以提交命令是真仓里写 git 的唯一一条受信的路(它的脚本文件受写保护,见「提交命令」);施工区里造副本的命令在副本里自己建版本库、提交,那不是真仓,不在此列。
**守不到**:脚本进程里直接调 git,守卫看不见(命令行只读只防手滑,与整套体系同一条边界,§十三 诚实边界⑤);用户自己的提交(`!` 命令、他自己的终端)不经工具调用,
守卫碰不到,钥匙石与代签设置这两个只归用户的文件就走这条路。守着它的床:`.claude/hooks/tests/command-git-readonly.test.js`。
**node 自己会落盘的开关是写入**:`--test-reporter-destination=` / `--cpu-prof-dir` / `--heap-prof-dir` / `--diagnostic-dir` / `--report-directory` / `--redirect-warnings` /
`--snapshot-blob` / `--trace-event-file-pattern` 的值、不带值往当前目录写生成名文件的 `--cpu-prof` 一族、环境变量 `NODE_V8_COVERAGE=<目录>`、`NODE_OPTIONS` 里写的同类开关,三处判定
(保护目标比对、直写清单、没签字免检面)都当成写 —— 不当成写的话,`node --test --test-reporter-destination=.claude/hooks/guard.js <受治脚本>` 放行并真覆盖守卫主程序,守卫退出码变 1 后全部关口失效;
与重定向 / cp / sort -o / git --output 同判(保护目标拦,其余进直写清单过需求闸;没签字只准落仓外或免检目录)。
**复盘那一笔带看板正文的指纹**(ADR-81 · ADR-98):任务说明生成时把看板正文的指纹(剥掉签字区,与结果单事实里记的同一份)记进任务说明的账本,守卫在复盘者收尾时随复盘那一笔记下;只留痕、不判 —— 复盘什么时候作废,见下「复盘之后看板的状态列可以动」。
**复盘判法与固定检查**(ADR-87):任务说明只写「要证明它错」、找到任何一条就判不过的话,题目没有边(病历:同一条需求入账复盘十五轮都不过,后几轮交付物早已达标、挑的全是守卫还能不能更严);
复盘者没有地方拿机器检查的结果,就每一轮从头重做(病历:一轮七十多分钟里,真正查改动的只有十来分钟)。所以任务说明写明:只对着签过字的「怎样算做完」逐条判达标 / 没达标,全达标就是过,标准之外的发现记「遗留」、不影响过不过;
列出上一次入账复盘之后范围里改了哪些文件(生成程序每次留底当时的清单,与账本里那一笔复盘的范围指纹对得上才用,对不上、没留下就按全部看 —— 留底被改坏只会让复盘者多看、不会少看);测试床与固定检查的结果直接写给复盘者,最多抽查三项(抽查只有两种做法:固定检查读它落在账本目录里的输出、不自己跑清单里的命令;测试床只许单跑只在临时目录里造沙箱的那种 —— 只读的复盘者直接跑命令或单跑床文件会绕开超时与关进程,单跑站点床还会重建多会话共用的产物);
预算十分钟左右、工具调用三十次以内(读这份说明本身的几次不计入,免得为省调用少读);不全盘查找、命令超时不转后台、收尾关掉自己起的进程;不运行复盘说明命令或接力命令重新生成说明(会换掉正在读的这一份)。结论行格式、复盘派出那一道、「最新一次入账复盘过了才能完结」照常(同一份任务说明结论相同的重复那一笔不算「最新一次」,见下「复盘之后看板的状态列可以动」)。任务说明把「遗留」的写法写死(ADR-93):先写「你实际核了什么」,再单独一节「遗留」紧挨着结论行 —— 标题单独一行写「遗留」,下面每条一行、以短横打头,没有就写一条「无」;最后一行仍只写结论。
**复盘说明写明车道**:任务说明在「需求」那一节之后多一节「车道」—— 这条需求的车道(流程 · 档,按此刻的落点现算,与确认区顶上那一行同一个判法 `requirements.laneOf`)、中了哪几个风险标记、照抄 §十五 车道表这条车道「复盘」那一格(运行时从仓根读本文那张表:认表头逐字是车道表那一行的那张、按「车道」一格找行、按栏名取格,`requirements.laneCell`),并注明「只是提示看哪里,过不过仍只按签过字的标准判」;车道判不了、那一格读不到(本文读不了、没有这张表或这一行、认不出流程)都照实写一句,照签过字的标准判。判法与结论行不因它变,三查不读它;任务编号随正文变,派发表头随编号变,守卫派发时核提示词逐字等于此刻现算的表头(见下「复盘进关口」)。守着它的床:`.claude/skills/x-harness-dev/tests/review-brief.test.js`。
**固定检查**:机器能查、又不适合做成常驻测试床的事(真浏览器里比像素、点一遍页面)登记在计划目录(清单 checks.json、脚本 checks/),`harness.js --action=checks` 一条命令跑完;结果按「范围里的改动清单 + 清单与脚本的内容」记账,没变不重跑(ADR-98:范围里的改动不计各版本单元的变更历史与锁清单 —— 那两类是封版自己写的,算进去每封一次版固定检查的账就过期一次、白跑一遍;哪两个文件算,问版本契约的名册(`isUnitMeta`),不另列文件名表,契约装不上就一个都不剔、照旧全算);
同一时刻最多两项,每项结束(正常结束或超时)把它起的进程连同子孙一起关掉(Windows 装进作业对象、整个作业一起终止,别的系统用进程组);三查第二查与任务说明都读它 —— 登记了而有一项没跑过、过期或没过,第二查红;没登记的计划,单子与编号都不变。
**守不到**:遗留 —— 守卫在复盘者收尾时把它从最后那段话里取出、随结论记进账本,完结时写进履历(见下「复盘进关口」与「履历多两栏」);守不到的是这几样:只认任务说明里写死的那一种写法(标题另认加粗的那一种,别的不放宽),写成别的样子认不出、记成没有,只在他收尾那一刻回给领队的话里提示一次、不拦;一轮最多记二十条,写多了的后面几条静默丢掉;遗留说得对不对、全不全机器不判;不可信的复盘带的遗留不进履历;预算靠复盘者自觉,超了没有闸;固定检查读了范围之外会变的东西(别的会话重建的产物、线上数据),指纹不知道;Windows 上起进程到装进作业对象之间的一瞬、检查主动让子进程脱离作业的,关不掉;变更历史与锁清单被手改,不让固定检查重跑(这两类文件的手改另由收尾的封版复核与版本契约拦)。
**复盘之后看板的状态列可以动**(ADR-98):复盘结论绑整份看板正文(剥掉签字区)的话,复盘派出之后勾一步、填一格固化对照表、写一条遗留,这一轮复盘就作废,
已开出的验收单也跟着换号 —— 办理会话只好在派复盘之前把看板冻住,复盘期间什么都不敢记。所以复盘结论与验收单只绑签字锁住的内容(内容编号管的那一份)、范围里的受治文件、签字之后的过程改动(核准记录与待核准清单,见上「签字只锁五样、过程由主控核准」⑦);
勾步骤、改状态栏、填固化对照表与发布表、写决策与遗留,都不让这一轮复盘作废,也不让已开出的验收单作废。标准的措辞与条数、自动用例不在签字锁住的内容里(它们是过程,改了编号不变、签字不作废),但没核准的、核准过一笔的,复盘都作废(过程指纹对不上)。
**验收单的编号**:不进编号的一共六项 —— 看板正文的指纹、步骤勾了几步、别的会话写的范围外改动、
没有写证据的范围外改动、归别的需求范围的改动(别的在办需求的,或已完结需求交付的)、第三查里「不归任何版本单元的改动」那份名单;六项照旧印在结果单上给人看,只是不进编号;重复的那一笔复盘也不进编号。
落盘的结果单分两栏放:进编号的事实放 `facts`,这六项另放 `outOfId` —— 守卫认「一条已完结的需求交付了哪些文件」时拿落盘单子的 `facts` 照编号的算法重算、对得上编号才认,两栏混放那一道就永远对不上。
照旧进编号的:签字锁住的内容、范围里的受治文件、办理会话自己的范围外改动、床与固定检查的状态、各版本单元的封版状态、每一笔算数的复盘与「不过」、签字状态、签字之后的过程改动(核准记录与待核准清单;没有过程改动的计划没有这一项)。为什么这样定:签过字的标准写的是「只有」改到签字锁住的内容与
范围里的受治文件才作废;几条需求并行办的时候,别的会话在自己范围里正常干活,不该把这一条已经开出的验收单作废掉、要用户重看重签(真仓发生过一次)。**守住的两道**:验收那一刻
守卫当场重算三查、必须全绿;用户看的那张必须是绿的。范围外的改动由谁守:办理会话自己写的,收尾对账拦、第一查红;别的会话写的,归它自己的收尾对账与它那条需求的三查;
没有写证据的,归收尾环的无主复核与部署门,其中改到某个版本单元里的,第三查照旧把那个单元列进来判(没封或封后动过就红)。**复盘者收尾两次**:三样都成立才算重复 —— 这一笔不可信(守卫照旧把同一份任务说明的第二笔记成不可信)、它的任务说明编号与前面某一笔可信结论相同、结论也与那一笔相同。重复的那一笔在结果单上照实列出、写明「重复、不计」,
不算一轮复盘、不进编号,第一查按剔掉之后的最后一笔判;结论不同的(先「过」后改口「不过」,或反过来)是改口不是重复,照旧按最后一笔判 —— 不可信、红,往不过的方向错;没记下任务说明编号的旧记录一律不算重复。
认法只住守卫需求零件一份(`requirements.duplicateReviews`),四处调它:三查的第一查与编号、「正在办」那一行的复盘次数、办得超没超这一档的轮数上限、履历的「独立复盘」与「用时与返工」
(履历里重复的那一笔照旧占「第几次」的号、写明不计,轮数里不算、另记一个数)。三查结果单另多一栏「第一查红在哪几样」(落盘结果单里的 `c1Red`;键的全集是核对零件导出的 `C1_RED`,八个键:账本被直接改过、没有可信的签字基线、会话台账读不了、
没有会话可算、步骤没勾完、本会话有范围外的改动、要(再)复盘、签字之后的过程改动还没经主控核准 —— 「要再复盘」的各种情形统一是倒数第二个键;核对命令从现成的事实派生,不新增判法;第一查绿不绿就按这一栏空不空算,只判这一遍;第一查判了一样没登记在这张表里的,
核对命令当场报错、不出单子;它不进编号),接力命令判是不是只差复盘只读它(见下「接力命令」)。
**守不到**:① 用户验收时看的看板可以与复盘者看的不同 —— 状态列,以及不在签字锁住内容里的文字(设计页签的说明这类);签字锁住的内容与范围里的文件没变,由内容编号与文件指纹担保。
② 用户看过验收单之后、点完结之前,有人用脚本(没有写证据)改了一个不归任何版本单元的范围外文件,不会要求他重看;
这种改动只由收尾环的无主复核与部署门接着,不经用户的眼睛。改到某个版本单元里的不在此列:第三查照旧把那个单元列进来判,没封或封后动过就红,完结照样记不成。
③ 别的会话在那一小段里写了范围外的受治文件同理:不让这张单子换号,归它自己那条需求管;它若动了这条需求改到的单元,第三查照旧红。
④ 「哪几笔算重复」三查只问守卫:守卫里没有那个函数(守卫与核对命令不是同一版)时一笔都不认成重复,照旧按最后一笔判,往不过的方向错,没有别的退路。
⑤ 第三查「不归任何版本单元的改动」那份名单把各单元自己的变更历史与锁清单也列了进去(名单按「哪个单元的名册都不管这个路径」认,而单元的变更历史与锁清单不在名册管的路径里),与落点表里列着它们的那一格重复显示;
名单不进编号、不影响红绿,留到下次动三查脚本时订正。
**守不到之处(按设计不改)**:账本与仓外镜像一起删掉,机器只能当成从没签过字 —— 签字与「不过」的记录随之消失、用户会被要求重签,分不出是谁删的;试过拿签字基线当物证判成「被改过」,测试夹具与账本清理也是「账本没了、基线还在」,整张守卫单元床红了十二条,代价大于洞。
**守不到之处**:需求对账的三个时刻各管一面,不是重复 —— 写前问「本会话是不是某条签过字的在办需求的办理会话」(ADR-98;归顶层四类版本单元的文件另问「是不是办着列有该单元的需求」,见下「顶层围栏」;文件在不在落点表的格里仍不归写前),
写后提醒与收尾对账才问「改的文件在不在设计范围里、是谁写的」。三道都保留,不合并。没有在办需求时(「有在办需求而本会话不是办理会话」同样处理),下面这几条路写受治文件
不经需求对账(或只经收尾那一次点名),照实写明、不补新机制:
① 笔记本编辑工具(NotebookEdit):写前不过需求闸,写后也不记写证据 —— 它的改动在收尾里算无主;没有在办需求时收尾只点名
本会话与分不清的改动,无主的不点名,所以它从头到尾不经需求对账。
② 命令行:写前那一道只在写前拦截在岗时有(没签字时只放闭集白名单;有在办需求而本会话不是办理会话的同样;被拦的提示句尾写明只做分析的事怎么办 —— 只跑仓里现成的脚本、新的怀疑留到修它的那条需求里先写测试复现 —— 并指向项目架构设计页的「怎么开一条需求」);收尾按命令时间窗把改动归到本会话才点名一次。
归属认不出的 —— 修改时间落在任何一条命令的时间窗之外(后台长跑的命令、复制时保留了修改时间、不是经本会话工具写的)——
算无主,不点名。命令行写入没有一个工具参数能直接说出落点,要补就得另起一套机制,不补。
③ 开闸时(settings 里是 _PreToolUse):写前那一道整个不在岗,编辑工具与命令行写受治文件当场都不拦;编辑工具写完仍有一句
「不在任何签过字的需求的设计范围里」,收尾仍按归属点名一次(编辑工具有写证据、命令行按时间窗),无主的同样不点名。
④ PowerShell 工具:平台另有一个能执行任意命令的 PowerShell 工具,守卫从来不处理它 —— 挂载名单里没有它(回归套件还断言名单
不许认上它),写前不判、写后不记时间窗,它写的文件到收尾算无主。这个缺口与挂载范围无关;
要不要给它加一套判定由用户定。
所以没有在办需求时能兜底的只有收尾那一次点名,而它的射程等于会话归属的射程:归属认不出的写入,需求对账看不见。
**路径归一与复盘记账的几条约定**:sed 原地写认短选项簇(-ri / -Ei)与 --in-place=;cp / mv 的 -t 形态按真实落点判;Git Bash 盘符路径与 Windows 路径归一;
挪删整个仓库根同硬保护;复盘者收尾核结果单编号、续跑不可信、同一份说明只记一笔可信、不可信不计连败(同一份说明的后一笔结论与前一笔相同的记成「重复、不计」,不把第一查打红);看板被清空同「不见了」;第三查每格必须变过(一格里的改动全归别的会话时另认一种情形,见下「落点格认办理会话签字后的写证据」);
完结后首次收尾不误拦完结前的合法改动;受治名单含 settings.local.json / .mcp.json / antd 文档基准。按设计不改、记洞:复盘结论绑什么见下「复盘之后看板的状态列可以动」,
会话身份来自环境变量,看板正文改字签字不作废,无写证据只列不挡,第二查不判改动实质。
**记洞不改**:第三查「封版之后动没动」按锁清单比,而框架锁清单的内容组不含任何测试文件(版本契约把测试目录整个跳过)——
封版之后改一张测试,第三查照绿;没被用例点名的测试,第二查也看不见;只有封版时写进变更历史的测试指纹与发布门(当场真跑)兜着。
**两次签字用需求方的话**(ADR-75):签字一(需求确认)的选项是「需求」「范围」「要你亲手验的清单」,动钱的需求多一项「动不动钱」;
签字二(实施交付)的选项就是机器镜像里 tests 为空的那几条用例(选项 = 用例号加「应该看到什么」),一条一项 —— 交付物清单不另起字段。
要亲手验的用例多于十五条时签字一就拦(签字一另按档核四个数,见下「定档与上限」;这一条照常)。**看板与机器镜像一致才让签**:签字那一刻核每条「怎样算做完」、每条用例的「拿什么作证」、
落点表每个目录在看板看得见的地方逐字出现,用例一条不多一条不少;「看得见」按标签逐个走,标签自己写明不显示的(hidden、行内的 display:none /
visibility:hidden / font-size:0 / opacity:0、没展开的 details)连同里层不算,注释、脚本、样式、模板不算。只核不生成:看板是给人读的原件。
这一核在两处:记签字一那一刻、记签字二那一刻(只在签字一核的话,签字一之后改看板照样弹题、照样记完结);
核对命令生成签字区时不核,写前那道选项题闸也不核 —— 它只比签字区的三个记号。
想在弹题之前先核一遍,手跑 `node .claude/hooks/guard/requirements.js --hash <名>`。
**签字搬进看板签字区**(ADR-78,取代 ADR-74 决策①与 ADR-75 里选项题的形态):核对命令(reconcile)每跑一次就把签字区写进看板的 `<!--签字区-->…<!--/签字区-->` 标记里(模板把这对标记放在第七个页签「签字」里;
没有标记的旧看板插在 `<body>` 之后):没签字 / 签字作废 ⇒ 需求确认区(签字区最顶上与「需求」那一组最顶上各有一行档与四个数;这份计划此刻签不了「确认」(认车道、定档没过)时不开确认区、写「确认区还没开:」加原因,见下「定档与上限」;签得了的,确认区顶上写明签了之后是当场开工还是排队、在等谁,见下「签字与开工分开」;需求 / 范围 / 要你亲手验的清单[/ 动不动钱]每组一个总勾,组里**逐条明细**各一个勾、一个意见框(「需求」组例外:组里的标准与自动用例只当说明列出,没有勾选框与意见框,只勾组名 —— 它们的措辞签字之后由主控核准,不是用户签的东西;「范围」组只列签字时加已核准的目录)——
需求组列这条需求、每条「怎样算做完」、每条自动用例,范围组列落点表的每一个目录、一个不省,清单组列每条要亲手验的在哪看怎么验;底部一条悬浮条放进度、总意见、「全选」(看了都没问题一键勾全)与「复制结论」,不用滚到底;
复制出来的结论按组写,组里没勾的条目并进那一组的意见;ADR-80);
在办且落盘那张单子三查全绿 ⇒ 验收区(验收单 + 要亲手验的每条用例各一个勾、一个意见框、在哪看怎么验,末尾带结果单编号与内容编号);有一查红 ⇒ 写明哪一查红、验收区不开;
签了字还在排队 ⇒ 一句「已签字,排队中」加在等什么(排队的签字作废了另带「要重签」,确认区重新开);完结 ⇒ 一句「已完结」;账本被改过 ⇒ 不出签字区、写明一切结论不算。勾用 `data-sign` 不用 `data-id`(数步骤的只数 data-id),默认全空。
改界面的需求,「签字」页签最上面、签字区之外另有一块「高保真」,它在核对命令生成的那一段之外 —— 核对命令写的只是签字区,不生成也不刷新它;不改界面的需求模板里那一块整块删掉。
块里直接嵌着用户点过头的那一版(一屏看完、不用点开),旁边是单独打开的链接与内容指纹(文件 SHA-256 的前 8 位),「设计」页签里同样嵌着一块。锁住这一版的是对着它的那条标准:
标准里写着这条需求自己 preview 目录里的文件名与内容指纹(只写文件名、不写仓里的完整路径:计划归档之后路径会变,需求履历里的计划路径也会被剥成占位);
标准的措辞是过程,改了文件名或指纹是待核准的改动 —— 签字不作废,由主控核准、验收时逐条列旧到新给用户;预览文件本身不进内容编号,守卫在签字那一刻也不另记高保真的指纹 ——
守不到:签了之后改了预览文件、标准没改,签字照样有效,要靠复盘时拿文件重算指纹、对着标准看出来。看板带进治理站点时这一块换成一句字,站上看不到高保真(站点规范 x-harness 条款 ARCH-B01)。
结果单的编号不含看板正文(勾步骤、改状态栏、填表都不改它,ADR-98),
刷新签字区不改编号(编号带着编号就每次重算都变)。守卫在用户说话那一刻认贴回的整段(parseBoardSign):内容编号对不上 ⇒ 签字区是旧的;结果单编号不是落盘那张 ⇒ 不是最新的那张;
两样都对才查勾没勾全、再当场重算三查比对、再看那张是不是绿的。写后认选项题答案有三种认成签字(见下「贴回经对话框」「对话框一键签」「带话的签字」);写前这一道核的是:带着答案的选项题一律拦,被认成签字题的要带地址、签字区要是最新的那一道(见下「签字题带地址」);弹题前的三查前置、分组合并、「有一项不对」都不在写前这一道里;
带执行体身份的事件不认。**贴回经对话框**(ADR-79):核对命令刷新签字区之后,执行者弹一道对话框(AskUserQuestion,题目写明看板路径与三步,
第一项固定放固定写法那一项,其余选项只放「看板打不开」「稍后再弹」这类不构成签字的话;题目正文不带看板完整路径与「签字」页签弹不出来),用户在「其他」输入位里粘签字区复制出来的那一段提交;写后守卫对答案按与说话同一份判法认 —— 答案整段等于某个选项标签的只记成他说过的话
(标签是执行者写的,否则把签字结论写成标签、用户一点就替他签了;恰好是固定写法的那一种标签除外,见下「对话框一键签」),
其余的分开看:单选题里他自己打的,与在对话里说的同等,另认一种带话的签字;以一个不是恰好固定写法的选项标签打头、后面多出一截的,整句只记成话;
多选题的、认不出属于哪一问的,只留一键签那一种认法 —— 怎样才算他自己打的、答案取哪一份,见下「带话的签字」;复制按钮把结论用「|」连成一行(单行输入位不被换行截断),parseBoardSign 换行与「|」都认;直接贴到对话里照旧认。
**签字区留底与只标改动**(ADR-85):签字一那一笔把编号盖住的那份内容(需求 / 怎样算做完 / 用例 / 落点目录 / 单元名)原样记进账本(`content`);
签字作废重签时核对命令拿当前内容逐条对底 —— 条目身份 = 组 + 标签(需求 / 标准 N / 用例 N / 落点目录),判没变 / 改了 / 新增,上次有这次没有的在组下列成「删了」;改了的那一条按句读切段、只标改动的段(`<mark>`)、下面折叠着「之前写的」;
改了橙色竖条 + 淡橙底 + 「改了」,新增绿色竖条 + 「新增」,没变的原样不变灰;顶部横幅写「改了 N 条、新增 N 条、删了 N 条,其余 N 条一字不差」,组标题写各组数字;悬浮条多一个「只看改动的」(藏掉 `data-diff="same"` 的明细,再按恢复;「全选」照旧勾全部)。
老账本(那一笔没留底)从签字那一刻钩子建的在办履历取底(履历重算出的内容编号等于那一笔的编号才用,履历剥过计划路径、剥过字的对不上),两样都没有横幅写明分不出、一条都不标;没签过字零标记;验收区(签字二)不标。
**范围组只比落点表里的目录**:留底里「落点目录」那一项是落点表目录与用例点名的测试文件的并集,而签字区的范围组只列落点表里的目录 —— 两边拿并集比的话,删一条自动用例,它那份落在某个落点目录下、没单列的测试文件会在范围组下被报成「删了」、横幅多算一条;换一个测试文件,旧的报删、新的不算新增。
所以范围组两边都只留落点表里的目录,测试文件归用例那一条管(它的正文写着「测试:…」,改了、删了在那一条上标)。
**签字作废了就不许说「一字不差」**:动不动钱是签字锁住的,不参加比对的话,只改它时签字作废、签字区却写「改了 0 条,其余一字不差」。所以范围组每一行连它归的单元一起比,
单元变了的行标「改了」、单元名标黄、折叠里写之前的;动不动钱翻转算一条改了,横幅写明、那一组带「改了」。档同理(ADR-94):重签时档变了,横幅与档那一行标「改了」。同一流程之内加或换的单元属过程、不锁签字,改它不单独引起重签;范围组仍连单元一起比,别的原因引起重签时照标。对准靠签字那一刻钩子建的在办履历 —— 它带着当时整张落点表(哪个目录归哪个单元、哪一格),重算出的编号等于那一笔签字的编号才用;
取不到就退回只凭留底判(留底里只有目录与测试文件的并集、单元名的集合)。兜底:编号变了而逐条都对不出差别(比如没有那张落点表时两个单元并成一个)⇒ 横幅写「没找到差在哪一条,请整份再看」、一条都不标。
**守不到**(只在取不到签字那一刻的落点表时):一行当时归哪个单元分不出,折叠里只能列上次签的全部单元名;一个文件既单列在落点表、又是用例点名的测试,这一次两处一起删掉时范围组不报删(用例那一条照报)。格的名字不是签字锁住的,改格名不标。
**对话框一键签**(ADR-86,给 ADR-78 / 79「选项标签一律不认」开一个口):执行者弹的签字题里固定一项「全选执行:确认 <名>」(验收题「全选执行:验收完结 <名>」;冒号是全角的,动词与名字之间有一个空格 —— 选项以「全选执行」打头而不是恰好这一种写法,题弹不出来),
写后守卫对恰好等于这一种固定写法的标签单独认(`requirements.onQuickSign`):看板签字区必须是最新的(签字区里核对命令写的内容编号 = 当前编号、那一道的头对得上,验收还核结果单编号),不是就不认并写明;认成「每组都对、没有意见」走与贴回同一份判法,
账本那一笔记 `via:'ask-all'`(履历分得出逐条勾的与一键签的);其余标签照旧只记成话(防执行者替他签那一半还在)。守不到:一键签省的是复制粘贴不是「看过看板」,用户没打开看板也能选,机器只核签字区是最新的。
**签字题带地址**(ADR-92):
题目里写明去哪看,只靠守卫提醒执行者的一句话不够,要机器核:
钩子接线的写前名单挂着选项题(AskUserQuestion),分发器有这一支,题弹出之前守卫先判,有一样不过就拦(退出码 2,这道题弹不出来、用户看不到)。
整次先看带没带答案:工具输入里答案一栏不是空的 ⇒ 拦,不分是不是签字题(答案只能由平台在用户点了之后填;报文以「环1 选项题:」打头)。再用一句便宜的判断筛一遍:整道题里「确认」「验收完结」「全选执行」
三个词一个都没有的不交签字题那一道,有任何一个的才交给需求零件(`requirements.askGateWhy`);另有一句同样便宜的判断管相对路径那一样 —— 哪一问的题目正文里都没有斜杠(正反都算)的不交 `requirements.askPathWhy`;两句都不中的才不装需求零件、直接放。先判签字题、后判相对路径(不带地址的签字题,被拦的原因照旧是缺看板的完整路径)。一次弹题有几问就逐问各自判,每一问按下面的先后走,先碰到哪一样不过就拦在哪一样;
被认成签字题而不过的,报文以「环1 签字题:」打头(封口那一支被拦时的报文同样以它打头),一次弹了两问以上的报文前加「第 N 问:」:
① 封口 —— 选项标签(空白归一之后)以「全选执行」四个字打头的,只许恰好是固定写法「全选执行:确认 <名>」或「全选执行:验收完结 <名>」(冒号是全角的,动词与名字之间有空白,名字是一段不含空白的字);
不是(后面多一个「推荐」之类的后缀、冒号写成半角、动词不对)这一问就不让弹。它排在最前,这一问认没认成签字题都生效;报文点名那个标签,说这四个字留给签字用 ——
防执行者顺手在第一项后面加个后缀,用户点了白点。
② 是不是签字题 —— 认三种写法(第三种见本条末),认不出的那一问直接放(普通选项题照旧);读计划目录出错、判不了这一问是不是签字题的,按拦处理(方向是拦不是放)。第一种:某个选项的标签(空白归一之后)整条恰好是上面那条固定写法;摆出这个写法就算签字题,名字对不对留给 ④。
第二种:这一问里执行者写的任何一段字(题目、标题栏、每个选项的标签、说明、预览,逐段空白归一)写着「确认 <名>」或「验收完结 <名>」,动词与名字之间隔着空白,
<名> 是一条没完结的计划的目录名或短名,而且名字到此为止。**名字到哪为止**(`requirements.planAtStart`,与下面「带话的签字」共用):名字里的字只有四样 —— 文字、数字、英文连字符、英文下划线;
一段字的开头逐字等于某份计划的目录名或短名,紧跟在后面的那个字是结尾、或不是这四样(空白、标点、破折号、各种符号都算到头),才算对上;同一处对上几个名字取最长的那个,
最长的那个恰好对上一份计划才算。所以动词与名字连着写的不算(「请确认签字题带地址的范围」是普通句子),名字后面紧跟文字或数字的不算,名字是已完结计划的不算(认不出、直接放);
名字后面跟破折号或符号的照认。第三种(ADR-98):与答完之后认打字的同一套写法(下面「带话的签字」里以「全选执行」开头的那一种 —— 冒号全角半角都认,这几样之间、动词与名字之间有没有空白都认);不认这一种的话,它弹题前认不出、不被核地址,用户照着打却签得成。
③ 谁弹的、签几道 —— 带执行体身份而被认成签字题的不让弹(签字题只能由领队弹;带执行体身份的普通题照放)。验收题必须是单选题(多选那一栏缺省或等于否才算单选);确认题可以多选(ADR-98)—— 每个选项各是一条固定写法「全选执行:确认 <名>」、各对得上一份没完结的计划时放,只有确认题合并、验收完结不做多选;
这一问里两种写法认出来的「动词加计划」去重之后只能剩一组,认出两个动词或两份计划不让弹(一问只签一份计划的一道;多选的确认题是例外:动词都是「确认」、每个选项各指一份不同的计划);固定写法里的名字对不上恰好一份计划的,排在数「几组」之前就按 ④ 报。
④ 认计划 —— 第一种写法里的名字照一键签的对法(去掉空白后等于目录名、短名或需求全文)对上恰好一份计划,对不上、对上不止一份不让弹;第二种写法认出来的那一刻就已经对上了恰好一份没完结的计划。
对上之后同样往下判:那份计划已经完结、账本被直接改过、机器镜像读不了,不让弹,各回各的原因。
⑤ 题目里有没有地址 —— 只看这一问的题目正文(不看标题栏与选项),先核路径、再核页签,缺一样就不让弹。一、看板的完整路径:盘符开头的那一整串(仓库根、计划目录、看板文件名拼出来的绝对路径),
正斜杠反斜杠都认,本机是 Windows、路径不分大小写所以大小写怎么写都认,但必须正好指到本仓里这份计划的看板文件 —— 这一串后面紧跟着英文字母、数字、下划线、连字符、斜杠,
或一个点再加英文字母数字的不算(那是另一个文件,接着往后找下一处),紧跟着中文、标点、空白或结尾的算;这一串前面紧挨着英文字母或数字的也不算
(那是别的字凑出来的盘符,比如 vscode:/… 这类地址里的)。二、「签字」与「页签」两个词挨着出现:谁先谁后都认,
中间只许隔引号、空白、星号这类不是文字也不是数字的字符,最多四个(「点最后一个页签「签字」」这种写法认得上)。多选的确认题:题目正文里要有每一份看板的完整路径,「签字」页签那两个词照旧要有。
⑥ 签字区是不是最新的那一道 —— 看板里读不到签字区(没有,或开头与结尾标记不成对)不让弹,并写明怎么修(标记要成对,缺了先补一对空的,再跑带计划名的核对命令)。读得到,再比现成的三个记号:
一、签字区里记着的内容编号等于这份计划此刻的内容编号;二、签字区现在开着的那一道(确认,或验收完结)就是这一问要签的那一道(那一道的头对得上),签字区在而没有开着的一道
(里面没有编号,比如三查还红、验收区还没开)也按这一样拦,报文带着签字区里写着的那句话,不说成「去刷新」;三、验收题另比,签字区里记着的结果单编号等于账本目录里落盘的最新一张结果单的编号。
这三个记号就是一键签在用户点了之后核的那三个,这里提前到弹题之前先比一遍。**这一步不重算三查**(重算要读几千个文件、好几秒),用户点下去那一刻的重算照旧。多选的确认题逐份比这三个记号,每一份的签字区都要是最新的那一道。
**被拦时回什么**:认成签字题之后被拦的每一种(③ 到 ⑥),守卫回给执行者的话固定带三样,句式是
「这一问被认成了签字题 —— 〈哪一段〉「〈原文〉」。这不是签字题的话,把这一处改个写法(…)。是签字题的话,这一次不过的是「…」…」:
把这一问认成签字题的那一处(哪一段、原文是什么);不是签字题该怎么改;这一次不过的是哪一样和怎么改 —— 缺路径的,报文以该写的那一整串看板绝对路径结尾;
缺页签的,以「可以照抄这一句:打开 〈路径〉 ,点「签字」页签」结尾;签字区不对的,写明是哪个记号、此刻是什么状态。普通的选项题撞上了,改一个写法就过(比如别让动词与名字隔着空白连着出现)。
守卫提醒执行者去弹签字题的那三句(签字作废时两句、没有在办需求时一句)说准了:题目正文写上看板的完整路径与「签字」页签,缺了这道题弹不出来;
题目里写明「请点第一项,或照第一项的字打,后面可以加话;别的说法不算签字」。
**带话的签字**(ADR-92,在「对话框一键签」上多认一种他自己打的写法:用户在验收题的「其他」里打了固定句、后面顺带说事;以「全部执行」开头的不认,见下「守不到」④):
写后认答案走 `requirements.onAskAnswers`。先定答案取哪一份:平台回的结果里答案一栏不是空的,只认它,工具输入里的答案一栏整个不看(多出来的键不看);平台没回答案才退回工具输入里的。再按答案属于哪一问分开看。
**怎样才算他自己打的**,三样都成立才算:一、答案的键逐字等于这次弹的恰好一问的题目,而且那一问是单选(多选那一栏缺省或等于否);二、答案不等于这次弹的任何一个选项标签;
三、答案不以任何一个不是恰好固定写法的选项标签打头(写后这一处的「恰好固定写法」指:匹配固定写法、而且名字对上恰好一份计划)。第一样不成立,照下面防替签的 ③ 办;第二样不成立,照 ① 办;
第三样不成立 —— 答案以这样一个标签打头、后面多出一截 —— 整句只记成话,哪一种签字都不认(贴回的整段、「确认 <名>」、带话的签字都不认);只有这句长得像签字时
(以「全选执行」开头、是贴回的整段结论、是固定句)守卫才回一句,说明它以选项标签打头、不算他自己打的、没有记签字,别的不回。
算他自己打的那一句,与在对话里说的同等(贴回的整段、「确认 <名>」照认),另认一种(`requirements.onTypedSign`):空白归一之后以「全选执行」、冒号、「确认」或「验收完结」开头
(冒号全角半角都认;这几样之间、动词与名字之间有没有空白都认),接着是一条计划的目录名或短名、而且名字到此为止(与上面「名字到哪为止」同一个判法;名字从现有计划的名字里对,
对上的取最长的那一个、恰好对上一份才算)⇒ 照认签字,与点固定选项的一键签同一份判法:看板签字区必须是最新的那一道,验收照旧当场重算三查;签字区不是最新的、或开着的不是这一道,不记签字并写明。
名字拿现有计划的名字去对开头、不靠放宽一键签那条写法 —— 名字后面直接是逗号、没有空格时,放宽之后后面的话会被吞进名字,对不上任何计划。
名字后面的话去掉打头的标点与空白之后记成他的意见(可以为空);后面的话不管说的是什么(哪怕是「但第三条不对」)都照认 —— 固定那句是他自己打的,就是他的意思,机器分不出一句话是不是反对;
真不同意就别打固定那句,照旧在看板签字区里不勾那一条、写一句、贴回,那才是「不过」。
记账:整句照旧进原话账本;签字那一笔记的原话就是这整句,另有一栏 `note` 记意见,来路记 `via:'ask-typed'`(一键签仍是 `via:'ask-all'`,履历分得出哪一次是点的、哪一次是打的);
守卫回给执行者的话末尾带一句「他在固定句后面还说了:『…』—— 这是他的意见,当场回应他,别当没看见。」
**防执行者替他签的那一半不松**(五条):① 答案整段等于某个选项标签的,照旧只认恰好是固定写法的那一种 —— 执行者把「固定句加一段话」写成标签、用户点了它,不认签字。
② 「怎样才算他自己打的」三样有一样不成立,带话的签字不认;其中以一个不是恰好固定写法的标签打头、后面多出一截的,整句只记成话,哪一种签字都不认。
③ 多选题的答案、或认不出属于哪一问的答案,只留「整段恰好等于固定写法那个选项」一种认法,其余(以固定句开头的、贴回的整段看板结论、「确认 <名>」)一律只记成话;只有这句长得像签字时
(以「全选执行」开头、是贴回的整段结论、是固定句)守卫才回一句,说明为什么没记签字、叫执行者用单选题重弹,别的不回 —— 平台把多选的几项用逗号加空格拼成一句,分不出哪段是他打的;
他自己的话里也会有逗号,按逗号拆不准,拆错了就是执行者替他签的口子。多选的确认题另认一样(ADR-98):答案里每一项恰好等于这次弹的一个固定写法选项的,各记一笔;夹着他自己打的话的那一项不认 —— 多选题里没有带话的签字。
④ 带执行体身份而被认成签字题的,写前不让弹;带执行体身份的答案,写后不记、不认(下面「组队与执行体」③ 里「执行体弹签字题写前拦」那半句就是这一条)。
⑤ 任何选项题带着预先填好的答案弹出,写前一律拦;平台回了答案时,写后只认平台回的那一份,工具输入里多出来的键不看。
**守不到**(六样,照实写,不许读成「签字题一定写得清楚」):
① 「那里列着什么」机器不核:题目正文里有指到这份看板的路径、有「签字」页签这几个字就放,写得清不清楚靠执行者 —— 机器判不了一段话写得清不清楚,硬核只会逼执行者堆关键词。
② 写前拦截摘下(开闸)期间这道闸不在岗:不带地址的、多选的、带答案的签字题都弹得出来;用户答完之后的认定照常。开闸时预先填的答案,只有平台没回答案的时候才可能被当成答案。
③ 签字区新鲜度只比现成的编号:弹题之前不重算三查,也不核看板正文与机器镜像一不一致,只比上面那三个记号(那一核在记签字一、记签字二那一刻做;弹题之前这道闸与核对命令生成签字区时都不核,
见上「看板与机器镜像一致才让签」);刷新之后别的会话又改了东西,用户点下去那一刻重算仍可能对不上,那时照旧不记签字、告诉执行者刷新重弹。
④ 「全部执行」这类不以固定句开头的话照旧不认:它没写是哪条需求、哪一道签字,认它等于机器替他猜,说法也列不完;补救是每道签字题的题目里写明
「请点第一项,或照第一项的字打,后面可以加话;别的说法不算签字」(规矩在两份工作流说明里,题目里有没有这一句机器不核)。
⑤ 认不出的题不核地址:两类 —— 不提固定句的(执行者弹一道既不摆固定写法、也不提固定句的题,请用户把看板结论贴进「其他」);提了固定句、但写成机器认不出的样子的
(名字后面紧跟别的字、名字加了引号;以「全选执行」开头、动词与名字连着写的那一种弹题前也认成签字题,弹题前与答完之后同一套文法,ADR-98)。这两类都不核看板地址,只过相对路径那一样(每道题不分认没认成签字题,题目正文里写了不带盘符的仓内相对路径就拦)。
靠工作流说明里「签字题第一项固定放固定写法」的规矩。
⑥ 路径只核指到这份计划的看板文件、打不打得开不核。
另两样:钩子接线文件不归任何版本单元(§十三 诚实边界 ③),写前名单哪天被改回去,只有守卫主自测里核名单的那一条会红,没有别的东西逼着重跑它;
直接在对话里(不经对话框)打「全选执行:……」不认 —— 对话里照旧是贴回看板结论或打「确认 <名>」。不认的时候当场回一句原因(见下「像签字却没记上,一律说原因」)。
**一题签几条、每道题都核地址**(ADR-98,给上面「签字题带地址」③「必须单选、一问只签一份计划的一道」开一个口):三样。① **确认题可以多选**:
多选只放开一种写法,认不出的一律照旧按「不是单选」拦(`requirements.askGateOne`):多选那一栏恰好是 true;每个选项的标签各是一条固定写法「全选执行:确认 <名>」、各对得上恰好一份没完结的计划,别的选项不放
(他不想签哪一条就不勾;有一个选项不是这种写法就拦,报文点名是哪一项);至少是两份不同的计划;题里提到的每一份计划都要有它自己那一项。单条签字题弹题前核的那几样对每一份各核各的(`requirements.askPlanWhy`):
认计划、题目正文里这一份看板的完整路径与「签字」页签、签字区是最新的那一道,哪一份不过,回话点名是哪一份。弹题之前另有一道预判:
每一份此刻签得了(认车道、定档当场现算,与签字那一刻同一个函数 `signHoldWhy`;有一份签不了就拦,带着它的原因)。同一个版本单元上的几份可以放进同一道题:先记的那一份开得了工就当场开工,后面的记成排队,各记各的,用户不会白勾一条。
弹出之后用户点一次,答完那一半在 `requirements.onAskAnswers`:认出这一问是多选的确认题(与弹出之前同一种写法),就按平台拼答案的分隔(逗号加空格;值是数组时就是各个元素)拆开,恰好等于这一问某个选项标签的那几段各走一次一键签 ——
各记一笔、各核各的档与上限、各判各的开不开得了工、各认各的办理会话、各建各的履历,哪一份签不上只它签不上(一键签每次重读全部计划的状态,前一份刚开了工占了单元,后一份判开工条件时看得见,记成排队);同一份计划摆了两项、两项都勾了只签一次;
哪个标签都不等于的那几段是他另打的字,只记成他说过的话、交执行者当场回应(像签字的多回一句:没有记签字,要签就勾那一项或用单选题重弹)。回话里每一项先点名是哪一项、再接它的结果,末尾合计一句签上几项、没签上几项。
只有确认题合并;验收完结不做多选(验收要当场重算三查、逐条亲手验),照旧一问一道、单选。
② **每道选项题都核地址**(`requirements.askPathWhy`):题目正文里出现不带盘符的仓内相对路径就拦下、要求写成完整路径,不分是不是签字题、谁弹的(执行体弹的题同样核)——
普通题里一句「去某某目录看」用户同样找不到地方。「仓内相对路径」只有一种认法,三样都成立才算、认不出的一律不拦:一、题目正文里出现仓库根下面第一层真实存在的目录的名字,后面紧跟一个斜杠(正反都算,Windows 上名字不分大小写;名字前面可以带若干个「./」「../」);
二、这一处往前紧挨着的那个字不是英文字母、数字、下划线、连字符、点、波浪号、冒号、斜杠、反斜杠(是的话它只是一条更长的路径或网址的中间一截 —— 盘符开头的完整路径就这样自然放行),紧挨在它前面那一串英文字符里出现过「://」的(网址参数里带的路径)也不算;
三、斜杠后面那一段对得上那个目录里真实存在的一项的名字,而且名字到此为止(「x-client/x-technician 两端」「和/或」这类普通的斜杠用法对不上,不算)。只看题目正文,标题栏、选项的标签、说明、预览不看。
报文以「环1 选项题:」打头,点名那一处原文并给出该写成的完整路径;读不了仓库根、判不了的按拦处理。③ **弹题前认签字题的文法与答完之后认打字的文法是一套**(`requirements.typedSignStarts`,与带话的签字共用同一条正则,只去掉「必须在段首」那一个记号):
某一段字里写着「全选执行」、冒号、动词、名字,这几样之间有没有空白都认 —— 两边文法不一的话,一道没被核过地址的题能收到一笔真签字;认成签字题就核看板完整路径。
前面没有「全选执行」的普通句子(「请确认签字题带地址的范围」)照旧不算。
**防替签的那一半不松**:多选题里能记成签字的只有他勾到的固定写法那几项;固定写法的名字里没有空白,标签里不会有平台拼答案用的那个分隔,两个标签拼不出第三样东西,拼出来的整句也不拿去认;他在多选题里打的字照旧不认签字
(带话的签字、贴回的看板结论、三句固定的话都不认);带执行体身份的照旧不让弹、不认。不是这一种写法的多选题,答案照旧只记成话。
**守不到**:① 一题签省的是点的次数,不是看的次数 —— 每份看板用户都该打开看过,机器只核每份的签字区是最新的那一道;② 同一个版本单元上的几条一题签时,先记的那一条先开工、后面的排队 —— 先后按选项的次序,机器不核该谁先(先后归项目经理排、主控拍板:要定先后就按次序摆选项,或一份一份签);
③ 相对路径那一样只认得出从仓库根下面第一层数起、指着真实存在的东西的写法:不是从第一层数起的(只写计划目录下那一截、只写一个文件名)、
只写到第一层目录为止的、指着还不存在的东西的、换一种说法指地方的(「看板里」「上一条说的那个文件」)它都不管;④ 「此刻签得了」只在多选时弹题之前当场现算,单选的签字题照旧只比签字区里现成的记号;
弹出之后情况变了的,靠点下去那一刻各核各的兜;⑤ 多选题「其他」里他打的字与勾的选项被平台拼成一句,守卫按最保守的拆法认:拆开之后恰好等于某个选项固定写法的那几段才算签,其余拼回一句只记成话 —— 他打的字里有一段逐字就是某个选项的固定写法时,那一段按勾了那一项算;
⑥ 开闸期间这几道都不在岗(同「签字题带地址」守不到 ②):不过预判的多选题也弹得出来,靠答完之后各核各的。
**像签字却没记上,一律说原因**:用户的话或选项,守卫认签字那一套判法认得出是签字的样子 —— 以「全选执行」打头、贴回的看板结论、固定的几句话,或任何位置出现「全选执行、冒号、动词」(`requirements.signLikeText`)—— 却没有记上的,选项与说话两条路都当场回一句为什么,以「【签字】」打头,几句原话只住需求零件一处(`requirements.SIGN_SAYS`):执行体弹的题(签字只认领队弹的题,这一次没记签字、原话也不记,把要签的事交回领队重弹);说话的会话不是登记的主控(登记了主控之后,签字说法只认主控窗口里说的,写明用户的签字只在 X大脑 窗口里说才算);两份答案都空(平台回的结果与工具输入里答案一栏都没有);认签字途中报错(带报错的第一行);选了不是固定写法的选项(只记成他说过的话);在对话里直接打出「全选执行:…」(在对话里打不算签字,要签就点对话框里那一项或在它的「其他」里照打),或在「其他」里打了而固定句不在最前面;验收那一支重算没赶上时限(见下)。
**验收那一支的重算放进子进程、有时限**:签「验收完结」那一刻当场重算三查,改由需求零件自己的命令行(`--sheet`)在子进程里算;时限 = 说话钩子的起点(守卫进程启动那一刻)加三十秒、减去六秒余量、减去已经用掉的(`requirements.setHookDeadline`),一点都不剩就不起子进程;子进程只算,不写需求账本、需求履历与受治文件(起 git 时设 GIT_OPTIONAL_LOCKS=0,也不认领仓外镜像);账本只由钩子进程拿到结果之后、在时限之内写。到点被掐或起不了,就一笔不记、回「机器忙,过一会儿再点」并写明等了几秒(起不了的写钩子剩下的时间不够起它),过后也不补写;子进程出错(退出码不是 0、没有结果)照旧按三查算不出那一支记一笔判不了、不记完结。只给床用的两个环境变量:X_GUARD_HOOK_MS(把钩子时限改小,不比三十秒小的不认)、X_REQ_SHEET_ONLY(子进程不认领仓外镜像),都只会让守卫更早放弃或少写一次,放不出任何东西。
**收尾补说一次**:守卫当场把原因说出去了(用户说话那一刻,或领队弹的题答案像签字),就在会话台账记一笔「回话已出」(`sg`,记着这一次钩子从起到止的两个时刻)。收尾时(`requirements.unrecordedSigns`,只读原话账本、各计划账本与这一轮已读进来的会话台账):本会话往前 24 小时之内像签字的话,没有被哪一笔「回话已出」盖住(多半是钩子在时限里被掐断、一句都没回出来),需求账本里也没有本会话在它之后 35 秒之内的确认、验收、不过或完结那一笔(与原话同一次钩子写的:钩子时限三十秒加五秒余量),就在收尾附注里补说一次,说要签就刷新签字区、重新弹题让他再点;附注真说出去的那一刻才记「已补说」(`ss`,记着补说了哪几句的时刻),之后不再说。去重只认「回话已出」与「已补说」两样,不从本会话上一次收尾(`sr`)算起:继续拦的那一轮先记 `sr`、再从不带附注的出口退出,照 `sr` 算那几句就被越过去、从此没人说 —— 所以继续拦那一轮不说也不记,下一轮带附注的出口照说。这里不是闸,判法出错只在附注里说一声。
**守不到**:① 执行体弹的签字题,守卫回的原因只进那位执行体自己,领队看不到、要靠它转述;② 判法认不出是签字样子的话照旧只记成话、不回原因;③ 三查要整读全部台账,台账越长重算越慢,机器很忙时会一直回「过一会儿再点」;④ 那句原因回给当场的会话,用户看不看得到取决于执行者转述;⑤ 收尾补说只往前看 24 小时,隔得更久才收尾的不再补说;35 秒之内本会话又记上了别的签字,前一句没记上的就被盖掉、不补说(那时已经签上了);「回话已出」记不上的那一句收尾时可能多补说一次,「已补说」记不上的下一轮会再说一次。守着它的床:`.claude/hooks/tests/requirements.test.js`、`.claude/hooks/tests/requirements-signing.test.js`、`.claude/hooks/tests/stop-ring.test.js`(收尾补说)、`.claude/hooks/tests/verify-harness.test.js`。
**守不到之处**:签字区是派生块、看板是免检面,用户把签字区里的勾改成「对」再复制与真点一下无异 —— 签字本来就是他的意志,机器只核他贴回的是不是对着当前内容与当前单子;
签字区的勾在浏览器里不保存,刷新页面要重新勾(执行者刷新签字区时也让他重新勾,就是这个意思)。
**记洞不改**:用户在对话框里粘回结论时若自己多打一行,而那一行恰好长成「某某:对」「某某:不对」或以「意见:」开头,
parseBoardSign 会把它当成一项或总意见吞进去、签字照记(多出的项不在要求的三样里,不改变判定),只有长得不像这两种形态的行才整段不当签字;用户手打成这个形态的概率很低。
**验收单**:结果单末尾一节,上半张逐条需求(标准尾部写「(对着需求 N)」、用例写 std)列出对着哪几条标准、自动用例过没过、要亲手验的是清单第几项,
机器镜像没写配对时如实写「列不出来」;下半张就是要亲手验的清单;验收单进结果单编号。**范围与基线**:收尾与三查取范围时,在办的需求认此刻的范围,
签字作废的只认本会话办理的、只按签字时的目录加已核准的目录(作废之后改宽的、没核准的不算);收尾对账里在办的也只认本会话办理的(ADR-98),本会话写进别的会话在办范围里的改动点名一次、记账(三查照旧把落在别的在办需求范围里的单列一栏);越界只记进本会话办理的那份账本或没签字那份;
开工那一刻(当场开工的就是签字那一笔)带基线指纹,开了工而基线没了的拒绝重记;只在仓外镜像里有的账本只点名、不拷回(拷回等于不经用户多一次签字)。
没签字时命令白名单里「受治树里已有的脚本」收紧成受治且文件存在;node 的预加载开关(-r / --import / --loader / --env-file,含「=」粘连写法)的值与主脚本同判
(堵的口子:node -r ../evil.js 受治脚本 ⇒ 仓外脚本先跑、真写进受治目录);-v / --check 只认写在主脚本之前的,
install / ln / rsync 的落点与 cp 同判(保护目标比对 + 进直写清单),免检面里的脊柱(账本目录、射程缓存)不免检(堵的口子:node ../evil.js -v 放行且真写入;
install <伪造账本> .claude/tmp/requirements/x.jsonl 整条放行);只读名单里有写旁路的几个命令(sort -o / --output=、uniq 与 xxd 的输出文件、mktemp 的落点、tree -o、history -w)
的落点按同一套免检面判,起别的程序的开关(rg --pre、sort --compress-program)一律拦(堵的口子:sort -o .claude/hooks/guard.js /dev/null 没签字时整条放行、当场把守卫清空);
trap 带命令串与 eval 同类、不看签字一律拦(退出时才跑,守卫看不见里面的发布与重定向),awk 的 `| "命令"` 与 `"命令" | getline` 与 system( ) 同判,没签字时命令里带 `$( )`、反引号、`<( )` 一律拦
(堵的口子:trap 'tcb fn deploy x' EXIT、cat "$(node /tmp/evil.js)" 没签字时整条放行);env 的 -S / --split-string(含长选项缩写与短选项簇)把整串命令装进一个参数、
由 env 自己切开执行,不分签没签字一律拦 —— 不复刻 env 的切法,剥壳给词表打标记、判段据它拦(堵的口子:env -S'tcb fn deploy x' 被剥成空词表放行,nohup / timeout / exec 包着照样);
没签字时命令词连同被剥掉的包裹词写成路径的一律拦(白名单里的命令写裸名字、受治脚本写 node <脚本>),命令行上改 PATH 这类决定「跑的是哪个程序」的变量(裸前缀、env 前缀、export / declare /
typeset / readonly / local / read / printf -v)与 hash -p / -d 改查找表同拦(堵的口子:./ls、计划目录里的 ls、/tmp/evil/cat、PATH=/tmp/evil ls 全放 —— 白名单只按命令词最后一段判,
计划目录与仓外谁都能写,先写一个叫 ls 的脚本再按路径跑它整条链不用签字);没签字时命令里换了目录(cd 到仓根之外、cd 不带目标、pushd / popd)或钩子说当前目录不在仓根,
node / python 相对路径的脚本按「解析不出是哪一份」拦、绝对路径照常判(堵的口子:cd 计划目录 && node 受治相对路径放行,实跑的是计划目录里可随意写的同名文件;
守卫把钩子输入的 cwd 交给命令判定);分词把 `( ) { }` 与 `;` 一样切段,函数体与 case 分支体里的每条命令独立受判(`${VAR}` 与 find 的 `{}` 并进当前词),没签字时定义 shell 函数本身也拦,
git 全局选项 -c 只放显示类小名单、--config-env 与 --exec-path= 同拦,靠环境变量起程序的 GIT_* 并进「决定跑哪个程序」的变量名单(堵的口子:name() { cp … 保护目标; }; name、
case 分支体里的 cp 整段按第一个词放行,连保护目标比对都没看见;git -c diff.external=… diff 真执行了外部程序);git 的输出文件开关(log / diff / show 的 --output、
format-patch 与 archive 的 -o、bundle create 的文件)当成写:保护目标拦、有签字进直写清单、没签字按免检面判(堵的口子:git log -1 --format=… --output=<受治文件>
没签字时放行、内容任意、文件真被覆盖);换了目录(命令里的 cd / pushd / popd、env -C、钩子说当前目录不在仓根)之后相对路径的落点一律拦、不分签没签字,绝对路径照常判
(堵的口子:cd 计划目录 && cp 仓外文件 ../../hooks/guard.js、rm -rf ../tmp/ledger 两种状态都放行 —— 落点按仓根解析、开头的 .. 被丢掉);
git grep -O、LESSOPEN / LESSCLOSE 起程序与 TMPDIR 定落点也在名单里;2>&1 / >&2 是描述符复制,不进直写清单、不当成相对落点(不然 cd 子目录 && 只读命令 2>&1 会被误拦)。
**迁移前的旧账本不认领**:没有链也没有镜像的账本一律判成被改过 ——
要是第一次被看见就抄进镜像,「去链、追加没链的已完结、删镜像」与「凭空放一份没链的 confirm」都长得像旧账本、会被认领成合法签字;
守卫给没有镜像的账本第一次记账时,仓内已有的内容没有链就不抄进镜像(镜像只从这一笔起头,与仓内对不上照旧判成被改过)。
**记洞不改**:看板核对按子串找、只核机器镜像到看板一个方向,靠样式表类名藏的判不了;
写前拦截停着时带答案弹的选项题拦不住(在真实会话里实测过一次:平台遇到预填答案照常弹题、返回的是用户真点的,不认预填;只测了一个版本、
一种交互方式。带答案的选项题写前一律拦,不分是不是签字题;写后只认平台回的那一份答案,预填的只有平台没回答案时才可能被当成答案;
开闸期间写前这一关不在岗);往账本追加一笔是「读末行、再追加」两步、没有跨进程排队,两个钩子正好同时落笔会让第二笔的链对不上、整本账判成被改过
(方向是全关不是放行,真撞上要人手改回经守卫记的那份;没有复现过,留给下一条需求加文件锁);「计划连同账本一起没了」要不要点名看的那份小账(`_vanished.jsonl`)不带链、不进镜像、
不在完整性核对里(它只管这一种情形的提醒,签字、写前拦截、三查都不看它);结果单「归别的需求范围」一栏的「本会话在它完结之前写过」判的是曾写过且时刻早于完结、
不看此刻内容是谁写的,只是文案、越界判定不受影响(两处都留给下一条需求)。
**组队与执行体**(ADR-77,零件 `guard/team.js`;同一个零件另管两件,见下「派发闸」「写域点名」(ADR-102)):依据是两次探针 —— 队友与领队同一个会话号,它的工具事件照常过项目钩子并带执行体编号与名字,
钩子退出码 2 对它的写前与「执行体停下」都管用。所以归属照会话号算,队友的改动天然算本会话;另做五件:① 写证据与命令记录带执行体标记,
领队派队友那一下记「名字 → 定义」,结果单列各执行体各写了几个、两个执行体(按编号分)都写过的文件点名(这一栏出现才进结果单编号);② **停下来那道关**(SubagentStop):
执行体用编辑工具写过、此刻内容还是它写的那些文件(取最新写的一批)增量检测有红项 ⇒ 不让停、把红项告诉它;同一个状态(文件键、内容指纹、判据指纹)
只拦一次、一次停不下来最多连着拦若干次(真停下过之后重新数),查过干净的状态不重查,检测没跑完、超时或拦够了放行都记一笔;只查检测,测试留在领队的收尾环;③ 带执行体身份的
「说话」与选项题不认签字、不记成用户原话,执行体弹签字题写前拦,包着队友标签的话同样不记;④ 另一个执行体刚写过、之后还没放手的文件,
这个执行体再写,写前拦(官方写明两个队友改同一个文件会互相覆盖);领队接手不归这一关。「放手」= 写这一笔的那一位之后自己停下过(闲下来也算),
或被领队按名字停掉(平台不给被停的队友发「停下」事件,领队停队友那一下由写后钩子按名字补记一笔);⑤ 还有队友活着(平台在收尾输入里列着)时,领队这一轮的检测与测试
只推迟「此刻内容是执行体写的、写它的那一位还没放手」的文件、附注点名是谁的;推迟的是哪几个文件(连同是谁写的)只在变化时记一笔,上一笔里有、这一轮进了检查而且还没记过干净的
⇒ 这一轮不算「被拦之后接着的那一次」、按新的一轮全拦并点名是谁写的(每放出来一批只多拦这一次);这一轮有文件新被推迟时,红数变少不算「红项在减少」;
需求对账的越界点名不受影响。带名字派复盘者写前拦(带名字的是队友,类型填的是名字,结论会记成不可信)。已完结需求的范围:
计划目录没了、账本还在的也认(完结后计划搬进归档,计划目录下没有它;只从还在的计划目录取的话,下一次收尾会把它范围里完结前的合法改动当越界拦一次),范围取最后一次签字记下的目录。**记洞不改**:只对单窗口方式成立;
队友自己崩了或被领队用任务编号停掉时没有「放手」那一笔(十分钟窗口与「队友全部停掉后的那一轮」兜);执行体用命令行写的这几关看不见;
写域机器不拦(收尾环点名越出写域的那一笔,只点名,见下「写域点名」;结果单照旧只列领队与各执行体名下各几个文件、以及共写的文件名,复盘者对着执行体定义看);结果单「谁写的」一栏只记此刻内容还对得上写证据的文件 —— 执行体写过的文件后来被删掉或被领队重写,
整栏就没了,停下来那道关那一行也只写拦过几次、不点名是哪个执行体写了哪个文件,复盘者据以核写域的依据随之消失(
写证据与命令记录都还在台账里、事后查得到;补法留给下一条需求:那一行带上执行体名字与文件数)。
**派发闸**(ADR-102,零件 `guard/team.js` 的 `dispatchWhy`(两关:类型与名册在 `typeWhy`,型号与推理档在 `modelWhy`)与 `rosterOf`):
不设这道闸,名册外的类型、平台内置的通用执行体照样派得出去,名册上该有人干的活就由它们顶着。
它在写前派执行体那一下判,排在复盘派出那一道(见下「复盘进关口」)之后,报文以「环1 派发:」打头。**第一样只看派出去的类型**(去掉首尾空白;第二样判型号与推理档,见下「派发的型号与推理档」):带名字派的队友、不带名字派的子代理、执行体自己再派执行体,同一个判法。
① 类型是平台自带的两个工具型 claude-code-guide、statusline-setup ⇒ 放 —— 在读名册之前就放,名册读不到时它们照放;
② 类型是平台内置的通用执行体 Explore、Plan、general-purpose、claude、fork(不分大小写)⇒ 拦,报文写明这是平台内置的名字 —— 这一判排在名册判断之前、判的时候不看名册(ADR-103),
只看守卫里写死的这张内置名单:名册里有同名的一行、执行体目录下也有同名的定义文件,照样拦;名册读不到时报的仍是平台内置这一句,第二行写明名册此刻读不到、先把它恢复
(名册只拿来写报文里「换成谁」那一句)。要是靠下面 ④ 拦它们(「它们本来就不在名册里」),
拦得住只因为名册里恰好没有;名册里加一行同名的、目录里放一份同名文件,③ 就会把它放出去。派发闸要挡的正是平台内置的通用执行体,这件事不该靠名册里恰好没有;
③ 在名册里、而且执行体目录下有同名的定义文件 ⇒ 放;④ 其余一律拦:不写类型(平台派出去的是内置的通用子代理)、名册外的名字;
⑤ 名册读不到 ⇒ 拦,报文写明读不到的是什么(设计页不在、读不了、页里没有名册表、表里一行都没有);⑥ 名册里有这一行而定义文件不在 ⇒ 拦(派出去的不会是这位执行体)。
**名册怎么读**:就是 agent 架构设计页里那张名册表,守卫自己读、不调检测引擎,读法与 x-agent 判据的名册闸同一口径(带名册标记的表、行上的执行体标记;注释掉的行不算;
名字只认小写字母、数字与连字符,写了别的字符的那一行按没登记算)。**被拦时回两行**:第一行是原因、点名拿到的类型;第二行是怎么办 —— 换成名册里的谁(把名册里的名字列出来;名册里写着平台内置名字的那一行不列,它派不出去)、
名册表在哪、查资料找代码这类只读的活派调研员、平台自带的只放哪两个。**这是闸**:组队零件经守卫的装载口装,装不上走启动壳、退出码 2;判的时候出错不包起来,走守卫主文件末尾的总兜底,
同样退出码 2 —— 判不了不当成放行。领队派执行体这一下因此也要装组队零件(见本节开头「零件用到才装」);拦下的那一次照拦截出口记一笔(派执行体取类型)。
**后果**:全仓所有会话都派不出平台内置的通用执行体,查资料、找代码的活由调研员接,别的活由名册里对应的那一位接。
**守不到**:① 只在写前、工具是派执行体时判:写前拦截摘下期间不在岗,没有写后补判;② 只核类型在不在名册、定义文件在不在 —— 派得对不对(该派谁、提示词写得对不对)不核,
平台实际装的是不是这份定义(平台按定义文件里写的名字认)也不核;③ 定义文件只认直接住在执行体目录下的,不递归子目录(x-agent 的名册闸递归,两边在这一点上不一样);
④ 不经派执行体那个工具起的执行体不过闸 —— 平台内部自己起的子代理;经工作流工具起的也不过,这一条是推断,没核;⑤ 主控的定义也在名册里,把它当执行体派出去闸照放(它照定义回一句不接派工就停);
⑥ 名册表与执行体文件对不对得上归 x-agent 的名册闸,守卫只读不核;⑦ 内置名单是守卫里写死的一张表:平台以后新加的内置类型要人来加进去,
加进去之前它只靠名册里没有它被 ④ 拦下 —— 名册里同时有了同名的一行与同名的定义文件就会被放出去,与上面 ② 说的是同一个口子;名册里有没有与内置同名的行,守卫也不核,只在派的那一下拦。
守着它的床:`.claude/hooks/tests/team-gates.test.js`(派发闸那一组的 T8h:名册里加 general-purpose、explore 两行并放同名定义文件,经守卫入口照样拦、报文写明是平台内置;
床里自带探针式改坏对照,把内置名单那一判撤掉这一条就红。空壳对照下这张床起不来(空壳守卫旁边没有技能目录),它咬不咬得住靠的是这条改坏对照);
守卫回归套件里派 Explore 的那一条(RV7)期望拦,认的是「是平台内置的类型」那一句报文。
**派发的型号与推理档**(ADR-127,判法是 `guard/requirements.js` 的 `modelDispatchWhy`,组队零件的 `dispatchWhy` 里 `typeWhy`(类型与名册)过了之后由 `modelWhy` 调它,前一关拦下就不看后一关;派它的会话号由同文件 `dispatchBlockWhy` 的第一行记下、`dispatchSessionOf` 取出;派发闸的第二样;守卫里没有任何型号字面量):
对每一次过了类型与名册那一关的派执行体(队友还是子代理,复盘者也走这一道;平台自带的两个工具型只免类型与名册那一关,型号与推理档照判)判入参里的 `model` 与 `effort`,配置住 `.claude/model-settings.json`(§十五「型号与推理档」),读它只为「执行类推理档」与「主控类名单」。
**派它的会话分两类,按会话号认**:登记的主控与会话登记册里角色在主控类名单(`core/model-settings.js` 的 `MAIN_CLASS_ROLES`)里的会话是**主控类**,其余(含登记册里没有的)是执行类;
执行体在主控类会话里再派也算主控类(会话号相同)。① `model`:不写或写 `inherit` 放,**写了别的一律拦**(型号跟着派它的会话走,要换型号改型号配置);
② `effort`:写了就**只放等于配置里执行类推理档的**(逐字比,大小写与空白都不放宽),别的拦,报文写明执行类的值;**主控类会话派执行体必须带它**,不带也拦,报文写明该带什么(例如「effort=<执行类推理档>,型号配置里执行类的推理档」);
执行类会话不带照放(继承的就是派它那一位的推理档:没单独设的就是执行类的,单独设了的是它自己那一行的;闸不看「按角色」);③ **配置读不出**:执行类会话**不带任何参数**的派发照放(本来就是继承),其余一律拦,报文写明怎么修。**守卫只拦、不改写入参**;拦下的报文两行,以「环1 派发:」打头,第一行写错在哪、第二行写怎么办。
**守不到**:两类型号不同、或派它的那一位单独设了型号时,执行体型号跟派它那一位走,守卫只核推理档;单独设了推理档的执行类角色派执行体不带推理档照放,执行体跑的是那一位自己的推理档;派发带的推理档平台照不照办、执行体的推理档在对话记录里看不看得到,只能靠平台
(平台若不照办改写,执行体会静默跑成主控类的档;拦是看得见的,所以这一道只拦、不替它补);常驻会话要等重起才跟新配置;闸认会话类只凭会话号查登记册,登记册读不出来或没登记的会话一律按执行类(主控类会话在那种状态下不带 effort 也放得过去);型号配置零件装不上时拿不到主控类名单,只认得出登记的主控,两位架构师按执行类算;不经派执行体这个工具起的执行体不过这一道;写前拦截摘下期间不在岗。
守着它的床是 `.claude/hooks/tests/model-dispatch-gate.test.js`(进程内六组、起真守卫的端到端、逐处改坏对照)。
**写域点名**(ADR-102,零件 `guard/team.js` 的 `domainNotes`、`domainOf`、`segCovers`;守卫主文件收尾那一段把话说出来):写域的检测只判那一行在不在,
执行体越没越界机器不拦(上「组队与执行体」的「记洞不改」);领队收尾时多说一句,**只点名、不拦**:退出码与拦不拦都不因它变。
**看哪些文件**:这一轮归本会话的改动里,此刻内容出自某个执行体的编辑工具的文件(取写出这份内容的最后一笔写证据,它带执行体标记)—— 内容被领队重写过就算领队的,不点;
改动已经提交的不在这一轮的改动里,不点。**对谁的写域**:不带名字派的,标记里的名字就是定义名;带名字派的队友按台账里「名字 → 定义」那一笔对回定义。
**写域怎么取**:那份定义「## 闭环」一节(到下一个一级或二级标题为止,与 x-agent 判据的闭环三行闸同一口径)「- 写域:」那一行里反引号包住的每一段,当仓根相对的目录、文件或通配 ——
认两个星号、一个星号、问号与花括号枚举;不带通配的按「就是这个文件,或在这个目录之下」算,带通配的匹配到文件自己或它的某一级上级目录都算。
一段反引号都没有(如「只读」)= 没有写域,写了任何仓内文件都点名。**判不了的不点名、也不出声**:定义文件读不到、没有「闭环」节或「写域」行、带名字的队友对不回定义、没有名字的执行体。
**同样的内容只点名一次**:点过的记进本会话台账一笔 {twd}(文件键加内容指纹;一笔最多记两百个,多出来的下一轮再点),内容变了再点;那一笔等附注真说出去的那一刻才记 ——
被拦之后接着的那一轮有两个出口不带附注,先记了这句话就再没人说。**不是闸**:只在本会话有改动、台账里又有带执行体标记的写证据时才现装组队零件,不走「装不上就拦」的装载口,
装不上或出错只在附注里说一声;台账用这一轮已经读进来的那一份,不另读(下面「台账一轮只整读一次」)。
**说的话**一例:「写域点名(只点名、不拦):执行体「x-server-engineer」写了它写域之外的 2 个文件:…… —— 它的写域是 ……(.claude/agents/x-server-engineer.md「闭环」一节「写域」一行)。
该不该由它写由领队定:改派给写域盖得住的执行体,或把它的定义改对,同样的内容只点名这一次」;一位执行体一次最多列五个文件,多了给总数。
**守不到**:① 只看得见编辑工具写的 —— 执行体用命令行或脚本写的没有逐文件写证据,看不见;② 写域只认那一行里反引号包住的段:不从仓根写起的段(如只写「各技能的 tests」)盖不住任何文件;
写在「不写某处」后面的反引号段也会被当成写域 —— 那一行里反引号只放它能写的目录;反引号段后面用话写的「除外」「只写其中哪一部分」机器不认,整段都算写域;
③ 写域那一行写得对不对没有闸(x-agent 只判那一行在不在);
④ 只点名、不拦,也不进结果单编号:越出写域而落在这条需求范围里的照旧过得了三查,该不该由它写由领队定;越出需求范围的照旧归需求对账;
⑤ 只在领队收尾时点,执行体停下那道关不判写域。守着它的床:`.claude/hooks/tests/stop-ring.test.js`。
**守卫提速的几处口径**:① 收尾对账与三查判「写没写范围外」用同一个函数(口径在一类上分开:本会话写进别的会话在办范围里的改动,收尾对账算越界 —— 它只把本会话办理的那几份范围交给这个函数,没盖住的再逐个问落没落进别人在办的范围,落进去的拦一次、记账;
三查不收紧 —— 把全部在办需求的范围交给它,这一类印在「归别的需求范围」一栏、不算本需求越界,见下「写前按办理会话判」)—— 范围的取法
(范围 = 签字时的目录加已核准的目录,在办的与本会话办理的签字作废的同样;认办理会话),这个函数逐个文件问它「盖没盖住」;三查把本计划自己放在最前面、
认它此刻的范围。「刚完结的需求范围里、完结前本会话写的改动不算越界」收尾与三查都认:三查里这类改动并进「归别的需求范围」一栏、
逐个标「已完结」;这一栏不进结果单编号,仍印在单子上(见上「复盘之后看板的状态列可以动」)。它排在判「谁写的」之前(收尾也是),所以封版前置读到的「本会话越界数」不含这一类。
**完结不误报**(ADR-88):上面那一条只认编辑工具的写证据,而封版命令写出的变更历史与锁清单没有写证据 —— 需求完结之后它们在别的在办需求眼里成了范围外的改动,
写入的时刻又可能落在别的会话一条命令的运行期间而被记到那个会话名下,把它的第一查挂红、验收签不上(真仓出过:「托管限流」完结后,它封版写出的两份文件被记成另一个会话四条在办需求的越界)。
所以「归一条已完结需求、不算越界」多认一种情形:文件此刻的内容,正是那条需求验收那一刻结果单上记着的内容(同一路径、同一内容指纹)—— 不看是谁写的、有没有写证据;内容之后再变就对不上、不再豁免。
结果单取账本目录里落盘的那张,只认完结那一笔记下编号的那张:编号对不上(完结之后重算过)、单子里的内容照编号的算法重算对不上(被改过)、单子不在了(临时目录清理过)⇒ 一个都不认、也不报错,照旧按写证据判。
收尾对账的两支与三查结果单仍是同一个判定器;结果单用到才读(多数收尾没有范围外的文件)。**守不到**:结果单的编号只有四位,不是防人伪造的强度;临时目录被清理之后这类文件会再被点名一次(方向是多拦不是放行)。
② 签字前数步骤与三查数步骤是同一个函数。
③ 已完结的需求再说「不过」,回话「已经完结」,不追加 reject、不回到实施。④ 编辑前先按「没写过」问该不该拦:放就不读台账;
要拦、而且本会话写过,再按「写过」问一次;只读本会话那一份台账,文件名逐字对上才读;写前判 Bash 命令的写文件那一支同序(先按「没写过」问、放就不读台账,被拦、而且本会话写过才再问一次 —— 本会话写没写过只会放宽、不会收紧,所以先问「没写过」放了就是放)。⑤ 收尾对账只给本会话改过的文件算指纹(会话归属里
本会话名下与分不清的、台账里本会话的写证据,这三样并起来算「本会话改过的」;指纹和「变没变」的比较都限在这个集合里,算法与全量指纹逐字相同,三样里一个受治文件都没有就一个也不算)。
判成「本会话的」「分不清」的文件只有这三样来源,所以拦的两条(本会话写的改动不在任何签过字的需求范围里、落进别的会话在办的需求范围里)与记进账本的越界记录不受这个限定影响,受影响的只有「范围外的改动」那条附注 ——
别的会话与没有写证据的改动不逐个读、不列进附注。列受治文件那一步多一个可选开关:点名的文件里没有 `.gitignore` 与 `.git/info/exclude` 时不做补忽略清单那步遍历,不传就照常做。
⑥ 收尾时需求对账或计划目录核对算不出来(调用出错)按拦处理、拦一次并写明判不了;被拦之后的那一次收尾只进附注(出错每轮都在,
不连着拦到平台上限)。⑦ 没签字的闭集白名单里 rsync 只看最后一个路径(它的 -t 是保留修改时间、不带值,不按 cp 的取法)。
⑧ 三查脚本自己装的量仓零件装不上,与量仓出错同样按「判不了」红(守卫的零件用到才装、不在一启动就把它装上,不这样判就会静默退回只看写证据、照样出绿单)。
弹验收题之前只比现成的三个记号、不重算三查,量仓零件坏了不影响弹题这一步;答完验收题当场的那一查,量仓零件装不上按「判不了」红、不记完结。
**项目架构与封存履历**(ADR-83,设计页 `.claude/arch/project/ARCH.html`):流水线自己立成项目架构(宪法 §三 说的五类架构里的一类),每道关口各写射程边界;阶段一、阶段四、阶段五的关口各有一处(下面 ① 与 ③)。共六个阶段 —— 阶段一需求与设计、阶段二实施与落地、阶段三测试与验证、阶段四复盘与验收、阶段五部署与上线、阶段六收尾与归档,每个阶段结束处一道关口(阶段六的关口见下「清理归档硬控」一段,ADR-97)。
① 阶段一的关口:签字那一刻核落点表里的单元是版本契约认得的单元 id 或字面 none(契约装不上按签不了字),短名不与任何履历已有的短名相同。这一处后面再接认车道与定档(见下各段);签字之前核的几道是一张五道的表,先后见下「定档与上限」;表过了之后再判开不开得了工(同一块排队、阶段六的关口,见下「签字与开工分开」)。
② 封存履历:签字一那一刻在 `.claude/arch/project/requirements/<需求名>/` 建出「在办」的履历(`RECORD.md` 给人读、`record.json` 机器读、`releases.json` 发布段);
验收完结三查全绿时先写全履历(含「用时与返工」「遗留」两栏,见下「履历多两栏」)、算产出指纹、把指纹写进账本完结那一笔、钩子给自己记写证据,再记 closed —— 履历写不出来就不记完结;「封死」= 履历有完结段且账本有带同一指纹的完结笔或归档笔,
缺那一笔按在办、钩子可重写(钩子半途被掐断不留改不了的半成品);生成时剥掉指向计划目录的路径 —— 需求、签字原话、怎样算做完、用例、遗留,给人读的与机器读的两份都剥,
剥掉的地方换成一句「(计划目录,完结后搬进归档)」(ADR-103);**落点表与用例点名的床清单同一个剥法**
(落点表逐格剥目录写法,单元名、哪一类、格名照原样;给人读的那一份渲染时再剥一次):这两样要是原样抄进两份履历,落点里列了计划目录下某个文件的计划,签字一那一刻写出的履历就带着计划路径,
治理规范「真相源不引施工计划」那颗闸当场红,只能改落点重签(撞过);
履历目录进脊柱保护与免检面(签字建履历不算越界);删计划那颗闸有前置「履历已封」(已完结的封没封都拦:封了的回话给出清理归档的命令,没封的要先让钩子重写履历,见下「清理归档」⑦);
封死的履历由检测核产出指纹。回填本架构之前完结的需求时给账本追加一笔「归档」带产出指纹(这是账本里的事件名,指回填时补的这一笔,与清理归档无关)。
**写给人看的时刻一律本机时间带时区**(ADR-104):履历给人读的那一份、复盘说明、发布段、三查结果单(连同看板签字区抬头那句「核对命令 … 生成」)里写出的时刻,
按本机时间写到分、后面标明那一刻的时区偏移,形如 年-月-日 时:分 +08:00(偏移从本机取,不写死东八区)。写法只此一份(守卫需求零件的 `localTime`),四处都经它写;
机器读的不经它 —— 履历机器版里的毫秒数,账本、签字基线、结果单与复盘说明留档的 json 里的时刻,判先后、判发布读的是它们,所以这个写法不动任何判定;
发布段里写的时刻读回去的只有一处:十态命令拿最后一次写出的时刻算环收尾(精度因此到分)。写成世界协调时、不标时区,比本机早八小时、凌晨的跨天,
主控照履历会把一条 9 点多完结的需求报成 1 点多(出过,还据此误判跨会话消息晚到了八小时)。
封死的履历不重写,所以较早封死的几份里写的是世界协调时、没标时区。
发布登记要从守卫零件目录装需求零件来写时刻,装不上就一个字不写、退出码 1(与它装联调零件同一种取法)。
守不到:写的是写下那一刻的本机时区,机器换过时区的,同一条需求前后几段的偏移会不同。
③ 阶段四与阶段五的关口:封版把「为了」解析到恰好一条签过字的需求并写进锁清单与记录行,发布前版本比对核基线之后的版本都绑着需求 —— 机制在 §十三「为了哪条需求」。
阶段五的关口在版本比对之前另判一道(ADR-100):这一次是联调还是正式发布 —— 正式发布核验收完结(要发的云函数或站点源码被在办需求签过字的落点表盖住就拦),
开发期联调上线有机器认得的口径、只放过那条需求落点表里的单元施工中;发布登记只给已完结的需求记已发布、按完结时那一版比。机制见下「部署门认联调」与「收尾单与治理站点一格」③。
守不到:开闸期间在办的履历能被手改而无痕迹(完结时重生成);履历跨机器只剩自核与脊柱写保护;剥计划路径只认 `.claude/plan/` 起头的写法(反斜杠写的也认),
不带 `.claude/` 打头的写法剥不到;较早封死的履历不重写,里面那句占位写着完结后删;签过字没完结又不打算做的需求没有废止路径(开了工的它还占着它列的版本单元,别的需求在这些单元上开不了工、一直排队,队放不开,见下「同一块排队」的守不到 ②);封版侧的跨会话拦见下「封版」。
**清理归档**(ADR-95):
流水线在部署之后有一个环节专管清理与归档:一条需求留下的过程文件(账本目录里的复盘任务说明、固定检查的输出、结果单的可读版、签字基线)、
各会话在仓库外面的临时副本、测试床留在测试根下的临时目录,由它清;已完结的计划不删,
整份搬进计划目录之下按日期分的归档目录;同一条命令把过程文件清掉;长期守着代码的测试不动。它是一个环节,不是一道关口:不加新的计划状态、不往任何账本记、不动需求履历,没做的只提醒、不拦(它前面有一道关口 —— 没做,新的需求开不了工,确认照签、记成排队;登记由守卫自动做、搬之前逐行核,见下「清理归档硬控」)。
① **谁跑、什么时候跑**:体系守护命令的 wrapup 动作(`x-harness-dev harness.js --action=wrapup`,零件 `x-harness-dev/scripts/core/plan-wrapup.js`),验收完结之后由接力命令完结之后三步调它(见下「接力命令」:刷新收尾单、预览,没人在跑床或建站才带执行开关;复盘和遗留、发现的去向不挡,在归档之后的后台办,见下「后台收尾」),也可以手跑 —— 手跑带执行开关不看锁;与发布的先后由主控排;钩子不替它跑(为什么见决策记录)。
它是受治树里现成的脚本,没有在办的需求时也跑得了(没签字时的命令白名单放受治树里已有的脚本,见上「换成闭集」)。结果不认是哪个会话跑的 —— 它没有会话号这个输入。四种用法,另有带需求名与起草开关 `--note` = 起草收尾单(五栏全写、在办的需求也起草,见下「收尾单与治理站点一格」②):
只带动作名 = 只读盘点,列五段(已完结还留在计划目录的计划,各带短名、需求名、完结日期、履历封没封死与那条命令;账本目录里每条已完结需求还留着的过程文件 —— 照账本列,计划在不在都列;
进程已不在的测试临时目录;老计划登记了但还在的仓外临时目录,见下「清理归档硬控」②;停滞区:对应的需求已完结、计划已归档或已不在、还没签字的施工区,只列不删,见下「项目自带」),不动任何东西;带需求名(`--plan=<名>`)= 预览,打印将搬什么、将清什么、哪些会被拒绝,不动任何东西(连空目录都不建);再带执行开关(`--execute`)= 真做;
`--legacy=<计划目录下的名字> --date=<年-月-日>` = 存量那一支(见 ⑥)。需求名只认计划的目录名、不认短名,大小写要与盘上的一致。有拒绝、或有一样没做成,退出码非零,其余为零 ——
预览里登记文件有不合的行、施工区文件夹本身不合规(是联接、不是文件夹、真实位置不在 `x-test/zz-work` 之下)同样算拒绝、退出码非零。经入口跑时,`--plan`、`--legacy`、`--date`、`--root` 出现却没带值 ⇒ 报用法、退出码非零(不把「忘了写名字」当成只读盘点悄悄过去);
`--plan` 与 `--legacy` 只能给一个。
② **三样前置**(带需求名时;缺一样就拒绝并写明缺哪样,什么都不动):账本没被直接改过(与写前拦、签字、删计划同一个完整性判法,`requirements.ledgerIntegrity`);这条需求的账本里记了已完结;
需求履历已封死(`project-archive.isSealed`,见上「项目架构与封存履历」②)。拒绝时写明现状是哪一种:没签字、在办、签字作废、账本被改过、已完结但履历没封死。
带需求名的预览与执行在这三样之后**多核收尾单这一样**(计划还留在计划目录时;认不到或缺栏就拒绝、什么都不动,见下「收尾单与治理站点一格」①);存量那一支、已经搬进归档的重跑、计划两边都不在的不查。收尾单核过之后、搬之前**再逐行核登记文件**(有一行没着落就拒绝、什么都不动,见下「清理归档硬控」②;只对留着登记文件的老计划有用,新计划没有这个文件);同一步另核这条需求的施工区文件夹本身(是联接、不是文件夹、真实位置不在 `x-test/zz-work` 之下就整条拒绝、什么都不动)。起草开关对签过字、此刻在办的需求只核两样(账本没被直接改过、这条需求确在办),见下「收尾单与治理站点一格」②;归档的执行与预览要的仍是这三样。
**不等发布**:机器只要求这三样。验收、发布、清理归档的先后由主控排;没有东西要发的(框架、规范、项目架构落盘即生效)、或攒着以后发的,验收后直接清。
③ **搬什么**:源是计划目录下这条需求的那个目录,目的地是归档目录下「完结那一笔的本机日期(年-月-日)」再下一层「需求名」。日期取账本里最后一笔已完结的时刻、按本机时区算
(履历给人读的那一份也按本机时间写、标明时区,ADR-104;较早封死的履历写的是世界协调时、没标时区,凌晨完结的那几条两处会差一天,以这里为准)。只用一次目录改名,不做复制再删:搬完之后里面的文件逐个与搬之前相同、修改时间不变。
改名失败原样报错、退出码非零,为这次搬新建的空目录收回去,源与归档目录都和跑之前一样,后面的清也不做。**判「归档里有没有它」不只看算出来的那一天**,而是到归档目录下逐个日期目录里找同名的
(完结之后换过时区,算出来的日期会变,已经归档的那一份不能因此认不出来)。四种情形:源在、哪一天下面都没有 ⇒ 搬;源不在、某一天下面有 ⇒ 报已归档并写明在哪一天下面,接着清;
源在、任何一天下面已有同名的 ⇒ 拒绝,不覆盖、不合并,也不清;两边都不在(这条规矩之前就删掉了计划的旧需求)⇒ 报没有可搬的,接着清。所以它可以重跑。
归档目录的名字只写在两处常量里(清理归档的零件 `ARCHIVE_DIR`、守卫需求零件 `PLAN_ARCHIVE_DIR`),那条命令的写法也各有一份(零件的 `commandFor`、守卫的 `requirements.wrapupCommand`),
两样都由清理归档的测试床对拍相等;本文不抄。
④ **清什么**(只在带需求名与执行开关、过了三样前置与搬那一步之后做;每清一样打印一行;有一样没清成,退出码非零、其余照做):
一、账本目录里这条需求的过程文件,按「需求名加固定后缀」逐个认、不按前缀 —— 复盘任务说明两份(`<名>.review-brief.md`、`<名>.review-brief.json`)、复盘说明留档(`<名>.review-briefs.jsonl`)、
固定检查的结果与输出(`<名>.checks.json`,以及 `<名>.check-<检查名>.out.txt` 与 `.err.txt`,检查名里没有点)、结果单的可读版(`<名>.sheet.md`)、签字基线(`<名>.baseline.json`)。
账本目录里另有一条名字更长、有自己的账本、也能当这个文件前缀的需求时(仓里就有这样的两条),这个文件归那一条、不归这一条 —— 名字前缀相近的另一条需求的文件一个不少。
「有自己的账本」按文件里记的是不是账本事件认、不按名字:复盘说明留档自己就长成一份账本的名字,只看名字它永远被自己认领、永远清不掉。
二、老计划留下的登记文件(`outside-dirs.txt`,住计划目录里,一行一个绝对路径;只有老计划有,是守卫在建的那一刻自动追加的,守卫不往新计划里写、新计划没有这个文件;不进机器镜像,随计划一起归档)里列的仓外临时目录。
各行照它的着落办(写明保留的不删、已经不在的写一行、合规的删);下面说的「不合的那一行拒绝并点名,其余各行照办」只剩计划已经搬进归档的重跑这一种情形 —— 计划还留在计划目录时,有不合又没写保留的行,在搬之前就整条拒绝了。
从计划此刻所在的地方读它(搬走之后就是归档里那一份);没有这个文件就跳过,读不了算一样没做成。每一行:是绝对路径,按真实位置算严格在系统临时目录之下、不在仓库里面、
也没把仓库包在里面,才删(另有一种一律不合规,ADR-98:这一行写的是某个会话的草稿目录本身、或各会话共用的那棵临时目录 —— 只按上面几条它合规,整棵删掉会连别的需求、别的会话的东西一起删;判法只问守卫登记仓外目录时用的同一个函数 `outsideUnitOf`,它不肯登记的那几种落点就是这里要拒绝的);不合的那一行拒绝并点名,其余各行照办;已经不在的写一行、不算失败。删的时候不跟着链接走:遇到目录联接或符号链接只解开这一个链接,不进去删它指向的东西
(副本里常放着指回真仓的联接);登记的那个路径本身是链接,同样只解开它。计划两边都不在的旧需求没有登记文件可读:照实写一行、不算失败,它的仓外临时目录清不到。
三、测试根 `x-test/` 下名字以 `zzharness-` 或 `zzmeta-` 打头、以进程号结尾的测试临时目录(测试床按进程号建的沙箱;只认真目录,链接不算):那个进程已不在的才删,还在的不动并写一行,
判不了的按还在。这一处不分是哪条需求留下的。
四、这条需求的施工区 `x-test/zz-work/<需求名>/`(ADR-112,见下「项目自带」):整份删,不跟着链接走 —— 遇到目录联接或符号链接只解开这一个链接、不进去删它指向的东西;施工区文件夹自己是联接、不是文件夹、真实位置不在 `x-test/zz-work` 之下的,在核登记文件那一步就整条拒绝了,不会走到这里;没建过的照实写一行「没有」。预览打印「将清(施工区)」并列出里面有什么(顶层条目、文件数、占多大、有没有联接)。
⑤ **不碰什么**:最后那张结果单的机器版(`<名>.sheet.json`:完结之后守卫还读它,
用来认「这正是验收那一刻交付的内容」,见上「完结不误报」;删了,封版命令写出的变更历史与锁清单会被重新判成越界)、原话账本(`says.jsonl`)、没签字账本(`_unsigned.jsonl`)、
名单之外的任何文件;任何 tests 目录下的测试一个不碰。账本与台账在提交之后挪进日志区、不删:账本本体(`<名>.jsonl`:签字、完结都记在这里,带链、仓外有镜像,少了它守卫判成账本被改过)连同仓外镜像目录里的那一份、会话台账,
清理归档都不碰,由提交命令在提交并推送成功之后挪(见 §十五「记录分几类、放哪」)。**签字基线为什么可以清**:读它的只有两处 —— 收尾对账与三查(见上「范围与基线」),
都只对在办或签字作废的需求算,已完结并搬走的计划没有任何一处再读。只清仓内那一份,仓外镜像里的那一份留着:万一有没查到的读者,它会照实报签字基线不见了,镜像里有原件、放回去即可。
清完之后:这条需求的账本完整性照旧为真;计划名单里不再有它(计划名单只数计划目录下一层、带机器镜像的目录,归档目录自己不带);收尾对账仍认它验收时交付的文件
(范围取最后一次签字记下的目录,见上「组队与执行体」里已完结需求的范围那一句;内容按结果单的机器版认,见上「完结不误报」)。
⑥ **存量那一支**(`--legacy`):给这条规矩之前留下的历史材料用 —— 只认计划目录下一层的名字(目录或散文件),不认归档目录自己、不认带斜杠的名字。那一项有机器镜像,
或者账本目录、仓外镜像目录里有它的账本 ⇒ 拒绝(这种要走带需求名的那一支,核三样前置)。没给日期、或日期不是真实的年-月-日 ⇒ 拒绝:存量材料没有完结那一笔,日期只能由跑的人给。
目的地是归档目录下那一天里的同名项;归档目录下任何一天已有同名的 ⇒ 拒绝。只搬不清;不带执行开关是预览。
⑦ **守卫在哪几处配合**(一颗闸,三处提醒;都不加新的账本事件):
**删与挪的那颗闸**(上面「三查接关口」里讲删计划那一句的现状):凡已经接到「能不能删计划」这一处判定的命令 —— rm、rimraf、del、unlink、git rm、mv、git mv、带路径的 git stash push ——
对着计划目录下的任何一份都拦(`requirements.rmPlanWhy` 对计划目录下的任何路径都回一句原因,没有放行的一支;命令策略里也没有「全部是完结了的就放」的放行分支)。各支的回话:
目标落在归档目录里(先判;不拿归档目录的名字去查账本,所以不把它当成一份没签字的计划来回话)⇒ 归档的计划不删不挪;账本被改过 ⇒ 拦;已完结且履历封死 ⇒ **拦**,
回话写明已完结的计划不删、用清理归档的命令搬进归档,并给出带着这条需求名字与执行开关的那条命令;已完结但履历没封死、签过字开了工没完结 ⇒ 拦,回话里说「之后再清理归档」;签了字还在排队(没开工) ⇒ 拦,回话写「还没开工」、不说「先把三查跑绿」;没签字 ⇒ 拦。
这几句原因 rm、rimraf、del、unlink、git rm、mv 被拦时带得出来;git mv 与带路径的 git stash push 拦是拦的,回的只是一句通用的话、不带那条命令。
**验收完结那句回话**:「已记「已完结」。需求履历已封死(…)。」后面接收尾那一句:之后先收尾,跑一次接力命令收尾(带着这条需求名字的那条接力命令,`requirements.relayCommand`,命令后面接一个全角空格、不接句号;它刷新收尾单、预览清理归档,没人在跑床或建站就直接归档,计划整份搬进归档、过程文件清掉,它搬走之前新的需求开不了工;归档不了会原样说出原因,见下「接力命令」),再接一句复盘经理的复盘和遗留、发现的去向在后台办、不挡归档、提交和下一条开工(见下「后台收尾」),再后面是办得超了的那一句与遗留那一句(遗留逐条列出、交主控定去向)。原句只住守卫需求零件里完结那一支。
**每次回话点名**:用户每说一句话,守卫对每一份已完结、还留在计划目录的计划各出一行「【待清理归档】<短名>(<需求名>)已完结,计划还留在计划目录:」加那条命令,排在「正在办」那几句之后、
接进度之前;行首不是「【正在办】」,接进度那一步接不到它,两样同时在场时互不挤掉。判据就是状态表里状态是已完结的那几项 —— 状态表只列计划目录下一层、带机器镜像的目录,搬走之后它不在表里,这一行自然消失。
在办的、签字作废的、没签字的、账本被改过的、机器镜像读不了的不出这一行;已完结但履历没封死的也会被点名,照那条命令跑会被拒绝并写明缺什么;签验收的那一次回话里,刚完结的这一条也会被点名
(同一条命令在那一次回话里出现两遍)。点名这件事不往任何账本记(用户原话照记)。这一行讲收尾单:这份计划里认不到收尾单文件时,冒号之前多半句
「,收尾单还没写(先起草:起草的命令 五栏由机器起草,核一遍、改掉写错的)」;收尾单在而缺栏时这半句是「,收尾单还缺几栏(缺的栏名),写全再清理归档」;五栏齐全时不带这半句。三种都以清理归档的命令结尾。
**发布登记**:record-release 动作打印每条需求状态的那一行时,已完结(含已发布)而计划的机器镜像还在计划目录里的,行尾加「 (还没清理归档:」加那条命令加「)」;已经搬走的、在办的不带;
只是打印,写出的发布段文件不因这一句而变;没有履历的需求不出现在发布登记里。发布登记给每条需求多推一格「治理站点」(只有业务域落点的需求不带,判法见下「收尾单与治理站点一格」里「发布登记的新记法」二),清理归档执行到末尾会重算这条需求的发布段,
守卫另有一行「待发布」的点名 —— 三样都在下「收尾单与治理站点一格」③④。
三处都只提醒、不拦:没清理归档不挡封版、不挡发布。另有一道挡开工的:没清理归档,别的需求开不了工(确认照签、记成排队;已经开了工的需求重签不挡),上面两句回话各多半句「它搬走之前,新的需求开不了工」(见下「清理归档硬控」③)。开闸期间:删与挪的那颗闸挂在写前拦截上,不在岗;验收回话与每次回话点名挂在用户说话那一刻,照常;发布登记与清理归档的命令是脚本,照常。
**待提交、待补推的点名**(守卫需求零件;只提醒、不拦,不往任何账本记):用户每说一句话,守卫在「待清理归档」各行之后、接进度之前另出两种点名行。**两行从账本认、不看计划目录** —— 这时计划多半已经归档、不在计划目录里,只看计划目录这两行永远出不来(与开工条件认占用者同一个读法)。① 已完结、完结那一笔记着「要提交」、账本里还没有「提交」那一笔的,点名「待提交」,带提交命令(还没发完、没归档时,命令的预览会说还差哪样);② 「提交」那一笔记着没推成的,点名「待补推」,带重跑提交命令。完结那一笔不带「要提交」的需求不点名。「待清理归档」那一行后面的半句写「它搬走之前,新的需求开不了工」。
**叫法**:这个环节叫「清理归档」;封履历叫「封存履历」;账本里回填时补的那一笔叫「归档」笔(账本里的事件名)。
**守不到**:① **命令行之外删计划拦不住**:那颗闸只挡命令行的直写形态(换目录、变量展开、find -exec 这类拦不住,见上「三查接关口」),脚本进程内的删与挪它看不见
(与整套体系同一条边界,§十三 诚实边界⑤),开闸期间不在岗。签过字没完结的计划被删掉,收尾点名一次;**已完结的计划被脚本进程内删掉(不是搬进归档),没有任何一处点名** ——
收尾点名只管签过字没完结的,三处提醒也跟着消失:它们只看计划还在不在计划目录,分不出是搬走了还是删掉了。唯一还看得见痕迹的是清理归档命令的只读盘点
(第二段照账本列出它还留着的过程文件;带着它的名字跑,报没有可搬的),要人去跑。
② **归档进去的文件只挡命令行的删与挪**:命令行删不了、挪不走,但编辑工具仍然改得了(计划目录是写前拦截的免检面),脚本也改得了、删得了。归档进去的看板不在看板规范那四颗闸的射程里
(x-plan-doc 把归档目录排除在外),改坏了没有检测会报。
③ **施工区之外的临时东西清不到**:放在系统临时目录里的副本、备份、探针(签字之前的实验、没听提醒的)清理归档不管 —— 守卫不登记、只回一句提醒;老计划登记文件里的行按登记清:没登记的清不到,登记了、但不在系统临时目录之下或落在仓内的那一行被拒绝,也清不到,登记成整棵草稿目录或各会话共用那棵临时目录的整条拒绝;计划早先就删掉的旧需求没有登记文件可读,同样清不到;
东西放没放进施工区、要留的记录有没有放错地方,没有机器核,靠工作流说明里「副本、备份、探针只放本需求的施工区」的规矩(见下「清理归档硬控」「项目自带」的守不到)。
④ **搬过去的文件没有写证据**:改名不经编辑工具,它们在新位置上算无主的改动,由收尾环的无主复核接住(每轮至多 40 个,文件多的要分几轮,见上环3 开头讲无主的那一条);
复核过之前没有干净结论(干净结论按文件与内容记,换了位置就是新文件)—— 这一小段里,变更类的云端写若待检范围含着它们,部署门会拦(环1「部署门」;三类静态站点的发布只数自己的原料目录,数不到计划目录)。
计划目录不在需求对账的范围里,搬进归档不算任何需求的越界。
⑤ **验收完结之后那一次接力命令靠人跑**:机器只提醒、不拦,验收完结之后没人跑那一次接力命令(或手跑清理归档),计划就留在原处、过程文件照旧攒着(忘了的代价:新的需求开不了工;封版、发布、在办需求的重签不挡)。点名只在用户说话时才出现:新开会话那一刻的开场清单不点名已完结待清理的,要等用户说第一句话才点;
它是守卫回给当场那个会话的话,用户看不看得到取决于执行者转述,验收完结那句回话同理;发布登记那一句只在有人跑它时才看得见。
先后也不由机器管:机器只要求已完结,发没发、该不该先发,由主控排(§十五)。
⑥ **清理归档的命令本身不在写保护名单里**(同目录的三查核对命令与复盘说明程序在,它不在):把它清的名单改宽,写前没有东西拦,守着它的只有它的测试床。
而它删的账本目录是脊柱写保护的 —— 它在脚本进程内删,守卫看不见,与封版命令在进程内写锁清单是同一种做法。判完到动手之间别人换了目录里的东西,它看不见。
⑦ **测试临时目录按进程号认**:进程号被系统分给了别的进程时,按还在处理、这一次不删(方向是少删);名字不是这两种形态的测试残留不认。唯一运行器每跑完一轮也清这一类(同一份认法),不必等有人跑清理归档。
⑧ **这条规矩之前的不补**:早先已经删掉计划的旧需求,走两边都不在那一支,只清不搬、不补空位(它们的摘要在需求履历里)。履历生成时把计划路径换成的那句占位
是「(计划目录,完结后搬进归档)」(ADR-103);较早封死的履历改不了,里面写的是完结后删(见上「项目架构与封存履历」②);
回填的履历写着计划已删,已封死的改不了。
**收尾单与治理站点一格**(ADR-96):
为的是会话有个结尾、治理站点发没发有处记 —— 不然验收完结之后办理会话只是停下、清理归档核三样就把计划搬走,只碰框架、规范、项目架构的需求一完结就显示已发布,治理站点在它之后发没发没有任何一处记。
这一段两样,都挂在清理归档这个环节上:搬之前必须有一份收尾单;末尾更新历史记录(重算发布段),治理站点那一格没发的由守卫点名。主线顺序是需求 → 实现 → 测试 → 部署 → 清理归档,没有专门的计划状态与账本事件。
① **收尾单:清理归档多核的一样**。收尾单是这条需求的计划目录里一份固定名字的文件(`WRAPUP.md`),固定五栏,各占一行二级标题:「一、做成了什么」「二、没做什么、为什么」「三、遗留与去向」「四、要发的格与此刻状态」「五、链接」。
文件名、五栏的名字与「缺哪几栏」的认法只住守卫的需求零件里一份(`requirements.WRAPUP_NOTE_FILE`、`WRAPUP_NOTE_COLUMNS`、`wrapupNoteMissing`、`wrapupNoteState`),清理归档的零件从那里取用(它本来就装着需求零件),没有第二份。
认法:一栏算有 = 有一行二级标题逐字是这一栏的名字,而且它到下一行二级标题(或文末)之间有不是空白的字;注释先整段去掉,所以只有注释的栏算空;文件不在、或那个名字不是文件,五栏都算缺。
清理归档带需求名时(预览与执行一样)过了三样前置、过了「两边都在」那一判之后:计划还留在计划目录、里面认不到收尾单 ⇒ 拒绝,写明放在哪、叫什么、要哪五栏、用哪条命令起草;有栏缺 ⇒ 拒绝并点名是哪几栏。
拒绝时不搬、不清、退出码非零。计划已经搬进归档的重跑、计划两边都不在的旧需求、存量那一支不查。只读盘点里每份已完结还留在计划目录的计划多写一句收尾单有没有、缺哪几栏。机器只核在不在、五栏全不全,不判写得对不对。
② **起草**(`--plan=<名> --note`;与执行开关、存量那一支不能同用;五栏全部由机器起草、不等验收,ADR-98):已完结的同样先核三样;签过字、此刻在办、还没验收完结的也起草(接力命令第二段在用户验收之前调它),这时只核账本没被直接改过与这条需求确在办 —— 没签字、签字作废、机器镜像读不了的拒绝。计划已不在计划目录(已归档的、早先就没有的)⇒ 拒绝、什么都不写。
**起草两次,两次都是机器**:第一次不等验收 —— 接力命令第二段(复盘结论入账之后)调它,写出草稿;第二次在验收完结、履历封死之后 —— 接力命令完结之后三步的第一步调它(归档之前办理会话改过第三栏去向的,遗留原文对得上的那几行照它的)。**已有收尾单再跑不整份重写,只刷新机器管的几处**(这条需求还在办时再跑也一样):开头写状态的那一句、第一栏「用时」那一行与用例后面的「等用户验收」(靠整行还是不是机器写的那个形态认)、第一栏「用时」后面的「过程复盘」一节(下面单说)、第二栏只补登记文件里新多出来的行(已有的行不动)并照此刻的施工区重写那一行「- 施工区 …」(只对机器起草的第二栏,靠第二栏里机器写的固定一行认;手写的第二栏一个字不动)、第三栏照此刻该取的来源重排(验收完结之后改取履历的遗留;遗留原文对得上的保留办理会话改过的去向,新出现的加上、默认「后台办理中」,来源里已经没有的去掉并点名)、第四栏与第五栏重填。办理会话写的别的字不动;认不出是不是机器写的原样的那一行不动,在打印里点名、写明此刻机器会写成什么;哪一栏的标题没有或有两处,那一栏不刷新并点名;刷新之后守卫认得的栏比刷新之前少就不写、照实报;机器管的几处都已是最新的,什么都不写。
草稿开头是短名、需求名与完结的本机时刻(验收之前起草的那一份还没有完结时刻),五个标题都在、五栏都有内容。第一栏照三查结果单与需求账本:签过字的标准逐条对着它的用例各是什么结论、改了多少文件落在哪几格、动了哪些单元与版本(结果单上没有这一项时,退到各单元变更历史里记着为了这条需求的那几版)、复盘几轮与用时(与履历「用时与返工」同一个函数,在办的数到起草这一刻)。第二栏照三查结果单、施工区里有什么(机器写的一行「- 施工区 …」:清理归档整份删它,没建过的写没有)与老计划登记文件逐行的着落。
第三栏把遗留逐条列出、各带一栏「去向」(默认写「后台办理中」:去向在后台办,由 X大脑 定、项目经理记进待立项目清单与总账,不回头改这份收尾单;履历之外的补记写第二栏):验收之前那一次,履历里还没有遗留这一栏,取看板「欠下的」逐条加账本里各次可信复盘带的遗留(守卫完结那一刻写履历用的同一个取法),并写明是此刻取的;验收完结之后那一次改取需求履历的「遗留」一栏。办理会话只改写错的那几行;五栏的名字与认法只住守卫的需求零件里一份,
起草出来的原样拿去清理归档认得过。第四栏由机器填:当场对这条需求重算一次发布段(与发布登记同一段代码,`record-release.noteFacts`),逐格写「格名:状态」;重算做不成(版本契约装不上、履历读不了)时
只照落点表里的单元名与治理站点列出(该有「治理站点」一格的才列它)、状态写「待登记」,并写明没重算成。第五栏由机器填:看板现在的位置与归档之后的位置(归档目录下完结那一天)、需求履历、治理站点上的记录页(站点里的相对位置与本机产物的位置)、
这条需求产的各版本 —— 从各单元变更历史里封版记下的需求那一行反查(`record-release.versionsFor`;那一行与锁清单的「为了」是同一份,名字相近的另一条需求的不算),不从看板抄。起草只写这一个文件(外加重算出的发布段)。
**过程复盘进收尾单**(ADR-120):已完结的专项,起草与每次刷新都在第一栏「用时」那一行后面写一节「过程复盘」(三级小标题,守卫只按二级标题切栏,所以五栏的名字与认法不受影响;没有复盘记录也写,在办期不写)。
节首一句说明:表由接力命令每次刷新收尾单时从账本现算,在归档那一刻定格(归档把施工区删了,之后现跑读不到副本里的跑床行);结论取自复盘记录,还没写时写「后台办理中」。里面的**表**与它的**红旗**各条由这一回从账本现算(调耗时表生成器验收之后的口径,见 §八「过程复盘的耗时表与红旗」;不从复盘记录里抄,所以账本变了再刷新一次表跟着变、复盘记录里也不留旧表),
最后一行是**结论**:复盘记录里的结论一行写了就抄,没写时写「结论:后台办理中,复盘经理写在 <复盘记录的仓根相对路径>,写好后以那里为准。」;这一节整节由机器每次重写,办理会话要补话写在它后面;表里一个命令原文都没有。复盘记录里的发现不进收尾单(归档时它多半还没写;发现的去向见下「后台收尾」)。
复盘经理写的结论(归档前写好的)原样进收尾单、不加过滤:收尾单会随站点公开(下「守不到」②),不贴命令原文与敏感值由它的定义管,机器不过滤。五栏的名字与认法不动(只住守卫的需求零件里一份)。
③ **治理站点是一格**(发布登记 `record-release.js`):每一条需求都推一格「治理站点」(不归哪个版本单元)—— 它的履历与它改到的受治文档都要随站点重建、发布才上线;落点表碰到治理站点源码的需求也只有这一格。
**只有业务域落点、又没有哪一行业务域只改业务设计页的需求除外**(ADR-100;只改业务设计页的那一种见 ADR-108):落点表里除了不归任何单元的那几行,单元全是业务域,
没有哪一行业务域只改业务设计页,而且没碰治理站点自己的源码 —— 这样的需求不带这一格。**只改业务设计页**说的是业务域那一行的目录至少写了一条、而且条条都落在业务架构目录 `.claude/arch/business/` 下
(只改域的设计文档、变更历史与锁清单;`designOnly`):这一行不按端推格,有一行这样的,需求就带上这一格;其余需求每条都有(判法见本段「发布登记的新记法」二)。
这一格只有一种判法(`judgeRecordSite`):入库的发布台账里最后一条治理站点「已上线」的记录,它的发布号所记的时刻(年月日加时分秒,到秒)晚于这条需求的完结时刻 ⇒「已发布」;发布号读不出时刻的那一行按台账时间(到分)比;
需求没完结(或完结段没有产出指纹)、没有上线记录、最后一次上线不晚于完结 ⇒「未发布」。两边换成同一个绝对时刻再比:履历机器版里的完结时刻是毫秒数,发布号与台账时间按本机时间换算(履历给人看的那一份不拿来比:它把时刻写成本机时间带时区,形如 年-月-日 时:分 +08:00,较早封死的写的是世界协调时;ADR-104)。
发布当时带站点名跑的记法、早先记下的结论都不参与这一格:那种记法取的是跑登记的那一刻,在办的需求会被它翻掉。所以只碰框架、规范、项目架构的需求,完结之后状态停在「已完结」,站点在它完结之后发过一次、再跑一次发布登记才翻「已发布」。
写出的发布段多记短名;状态、短名、各格都与上一次写出的一样时不重写文件(发布段是治理站点的源文件,白写一次会让站点显得过期)。**清理归档执行到末尾**(搬完、清完)对这条需求重算一次发布段并打印它那一行;
治理站点那一格还没发的接着打印一句话 —— 站点的发布归运维经理、验收完结那一签已经授权这条需求的发布(主控把验收原话或代签记录转给运维经理)、可以攒着发,发完再跑一次发布登记
(起草的收尾单第四栏末尾用的是同一句);重算没做成算一处没做成(退出码非零),已搬已清的不回退;预览不写发布段。
**「联调」是单独一种格**(ADR-99;由机器自动记,ADR-100;同一个发布登记程序):开发期联调上线(建数据表、联调时部署云函数,§六「五类需求各从哪进」)由运维经理在授权下(用户的单次授权,或照代签设置由 X大脑 代授权)做。
联调放行的那一次上传成功之后,机器自动对那条需求跑联调记法 —— 经云端工具的,守卫当场只往本会话台账记一笔,这一轮收尾时才逐笔写进履历(一笔算一次);
经脚本通道的,发布脚本在联调上传成功之后当场记一次(见下「部署门认联调」⑦)。上线了什么写函数目录或表文档的路径;
发布当时的记法命中还在办的需求时,只有落在这条需求落点表里的函数目录记进这一格(站点不记,落点表之外的函数不记,见本段「发布登记的新记法」四)。
同一条记法也可以手跑,给机器看不见的那几种留痕(控制台里用户亲手做的导入与发布):
`node .claude/skills/x-harness-dev/scripts/harness.js --action=record-release --plan=<需求名> --trial=<联调上线了什么,…>`(逗号分开写函数目录、表名这类,半角全角逗号都认)。这条需求的发布段多出一格,格名「联调」,
状态只有一种「已联调(不算发布)」,记最近一次的时刻、一共几次、联调过哪些东西(去重累加);经云端工具上线的,这里的时刻是写进履历的时刻(那一轮收尾)、不是上传的时刻,
次数照上传的次数。它不从落点表推,只在记过联调的需求上有;不是给云函数那一格加一个状态。**只留痕**:不翻任何别的格、不算进该发的格 ——
它在不在、是什么状态都不影响这条需求翻不翻「已发布」,云函数那一格要在验收完结之后正式发一次才翻;记过之后每次重算原样带着,不带这个开关的重算不改它。拒绝并且什么都不写的四种:开关后面没写值、
没有同给需求名、与记正式发布的两个开关(站点、函数目录)同给、这条需求没有履历。**守不到**:自动记不上不重试、只说一次并给补记的命令,没有东西回头催;经云端工具上线的要到这一轮收尾才写进履历,
会话没走到收尾就断了的,等它下一次收尾补写,一直不再收尾就一直没写;控制台里做的联调机器看不见;验收完结之后补记联调不拦 —— 机器分不清那是补登记还是真在完结之后又联调了一次;
手跑时「联调上线了什么」是跑命令的人写的字,机器不核它与线上对不对得上;授权没有机器核。
**发布登记的新记法**(ADR-100;同一个程序,四样):一、**体系外两格** —— 数据表与微信原生包两格固定记「在体系之外发(控制台)」「在体系之外发(微信开发者工具)」,
另记在哪发,不算进该发的格(数据表在控制台导入发布、原生包由用户在微信开发者工具上传,体系发不了也记不了;记成「发布无记录」的话,带数据表或小程序端的需求永远翻不成已发布)。
二、**只有业务域落点、又没有哪一行业务域只改业务设计页的需求不带「治理站点」一格**(`siteGridDue`)—— 判法四样都成立才不推这一格:判单元时不算落点表里字面写 none 的行(不归任何版本单元的文件,最常见的是测试);
去掉之后至少有一个单元、而且全是业务域;没有哪一行业务域只改业务设计页;并且落点表没有碰治理站点自己的源码(x-harness/ 之下)。碰了站点源码的带这一格;
只改业务设计页的业务域行(`designOnly`:这一行的目录至少写了一条、而且条条都落在业务架构目录 `.claude/arch/business/` 下 —— 只改域的设计文档、变更历史与锁清单,不碰代码与数据)不按它描述的端推格,
有一行这样的,这条需求就带上这一格(ADR-108);一条目录都没写的业务域行不算,按端推(宁可多推端格,不漏掉该发的端格);有目录落在代码或数据上的业务域行按端推,几个业务域两种都有的,两样都推。
十态判已发布与收尾单第四栏问的是同一份推法;每次跑发布登记都照履历里的落点表重推,已完结的这类需求不用重签。
其余需求(落点表里有整个框架、系统规范域、项目架构、agent 架构、业务总览的,或一个版本单元都没有的)每条都有。
**「已生效」一格出给谁**(ADR-103):落点表里每个不是业务域的单元各出一格「已生效 · <单元>」——
整个框架、系统规范域、项目架构、agent 架构、业务总览。认不认得这个单元只问版本契约的单元名册(发布登记推业务域的格本来就装着它,`knownUnit`),发布登记里不另写一份单元的写法:
名册里此刻有它 ⇒ 认得;此刻没有、但与名册里某个单元同一类(冒号前那一段相同,业务域那一类除外)⇒ 也认得 —— 后来撤掉的规范域就是这样,需求落盘那时它就生效了,
全量重算时不该把早已「已发布」的需求翻回「已完结」;都不是、或名册读不了 ⇒ 单独标一格「认不出的单元 · <单元>」,不无声丢(它算该发的格、判不了,这条需求就翻不了「已发布」)。
不在发布登记里写死单元的前缀:写死的话新加一类单元会跟不上(agent 架构就跟不上过)—— 落点有它的需求发布段里少一行「已生效」(翻不翻「已发布」不受影响,少的是一行留痕),
别的认不出的单元无声丢掉;认名册的话再加一类单元,发布登记不用跟着改。守不到:名册里业务域以外的单元一律算落盘即生效 —— 以后加一类自己另有线上发布面的单元,
发布登记只给它出「已生效」,要回来改这一处;名册读不了的那一次,业务域以外的单元全标成认不出、判不了(只会更慢翻,不会误翻);「已生效」没有可比的版本(见本段末「守不到」)。
三、**该发的格与翻不翻** —— 该发的格 = 不是联调格、不是体系外格的那些;已完结的需求,该发的格全部是已发布、已发布(按时间推)或已生效 ⇒「已发布」,
一格该发的都没有也算(验收完结即已发布)。四、**发布当时只给已完结的记、与完结时那一版比** —— 带站点或函数目录跑的那种记法,
命中的需求已完结才精确记「已发布」,记下的版本是它完结时产的那一版(履历完结段里记的各单元版本;履历没记这个单元才用当下锁清单的版本);命中的需求还在办,不记已发布 ——
站点命中的什么都不记,也不进「联调」一格(静态站点没有联调),只打印一行;函数命中的,只有落在这条需求签过字的落点表里的函数目录才记进它的「联调」一格(次数加一、时刻、上线了什么),
不在的不记、打印一行(够不够得着问守卫联调零件的同一个判法;零件装不上 ⇒ 这一次不记联调并打印原因,别的格照常算)。
收窄的原因:命中按站点名或业务域单元算,而没开闸时正式发布发得出去的东西必然不在任何在办需求的落点表里 —— 命中的全记进去,记下的几乎全是别人的东西。
已完结的需求每次重算:发布当时精确记下的版本与履历里它完结时那一版都有而不同 ⇒ 这一格作废、记回「未发布」并带一句为什么;
在办时留下的精确「已发布」先不动(在办时状态本来就是在办),完结后的第一次重算照此判;守卫在记下「已完结」的那一刻顺手重算一次(见下「部署门认联调」⑦)。
「治理站点」那一格只按发布台账判,不走这一条。**守不到**:版本比对只对发布当时精确记下、履历里又有那个单元完结时版本的格起作用,按时间推的、已生效的格没有可比的版本;
云函数没有入库台账,没有发布当时的精确记法时事后重算仍记「发布无记录」、不算已发布;只有业务域落点、又没有哪一行只改业务设计页的需求,它的履历页与业务域文档在治理站点上要等下一次站点发布才更新,
发布段不等它、「待发布」那一行也不点它;推格只看落点表里写下的目录,业务域那一行漏写了代码目录,机器照只改业务设计页推格(阶段二的关口照样拦范围外的写);一条目录都没写的业务域行按端推。
④ **「待发布」的点名**(守卫需求零件 `siteReleaseLine`;只提醒、不拦):用户每说一句话,守卫读各条需求的发布段(履历目录下每条需求一个小文件),状态是「已完结」、而「治理站点」那一格还不是已发布的,合成一行,
以「【待发布】」打头,列出短名(多于八条的写前八条与总数),写明站点在它完结之后还没发过、站点的发布归运维经理,验收完结那一签已经授权这条需求的发布(主控把验收原话或代签记录转给运维经理)、可以攒着发,
以发布登记的命令结尾;一条都没有就没有这一行。这两处与十态表里讲发布的那半句说的是同一条规矩,明文在 §十五「谁来发布、怎么授权」。排在「待清理归档」各行之后、接进度之前。
不往任何账本记;哪一条的发布段读不了、或里面还没有这一格(早先写的发布段;只有业务域落点、又没有哪一行只改业务设计页的需求本来就没有这一格)就跳过,出错只少这一行。它只读发布段、不读履历与台账、不自己判 —— 判法只在发布登记一处。读发布段的那个目录守卫自己记了一份、不去装履历零件:
说话这条路只许装需求零件与会话台账(「零件用到才装」,主自测 LZ 组守着),与履历零件的那一份由需求对账床对拍相等。两行点名的交接:完结之后、清理归档之前,这条需求由「待清理归档」那一行点着(它的发布段可能还是完结之前写的);
清理归档末尾重算之后,计划已不在计划目录、那一行消失,由「待发布」接手,直到站点在它完结之后发过一次并登记。
**守不到**:① 收尾单写得对不对、主控转没转给用户、会话清没清空,机器都不核(前三栏也由机器起草:它抄的是账上的事实,为什么没做、去向该改成什么,机器不替办理会话想;草稿原样过得了格式这一关,写得对不对靠主控与用户看原文);「收尾单发出、清理归档跑完、站点那一格翻了,项目经理才关会话」是纪律(没有「治理站点」一格的需求不等这一样;项目架构设计页第十节)。② 收尾单不进履历:它在验收之前就由机器起草过一次,验收完结之后那一次接力命令刷新过才定稿,那时履历已经封死,
随计划进归档;治理站点从归档里取每份计划的看板与收尾单带进产物(项目架构页里每条需求的页签,动钱的需求不取;取材面与敏感内容那颗闸的射程归治理站点规范与治理规范),所以收尾单会随站点公开。③ 治理站点这一格只按发布台账判:站点回滚到更早的一版、台账被直接改过,它看不见;发布号读不出时刻时退到台账时间(到分),卡在打包与上线之间完结的那种情形就分不出来。
④ 站点页面上这一格显示的是构建那一刻的状态:站点发出去那一刻它还没翻,登记之后翻了,页面要到下一次发布才显示已发布 —— 比登记慢一拍。⑤ 「待发布」读的是发布段文件:一条需求完结之后既没清理归档、也没人跑过发布登记,
它的发布段还是旧的,这时它由「待清理归档」那一行点着;计划若被脚本进程内删掉(不是搬进归档),两行都不点它,要等有人跑一次发布登记。点名只在用户说话时出现,是守卫回给当场那个会话的话。
⑥ 这一步每次说话要读全部需求的发布段小文件:实测 25 条需求约 7 毫秒、100 条约 23 毫秒、300 条约 85 毫秒、1000 条约 297 毫秒;需求攒到几百条时该改成由发布登记顺手写一份名单,还没做。
⑦ 发布脚本发完站点之后还不会自动跑发布登记,要运维经理手跑;忘了跑,点名不会消失(自动记的只有「联调」那一格,正式发布的登记手跑)。站点发没发、什么时候发,机器只提醒、不拦。⑧ 已经搬进归档、当时没有收尾单的计划不回头查;起草写进第四栏的状态是起草那一刻的;验收之前起草的那一份,开头写状态的那一句、第三栏与各格的状态要等验收完结之后那一次接力命令(完结之后三步的第一步)才刷新 —— 不经接力命令、手跑清理归档又没先跑起草开关的,归档进去的收尾单开头仍写着那时还在办、遗留与各格状态是验收之前的,手跑的清理归档不拦(它只核在不在、五栏全不全)。
**部署门认联调**(ADR-100):部署门认联调、正式发布核验收完结。
只认「全部版本单元封着才让云端写入」一种状态的话,开发到一半要联调(建数据表、联调时部署云函数)就得先把施工中的单元封版,联调之后每改一行再封一次;正式发布也核不到这条需求验收完结没有。
一次云端写入(或脚本发布)到了发布门,先判它是联调还是正式发布,两条路各过各的关口;两条路上待检清单、资损床、内核装配、上传内容核对一样不少。
判法只有一份,住守卫的联调零件(`guard/trial.js`:纯判定加读写标记,用到才装 —— 只在进部署门、写后记联调、收尾点名与联调命令里装);
守卫的部署门、云函数脚本出口、静态站点发布准备调的是同一份(后两处与发布前版本比对一样,从仓里守卫的目录取它);
发布登记判「在办需求被命中的函数目录在不在它的落点表里」问的也是它(用到才装,见上「发布登记的新记法」四)。
① **联调成立要四样同时成立**:有口径(有效的联调标记;脚本通道另认发布命令上的需求名与联调两个开关 —— 给了就只认命令上那条需求、不读标记,没给照标记判);
那条需求在办(签过字、开了工、没完结、签字没作废、账本可信;签了字还在排队的不算在办,开不了联调);这次要上线的全部东西都落在它签过字的落点表里;这次要上线的是云函数或数据表(静态站点没有联调)。
四样缺一样 ⇒ 一律按正式发布判,并带一句联调为什么没成立(拼进后面每一句拦截报文)。判不了(需求零件出错、联调标记在却读不出来、在办需求盖着哪里无从得知、
账本目录或仓外镜像目录在却列不出来 —— 不存在算空,列不出来不等于没有)按拦处理 ——
守卫顶层退出码 2,脚本通道把错误当拒绝原因;没有「判不了就按正式发布放」的分支。
② **联调只放一道**:发布前版本比对(§十三 第 4 关)只放过这条需求落点表里的单元处于施工中(变更历史最上面加了新的一版、还没封);这些单元别的毛病
(封后改了没加新的一版、锁清单坏了)照拦;别的单元照旧要封着且一致。比对函数为此多收一份「放过哪些单元的施工中」的名单(缺省是空的,
名单外的施工中照报;整个框架在名单里时,守卫的框架锁极简比对也按施工中放过)。
③ **放行面 = 签过字的落点表,不另设登记**(ADR-111:这里的「落点表」指签字时的目录加主控已核准的目录 —— 签字之后新加、还没核准的目录不在放行面里,放行的单元同样只放签字时的单元加已核准的,没核准的单元不放;正式发布核验收完结那一道仍读整张落点表,宁多拦,见 ④):云函数 —— 函数目录下的源码文件(不算内核目录与依赖目录)有任何一个落在落点表的格里就算盖住(判落在哪一格用守卫需求零件现成的那一个);
候选的函数目录 = 这次给出的(脚本通道给的函数目录、云端工具通道落在仓里的上传目录)加上按函数名在 x-server 里找到的(目录名等于函数名、带入口文件或包配置的)。
联调要每个函数的每个候选目录都盖得住才放,正式发布任一候选目录被盖住就拦 —— 传上去的是哪一份认不准时,两头都取严的。
数据表 —— 表文档(x-data 里文件名等于表名的那一份,每张表要恰好找到一份)落在格里。站点 —— 落点表里有任何一条目录写法落在这个站点的原料目录之下
(原料目录取发布库的同一份定义,与部署门待检范围同源;取不到按站点的顶层目录),或者是一条带通配、字面前缀够得着这个目录的写法(宁多拦不漏放);站点只用在下面 ④。
与写前拦截、收尾对账是同一个范围口径:这条需求签过字能改的地方,就是它联调能上线的地方。
④ **正式发布核验收完结**:按正式发布判的那一次,要发的云函数目录或站点源码目录被任一在办需求签过字的落点表盖住 ⇒ 拦。
「在办」怎么算:签过字、开了工、没完结的按此刻的整张落点表(还没核准的目录照拦);排队的(签了字、还没开工)不算在办,不挡正式发布;签字作废的(开过工的)也算在办,照签字时的目录加已核准的目录算(作废之后改过、没人签过的机器镜像不算数,否则把落点表改窄就能把正式发布放出去);
账本被直接改过的判不了完没完结,按在办算(此刻的落点表与留底的目录都算);机器镜像读不了而签过字没完结的照留底的目录算,连留底都没有就判不了、按拦。
**计划不见了也算在办**:守卫的计划状态表只列计划目录里有、机器镜像读得成一个对象的计划 —— 一条在办需求的机器镜像被写成空值、被删,整个计划目录没了,或者计划目录一时列不出来,它就不在那张表里
(计划目录是写前拦截的免检面,往机器镜像里写一个空值不用开闸;只照那张表认在办,正式发布就被一次编辑放出去了)。所以表之外另从账本认:
账本目录里每一份需求账本,加上仓外镜像里有、账本目录里没有的那几份,名字不在表里、开了工(有开工那一笔,或有一笔不带排队标的确认)而没有「已完结」的,算在办,这一道照旧拦、照旧点名它(名字取履历里记的短名,读不到用目录名)。
按什么范围算:账本目录里那一份可信(链没断、与仓外镜像一致)⇒ 最后一次签字时留底的目录;不可信、或只剩仓外镜像里那一份 ⇒ 全部签字留底目录的并集(只会多拦);
一条留底都没有 ⇒ 判不了、按拦。完结与否只看账本目录里那一份(只在镜像里有的才照镜像里记的 —— 镜像住在仓外、谁都写得进去,账本目录里那一份还在时不拿它当已完结的来源)。
按留底算的那几种,留底的目录连用例点名的测试也在内,比在办时按落点表算的略多拦。没签过字的、签了排队没开工的、已完结的不算。
报文固定以「正式发布核验收完结:」打头,点名第一条盖住它的需求(短名、目录名、哪个单元哪一格;站点写那条目录写法),
云函数那一句末尾带上联调开始的命令,站点那一句写明静态站点没有联调、等它验收完结再发。数据表在正式发布这条路上不核这一道,照旧过待检清单与全部单元的版本比对;
其余变更类调用(云存储、网关、权限、数据读写)既没有联调也不核完结;回滚与清理不进这一道(它们本来就不进部署门)。
⑤ **联调标记**(云端工具通道没有命令行参数,口径靠它):`.claude/tmp/requirements/trial.json`,一份,住需求账本目录(脊柱写保护,编辑工具与命令行直写写不进),
记着需求的目录名与短名、哪个会话开的、起于何时、有效到何时;有效 30 分钟 —— 从起始时刻算起,文件里把截止时刻写得再大也不多算;到期自动失效(文件不删,读的时候判)。
标记在却读不出来(半份、被改坏)时,云函数与数据表这两类判不了走哪条路、按拦,重新开始或结束才解得开。由体系守护命令的 trial 动作开与关:
`node .claude/skills/x-harness-dev/scripts/harness.js --action=trial --begin --plan=<需求名>` 开(需求名写目录名或短名,要对上恰好一条在办的需求;
同一条需求再开是续期;另一条需求的标记还有效时被拒绝),`node .claude/skills/x-harness-dev/scripts/harness.js --action=trial --end` 关,只写动作名是看状态(只读)。
脚本通道等价的写法:`node .claude/skills/x-deploy-dev/scripts/create-deploy.js --target=server --path=<函数目录> --plan=<需求名> --trial`
(两个开关要同给、只用于云函数、要点名函数目录、不与全量发布、只验证、只读查部署门同给,写法不对当场拒绝;给对了入口先预判一次,判不了或正式发布那一道就不过的当场拒绝,
真正放不放由上传出口在上传之前再判一次)。统一入口把需求名放进环境变量 `X_DEPLOY_TRIAL_PLAN` 带到上传出口;没给这两个开关时,外面带进来的同名环境变量不算数(入口把它清掉)——
这一句只在经统一入口时成立:直接跑云函数子入口或 bff 下两个入口时,手设这个环境变量等价于带了两个开关,放不放仍由联调零件判。
30 分钟取的是一次联调动作的量:太短要反复重开,太长会把之后的正式发布误当联调。
⑥ **三条通道接同一个判定**:守卫的部署门在待检清单之后、版本比对之前判(环1「联调还是正式发布」);云函数脚本出口过门那一步
(`x-deploy-dev/scripts/server/core/deployer.js` 的 `gateFunctions`)在版本比对之前判 —— 被盖住就不过门、不上传,联调成立时把放过的单元交给版本比对;
静态站点的发布准备(`x-deploy-dev/scripts/release/publish-tests.js`)只在准备发布时核 ④ 那一道,核两次:跑床之前一次(版本比对之前;不过就不跑床、不准备档案),
打包发布档案之前再硬核一次(一律核、不看命令行 —— 测试与构建那一段时间里别的需求可能刚签了字)。带着只验证(`--validate-only`)或只装配看效果(`--materialize-only`)开关的那一次
不往线上放东西(不打包发布档案),跑床之前那一次不拦、只打印一行说明(判不了时同样只打印一行),照旧往下比版本、跑床 ——
手机端的需求封了版、还没验收时,要先装配出来给用户亲手验;拦了就验不了,也就完结不了。
**版本比对的问题行带封版命令**:比对函数给出的每一行(判不了那一行除外)末尾是「封版命令:」加那个单元的封版命令(取版本契约的那一份),三条通道原样打印这个函数给的行、不各自拼。
⑦ **联调自动记、收尾点名、完结那一刻重算**:经云端工具的联调 —— 放行的那次写入成功之后,守卫当场只往本会话台账记一笔(环2「联调放行之后自动记」),不写履历;
这一轮收尾时(第一次量工作树与归属之后;真写出了文件再重量一次),守卫把本会话台账里还没写进履历的每一笔写进那条需求履历发布段的「联调」一格(调发布登记的联调记法,一笔调一次,上线了什么写函数目录或表文档的路径),
写出的发布段文件给本会话记写证据、在同一次收尾里被复核,全部写完往台账记一笔「已写进履历」(带各笔的结果)。发布登记是体系守护技能的脚本(从守卫自己所在的仓取,现装),
不是系统规范也不是业务材料 —— 与部署门加载发布库同一个先例(见下「环1 静态托管发布面物理闸」里「数据只读」一条)。
为什么不在写后当场写:当场写出的发布段文件是一处没有干净结论的改动,同一轮紧接着的第二次联调上传会被待检清单拦下 —— 云端工具通道一轮就只能传一个函数。
连带三样:这一格里的时刻是写进履历的时刻(那一轮收尾),不是上传的时刻,次数照上传的次数;会话没走到收尾就断了的,台账里有那一笔、履历里还没写,这个会话下一次收尾时补写;
记不上的(那条需求没有履历、发布登记出错或装不上)不重试 —— 照样算写过,收尾的附注里说一次并给出补记的命令。这一段不是闸:整段出错(不是某一笔记不上)只在附注里说一声、
不记「已写进履历」,那几笔留到下一次收尾再写,不拦收尾。写进履历的结果与下面的点名在附注的同一处说,要说的话从台账那一笔取、不从内存取(继续拦的那一轮有不带附注的出口,只留在内存里的话就再没人说)。
经脚本通道的联调:一条命令发完一批,上传成功之后当场记一次;同一轮里紧接着再跑一次发布,会被它自己开头的「先查部署门」拦下(刚写出的发布段还没经收尾环复核),
要先结束这一轮 —— 与正式发布之后跑发布登记相同。
本会话凭联调标记上线过的,收尾时附注里点名一次 —— 上线了几次、哪条需求、标记是哪个会话开的
(不是本会话开的另注明)、上线了什么,并写明联调不算正式发布、验收完结之后照旧要正式发一次;只进附注、不拦,说过记一笔、不再说。
守卫记下「已完结」的那一刻(用户说话与答完选项题两处)顺手对全部履历重算一次发布段(内容没变的不重写),出错只说一声。发布登记的新记法见上「收尾单与治理站点一格」③。
**守不到**:① 机器只认有没有有效的联调口径 —— 这一次是不是用户授权的、是哪个会话在发,不核(授权是用户的一句话,机器认不出会话身份,§十五「谁来发布、怎么授权」)。
标记一份、全仓共用、谁都开得了:别的会话误用它,能让落点表里的函数绕过正式发布核完结那一道;兜着的只有收尾那一次点名(只说、不拦)。
② 放行面写得宽会把范围里没改的函数也放过去:落点表列的是整目录时,目录下每个函数都算盖住 —— 那本来就是这条需求签过字的范围。
③ 云函数按「仓里同名函数目录此刻的文件」判:云端工具通道传上去的若是仓外的包,按 x-server 里同名的目录认;同名目录不止一个时两头取严的(见上「放行面」那一条)。
x-server 里找不到同名目录、上传目录又不在仓里的,联调成立不了,正式发布核完结这一道也拦不到它 —— 它后面还有上传内容核对(没在仓里跑绿过测试的函数传不上去)。
标记文件在本机,脚本进程内写得了(与需求账本同一个前提);它不进账本的链、没有仓外镜像。
④ 机器认的联调只有云函数上传、建表与改数据模型三样:静态站点没有联调;网关(新建函数之后的建路由在内,见 ⑬)、云存储、数据读写没有联调这条路、也不核验收完结,照各自的关口判。
控制台里用户亲手做的导入与发布不经发布门,机器看不见、不自动记。
⑤ 签字作废的需求也算在办:它盖住的东西正式发布照拦,它自己的联调也不成立(联调要签字没作废),重签之后才恢复。那一次签字没有留底的老签字没有东西可比,只能照此刻的落点表算 ——
作废之后把落点表改窄,这一道就少拦(签字都带留底,这一支只为留底之前签的老账)。占着落点而不办了的需求,它盖住的函数与站点正式发布一直被拦:
没有「作废一条需求」这句话;删计划放得开单元占用那一处(见下「同一块排队」的守不到 ②),放不开这一道 —— 计划不见了照留底算在办(见上 ④),只有等它验收完结(计划删掉了的先恢复回来,见 ⑩)。
站点那一侧宁多拦:落点写得宽的在办需求会把不相干的站点发布也拦住,要等它验收完结。
⑥ 标记过了 30 分钟:之后的上传按正式发布判,被这条在办需求自己盖住而拦下,重开一次即可;反过来联调做完没结束,时限里落在这条需求落点表里的上传仍按联调判。
⑦ 联调自动记只是留痕:记不上不重试、只说一次(云端工具通道在收尾的附注里、脚本通道在脚本的输出里,各给出补记的命令),不影响别的记账,没有东西回头催;
写前到写后之间标记正好到期的那一次不记;记的是函数目录与表文档的路径。经云端工具上线的要到这一轮收尾才写进履历:会话没走到收尾就断了,台账里有那一笔、履历里还没写,
要等这个会话下一次收尾补写 —— 一直不再收尾就一直没写;这一格里的时刻因此是写进履历的时刻,不是上传的时刻。脚本通道同一轮里紧接着再跑一次发布会被它自己的先查部署门拦下,要先结束这一轮;
脚本通道的联调上传不经守卫写后那一支(它是一条命令,守卫认不出里面传了什么),本会话台账没有那一笔,收尾不点名 —— 它的留痕只有发布脚本当场记的那一格。
联调放行的那次云端工具调用,平台报成功而云端实际没成的,也会被记进「联调」一格 —— 机器只看得见工具返回了,不读返回里写的是成是败。
⑧ 开闸期间守卫写前那一道不在岗:经云端工具的上传写后只补判、记一笔、收尾报红,拦不回来(环2);两条脚本出口的判定在脚本里,开闸也照样判。
⑨ 发布之前的只读查(§九「发布之前先只读查部署门」)不查这一道:被在办需求盖住,要到过门那一步才报。
⑩ 计划不见了的在办需求(计划被删、被搬走,机器镜像读不成一个对象)从账本认得出、照留底的范围拦(见上 ④);看不见的只剩一种 —— 账本目录与仓外镜像两处都找不到它的签字记录,
那时这一道拦不到它盖过的函数与站点,收尾也点不了名。计划不在的需求联调开不了(联调开始与联调标记都只认计划状态表里的需求),把计划恢复回来才办得下去;
收尾会点名它一次(见上「清理归档」的守不到 ①)。计划不在时账本里的「已完结」照读到的算、不核那一笔可不可信:往账本目录里那一份直接添一笔假的已完结、
再把机器镜像写坏,这一道看不见(计划还在状态表里时,同一种改法会被判成账本被改过、照拦);账本目录是脊柱写保护的,写得进去的前提与联调标记相同(见上 ③)。
⑪ 内核不算进云函数的放行面:云函数按函数目录下的源码判,不算内核母本(x-core/server/sys)。只改内核的需求在办时,正式发任何函数这一道都不拦,而内核会装配进每个上传包
(手机网页版的原料目录带着母本包,改母本包的在办需求拦得住网页版的发布;云函数这一侧拦不住,两边不对称)。
⑫ 治理站点的正文取材于 .claude 下的受治文档,这一道只按站点自己的源码目录(x-harness)核:只改受治文档的需求封了版、没验收完结时,站点照样发得出去(发上去的是封过版的文档)。
发布登记却认定这类需求有「治理站点」一格 —— 两处问的不是一回事:这一道问发不发得出去,那一格问它完结之后发过没有。
⑬ 建路由不在联调里:联调只认云函数上传、建表、改数据模型。经云端工具新建函数之后的建路由算其余变更,照全量版本比对判,本需求的单元施工中时会被拦 ——
所以开发期联调上线时新建函数走脚本通道(上传与配路由在同一条命令里),带需求名与联调两个开关。
⑭ 守卫这一侧取站点原料目录靠发布库与端名册:装不上时退到站点自己的顶层目录,手机网页版的母本包目录就核不到(装不上是因为工作区地图读不到的除外:端名册文件在加载时读地图,那一种原样往上抛、守卫按拦,不退到顶层目录);发布准备那一侧直接调发布库,装不上就起不来。
⑮ **代授权的发布与联调**(ADR-116):代签的那条需求,验收完结那一签同时授权这条需求该发的每一格各发一次(出问题立刻回滚算同一次),开发中途的联调上线另按同一个设置由 X大脑 代用户授权 —— X大脑 把代签记录转给运维经理(不是用户的原话),运维经理照发。机器核的只有带标记的这一条路:代授权的发布与联调要在命令里显式带需求名和「代授权」标记(标记的具体写法由守卫的联调零件定,三处过门共用),守卫的部署门、云函数脚本出口(`deployer.js`)、静态站点发布准备(`publish-tests.js`)只核带标记的 —— 发布:这条需求的验收是代签、设置此刻仍允许这一类代签、要发的东西落在它签过字的落点表里、要发的内容指纹等于验收那一刻的,才放行 —— 其中治理站点不拿站点自己的源码目录去对落点表,改问这条需求有没有「治理站点」一格(治理站点发的是此刻封过版的整棵受治树,原料目录 `x-harness/` 只占其中一小块,只改受治文档的需求落点里没有它,而该不该发这一站本来就是这条需求有没有这一格):这一格的判法只有一份,住守卫的联调零件,发布登记给需求推格问的是同一个,三处过门问的也是它;答有、没有、判不了三样,有就过,没有就拦并写明这条需求没有治理站点一格,判不了(履历读不到、落点表是空的或形状不对)当没有拦并写明判不了,发布登记那头把判不了当有;后台、手机网页版、官网这些别的站点按落点表够不够得着原料目录认,内容指纹那一道对所有站点一样;联调:设置此刻允许这一类、这条需求在办、落点对得上(与上面 ①③ 同一个口径)。设置改成亲签之后,带标记的被拦并写明原因,那一类的发布、联调都要用户单次授权;内容指纹对不上同样拦。**不带标记的**(用户本人授权的)发布与联调:机器不核授权、不核是哪个会话在发,靠纪律 —— 亲签关掉的是代授权这条路,不是门强制用户在场。守不到:代授权的凭据是 X大脑 转来的代签记录,运维经理只认发件名是 X大脑 的消息当中转,发件名是平台给的,认得出叫 X大脑、认不出是不是主控本人;代签命令认主控靠会话登记册,登记册的口子(§二)同样是这里的口子;治理站点这一支只信履历里记的落点表(履历受写保护),不核它与盘上的文件对不对得上,内容指纹只比这条需求交付的、落在 `x-harness/` 之下的文件,它交付的受治文档不比 —— 验收之后别人改了别的受治文档、封了新版,这一道看不见,归版本比对与待检清单管。
守着它的床:`.claude/hooks/tests/trial-gate.test.js`(判定函数层与守卫入口层)、`.claude/hooks/tests/delegated-signoff.test.js`(代授权那一支)、`.claude/hooks/tests/release-versions.test.js`(问题行带封版命令、只放名单里的单元)、
`.claude/skills/x-deploy-dev/tests/deploy-gate-wiring.test.js`(两条脚本出口的接线)、`.claude/skills/x-harness-dev/tests/plan-trial.test.js`(联调命令)、
`.claude/skills/x-harness-dev/tests/record-release.test.js`(发布登记的新记法)。
**清理归档硬控**(ADR-97):这一段把三样交给机器 —— 放哪(一条需求的副本、备份、探针只放它自己的施工区、守卫不登记,ADR-112)、收尾照单清(施工区整份删,老计划留下的登记文件逐行核)、不做收尾与归档下一条开不了工;另让唯一运行器跑完自己清。
不交给机器的话,清理归档做不做没有关口拦,临时东西记漏了就清不到,不合规的登记行只是被跳过、计划照搬,测试跑挂留下的临时目录要等有人跑清理归档才清。
① **副本、备份、探针放进施工区,守卫不登记、只提醒**(ADR-112):办一条需求用到的一切临时东西只放这条需求自己的施工区 `x-test/zz-work/<需求名>/`(见下「项目自带」),登记的单位因此是这一个文件夹、不是逐个仓外目录。守卫写后记账那一支(`requirements.registerOutside`)不往登记文件里追加,只提醒:一次工具调用做完之后,守卫取出这一次的落点 —— 编辑工具(Write、Edit、MultiEdit)写的那个文件,或命令行里 mkdir、cp、mv、robocopy、xcopy 的目标,以及命令行里 powershell 或 pwsh 包着的命令串里建目录、复制、移动那几个动词的目标(New-Item、Copy-Item、Move-Item 与它们的常用别名;先问的那一句预筛 `command-policy.outsideMaybe` 与取目标用的是同一份动词名单)
(取法 `command-policy.outsideTargetsOf`:拆词、剥壳、cp 与 mv 取目标都用写前判落点的那一套;只取字面路径,带变量、通配、反引号、花括号的不取,以波浪号打头的不取;
同一条命令里先换目录再用相对路径建的,相对路径接在换到的目录后面,换到哪算不出的之后的相对路径不取)。先过一道便宜的预筛:落点的字面写法看着像在系统临时目录里
(以系统临时目录的路径打头、`/tmp` 打头、路径里带 tmp 或 temp 一段、带 scratchpad 一段;相对路径则看钩子给的当前目录)才去装需求零件 —— 普通命令与写仓里文件的编辑工具不因此多装零件(主自测「零件用到才装」对照表守着)。
需求零件里:这个会话是某条在办或签字作废的需求的办理会话(`handlerOf`)才提醒,办着几条的取最近签字的那一条;不是任何一条的办理会话 ⇒ 不提醒(签字之前的实验仍放系统临时目录)。落点按真实位置算(它还不存在时取最近一层存在的上级的真实位置再接上剩下几段),在系统临时目录之下的回一句以「【提醒】」打头的话 —— 副本、备份、探针放进本需求的施工区。不提醒的:
不在系统临时目录之下、或在仓库里面(仓库自己住在系统临时目录里时)、落点就是系统临时目录本身、在某个会话草稿目录(路径里名叫 scratchpad 的那一层)里面或就是它、在 Claude 自己那棵目录(系统临时目录下名叫 claude 的那一层)里。
同一个会话对同一个落点只提醒一次(记在台账目录的 `outside-reminded-<会话号>.json`,运行时产物、已被忽略)。出任何错都当没发生(提醒不许连累别的记账)。测试假仓、运行器的锁与输出、云函数上传包由脚本建、不经这一道。
挂在写后这一支:写前拦截摘下(开闸)期间照常在岗;带执行体身份的照提醒(提醒的是派它的那个会话办的需求)。
② **收尾:整份删施工区,老计划的登记文件逐行核**(清理归档零件 `plan-wrapup.js`):带需求名时(预览与执行一样),计划还留在计划目录的,在核过收尾单之后、搬之前:
(a) **施工区**:先核这条需求的施工区文件夹本身(`areaProblem`)—— 它是联接(符号链接或目录联接)、不是文件夹、或真实位置不在仓里 `x-test/zz-work` 之下(上面哪一层被换成了联接)⇒ 拒绝并点名,什么都不动(计划不搬、过程文件不清);没建过 ⇒ 不是问题,写一行「没有」。核过之后,执行时作为「清什么」的第四处整份删(不跟着联接走,见上 ④ 四)。预览与起草收尾单第二栏列出里面有什么。**只读盘点多列第五段「停滞区」**:施工区根下的每个文件夹,对应的需求已完结(计划还在或已归档)、计划已不在、还没签过字的 —— 名字、占多大、对应需求的状态与要删的命令(`rm -rf x-test/zz-work/<名>`),只列不删(守卫对这样的区谁都放);签字作废中且 7 天没动过的活区另加一个只读标注、不算停滞区;账本被改过或机器镜像读不了的需求的区单列一句,既不算停滞也不让删,先查清。
(b) **登记文件**(`registryFates`;只对留着登记文件的老计划有用,含归档里的,新计划没有这个文件):把登记文件逐行判成五种着落 —— 此刻已经不在(算已清);合规、这一次会清
(合规的判法就是上面「清什么」二那一条:绝对路径、按真实位置严格在系统临时目录之下、不在仓库里面、也没把仓库包在里面);收尾单第二栏里写明保留;三种都不是(其中指向整棵草稿目录的那一种先认:写明保留也不算、此刻在不在都不算已清,只能改登记文件);这一行判不了(读不了或权限不够,带原因)。后两种都算没着落。
**写明保留的固定写法**:收尾单第二栏(「二、没做什么、为什么」)下面单独一行「- 保留:<这一行登记的路径> —— <理由>」,理由不能空;路径要与登记的那一行是同一个(绝对路径按落到盘上的同一个位置比、Windows 上不分大小写)。
第二栏怎么切只问守卫的 `requirements.wrapupNoteSection`(收尾单的认法仍只住守卫一份)。有一行没着落(三种都不是,或判不了)⇒ 拒绝并点名是登记文件第几行、哪个路径、为什么,什么都不动(计划不搬、过程文件不清、别的登记行也不删),退出码非零。
都有着落才搬:写明保留的那一行不删并打印理由,已经不在的打印一行,该清的清。计划已经搬进归档的重跑不整条拦(登记文件从归档里那一份读):不合规的行逐行拒绝、其余照清、写明保留的不删。
没有登记文件、登记文件是空的不算失败;登记文件读不了 ⇒ 拒绝(判不了各行有没有着落)。**只读盘点多列第四段**:已完结的需求(计划还留在计划目录的、已经在归档里的都算)登记文件里此刻还在的每一行,
写明是哪条需求的、哪个路径、是等着清、写明保留(带理由)、不合规(带原因)还是判不了(带原因;逐行判,某一行读不了或权限不够只把这一行单列,不把整份登记文件报成还在);一行都没有时写没有。起草出的收尾单第四栏末尾那句说明按「治理站点」这一格发没发分两种写法(已发布的写它已经发过,不让人等);第三种(ADR-100):这条需求没有「治理站点」一格时,那一句改说它只有业务域落点、没有这一格,数据表与微信原生包在体系之外发(控制台、微信开发者工具)、不算进该发的格。
③ **阶段六的关口**(`requirements.wrapupGateWhy`,是开工条件的第三样,在开工条件那一个函数里与单元占用、判定代码占用出同一段话):签「确认」那一刻判、开工命令再判 —— 这份计划还没开工(第一次签,或排队的重签),
而状态表里有状态是已完结的计划(状态表只列计划目录下一层、带机器镜像的目录,所以就是「已完结、计划还留在计划目录」的那几条,不论是哪个会话办的)⇒ 开不了工:这一笔确认照签、记成排队。原因那一段以「收尾与归档:」打头,
逐条点名「<短名>」(<需求名>)、那一条的收尾单还没写或缺栏的同一句里写明(与「待清理归档」那一行里讲收尾单的半句是同一个函数)、各带清理归档的命令,末尾写明先把它们清理归档、已经开了工的需求重签不受影响;
确认那一支回话时写明这一笔记成了排队、在等它们清理归档。**已开工的重签不查**:与同一块排队「重签自己已经占着的不查」同款 —— 别人没做收尾与归档,不该把正在办的卡死。
**只挡开工**:不拦签字,不拦封版、发布与在办需求的写。因为它住在开工条件那一个函数里,三处自然一致:签字那一刻的回话;核对命令生成签字区时写的「签了之后是排队、在等什么」;排队一览第二段里这份计划在等什么、第四段里卡着它的是哪几条。
排队一览有一段**「卡在收尾、归档与提交」**:问守卫的 `wrapupPending`(此刻已完结、计划还留在计划目录的每一条:短名、收尾单现状、清理归档的命令)与 `wrapupGateWhy`(排着的计划逐份问),另列完结了等提交的每一条,
一条都没有时写没有;守卫里没有这两个判法或当场出错,只在这一段写判不了、别的几段照出。两句回话各多半句:「待清理归档」那一行在「计划还留在计划目录」后面多「(它搬走之前,新的需求开不了工)」;
验收完结那句回话的括号里写「计划整份搬进归档、过程文件清掉;它搬走之前,新的需求开不了工」(施工区随清理归档整份删)。
④ **运行器跑完自己清**(`bed-runner.sweepAfterRun` → 清理归档零件的 `sweepTestTemps`):唯一运行器每跑完一轮(床过没过都一样;账本里都新鲜、一张都不用补跑的那一支也算跑完一轮;只列不跑的不算),
把测试根下名字以进程号结尾、那个进程已经不在的测试临时目录清掉,每清一个打印一行;进程还在的不动;清不掉的打印一行、不影响这一轮的结论与退出码。认法与清理归档「清什么」三是同一份(`tempDirs`),清理归档里那一处也留着。
这一处在运行器的判定口径区之外。测试造的沙箱因此不进施工区也不做登记(这一类按名字加进程号认得全;老计划的登记文件只管仓库外面的目录,测试根下的沙箱记进去会被清理归档按规矩拒绝)。
**守不到**:① **提醒只认守卫看得见的建法**:脚本在运行中自己建的目录(脚本里建目录、测试在系统临时目录里造的沙箱)不提醒,测试跑挂留在系统临时目录里的沙箱没有人清;命令里带变量、通配或反引号的路径认不出;
解压、克隆、重定向新建文件这些别的建法不认;PowerShell 的同义动词只对命令行里包着 powershell 的写法起作用,而且只在写前拦截摘下(开闸)期间 —— 写前拦截在岗时那种写法本来就被拦;平台另有的 PowerShell 工具没接进钩子接线(上面「守不到之处」④),经它直接建的仓外目录不提醒,要接进去得改接线文件、归用户定;包着 powershell 的写法里目标带变量或由表达式算出来的、解压这类别的建法、cmd 包着的建目录同样不认;robocopy 与 xcopy 的目标写成以单个斜杠打头、后面全是字母的(与它们的开关同形)不认。
预筛按字面写法判:相对路径而钩子给的当前目录不像在系统临时目录里的不提醒(写前拦截在岗时,当前目录不在仓根的相对落点本来就被拦;摘下期间这种写法照跑、会漏)。提醒只是提醒:东西放在了施工区之外,机器不拦、清理归档也清不到,靠办理会话照着这一句挪回施工区。
② **签字之前建的不提醒**(那时这个会话还不是哪条需求的办理会话,签字之前的实验本来就放系统临时目录);不是办理会话的会话建的不提醒;办理会话认错的时候(见上「办理会话」的守不到)提醒跟着记错人。
③ **老计划的登记文件本身被手改机器不核**(删掉一行,那一行就不再被核、也不再被清);保留的理由写得对不对不判,只认写法;写明保留却早已不在的那一行按保留打印(先认保留)。
④ **阶段六的关口只挡还没开工的需求开工**:一条已完结的需求一直没人做收尾与归档,会让后面所有新需求排着开不了工,出路是任何会话都可以替它写收尾单、跑清理归档(命令不认会话);排着的会话提前往仓里写它不挡(挡它的是写前按办理会话判);
已完结的计划被脚本进程内删掉(不是搬进归档),这一道跟着放开、没有任何一处点名(与上「清理归档」守不到 ① 同一个边界)。
⑤ **运行器只清认得的那一类**:进程号被别的进程重新用上的按还在、这一次不删;不经运行器直接起测试留下的,要等下一次运行器或清理归档。
⑥ **脚本进程里的写绕过写前拦截**(§十三 诚实边界⑤):办理会话撞上过一次 —— 脚本在闸关着的时候改了受写保护的测试运行器,直到用编辑工具补最后一笔才被拦下。
要不要补一道事后的核对(受保护的文件在闸关着的时段里变没变),归守卫盘点那条需求。
**项目自带**(ADR-112):一条原则、一个单位、七件事。
**原则**:办一条需求用到的东西都放在项目文件夹里,换电脑时把整个项目文件夹拷过去就能接着干。必须留在项目外的只有三类,换电脑清单(项目架构设计页第十节最后一个小节)里逐类写明理由:Claude Code 平台自己的目录(会话记录、会话临时目录、用户级设置、信任与授权);本机装的工具与账号登录态(node、pnpm、tcb 与它的登录、python、git 与它的本机设置、微信开发者工具、x-vpn 写进 PowerShell 启动文件的那一行、代理程序的配置与授权);只活一次运行的东西(测试临时搭的假仓与运行器的锁、输出放系统临时目录;云函数上传包永远在项目外 —— 云开发的打包器按忽略清单剥掉 `sys/`,放在项目里发上去的就是缺了内核的包)。测试假仓搬进项目留给后面的「测试用工作树」那一步。
**单位是施工区**:每条需求一个文件夹 `x-test/zz-work/<需求名>/`(需求名就是计划的目录名),办理会话的整仓副本、前后对照、探针、换文件前的备份、过程记录只放这里。git 不管(忽略清单里 `x-test/zz*` 那一行盖住它),测试根里以 `zz` 打头的目录不当床。**要留给复盘和后续步骤看的记录**(耗时、前后对比、改坏对照)**不放施工区** —— 它归档时整份删;写进计划目录或设计目录。
① **守卫隔开别的会话**(写前拦截;`requirements.workAreaOf / workAreaStateOf / workAreaWhy` 判,命令判定零件 `workAreaBlock / deadAreaTarget` 接线):往施工区里写 —— 编辑工具,以及命令行里认得出落点的写(重定向、sed -i,与命令判定零件里那张写命令全集 `PATH_CMDS` 的每个动词:cp、mv、rm、rmdir、mkdir、touch、ln、install、rsync、tee、dd、truncate、chmod、chown、unlink、rename、rimraf、del、del-cli;mv 的来源算删)—— 只放这条需求的办理会话(在办或签字作废中;执行体与派它的会话同一个会话号,改派后跟着改派)。别的需求的办理会话、没签字的会话、施工区根与根下直接放的散文件、名字对不上任何在办或签字作废中的需求的文件夹,写一律拦,报文三句:这个区归谁、你是谁、怎么办;床里不传会话号不判这一道(与顶层围栏同一个规矩)。
跑施工区里的脚本(node、python、sh、bash 的主脚本与 node 的预加载,和直接当命令词的路径)同样只放这条需求的办理会话 —— 副本里要跑引擎和守卫;没签字与不是办理会话的会话走闭集白名单,它只放受治树里已有的脚本,施工区不受治,所以跑不了。**死区只许删、不许写**:需求已完结、计划已归档、计划已不在、还没签过字的文件夹(`closed / archived / gone / unsigned` 四种),写拦,删除类动词(rm、rmdir、unlink、rimraf、del、del-cli)谁都放,包括没签字的会话(要清它就直接删);需求账本被直接改过或机器镜像读不了的需求的区既不算死区、也删不掉(清理归档的脚本除外),先查清账本。换了目录之后的相对落点一律拦(持久的当前目录和同一条命令里的 cd 都认),绝对路径照常判;施工区这一道落点检查只对施工区,普通受治文件上 rm 的答案不因它变。
**命令里看不出落点的几种绕法也拦**(都在施工区那一道里):区名那一段(`zz-work` 后面第一层)带通配、方括号、花括号展开(分词器把 `{` 当分组切开、只剩前缀,所以另记下紧挨着 `{` 的那个词)、反斜杠转义、变量、波浪号、感叹号、反引号的写法(`x-test/zz-work/[j]ia`、`ji\a`、`j{ia..ib}`、`*`),shell 会展开成别的区名,字面判不了动的是哪个区,不分办理会话与否一律拦;没签字与不是办理会话的会话删死区的免检只给「磁盘上真有、路径文字干净、从仓根往下一路没有联接、所在的区确是死区」的路径;删除类命令(含 mv 的来源)的路径穿过联接(联接里面的路径,或联接后面写了尾斜杠 —— Git Bash 的 `rm -rf 联接/` 会跟进去删它指向的真目录)对办理会话也拦,不带尾斜杠地删联接本身放行(死区的「怎么办」一句因此写不带尾斜杠的删法);`cd` / `pushd` 进别的区再跑相对路径的脚本,按「当前目录(钩子带来的,接上命令里字面的 cd / pushd 目标)加相对路径」算出落点再判;`install -d` 建目录的操作数进直写清单,过保护目标与施工区两道。
② **施工区里的东西不受治**:路径判断只认仓根相对路径以精确的 `x-test/zz-work` 起头 —— 近似名(`zz-workshop`、`zz-work.bak`)与路径中段混进来的同名诱饵不算;写法换了照样认(大小写不分、反斜杠当斜杠、每一段尾巴上的点和空格不算、`/e/` 开头的盘符写法先换成仓根相对路径)。受治判断答「不受治」(先于「任何一层 `.gitignore` 受治」那一条 —— 否则副本里抄来的 `.gitignore` 会被当成真仓的忽略清单,列忽略清单的两个遍历也不进施工区),所以施工区那一支在写前拦截和写后提醒里都排在受治判断之前;写保护的五个谓词(脊柱、检测引擎、保护区、生成物、发布档案)对施工区答「不保护」(副本里的跑床账与射程缓存除外),副本里的 `.claude/hooks`、`.claude/agents`、`sys/` 才能用编辑工具改,真仓里同名的照旧拦,经 `..` 折叠出真仓路径的按折叠后的判。**例外 —— 副本里的跑床账与射程缓存**(ADR-121):副本里的 `.claude/tmp/ledger`(床账与准入册)与 `.claude/tmp/.scope-cache`(检测引擎的射程缓存)照真仓写保护,编辑工具与命令行都写不了(办理会话自己也一样)—— 副本床账里的结论会在换入之后被收回真仓(§十六「床账跨根」),收回去的结论不能比真仓自己记的更好改;副本里放一份键对得上、射程缩小的缓存,床里的检测就漏文件,该红的床在副本里变绿,指纹对得上就被收回真仓。`.claude/tmp` 下别的子目录(需求账、会话登记册、装配标记)收回的结论不读它们,与副本里其余文件一样照旧不保护(守卫 `.claude/hooks`、运行器、换入帮手也照旧能写);运行器与检测引擎在进程内写这两处、不经这道闸,副本里跑床、跑检测不受影响。写证据、收尾的工作树测量(`worktree-probe` 的 `PROBE_EXCLUDED`)都不记,写后不提醒「不在设计范围里」。
③ **检测引擎与站点都不进施工区**:索引不进 x-test;引擎自己走目录树的遍历(`scanners/file.js` 的 `ignoredByPath`)加路径级跳过,复用索引用的路径前缀名单 `IGNORED_PATH_PREFIXES`(`defaults.js`,名单里有 `x-test/zz-work`,只认这一条路径、不挡别处同名目录;名单里的 `.claude/tmp` 对遍历也生效,对任何规范的检测结论没有影响 —— 没有规范的射程落在那里,对拍台回放零差异,见上 §七「路径级忽略」);唯一运行器收床跳过 `zz` 打头的目录,它的卫生检查对 `x-test/zz-work` 及其下面的路径不验「是不是不存在的床」(这条路径在没人办需求时盘上不存在,而守卫、引擎、技能说明、设计页都会写到它)。治理站点的源清单、发布前待检清单、对拍台金标准都不读施工区。
④ **清理归档整份删**:见上「清理归档硬控」②。系统临时目录里我们自己程序留下的老残留不做常驻扫描代码:验收完结前由主控照清单列出疑似残留,BOSS 点头之后一次性手工删。
⑤ **造副本与换入两个动作**(体系守护技能,`core/work-copy.js`、`core/swap-in.js`):办理会话要改受写保护的东西(守卫、检测引擎、执行体定义、项目设置),先经 `harness.js --action=work-copy --plan=<需求名> --name=<副本名>` 在自己的施工区里造整仓副本 —— 不带 `.git`、各层 `node_modules`(只把来源仓根上那一层原样拷进副本,见下)、`x-test/zz-work` 本身、`x-release`、`x-demo`、`x-temp`、计划的归档目录、`.claude/tmp`(只带真仓的床账与准入册两份,见下)、`dist`、`.cache`、`.umi`、`miniprogram_npm`(按名字不带,各端主包与分包原样补回,见下)、`worktrees` 与一切联接,另按文件名不带本机才有、带明文密钥的几类(`.env` 一族、`.mcp.json`、`.npmrc`、各层 `.claude/settings.local.json`;预览里列出不带的规则,要用由办理会话显式放进去);副本根默认放一个**空的 `.git` 文件**当标记(副本在仓里面时不放的话,git 会顺着往上找到真仓、答真仓顶层;空 `.git` 目录挡不住;空 `.git` 文件让 git 一律以退出码 128 报错、绝不往上找,与副本在仓外时的退出码相同),旁边另存复制那一刻的指纹清单;复制用读写,修改时刻保留来源的、访问时刻设成此刻。**带账、补环境**:副本里的 `.claude/tmp` 不建空 —— 真仓的床账与准入册(`.claude/tmp/ledger/beds.json`、`.claude/tmp/ledger/bed-trace.json`)带进副本的同一位置,手机端包 `miniprogram_npm` 补回,来源仓根上的 `node_modules` 原样拷进副本,其余各层依赖不补、只点名(细节与理由见 §十六「床账跨根」)。
**标记副本里任何 git 命令都退出码 128**:要在副本里跑整套回归的(唯一运行器的卫生检查按版本库列文件、对拍台按提交读源码,都要真 git),造副本时加 `--git` —— 改在副本根建一个沙箱版本库:`git init`、提交一次基线、`objects/info/alternates` 指回真仓的对象库(不复制对象,仍不往上找真仓);沙箱库的配置只写副本自己的 `.git/config`(不转换行、不签名、提交人是占位值)。默认是标记文件:造得快,只跑带筛选的床够用。
副本里的守卫、引擎、技能的工具认根以副本为根;在副本上改、跑床,改好再经 `--action=swap-in --from=<副本根> --list=<清单> --backup=<备份目录> --base=<指纹清单> [--execute]` 换进真仓(不带执行开关只预览;执行时先备份并附指纹清单、用读写写目标并把修改时刻设成此刻、给本会话记写证据、写完逐字节核对、打印恢复命令),出事 `--action=restore` 换回;换入成功之后收回副本里跑出来的床账(§十六「床账跨根」)。**副本里删掉的文件也要从真仓一起删**:受保护文件的删除尤其如此(写文件工具与命令行只放行写、挪走与删除照拦),所以由换入帮手做 —— 清单里一行写「删 <相对路径>」或命令行 `--delete=<相对路径,…>` 显式标出(副本里缺一个文件分不清是删了还是漏拷了,不凭「副本里没有」猜着删);标删的路径在来源根里必须已经不存在、在目标根里必须是普通文件,一个路径不能既标写又标删;受保护的目标问的是与写同一份放行(这批里有一个不放行就整批既不写也不删),整批(写的、新加的、标删的)先备份完才动手,先写后删,删完核对目标已不在并给本会话记写证据;恢复时把删掉的放回原内容并核指纹。备份目录可以放在目标根的施工区里(`<目标根>/x-test/zz-work/<需求名>/…`,不能是施工区根本身,路径上不能有联接),不能放在来源根里面,也不能放在目标根里施工区之外(会被当成受治文件);复制之后真仓里的目标被别人改过、新建(复制那一刻没有、此刻有)或删掉(复制那一刻有、此刻没有,换入会把它原样复活)的,带 `--base` 时都拒绝;换入中途出错(比如第二个文件写不进去)也把恢复命令一并打出来,不留新旧混在一起的半截状态。换入帮手本身进脊柱写保护名单;它不绕过守卫 —— 目标是受保护文件时只认签字放行(ADR-116):这条需求在办、跑它的是办理会话、目标落在签字那一刻的落点表算出来的受保护格里(四样条件同环1「签字放行」),才放行,否则拒绝;手动开闸只在急救时用。
⑥ **平台读副本里的嵌套说明**:平台读、写或编辑施工区副本里的文件时(Bash 的 cat、head 读单个文件也算),会把里面嵌套的 `CLAUDE.md` 和 `.claude/rules` 当指令加载;项目设置里的 `claudeMdExcludes` 加了 `**/x-test/zz-work/**` 排除掉这两样(实测:不排除时读一个文件就加载五个,排除后一个都不加载,只剩项目根的宪法)。副本里的自研技能说明(`.claude/skills/*/SKILL.md`)排除不了:`/名` 仍跑根上的那份,但平台会把带目录前缀的那份也列给模型,并引导它在副本里读写文件时用副本那份 —— 多列一份、占上下文,读真仓文件时有误用副本版本的风险。
⑦ **记忆搬进项目**:Claude 的自动记忆目录由用户目录改到项目里主控线的目录下(具体位置写在主控线总账里),文件入库、跟着项目文件夹走;设法是 Claude Code 的 `autoMemoryDirectory` 写在本机的项目本地设置 `.claude/settings.local.json`(不入库,值是盘符开头的绝对路径;官方文档:任一设置层都认,值须是绝对路径或 `~/` 开头,并受工作区信任),本地设置不生效就改放用户级设置。该设置只对新开的会话可靠;所有会话共用一个记忆目录,搬家那一下挑没人在跑的时候。换电脑要装什么、带什么、做什么写在项目架构设计页第十节「换电脑清单」。
**守不到**:① 施工区的隔离只拦编辑工具和命令行里认得出落点的写:脚本进程里自己写的东西、落点带变量通配反引号的写、经施工区里的联接或硬链接去写真仓的路(词法看不出)、8.3 短名这类别名、云端工具(MCP)往本地落盘的写,都拦不住;系统临时目录以外的仓外落点既不提醒也不清。② BOSS 手动 `git clean -xdf` 会清空全部施工区(含换入前的备份)。③ 施工区里「要留的记录」和「施工材料」分没分开,机器不核。④ 计划目录下的文件命令行删不了、挪不走,作废的记忆只能改写成作废说明并从索引里拿掉。⑤ 写保护的几个谓词对施工区答「不保护」(副本里的跑床账与射程缓存除外,见上 ②)是有意的取舍 —— 副本里得改得动守卫才叫副本;换进真仓那一步由换入帮手与写前拦截把关。⑥ 副本里的技能说明会被平台多列一份。⑦ 记忆目录的设置对已开着的会话不保证生效,要请开着的会话重开。⑧ 脚本自己的命令行开关别取 `-e`、`-p`、`--eval`、`--print` 这几个名字:守卫查 node 的求值开关时连脚本后面的参数一起看,会把它们当成求值当场拦下(核准命令的指纹开关因此叫 `--fp`;守卫那道安全墙不放宽,放宽要另起一条认真审)。⑨ 写工具的 NT 前缀(`\\?\C:\…`)和 UNC 管理共享(`\\localhost\C$\…`)写法折不回仓根相对路径,区隔离拦不住 —— 受治业务文件上的需求闸有同一个洞。⑩ 「认得出落点的写」只有命令判定零件那张写命令全集 `PATH_CMDS`(含 `install -d`)加重定向、`sed -i` 这几类;全集之外的命令(`find -exec rm`、`xargs rm`、`shred -u`、`split`、`tar -C`、`curl -o`、`git clone` 到区里、Windows 的 `copy` / `move` / `xcopy` / `robocopy` / `rd` / `attrib` 等)往别人的区里写拦不住。⑪ 换了目录再跑相对路径的脚本,当前目录算不出时(`cd` 不带目标、`cd` 带变量、`pushd +N`、`popd` 之后)只能照字面判,字面里没有 `zz-work` 就放;带逗号的花括号展开(`{a,b}`)本来就被「命令名混淆」那一道拦下,序列写法(`{1..3}`)由紧挨着 `{` 的那个词认出。⑫ 删除类命令穿过联接才拦;写类命令经联接写进它指向的真目录(办理会话自己挂的 `node_modules` 联接就是这样)拦不住,与 ① 里「经联接去写真仓」是同一个边界。⑬ 标记副本(默认造法)跑不了整套回归,要整套的加 `--git` 造副本;沙箱库的提交人、换行配置是占位值,副本里提交的东西进不了真仓(换入只认文件内容);alternates 里写的是真仓对象库的绝对路径,换电脑或挪了仓库目录之后要改,重新造一份更省事。沙箱只往自己的对象库里写(床里钉着:在沙箱里提交、打标签之后真仓的 `.git` 一个字节没变;沙箱里没配远端、推送没地方可去;拿掉 alternates 沙箱自己的历史与对象照样齐全),真仓那一头是只读的借用;**反过来真仓哪天 `gc --prune` 清掉不再被引用的提交(比如改写历史之后),还活着的沙箱借读那些提交就报缺对象** —— 沙箱自己的基线对象是它自己写的(alternates 在提交之后才写),不受影响,借的只是真仓的历史。所以沙箱只活一条需求,用完随施工区整份删,不留着长期用。
**接力命令**(ADR-98):一条需求从实施完到开出验收区,中间的机器节点各是一条命令;不串起来,
谁先谁后、跑没跑全靠办理会话记着、靠主控发消息催,跑红了自己判断从哪接着来。体系守护命令的 run 动作 `harness.js --action=run --plan=<计划名>`(零件 `x-harness-dev/scripts/core/plan-run.js`),
把它们串成一条命令,分三段。**复盘结论入账之前七步**:增量检测 → 按改动跑床 → 规范同步(落点表里每个系统规范域一次)→ 封版(这条需求改到而还没封的单元各一次,用版本契约给的那条封版命令)
→ 固定检查 → 三查 → 生成复盘说明,末尾先印一段夹在两条分隔线之间的派发表头(几行字,与复盘说明命令印的是同一段,派复盘者时提示词就是它,见下「复盘进关口」)、最后一行是复盘说明的编号,停下等办理会话派复盘者。七步的名字与次序固定,封版那一步自己先把它要读的账备好(固定这样做,没有开关):这一步真有要封的单元时,
封版之前先调一次固定检查那个程序(账新就沿用,不新就跑;没过就停在第四步并点名是哪一项;没登记固定检查的照实说没有要做的;没有要封的单元就不备账),第五步「固定检查」沿用 —— 封版命令自己的需求对账要第二查绿,而第二查含「登记的固定检查对当前内容全过」。
**复盘结论入账之后三步**(再跑同一条命令):三查 → 开验收区 → 起草收尾单,末尾打印「可以弹验收题」。
**验收完结之后三步**(已完结、计划还在计划目录的需求再跑同一条命令,开头那一行写「已完结:走完结之后那三步:刷新收尾单 → 预览清理归档 → 清理归档」):刷新收尾单(清理归档的起草开关;已有收尾单只刷新机器管的几处,办理会话写的去向照留)→
预览清理归档(不带执行开关;它拒绝就停在这一步、原话带出,核的是它打印了预览的结论)→ 清理归档:先问清理归档零件的 `archiveHolds` —— 只问一样:跑床与建站两把锁都没有活着的进程拿着(判不了的锁照拦;归档搬的是站点取材面,别人正在建站或跑站点床时搬,它们读到的是半截,所以这一样是物理安全、不是在等人),
没人拿着才带执行开关真做、核过计划已从计划目录搬进归档目录,末尾打印「收尾归档做完了」;有人拿着就停在这一步、什么都不动,回话写明是跑床还是建站有人在,等它跑完再跑同一条命令(锁判不了的,写明哪把锁判不了,照原因修好再跑)。
复盘记录里的结论写了没有、收尾单第三栏的去向定了没有,都不问、不挡归档 —— 复盘和遗留、发现的去向在归档之后的后台办(见下「后台收尾」)。
跑床那把锁的位置问唯一运行器,建站那把锁的位置问站点构建器(用到才装;构建器文件不在当没有人在建站)。
走哪一段不用人说:已完结、计划还在计划目录的走验收完结之后三步(守卫需求零件的 `planStates` 认已完结,不重算三查);没完结的,命令开头当场只读重算一次三查(不落盘),
第一查绿(复盘结论已入账、而且对当前内容有效)走三步,否则走七步;七步里封版那一步在规范同步没有同步任何系统规范域时沿用开头这一次的结果单、不重算一遍,同步过的重算(同步可能刚刷新过条款书与架构页的派生区)。**它只接力、不判**:每一步起子进程调那一步自己的那一个程序(检测引擎的增量检测、唯一运行器按改动跑床(路数不写死,吃命令行入口的缺省,见 §十六「跑床分道并发」)、元治理的同步与封版、
业务域的封版入口、本技能的固定检查、核对命令、复盘说明的生成程序、清理归档的起草开关、预览与执行),不把它们的判法装进来另算一遍,也不新增任何一道拦人的闸(完结之后那一段第三步的两把锁,判法住清理归档零件的 `archiveHolds`,接力命令只交给它两把锁的位置、照它的结论停或走);一步红不红,听那个程序的退出码与它自己留下的账。
不经它、一条一条手跑,结果完全一样。**哪一步红停在哪一步**:打印到了第几步(共几步)、那个程序的原话、修完从哪一步接着跑;后面的步骤不跑、不留新的产物。**不另记账**:
接力命令自己不记哪一步过没过,重跑总是从第一步核起 —— 前面过了的几步因为各自的账很快走过(床只补跑不新鲜的,固定检查内容没变不重跑,已封的版不重封)。**没有要做的照实说**:
落点里没有系统规范域、没有改到而没封的单元、没登记固定检查、改到的文件没有测试覆盖,那一步打印「这一步没有要做的」并算走过,步号不变。**每一步核产物**:程序退出码是 0 还不够 ——
床的账、封版记录、固定检查的账、三查结果单、复盘说明、收尾单、归档目录里的那一份计划各由各的程序写出,这一步走完要看得到它那一份,看不到就报这一步没跑成(预览清理归档没有落盘的产物,核的是它打印了预览的结论;生成复盘说明那一步另核现算得出派发表头,出不来也报没跑成)。
第一步增量检测没有落盘的账,核的是检测程序打印的结论:退出码是 0 却一个字都没打印,报这一步没跑成(防的是检测程序被换成什么都不做)。
**改动文件一份规范都不适用时照实走过**(ADR-103):这时检测程序本来就退出码 0、一个字不打印 —— 一律把它判成没跑成的话,整条停在第一步,
只能手跑后面几步(一条只改说明文件、落点写 none 的需求撞过)。所以逐批看:一批退出码 0 而没打印时,先问检测引擎现成的射程(`plan-run.specCoverageOf`:与增量检测那一段同一套 ——
索引器、规范发现、射程缓存,元规范不算;接力命令只读借用,不另算、不改引擎):这一批一份规范都不适用 ⇒ 按「没有规范覆盖」照实走过、打印一句说明(这一步算过了,不是「这一步没有要做的」),
接着跑后面几步;有规范适用而一个字没打印的,报没跑成,并点名是哪几个文件、哪几份规范;射程判不了(引擎装不上、算不出)也按没跑成算。代价:每个一字不打印的批次都要算一次射程,
没有缓存时一次约 9 秒。**第一段的三查那一步怎么算红**:
复盘入账之前第一查必红(还没有复盘)、核对命令的退出码恒非零,所以这一步不看退出码、看它写出的结果单 —— 第二查、第三查必须绿;第一查里「复盘」之外的几样
(账本没被改、有基线、台账读得了、认得出办理会话、步骤全勾、办理会话零越界)照结果单里「第一查红在哪几样」那一栏读(`c1Red`:恰好只有复盘那一个键 `review` 才算只差复盘),除了还没有复盘之外还有别的就停在这一步、
把那几样带出来;那一栏不在(核对命令还是没有这一栏的旧版)就是判不了,同样停在这一步,不拿结果单里别的栏去猜。**第二段的开验收区那一步不另起程序**:三查全绿时核对命令已经把验收区写进看板,
这一步用守卫的 `boardToken` 核它开着的是「验收完结」那一道、里面记的就是刚算的那张结果单与内容编号。
开头与末尾各打印一次这条需求在环里的态(§十四「项目架构环的十态与启动、收尾」)。它只对脚本自己所在的仓跑(不收改仓根的开关:各步的程序都按自己所在的仓认仓根)。守着它的床:`.claude/skills/x-harness-dev/tests/plan-run.test.js`。
**守不到**:① 它串的是机器节点 —— 派复盘者仍由办理会话做(复盘要一个干净的上下文,机器派不出「干净」,见 ADR-98 否决栏),签字一仍是用户(验收完结按代签设置由用户本人或 X大脑 代签);它不排窗口(开闸不是日常窗口),
跑床要的那把仓库级的锁,由主控排、由锁排队;② 「只差复盘」只读结果单里那一栏(第一查绿不绿就按它空不空算,「要再复盘」的各种情形统一是一个键):那一栏的键表改了,接力命令认「只差复盘」的那个键要同批对,
对不上的后果是该往下走时停住、或不该走时多生成一份复盘说明(不放行任何东西 —— 完结那一关仍是三查全绿加用户签字);③ 固定检查在一次接力里可能被叫两回(第四步备账一回、第五步一回),第二回靠它自己的账沿用,不重跑;
④ 档只打印、不改步骤(这七个程序里没有哪一个按档取舍);⑤ 一步的程序写了一半被打断(机器睡眠、进程被杀),留下的半份账由那个程序下次自己认,接力命令不会自己续,重跑从第一步核起;
⑥ 子程序的输出这一步结束才打印,跑床那一步中途看不到滚动的输出(每张床的输出在运行器自己的日志目录);
⑦ 「没有规范覆盖」信的是检测引擎的射程:射程把有规范管的文件算成了没有,而检测程序又恰好一个字没打印,这一步会照实走过 —— 要两样同时出错;
退出码非零是红,不走这一判。
⑧ 完结之后那一段只问两把锁:复盘结论和去向写没写、写得对不对,既不核也不挡(只在十态清单与结案报告里显示,见下「后台收尾」);验收完结之后没人跑它,计划就留在原处(阶段六的关口挡下一条的签字);⑨ 两把锁只看问的那一刻:问完到归档之间才起的跑床或建站,挡不住;⑩ 站点构建器文件在而装不上(或没导出取锁文件的函数),建站那把锁判不了、照拦、不归档,构建器文件不在当没有人在建站;⑪ 手跑清理归档带执行开关不看锁 —— 这一道只在接力命令里。
**环的十态**(ADR-98):体系守护命令有一个只读动作 `harness.js --action=loop [--plan=<计划名>]`(零件 `x-harness-dev/scripts/core/plan-loop.js`)。带计划名:这一条此刻在哪一态、凭什么、环几点启动、
几点收尾(没收尾就写还差哪一样)、下一步该谁做什么;不带计划名:计划目录与归档目录里每条需求各一行。只读:不写任何文件、不起子进程。十态的名字、次序、各自的认法与下一步
只有零件里那一张表(`STATES`),本文 §十四 逐字抄它。**判每一态用的事实都取现成的,不另算**:在不在计划目录、签没签字、开没开工、完没完结、账本可不可信,问守卫需求零件
(`planStates`、`readEvents`、`ledgerIntegrity`);办理会话问 `handlerOf`;已封版看落盘的最新三查结果单第三查是绿的、而且算的是当前内容;复盘过看账本里最后一笔可信的独立复盘是「过」、
对着当前内容、之后用户没有说过「不过」;待验收看看板签字区此刻开着的是「验收完结」那一道(守卫的 `boardToken`,一键签认的同一个记号);已发布看需求履历的发布段(发布登记写的)
状态是「已发布」(发布段还没翻时另拿发布台账对一下治理站点那一格,用的是发布登记自己的判法,只为在打印里提示「差的是跑一次发布登记」,不改态;这句提示只对该有「治理站点」一格的需求出,只有业务域落点的需求没有这一格);已归档看归档目录里(逐个日期目录找)有这份计划、而计划目录里已经没有它。完结之后只看发布与归档两样;完结之前从后往前认 —— 走到了后面的态,前面几态自然都过了。
**表里没有的几种情形单独说、不另立态**:签字作废的,态照事实算并注明后面几态要等重签之后重新走,下一步换成刷新签字区、重签;签了字还在排队的,态算已立项并注明在等什么,下一步换成排到了由项目经理(或主控)跑开工命令(签字又作废、要重签的,下一步另写「排队、要重签」);账本被直接改过的,态照账本的字面算并注明不可信;
机器镜像读不了的只按账本算并注明;签过字没完结而计划不在计划目录了的,注明并把下一步换成主控去查;计划目录与归档目录里各有一份同名的,按还没归档算。
启动的时刻取开工那一刻(当场开工的取账本里第一笔确认,排队的取账本里的开工那一笔);收尾的时刻取「发布段最后一次写出」与「归档里那份计划目录的状态变更」两个时刻里晚的那一个;打印一律换成本机时间并注明。
**在办的需求多一行红旗**(ADR-120):在办的需求(开了工、没完结)若过程复盘的耗时表生成器按在办期的口径算出红旗,多打一行「红旗:…」(带计划名时紧跟在办理会话那一行后面,列清单时挂在那条需求下面);排队的、已完结的不打,账本读不了、生成器装不上都当没有红旗、不挡十态、不抛错。红旗是什么、门槛住哪、为什么在办期只认三种,见下「过程复盘的耗时表与红旗」。
**后台没办完的多一行**:不带计划名列清单时,新式专项的复盘结论或去向还没到,就在那条需求的「注:」「红旗:」之后挂一行「后台还在办:…」,办完的、老式的不挂;带计划名的十态不加这一行(结案报告里有一栏)。取数与新老式怎么分见下「后台收尾」。
**守不到**:① 出的是落盘的样子 —— 结果单、签字区、发布段都只读盘上那一份、不当场重算:改了文件还没重跑核对命令、发了站点还没跑发布登记,看到的仍是上一次的
(「已封版」另核结果单算的是当前内容,「待验收」另核签字区里的内容编号是当前的,对不上就不算);② 「复盘过」只核那一笔可信、是「过」、对着当前内容、之后没有「不过」:
复盘之后范围里的文件又变过的,要等核对命令重算才看得出;③ 收尾的时刻 —— 发布段只在内容变了时才重写,归档目录里事后有人增删文件会让时刻变晚,两样都读不出就照实写读不出;
④ 不带计划名时只列计划目录与归档目录里的,完结之后计划被删掉的旧需求(清理归档之前的老做法)不列;⑤ 会话清没清空机器看不见,不入态;⑥ 它不落盘、不提醒,判错只会误导看的人,
不拦任何东西;⑦ 本文 §十四 抄的那张表与零件里的常量表一不一致,没有机器对拍,改一边要同批改另一边。守着它的床:`.claude/skills/x-harness-dev/tests/plan-loop.test.js`(只核零件自己那张表与各态的认法,不读本文)。
**过程复盘的耗时表与红旗**(ADR-120、ADR-121):体系守护命令有一个只读动作 `harness.js --action=retro --plan=<计划名>`(零件 `x-harness-dev/scripts/core/plan-retro.js`),对一条专项出过程复盘的耗时表与红旗。
**只读**:不写任何文件、不起子进程。已完结的专项按验收之后的口径(按 8 条门槛查),在办的按在办期的口径(按 3 条门槛查);账本取自需求账本、会话台账、跑床账(只取封版记录和「全仓有动静」的证据,不从这里数次数)、运行器的跑床记行(`.claude/tmp/ledger/bed-runs/`,见 §十六「跑床分道并发」;跑床次数、并行度、CPU 占用只读这一处)、封版与发布记录,读法同现有的零件、不另算一遍,
账本里缺的项写「—」、不抛错,读不了账本就照实说原因。**表里有什么**:各段耗时(写计划到签字一、排队、开工到第一次换入、实施、封版、独立复盘几轮、等验收、发布、归档、提交)、各执行体从第一笔到最后一笔、
跑床(按运行器记的行算,直跑的不在内:总次数与机器时间,跑得最多的五张床与单次最慢的五趟,跑床并行度〔床自报用时之和除以跑床墙钟〕与跑床期间 CPU 占用〔整机占用按各趟跑床墙钟加权平均〕两项)、收尾环(轮数与合计时长)、拦截按原因计数、跑得慢的命令(超过生成器里那一档秒数的:条数与合计时长)、休眠。取数口径:封版时刻取跑床账里的封版记录(只对已完结的需求找得到),第一次换入取受保护文件的放行留痕,账里缺了写「—」(不碰受保护文件的需求「开工到第一次换入」恒为「—」)。跑床各项取运行器记的行:真仓里的行按会话号认(这条需求的办理会话和它派的执行体是同一个会话号),这条需求施工区里各副本记的行就地全算(副本里记的行留在副本自己的账本目录里,清理归档之前读得到),两处都只认开跑时刻落在开工到完结之间的行。「独立复盘」一段从派出第一轮复盘算起(审查官不带名字派、守卫只记带名字的派出,所以多半没有派出记录,这时取审查官在会话账里第一笔带执行体名的动静;两样用同一个过滤:落在开工到完结之间、不早于最后一次封版),到最后一轮结论入账;两样都没有这一段写「—」,不拿封版顶替。**命令原文一个字都不打印**:
表会进收尾单、随治理站点公开(上「收尾单与治理站点一格」守不到 ②),表里只放数、时长和原因的名字。
**休眠**:全仓所有会话(不止这一条专项)的台账同时一笔都没有、并且那段时间里没有命令在跑(按台账里每条命令记的起止算),长过门槛的那一段 —— 关机、睡眠就是这样。表上单列一类「休眠」(段数与合计时长),
各段耗时里减掉它,不算等待、不算卡住;最小长度和「两笔动静之间空多久算红旗」共用生成器里同一个常量,短的不单列。全体台账都空、但中间有一条长命令在跑(台账里记着起止)的那一段不算休眠,照常算空档。
**红旗**(门槛的数只写在生成器 `THRESHOLDS` 一处,本文不抄;表上与十态都照打出来,一条一句人话、带门槛与实际值):验收之后按 8 条门槛查(表头写「按 8 条门槛查」,说的是查几种、不是亮了几条;亮了几条看表后「红旗(N 条)」那一行)—— 某一段超过这一档的时长上限(档的上限只读守卫需求零件里现成的那一张;档上限说的是「办的时间」,所以只比开工之后、验收完结之前的做事段 —— 开工到第一次换入、实施、封版、独立复盘 —— 和办的时间合计,写计划、排队、等验收是等人,发布、归档、提交在验收之后〔发布常隔天批量做,比了会常亮〕,表上都列时长、都不比;排队的需求没开工、红旗恒为空)、
同一张床跑得太多次(按运行器记的行里的床清单数出来,直跑的不在内)、同一种拦截出现得太多次、一条命令跑得太久、这条专项两笔动静之间空得太久(等用户签字、等验收的空档和休眠不算,剩下「别的会话在动、偏偏这条不动」的连续时长才算)、独立复盘不止一轮、跑床并行度低于门槛(床自报用时之和除以跑床墙钟,低了是该同时跑的没同时跑)、跑床期间 CPU 占用低于门槛(整机占用按各次跑床墙钟加权平均,低了是机器闲着)。这最后两条是「低于才亮」,前面各条是到了才亮(某一段超上限是超过才亮);这两条还要经运行器跑床的墙钟合计够生成器里写的分钟数才判,一两张床的小批本来就起不了池、样本太小,表上照列数、不判。
在办期只认其中三种 —— 同一种拦截出现得太多次、一条命令跑得太久、两笔动静之间空得太久:接力命令反复跑床是常态,「同一张床跑得太多次」和「某一段超上限」在办期会常亮,小批的并行度与 CPU 占用也天然偏低,所以这几条只在验收之后的过程复盘里算。
**十态用同一个生成器**:环的十态(上)对在办的需求用在办期的口径算一遍,有红旗就多打一行;项目经理巡检看到,当场报 X大脑,X大脑 照 §十五「遇到顶层问题的两种走法」后面那一段的口径定。
**复盘记录与收尾单里的表**:复盘经理写的复盘记录(放哪、谁写见下「后台收尾」)只放结论一行、发现每条一行与项目经理后补的去向一行,写法只住 `plan-wrapup.js` 的常量一处;表不抄进去 —— 接力命令每次刷新收尾单时现算(上「收尾单与治理站点一格」②),
所以账本变了再刷新一次表跟着变,到归档那一刻定格;归档之后现跑的表与定格的表怎么取、怎么对着看,写在 §十六「跑床分道并发」里「每次跑床记一行」那一条。
**守不到**:① 结论写得对不对、挖得深不深,机器不判,只核写没写(只用来显示,不挡归档,见下「后台收尾」)。② 卡住的命令账本里看不见,只能用「多久没动静」近似;歇下来等回话的空档和真卡住在账里分不开,都按空档算。
③ 休眠只认「全体会话的台账同时一笔都没有、也没有命令在跑」:机器开着、全体会话却都在等,长过门槛也会被认成休眠;命令跑到一半机器睡了,那一段算进这条命令的时长。
④ 用户在控制台里手工做的步骤(导入数据表、在微信开发者工具上传)账本里没有,表上不出现。⑤ 它只看这一条专项走过的这一程,整套体系的体检由体系体检官另做。
⑥ 门槛合不合适要看实跑;改门槛只改生成器那一处并同批改床,走框架需求。
⑦ 跑床各项按运行器记的行算,直跑的(不经运行器、直接起某张床)不记行、不在内,所以次数、机器时间和并行度只数经运行器跑的(表上写明「按运行器记的行算,直跑的不在内」);清理归档之后读不到施工区副本里的行,账本目录里 30 天前清掉的旧行也不计入;行是运行器自己写的,进程在写之前被杀就没有那一行;并行度的分母是整趟跑床的墙钟,含运行器自己的开销与池里排队,小批偏低,命令跑到一半机器睡了那一段也算进墙钟;CPU 占用是整机的,分不出是谁占的;拦截的原因只取守卫那句话开头的几个字词,命令里的参数和路径进不了表。守着它的床:`.claude/skills/x-harness-dev/tests/plan-retro.test.js`(用造好的小账本对拍各段耗时、计数、红旗与休眠,每条门槛两边各一条)与上面十态那一行的 `plan-loop.test.js`。
**后台收尾**(ADR-124):复盘经理的复盘、遗留与发现的去向,都在归档之后的后台办,不挡归档、提交和下一条开工。
**不挡什么**:接力命令清理归档之前只问两把锁(上「接力命令」);验收、该发的格、一条需求一个提交都照常。后台没办完的,既不挡提交,也不挡下一条的开工与签字 —— 复盘结论写没写、去向记没记,只显示、不拦任何事。
**放哪**:复盘记录住主控线的复盘记录目录,一条专项一个文件,文件名是需求名加 `.md`(位置与写法都只住 `plan-wrapup.js` 的常量一处,位置出自工作区地图的主控线区)。主控线整棵在工作区地图里是台账类(入库取「台账」),提交命令把台账随下一个提交一起带上 —— 所以后补的复盘记录与待立项目清单随下一次别的专项的提交进库,这条专项自己的提交带的是归档那一刻的骨架;用的是提交命令、开工条件、工作区地图的现成做法,一条需求仍是一个提交。需求履历(守卫写,脊柱加判官)与归档里的收尾单、看板在归档那一刻定格,之后不再改。
**骨架**:清理归档这一次调用真搬了计划时(接力命令与手跑带执行开关走同一处),紧接在「将搬/已搬」那一行之后建骨架:文件不在才建、已在不覆盖(复盘经理先建的不动),内容是一行讲三个记号怎么写的注释加一行空的「结论:」;预览只说将建、什么都不写。建不成(比如目录位置被同名文件占着)只说一句「没建成」、不拒绝,归档与退出码不受影响,复盘经理自己建这个文件也行。已归档的重跑、起草、盘点、存量都不建。
**谁写什么**:复盘经理写第一行「结论:」和「发现:」(下面每条以「- 」打头);计划已搬进归档的,它到归档目录读看板与机器镜像。X大脑 收结论与发现,连同完结那句回话列的遗留先过复杂化审查官的减法审,再逐条定去向(判法见 §十五「遇到顶层问题的两种走法」),交项目经理记:并进或排进清单的记待立项目清单、各线一览那一行写「N 条:并 a、不立 b」,不立而值得留理由的记总账里按「禁止复杂化」不立的那张表;记完在复盘记录末尾补一行「去向:…」,没有遗留也没有发现的写「去向:无」。机器只认「结论:」「发现:」「去向:」三个记号,写得对不对不核。产品经理这一程只跑接力命令收尾、结束一轮、报「没有待办」,不转遗留清单、不等复盘记录、不改收尾单第三栏。
**怎么看**:复盘记录目录里有这条需求的文件就是新式专项(骨架建了,或复盘经理先建的),只看文件在不在、不看日期;新式专项的后台收尾状态现算:「结论:」一行冒号后有字是复盘结论写了,「去向:」一行冒号后有字(「去向:无」也算)是去向记了,这一行恒要求。不带计划名列十态清单时,计划目录与归档目录里后台没办完的新式专项,在它的「注:」「红旗:」之后挂一行「后台还在办:复盘结论还没写、去向还没记」,办完的不挂;结案报告(已提交的需求)的最末多一栏「后台收尾」,写结论与去向各写没写和复盘记录放在哪。带计划名的十态、排队一览、接力命令的末尾都不另加这一行。没有这个文件的(归档在先的老专项,和骨架没建成又没人自己建的)是老式,报告与清单一个字不多。项目经理巡检时跑不带计划名的十态,看这一行催复盘经理写结论、提醒 X大脑 定去向。
**守不到**:① 后台收尾被忘记,只靠十态清单与结案报告的显示和项目经理的巡检催,机器不拦,接力命令跑完也不提醒;② 机器只核「结论:」「去向:」两个记号有没有字,写得对不对、去向是不是 X大脑 定的、每一条遗留是不是都记了,都不核;③ 骨架只在这一次调用真搬了计划时建,已归档的重跑不补,建不成只说一句,这几种与老专项一样按老式显示;④ 归档之后现跑的耗时表读不到施工区副本里的跑床行,收尾单里定格的表是归档那一刻的,发布、归档、提交几段那时多半还没发生(两张表怎么取、怎么对着看,见 §十六「跑床分道并发」里「每次跑床记一行」那一条);⑤ 迟到的复盘记录与清单在下一次提交之前只在工作树里,一直没有下一次提交就一直不入库 —— 它们不是任何一条需求「验收过的那一份」;提交命令对台账区里的文件不问是哪个会话写的、一并带上,只剩台账区改动时不会单独成一笔提交;⑥ 治理站点上看不到迟到的结论:收尾单第一栏那一节定格在归档那一刻,写的是「后台办理中」;⑦ 「下一步开工前插一条优化」那种去向的窗口缩小:提交之后下一条很快开工,X大脑 来不及定完去向时,它就变成立项排在下一条后面;⑧ 站点发布仍攒着发时,下一条照样等那一批;⑨ 复盘经理与项目经理往主控线目录写文件,守卫不拦也不核(免检写区),写没写对地方靠定义里的指针和显示出来的缺项;⑩ 归档与项目经理关产品经理会话之间没有机器闸;⑪ 两把锁只看问的那一刻。守着它的床:`.claude/skills/x-harness-dev/tests/plan-wrapup.test.js`、`.claude/skills/x-harness-dev/tests/plan-run.test.js` 与 `.claude/skills/x-harness-dev/tests/plan-loop.test.js`。
**提交命令**(ADR-118):体系守护命令有一个动作 `harness.js --action=commit --plan=<需求名>`(零件 `x-harness-dev/scripts/core/plan-commit.js`)。**不带 `--execute` 只预览**:
印出要提交的文件分几类各几个、提交说明、标签名、推到哪、哪几样核不过(核不过的照样列出来,分类照常印;还没完结的需求,交付清单取最新一张三查结果单并标明是预览口径);带了才做。
**谁跑、什么时候**:环收尾(已发布、已归档)之后由主控跑,项目经理看见环收尾就请它跑;命令本身不限谁跑 —— 它核的是这条需求的验收与环收尾,谁按都一样(与发布出口同一个道理),
不另立「只有主控跑得了」的敏感命令。授权就是验收完结那一签(亲签,或照代签设置代签),命令不另要一次授权。**提交完印下一步**:命令末尾另印这一次放开了哪些单元、此刻开得了工的是谁(排队一览第三段的内容),主控提交完转给项目经理,由它排下一条的开工,不用等下一次巡检。**跑之前依次核五样**,哪一样不过就停、什么都不写(不暂存、不提交、
不打标签、不记账)、印原因:① 找得到这条需求、账本可信、已完结,而且完结那一笔记着「要提交」(在提交命令之前完结的需求,提交归当时的手工提交,命令照实说一句、不碰它);
② 环收尾成立(已发布与已归档,问十态零件的 `stateOf`,不自己再判一遍);③ 还没提交过(账本里没有「提交」那一笔;有了就照实说已提交,只在推送没成时补推);
④ 当前在主干 main 上,暂存区里的路径都在这一次要提交的清单里(空也算;上一次做到一半留下的就是这样,不要求恰好等于 —— 重跑时清单比暂存区多是常态);
⑤ 这条需求交付的每个文件(取验收那一刻的三查结果单里的交付清单,与代授权发布核内容用的是同一份,被删掉的交付文件也在内)此刻要么仍是验收那一刻的内容(拿工作区字节,
用结果单记指纹的同一个算法比),要么库里已有验收之后提交的版本、且与工作区一致(问 git 而不比字节:本机换行会被换;这个文件最近一次被提交的时刻晚于验收那一刻才算;
改回库里验收之前的旧样子的不算「已在库里」)—— 两样都不是就不提交,点名是哪几个文件、此刻落在哪条需求的范围里。
**提交哪些文件**(共用一棵工作树时只提交这一条的)先列改动、再分类。列改动以 git 看得见的为准:已追踪的改了、删了,加上没追踪、没被忽略的新文件(用零字节分隔的输出,中文路径不被加引号;
没追踪的整个目录逐个文件列出,不折成一行);不复用收尾环量工作区的那个零件(它不量 `.claude/tmp`)。分类问工作区地图的「入库」属性,不另写名单。**带**:① 这条需求自己的 —— 交付的文件里
此刻与库里不同的、它的需求履历目录、它的归档目录、计划目录里已经不在的它那几个文件(归档挪走留下的删除);② 台账 —— 地图上「入库」是「台账」的(需求账本目录与射程缓存、发布台账),加主控线
(总账、待立项目清单、设计笔记、记忆、复盘记录)与需求履历里的发布段 `releases.json`(这两处在地图余段标成台账;发布段只带已完结需求的,在办的等它自己提交),别的会话写的台账一起带上 —— 台账本来就是随项目提交带上的那一类。
**不带**:别的需求还没走完的一切(它的计划、交付、履历与归档,等它自己提交);钥匙石与代签设置;地图上没有区的路径(按无主处理);不归任何需求、也不是台账的改动。没带的分类点名印出来,进结案报告。
**钥匙石 `.claude/settings.json` 与代签设置 `.claude/sign-settings.json` 从不提交**:地图上它们与普通文件一样是「入库」,分不出,所以写成提交命令里的一份短名单(只许加、不许减);它们与库里不一样时,
照常提交别的,在预览与执行的输出里点名「等你亲手看、亲手提交」—— 改这两个文件本来就只归用户(急救开闸、改代签设置),提交也归他。不因此整个拦下:钩子此刻开没开、管不管用,跟提交不提交无关,拦下补不了什么。钥匙石有改动时,他可以用「!」跑设置提交脚本提交它(§十五「要 BOSS 亲手做的事」);代签设置不在那条脚本的名单里,仍由他手敲。型号配置文件不归任何需求、也不是台账,这条命令不带它,由那条脚本提交。
**暂存与提交**:要提交的路径按零字节分隔写进一份路径清单文件交给 git(`--pathspec-from-file` 加 `--pathspec-file-nul`),不拼在命令行上(几百个长路径会撞 Windows 命令行的长度上限);
路径按字面认(`GIT_LITERAL_PATHSPECS=1`),路径里的 `[`、`*`、`?` 不当通配;永不 `git add .`。提交还没有时,每次都把清单里的全部路径重新暂存一遍(幂等,暂存的就是验过的工作区内容),提交已在就跳过暂存。
**提交说明**写成文件交给 git(`-F`,UTF-8),全文逐字三段:标题一行 `<短名>:<需求一句话>(<单元 v版本>、…)`(单元与版本取履历里完结那一刻记的)、一个空行、`需求:<需求名>` 一行,
后面不再有任何行(署名、空尾巴都不许);签字的时刻、亲签还是代签、发了哪几格都在履历与发布段里、随这次提交进库,说明里不抄。
**标签与推送**:打带说明的项目标签 `req/<需求名>`(需求名就是计划目录名,ASCII、全仓唯一)。推送只推主干与这一个标签、只许正常推,而且两样一起成或一起不成 —— 用全名
(`refs/heads/main` 与 `refs/tags/req/<需求名>`)、原子推送、机器可读的输出,不强推、不拉、不合、不推别的分支与标签,主干被拒时标签也不会单独上远程。远程比本地新、被拒(输出里认 `[rejected]`):
提交与标签留在本地,报主控(多半是在别的机器推过,要用户定);凭据要人点、断网、超时(多半是 git 直接报错退出,与「被拒」分开说):同样留在本地,重跑这条命令补推。推送绝不弹交互:
本机凭据走 Git 凭据管理器,只关终端提示不够 —— 子进程里清掉三个问密码的程序设置(`GIT_ASKPASS`、`core.askPass`、`SSH_ASKPASS`)、关掉终端提示(`GIT_TERMINAL_PROMPT=0`)、
让凭据管理器要人点时直接报错(`GCM_INTERACTIVE=false`),并给整条推送一个总时限(超时连子孙进程一起杀)。
**记账、出错与续做**:提交与标签做完,在这条需求的账本里记一笔「提交」(提交号、标签、推没推成);推送补成了再记一笔。做到一半出错(已暂存没提交、已提交没打标签、已推送没记账),
照实印到了哪一步;重跑时每一步先看自己做过没有,做过的跳过,从缺的那一步接着做,不重复提交:提交 —— 库里已有一个提交、说明正文里有一整行恰好是 `需求:<需求名>`(按整行比、不按包含,
一个需求名可能是另一个的前缀)就算已提交;标签 —— `req/<需求名>` 已在而且指向上面那个提交就算已打,指向别的提交就拒、点名,不挪标签;推送 —— 不先查远程、直接再推一次,
已在远程的 git 报已是最新、正常退出,就记推成。不做任何退回、重置这类恢复操作(死命令原则 12)。
**用户手工提交过的现场**:这条需求要提交的东西都已在库里(用户用 `!` 命令自己提交了)时,命令认出东西已在库里,照常打标签、记「提交」那一笔(带手工提交的标记);标签打在
交付文件验收之后最近一次被提交的那个提交上;交付文件分在几个提交里、认不出是哪一个,就拒、点名那几个提交,请用户用 `!` 自己打上 `req/<需求名>` 再重跑 —— 命令认出标签已在、
指向的提交含这条需求的交付,接着记账、推送;这条需求自己的文件没进库(多半是归档目录、履历)的,照常做一次机器提交、标签打在它上面。目录重叠、单元不同的两条撞上同一个文件时第 ⑤ 样会拒:
等改它的那一条提交之后再跑这一条 —— 那时那个文件已经和库里一致,这一条带上自己剩下的文件提交;两个提交先后颠倒,内容是对的。
**它受写保护、算判决依据**:`plan-commit.js` 进守卫写保护名单(与发布出口、核准命令同级:改它要签字一授权、到时放行),进判决依据名单「发布出口」那一样(改它的需求最低难事,§十五「七个风险标记」)。
它与代签命令一样写账本,所以不认换守卫目录的环境变量 `GUARD_HOOKS_DIR`、不从命令行接 `--root`,床经函数参数换仓。守着它的床:`.claude/skills/x-harness-dev/tests/plan-commit.test.js`。
**守不到**:① 提交只认三样进库 —— 这条需求验收过的交付、它的履历与归档、台账;它改过却不在这三样里的(不受治、又不是台账的文件),提交命令不带、点名留在工作树里;没有需求在办时,
主控线与账本的改动不会自己进库,等下一条需求提交时随它带上。② 核完内容到放进暂存区之间那一瞬间,别的会话改了交付文件,查不出;目录重叠、单元不同的两条撞上同一个文件时命令拒、点名。
③ 推送:远程是不是公开的,机器不知道;凭据过期要人点时推不出去,提交与标签留在本地;凭据管理器在本机的真实行为床里造不出来,床只造了回 401 的服务与会挂住的问密码程序;只许正常推靠守卫与命令本身,
要在远程也兜住,得在 GitHub 上给主干开禁止强推的保护 —— 只归用户,不在这条命令里做。④ 脚本进程里直接调 git,守卫看不见(见上「命令行里的 git 一律只读」)。⑤ 用户自己的提交机器不核;
他手工提交过某条需求的东西,命令认它已在库里、照常打标签、记那一笔。⑥ 提交说明的标题与结案报告照抄履历、发布段、收尾单与账本,那几份写错这里跟着错。⑦ 用户事后按标签看 diff 是纪律,机器不逼。
⑧ 账本追加没有跨进程排队:提交是账本的一个新写入者(在主控的会话里写),同一时刻两个会话往同一份账本追加,链可能断(断了判成账本被改过、照拦,不会放过)。
**结案报告**(ADR-118):十态命令带计划名查一条**已提交**的需求(账本里有「提交」那一笔)时,末尾印结案报告,没提交的需求不印。五行加一行提交号,行首的小标题固定:
`交付了什么`(短名、需求一句话、改了哪几个单元、各升到哪一版,取履历)、`发了哪几格`(每一格的状态与发布号,取履历目录里的发布段)、`还要你上传的端`(在体系之外发的格 —— 微信原生包与数据表,
没有写「没有」)、`遗留去了哪`(每条遗留与去向,取履历的遗留与归档目录里收尾单第三栏;去向读到「后台办理中」就如实显示)、`代签凭什么`(亲签写「你签的」;代签写「X大脑 代签」与证据在归档目录里的哪里)、另一行 `提交`
(提交号前几位、标签、推没推到远程,取账本里最后一笔「提交」);新式专项(见上「后台收尾」)的报告最末另多一栏 `后台收尾`。读不到的一栏写「读不到:原因」,不编、不留空、不抛错;这条命令仍然只读、不写任何文件、不起子进程(`git` 也不起)。同一条命令带计划名
查一条已完结的需求时,在「环几点启动、几点收尾」后面多一行**提交**:环还没收尾写要等环收尾之后由主控跑提交命令;环收尾了还没提交写待提交并给命令全文;已提交的写提交号前几位、标签、推没推到远程
(没推成的写待补推:重跑提交命令;手工提交过的句末注明);完结在提交命令之前的写提交归当时的手工提交、命令不碰它。项目经理拿结案报告转 X大脑、记总账一行,X大脑 原样转用户(会话之间的消息,是纪律)。
**守不到**:报告里每一栏照抄履历、发布段、收尾单与账本(后台收尾那一栏照复盘记录),那几份写错这里跟着错;提交那一行与结案报告读的是账本里记的最后一笔「提交」,不核提交号在不在库里。守着它的床:`.claude/skills/x-harness-dev/tests/plan-loop.test.js`。
**每次回话列进度**(ADR-93):主控不用等各会话来报、也不用请用户去那个会话看一眼,就看得见各条线走到哪 ——
用户每说一句话(打字,或在选项题里自己打字,两处走同一个函数),守卫回给当场那个会话的「正在办」那一行,
每条**在办**的需求后面多接一段(签字作废的那一种不接,它那一行只催重签;步骤数那半句照常),一条需求仍是一行。排队的需求不算在办:「正在办」那一行把它单列,写短名与在等什么(要重签的另标),不接这一段进度。这一段由一个函数拼(`requirements.progressLine`),
二百四十字封顶,超长先去掉最近一次被拦的原因。依次带七样,全取现成的、不重算(办得超了这一档的上限时,这条需求的那一行另接一句点名,接在这一段前面:它不在这七样里、不占这二百四十字的额度,也不跟这一段的两条规矩走 —— 这一段签字作废的不接、在办的多于六条时只给前六条接,点名都照接;见下「办得超了点名」):
① 谁在办 —— 本会话在办,或「会话 <编号前八位> 在办,它最后一次动静多久之前」(只看那个会话台账文件的修改时间、不读内容;文件不在就写没有动静记录)。
「谁在办」全仓只经一个取值函数拿(`requirements.handlerOf`):= 最后一次签「确认」与其后的改派,谁在后听谁的(ADR-98,见下「办理会话改派」);确认那一笔记下办理会话(ADR-94),那一笔没有这一栏的(早先签的)就是签那一笔的会话。口径要变,只改这一个函数(见下「办理会话」)。
② 签字 —— 第一次签字至今多久;签过不止一次的带上签了几次。
③ 三查与封版 —— 读账本目录里落盘的最新一张结果单(只读这一张、绝不重算):三查各绿各红、改到的单元封没封、这张单子是几点算的(本机时间);
单子上的内容编号与计划现在的不同时多一句「算的是改之前的内容」;没有这张就写「三查还没算过」。封版这个节点不在需求账本的事件里(它在锁清单与结果单里),所以取结果单。
④ 复盘 —— 账本里记了几次、最新一次是过、不过还是不可信;没有就写还没复盘。
⑤ 验收 —— 还没签;签过几次没成(带最近一次卡在哪);用户说过几次不过。
⑥ 被拦 —— 办理会话在第一次签字之后被守卫拦了几次(读会话台账里的拦截,见环1「拦截出口」),写前、收尾、其它三栏分开数,带最近一次原因的开头;没被拦过照实写。
⑦ 欠下 —— 看板「决策与遗留」页签「欠下的」一栏有几条(与完结时写进履历的是同一个取法,见下「履历多两栏」),一条都没有就写「没有欠下的」。
对谁说:每个会话都注入 —— 守卫分不出谁是主控;主控因此每次都看到全部「别的会话在办」的行,产品经理看到自己那条加别人的各一行。内容没变也照发(不折叠);
在办的需求多于六条时只给前六条接这一段,其余只有步骤数。它进的是执行者的上下文,不是弹给用户的话。任何一栏读不到就写「读不到」,其余照出;
这一刻出错只提示不拦。**用户说话那一刻不做重的计算**:不起子进程、不量工作区、不重算三查 —— 每条在办需求只多读一张结果单、一次文件时间与办它的那个会话那一份台账。
**守不到**:① 那张结果单是办这条需求的会话上一次跑核对命令时落盘的,可能是旧的 —— 行里带着「几点算的」,计划在那之后改过的还会写明「算的是改之前的内容」,读的人要自己看。
② 进度行里写的是会话编号(前八位)、不写名字(钩子输入里后台会话带着会话名,这一行没有用它);哪个编号是哪位产品经理,查会话登记册(§十五「会话登记册与恢复」)。
③ 「谁在办」取的是办理会话(取最后一次签字的会话的话,签字不在办它的会话签时会指错人):它是签「确认」那一刻按「这份计划的机器镜像最后是谁写成这样的」认的,会认错的两种情形见下「办理会话」的守不到 ① —— 认错了,这一栏与「被拦几次」跟着错。
④ 被拦只数办理会话自己的台账:别的会话替它干活被拦的不算;重签时办理会话换了人之后,前一个会话被拦的不算;而且只数经守卫出口的拦(环1「拦截出口」的守不到)。
⑤ 「最后一次动静」看的是台账文件的修改时间:只说话、只读文件的会话不往台账记,看上去像没动静。
⑥ 这一行只在用户说话时才出现:产品经理卡住了、超过预计时间没回报,机器不提醒,靠项目经理的定时巡检(核各条需求看板的状态栏、超时叫人)与节点回报的纪律(§十五)。
⑦ 它是塞给执行者的话:用户看不看得到,取决于执行者转述。
**履历多两栏:用时与返工、遗留**(ADR-93):
验收完结、三查全绿、封履历之前,钩子多算两样写进履历(机器读的那一份各一栏,给人读的那一份各一节;在算产出指纹之前写,照样封死):
① **用时与返工**(机器读的那一栏叫 effort;给人读的那一节标题就是「用时与返工」,排在「产生的版本」之后、「遗留」之前,六行)—— 只从账本现成的事件算,不加新的账本事件
(账本追加没有跨进程排队,见上「记洞不改」里讲往账本追加一笔的那一句)。六行:第一次签字的时刻;签字次数;用户说「不过」的次数 —— 数的是账本里全部的不过,
含签字一那一步没勾全记下的那一种,不含验收没成的次数;独立复盘几轮(过、不过、不可信分开数,不可信的不算进过与不过);总用时(从开工到完结,排队的时间不算进去;完结那一刻从账本里的开工那一笔取);
其中等用户验收多久(最后一笔可信的复盘到完结;没有可信的复盘时这一行写「没有可信的复盘,算不出」)。时长舍去不满一分钟的零头;时刻用履历的写法
(本机时间带时区,ADR-104)。只记数,不比任何上限,不数「封了几版」(超没超这一档在「正在办」那一行与完结那句回话里点名,履历这一栏只记数,见下「办得超了点名」);账本里没有签字那一笔的不出这一栏。
② **遗留** —— 两个来源逐条并进来。一、计划看板「决策与遗留」页签「欠下的」小标题下的内容(到下一个小标题或页签结束为止):只认列表与段落 —— 每个列表项一条,
没有列表项就每段一条;含方括号占位的条目当模板占位跳过,整条是「无」的不算;前缀标「计划欠下:」。二、账本里每一笔**可信**的复盘带着的遗留(复盘者收尾时守卫记下的,
见下「复盘进关口」):前缀标「复盘遗留(第 N 次):」,N 是这一笔在全部复盘里的次序。逐字相同的只留一条(按正文比,不含前缀);每条三百字封顶,合计最多四十条,
超出的在完结那句回话里说另有几条没写进履历;指向计划目录的路径照履历现成的办法剥掉(机器读的那一份也剥)。
完结那句回话后面写明「遗留 N 条已写进履历」并逐条列一次、交主控定去向;没有就写没有遗留。**取遗留出错不挡完结**:按零条处理,并在回话里说没取出来与原因。
较早封死、没有这两栏的履历不回填:重新渲染出来与原样逐字相同。
**守不到**:① 去向没有账 —— 遗留进了履历,但「哪一条后来立成了哪条需求、哪一条搁置了」机器不记:完结时逐条报给当场的会话一次,之后全看主控。
② 遗留一进履历就随治理站点公开、封死之后改不了:写错了或带了不该公开的内容只能留着(站点发布准备的公开内容扫描只扫 md 与 html,印在页面上的履历机器附件扫不到,§九);
遗留进履历之前不先给用户看一眼。
③ 只取「欠下的」那一栏、只认列表与段落:写在这一页签别的小标题下的、只在对话里说过的进不了履历;把「欠下的」写成表格的老看板一条都取不到;
「等你定的」里没定的不算遗留;没有在办需求的会话发现的问题没有登记口。
④ 复盘者的遗留是自由文本:没按写法写时认不出、记成没有,只在他收尾那一刻提示一次;一轮超过二十条的后面几条静默丢掉;不可信的复盘带的遗留不进履历。
⑤ 完结那一刻取遗留出错按零条处理,而履历这时已经封死,之后补不进去(回话里说了没取出来,要执行者自己把那几条报给主控)。
⑥ 完结回话里的遗留清单是塞给执行者的话:用户看不看得到,取决于执行者转述。
⑦ 用时是墙上时间,过夜与等待都算在内,所以把「等用户验收」单列;「等别的需求让路」分不出来;签字次数里分不出是自己改了需求、还是被别的需求牵连重签;
时长舍掉了不满一分钟的零头。
⑧ 履历里只记数:超没超这一档不写进履历 —— 超了在「正在办」那一行与完结那句回话里点名(见下「办得超了点名」),签字那一笔没记档的需求只记数、不比、不点名;在办的履历里没有这两栏,要到完结那一刻才写;较早封死的履历不回填。
**认车道:认流程、算最低档、改判定代码同一时刻只开工一条**:签「确认」那一刻,认流程与算最低档两道和定档同一处(`requirements.signHoldWhy`;签字区、出题命令与多选确认题弹题之前那道预判读的都是这一处),
守卫先核认流程与算最低档两道,再走定档;然后判开不开得了工 —— 改判定代码同一时刻只开工一条(下面 ③)、单元占用、阶段六的关口都是开工条件,不拒签,见下「签字与开工分开」。车道由一个函数算一次(`requirements.laneOf`),各出一行回话。
① **认流程**(`requirements.flowOf`,只看落点表,用例点名的测试不参与):单元 —— 整个框架、项目架构、agent 架构归 Harness 流程,系统规范归规范流程,业务域与业务总览归业务流程(认不出的单元名归阶段一关口的「单元认不认得」);
none 那一行逐条路径看它落在哪 —— 第一段是业务各端(守卫里写死一份端名,钉住床核它与工作区地图的名册「端」一致)、官网 x-website、内核母本 x-core、测试根 x-test 的,或落在业务架构目录 .claude/arch/business/ 下的,归业务流程,
x-test 里两个部署门入口(run-deploy-gate.js、deploy-gate-bite.js)除外;其余一律归 Harness 流程(仓根文件与不归业务的顶层目录都在内;计划目录 .claude/plan/ 下的文件同样归 Harness ——
业务需求的落点表里列了它,会被认成混在一条,回话提示把它拿掉,计划自己的文件本来也不该列进落点表)。认流程不展开通配。认流程用到的端名与 none 行的路径表写死在守卫里、不问地图(会话开始与每条命令读计划状态都要认流程),钉住床核它们与地图的名册「端」、属性「车道」一致;单元行按单元认,只有 none 行才走这张路径表(见 §十八「守卫读地图与读坏了怎么办」)。Harness 加规范按 Harness 走;
业务与 Harness 或规范混在一条签不上,回话写明业务那几处一条、其余一条,拆开各自建计划、各自签。
② **算最低档**:看签字那一刻落点表里的目录 —— 落点表里的目录加用例点名的测试(与阶段二的关口、签字基线认的范围同一个并集;只看落点表的话,把写保护的测试只写进用例就躲过了标记)。
过筛的路径 = 每个目录的字面(还没建的按字面判)、带通配的按此刻全部受治文件过滤、不带通配而盘上是目录的按「目录/**」再展开一次(只用于标记,往严的方向错);
照 §十五「七个风险标记定最低档」逐个判。写的档低于最低档签不上,回话写明最低是哪一档、写的是哪一档、中了哪几个标记(带几个例子与处数);
定档那一道也出话时,这一行末尾接一句「两处说的档不一样时以这一行为准」(定档那一道的原句照出)。
③ **改判定代码的同一时刻只开工一条**(开工条件的第二样):判定代码 = 判决依据五样(三查 —— 核对命令、核准命令与开工命令都算、复盘说明、两条封版命令、发布出口〔含提交命令〕、版本契约)加守卫目录整棵(含它的床与回归套件)、
检测引擎(check.js 与 check/ 整棵,不含各规范的判据与床 —— 不然每条改判据的规范需求都要和改守卫的排队)、测试运行器(bed-runner.js 与 bite/);
落点表里的目录碰到它、而已有一条碰到它的需求占着(开了工没完结的 —— 在办、签字作废、账本被改过、机器镜像读不了,与同一块排队认「占着」同一组状态,目录取此刻的与最后一笔确认留底的),这份计划开不了工、记成排队(确认照签),
回话点名被谁占着、它哪天开的工、步骤还剩几步、复盘过没过,出路是等它提交完、由项目经理跑开工命令,或并进它;已经开了工的需求重签时新碰到判定代码而被占着,拒签、点名;排队一览有一段此刻被谁占着(`requirements.judgeCodeHolders`)。
判决依据五样与判定代码两份名单住工作区地图的名册「裁判五样」「判定代码」(成员带附加信息:属于哪一样、文件还是目录),守卫需求零件第一次用到时按名册取成一处冻结常量(`LANE_LISTS`);写保护的扣除项、母本与内核的名单、none 那一行归业务的目录仍写在守卫需求零件里;签字区、出题命令、排队一览、复盘说明都读这一处;
写保护的谓词本身只住 command-policy;本文只写类别,不抄文件名。车道判不了(列不出受治文件这类)就签不了,回话照实说。同一次调用里只列一次受治文件。
**记进签字、不进内容编号**:认流程与算最低档两道都过了,签字一那一笔多记一栏车道 —— 认出的流程、最低档、中了哪几个标记、碰没碰判定代码(lane);它们由已锁的单元、目录、动钱与两栏推出来,
进了编号的话以后改一次标记表全部在途签字作废。机器镜像里的两栏(键名 permission:动权限与身份;breaking:改已发布表的字段类型或删功能)是写计划的人自报的布尔,
只在为真时进签字锁住的内容(为假或没写,内容编号与没有这两栏时逐字相同);签字区不为它们另加要勾的组,确认区顶上那一行点名 ⑥ ⑦,两栏翻转时签字区横幅写明改了哪一栏。
确认区顶上那一行与复盘说明按此刻的落点现算车道(流程 × 档,与中了哪几个标记),认不出流程、判不了的照实写;验收区顶上没有这一行。
**重签怎么核**:签字一那一笔里没记车道的(这三道核立起来之前签的)重签不按车道核,也不补记车道,确认区顶上那一行注明它重签不按车道核;
记过车道的重签按车道核:认流程与最低档照核;改判定代码那一道,还没开工的重签三样全判,已开了工的只查新碰到的(上一笔没碰到、这一次碰到了),被占着拒签 —— 免得改了落点、写低了档、新碰到判定代码靠重签绕过去。
**回话**:几道核没过的全部列出,认车道的两道按行写、排在定档之前,每行只点名它那一道涉及的单元;其余几道各出各的原句。开不了工的原因不在这里列,写在记成排队的那段回话里。签字那一笔里没有车道字段的旧账照读不误。
命令行算内容编号的那条命令不报这两道与开工条件(看签字区、出题命令或排队一览)。
**守不到**:① 两栏是写计划的人自报,机器不对着代码核(与「动钱」那一栏同一种边界);② 签字时不核格里的目录归不归旁边那个单元 —— 写计划的人能借单元名挑流程,业务域封版时版本契约会挡;
③ 主控认车道(那时还没有计划)、运维与分析两条认流程,靠纪律;④ 写得比最低档高时该是哪一档机器不判;
⑤ none 那一行写 x-test/** 会按第一段认成业务流程,而它盖住两个部署门入口,所以最低档会中 ② 判决依据、也算碰到判定代码 —— 写计划时把 x-test 写到子目录那一级就不会;
⑥ 内核清单 x-core/tools/manifest.js 受写保护、按版本契约归业务域:碰它的需求按「母本与内核」算难事,但它不在判定代码名单里,不进「同一时刻只开工一条」;
⑦ 通配按签字那一刻展开,之后新建进通配里的文件要到重签才重算;⑧ 名单只在守卫一处常量里,写漏了机器不知道。
守着它的床:`.claude/hooks/tests/project-gates.test.js`、`.claude/hooks/tests/requirements-signing.test.js`、`.claude/hooks/tests/verify-harness.test.js`。
**签字那一刻多一道定档闸与一道开工判断、账按办理会话算、写前多一道顶层围栏**(ADR-94):四样交给机器 —— 一条需求有多大、同一处同一时刻只落一条、用户只在主控签字、业务的会话不碰顶层;
另有办得超了点名、落点格不被后来者卡红两样。下面六小段各讲一样,各带各的守不到。这六样没有一处需要机器认谁是主控(说话钩子认登记册里的主控,见上「签字记录只认两条路」)。
**定档与上限**(ADR-94):档(小事、成条的事、难事,§十五「先分级、再选路」)要是只是主控立项时定的一句话,
小事越审越大没有东西拦(出过一条写了十八条标准、从签字到完结一百多个小时、复盘三十四轮的)。机器镜像有一栏「档」(键名 tier),只许三个值:小事、成条的事、难事;没写按小事算。
签「确认」那一刻走的是同一处 —— 看板贴回、对话框一键签、对话框里带话的签字三条路(连同直接打固定那一句)都汇到这里(一道确认题里多选的几条,每条各走一遍这张表、各核各的档与上限,一条签不上不连累别的);记签字之前核的是一张五道的表,按先后:账本被直接改过 → 计划写没写全 →
落点单元与短名认不认得(阶段一)→ 认车道与定档(这一道里先核认车道的两道 —— 认流程、算最低档,见上「认车道」;再按档核四个数;表仍是五道)→ 签字基线在不在、被没被改过(机器镜像读不了的排在这张表之前就回了,别的都不判;用户这一次贴回的结论本身对不对在第二道之后另核,不在这张表里)。这张表过了才记签字一那一笔;开不开得了工(单元占用、改判定代码、阶段六的关口)不在表里,它不拒签,见下「签字与开工分开」。定档这一道,守卫按档核四个数:标准条数、用例条数、
其中要用户亲手验的条数(tests 为空的用例)、落点表里不重复的版本单元个数(none 不算)。每一档这四个数最多各是几,机器用的是守卫需求零件里的一张常量表(`requirements.TIERS`;每档另带办的时间与复盘轮数两个数,见下「办得超了点名」),
给人看的数字只写在项目架构设计页(签字核的四个数在阶段一,全部六个数在第十节「先分级」那张表),本文不抄;最大的那一档前三样不设上限。
档写成这三个值之外的、或任一项超了,这一笔不记签字(基线也不记),回话点名:按哪一档核的、超的是哪一项、最多几条、现在几条,并给两条出路 —— 拆成几条需求,或把档改成这四个数放得下的最小那一档
(要用户亲手验的条数连最大的一档都放不下时,出路换成拆、或把几条亲手验的改成自动用例)。签上的那一笔多记一栏当时按哪一档核的(tier)。
**只在签「确认」那一刻核**:验收那一刻不核这四个数;这道闸不放进签字前查计划齐不齐的那一个函数(`requirements.missingParts`)—— 它在验收那一刻也会被调,放进去会把早先签下的、条数超了的在办需求挡在验收门外。
「要用户亲手验的用例不多于十五条」那一条上限在那个函数里,按档更严的是这里。**档进内容编号,但只在写了、而且不是小事时才进**:没写档或写「小事」的计划,内容编号里没有这一栏(与不带档的算法逐字相同)——
不带档的签字因此不受影响(有拿旧夹具对拍的用例守着这一条);写了「成条的事」「难事」或三个值之外的,编号里多这一栏(写坏的按原样进,把档改坏同样作废)。所以签过字之后改了档、编号因此变了的,
签字作废;没写改成写「小事」编号不变、不作废。**签字区**:核对命令生成确认区之前先问守卫这份计划此刻签不签得了(`requirements.signHoldWhy`,认车道与定档合在这一个函数里,与签字那一刻同一份判法),再问开不开得了工(开工条件,见下「签字与开工分开」),签得了的确认区顶上写明签了之后是当场开工还是排队、在等谁。
档与四个数各是几条、上限几条,连同按此刻的落点现算的车道与中了哪几个风险标记,那一行出在两处、同一份内容(验收区顶上没有这一行):整个签字区最顶上,与「需求」那一组最顶上。签不了(认车道的两道没过、超了、档不合法)时不开确认区,写「确认区还没开:」加守卫给的原因,
最顶上那一行照样出,核对命令打印的单子抬头也带这一句;签字题因此也弹不出来(「签字题带地址」⑥:签字区在而没有开着的一道就拦;被拦时回给执行者的「签字区此刻写着」,优先带「确认区还没开:」那一段的原因,
不被最顶上档那一行占掉)。重签时档变了,横幅与那一行标「改了」。
命令行算内容编号的那条命令(`node .claude/hooks/guard/requirements.js --hash <名>`)报的是「计划缺哪些部分」加定档这一道;开工条件、单元名、签字基线与认车道的两道它都不报(要看这几样,跑下面的排队动作)。
**守不到**:① 只数条数:五件事写进一条标准就绕过去了 —— 条数挡的是膨胀,挡不住单条标准写得宽(已完结的需求里有条数偏小却复盘了十七轮的),那种靠下面的用时与轮数点名、靠架构师审计划。
② 档由写计划的人填:机器按七个风险标记算出最低档、写低了签不上(见上「认车道」),写得比最低档高时该是哪一档机器不判 —— 超了把档改大一档就签得上(回话自己就给了这条出路),升到难事前三样不封顶;机器保证的是档不低于最低档、档与条数对得上、签过字之后升档必重签(用户在签字区看得见「改了」)。
③ 格数不进上限(格怎么分是写计划的人定的);每条标准多少字不限。④ 上限的数字有两处:守卫里的常量表(机器用的)与项目架构设计页(给人看的),两处没有机器对拍,改数字要两处同批改。⑤ 早先签下、没有档的在办需求不补核。
**签字与开工分开**(ADR-119):签「确认」是用户对做什么的点头,可以提前签、一次签好几份;占版本单元、放行写受治文件、算在办的是**开工**,不是签字。签字那一刻判此刻开不开得了工 —— 开得了当场开工,开不了记成排队,等项目经理(或主控)跑开工命令。
**开工条件三样**(签字那一刻与开工命令判的是同一个函数,逐个单元全判):① 它要占的单元(签字时的目录加已核准的)上,没有开了工没完结的需求,也没有完结那一笔记着「要提交」、账本里还没有「提交」那一笔的需求(见下「同一块排队」);② 它碰到判定代码时,没有别的开了工没完结的需求也碰着(见上「认车道」③);③ 仓里没有已完结、计划还留在计划目录的需求(阶段六的关口,见上「清理归档硬控」③)。
**账本里的样子**:三样都满足,当场开工 —— 记基线、占单元、放行写,账本里签字那一笔与普通的确认一模一样;有一样不满足,这一笔确认带「排队」的标 —— 不记基线、不占单元、不放行写,也不拒签,回话写明在等什么。**「开没开工」只有一个判法**(单点函数,照完结那一笔的 `closedOfEvents` 的写法):账本里有「开工」那一笔,或有一笔确认不带「排队」标 ⇒ 开了工,一旦开了工就一直算开了工;所以没有排队标的确认、排队的重签时开得了工的那一笔,都算那一刻开工。账本校验只验链与镜像、不认事件种类,「开工」「提交」两种事件不报警。
**签字那一刻三样怎么判,按开没开工分两种**:还没开工的(第一次签、排队的重签)三样逐个单元全判,不走「上次签过字就不查」的捷径 —— 排队的那一笔没占任何东西,走捷径会把它当成已占着、两条同占;都过当场开工,有一样不过记排队。已经开了工的重签:它已经占着的单元、已经碰着的判定代码、阶段六的关口不查,只查新加进来的单元与新碰到的判定代码,被别人占着拒签、点名,不退回排队 —— 退回去就放开了它手里的单元,下一条开工会动到它做了一半的文件。
**排队的需求,守卫怎么对待**:不占单元;不放行写(它的产品经理和没签字时一样,只能写计划目录、跑受治脚本);不算在办 —— 不挡正式发布、开不了联调、封版命令把「为了」绑不上它,三查、接力命令、验收完结、代签、验收区、出题、复盘说明都拒它并说「还没开工」;签字照样会作废(锁住的五样变了要重签,过程改动由主控核准),排队的签字作废后状态仍是排队、另带「要重签」的标;核准过程改动时,排队的需求不查单元占用与判定代码占用(它什么都没占,开工那一刻整张落点表重判)。发布登记给落点表盖得住的需求记「联调」一格,问的是账本里开没开工(需求履历的状态只有在办与完结两种),排队的不记;履历在签字一那一刻建、开工时不重写,「总用时」从开工算,排队的时间不算进去。
**读「在办」的各处按开了工认**:计划状态表有一个「排队」。只认「在办」才放行的读者(写前办理会话、签字放行、顶层围栏、收尾、封版绑需求)自然把排队排除在外;取反型的读者(只排除没签字、已完结、作废,剩下的一律当在办 —— 验收完结、代签、验收区、出题、排队一览、十态、复盘说明、封版绑需求的作废那一支)显式补「还没开工」一支,排队又要重签的进得了确认区与等重签的名单;直读确认那一笔的(基线的读取与「被删」的判断、联调零件里计划不见了从账本认在办、履历的总用时)一律问「开没开过工」与开工基线。
**开工命令**:体系守护命令的开工动作 `harness.js --action=start --plan=<需求名>`(零件 `x-harness-dev/scripts/core/plan-start.js`)。不带 `--execute` 只预览(印出开工条件三样此刻各过没过、过不了的点名在等谁),带了才做。**谁跑**:只有会话登记册里的主控与项目经理跑得了(身份取自会话环境里的会话号,与会话命令同一种认法);它不进守卫「执行体一律不许跑」的那几条敏感命令 —— 开工条件全由机器核,执行体跑了最坏是先后排错。**先核**:这条需求签了字一、还没开工、签字没作废、账本可信,再核开工条件三样;哪一样不过就停、什么都不写、印原因。**都过才做**:记开工基线(与签字那一刻当场开工记基线是同一个函数;本文与守卫里叫「签字基线」的就是这一份)与开工那一笔(时刻、谁开的、占的单元、开工基线),印下一步 —— 叫醒这条需求的产品经理(会话命令的叫醒子动作,会话号不变、办理会话不变),并经会话之间的消息告诉它开工。**它受写保护、算判决依据**:`plan-start.js` 进守卫写保护名单(改它要签字一授权、到时放行),进判决依据名单「三查」那一样(开工基线是三查的底,改它的需求最低难事,§十五「七个风险标记」);它与提交命令、代签命令一样写账本,所以不认换守卫目录的环境变量 `GUARD_HOOKS_DIR`、不从命令行接 `--root`,床经函数参数换仓。
**先后与卡住时**:开工的先后归项目经理排、主控拍板 —— 照主控定下的先后,同一单元一条接一条;提交命令末尾印出这一次放开了哪些单元、此刻开得了工的是谁,主控提交完转给项目经理,不用等下一次巡检。前一条的发布卡住(比如后台那一格要用户亲手构建),同一单元的下一条就开不了工,只能等它发完、提交;用户自己用 `!` 命令把它提交了的,主控再跑一次提交命令,它认出东西已在库里、照常打标签、记「提交」那一笔,单元就放开(开工条件只读账本、不碰 git)。
**守不到**:① 签了排队的计划,排得越久越可能因为前面的项目改动而要重签:锁住的五样变没变机器核,计划还合不合时宜机器不核。② 开工的先后归项目经理排、主控拍板,机器只管同一单元同一时刻只开工一条、碰判定代码的同一时刻也只开工一条,谁先谁后不核;开工命令按会话号认登记册里的主控与项目经理,执行体与派它的会话同号,主控或项目经理派出去的执行体也跑得了 —— 开工条件照样全由机器核,最坏是先后排错。③ 单元占到提交完:前一条的发布卡住,同一单元的下一条就开不了工(上一段);不同单元的两条可以同时开工,但全仓发布要求全部单元都封着 —— 先完结的那一条,要等另一条把它的单元封了版才发得出去;工作树之后从主干发,这一条随之没了。④ 环收尾到提交、提交到下一条开工,机器只在每次回话里点名「待提交」「待补推」,不替人跑命令;跑不跑、什么时候跑,靠主控与项目经理巡检。⑤ 签字与开工、或两次开工恰好同一时刻判同一个单元,两边都看到空着,可能两条同占,见下「同一块排队」的守不到 ⑦。⑥ 治理站点的项目页把排队的需求显示成「在办」(构建器把没完结的一律当在办):不报错、不挡什么;单列「排队」留给「五类架构跟得上」那一项。守着这一段的床:`.claude/hooks/tests/requirements.test.js`、`.claude/hooks/tests/requirements-signing.test.js`、`.claude/hooks/tests/requirements-legacy-walk.test.js`。
**同一块排队**:同一个版本单元上同一时刻只开工一条需求,后到的那一条签得上、记成排队 —— 同占一个单元的几条需求会互相卡着,谁都封不了版、完结不了,相撞的后果要到封版与验收才报出来。
这是开工条件的第一样(签字那一刻与开工命令判的是同一个函数):
这份计划**新要占**的版本单元上已有别的需求**占着**,就开不了工(确认照签、记成排队)。占着:① 开了工没完结的需求(状态是在办、签字作废或账本被直接改过;封了版在等用户验收的也是在办,算占着;排队的不算),而且它的落点表 ——
此刻的,或它最后一次签字时留底的 —— 列有这个单元(`requirements.unitHolders`)。机器镜像读不了、而账本里开了工没有完结的需求也算占着:此刻的落点表读不到,按它最后一笔确认留底的单元算,
回话里照样点名它(它没有短名,写的是目录名,并注明机器镜像读不了)—— 不这样,把占着某个单元的那份机器镜像存坏,别的计划就开得了工,修好之后两条同占。
那一笔确认没有留底的老签字(早先签的)认不出它占着哪些单元,也就不算占着,这一种守不到(守卫与排队动作一致)。
② 已完结、完结那一笔记着「要提交」、账本里还没有「提交」那一笔的需求 —— 到提交完才放开单元;这一类计划多半已经归档、不在计划目录里,所以占用者在计划目录之外另从需求账本认,按它签字时留底的单元与目录算占着(与联调零件「计划不见了从账本认在办」那一支同一个读法;只扫计划目录的话,前一条一归档下一条就开得了工,会动到前一条还没提交的文件)。
新要占:对已经开了工的需求重签,只查此刻的落点表里列着、而它自己上一次签字时没列的单元,已经占着的单元不查 ——
所以前一条签字作废时它自己重签得上,已经同占一个单元的两条各自重签得上、第三条被占着拒签、不退回排队;还没开工的(第一次签、排队的重签)不走这条捷径,逐个单元全判。上一次签字时列了哪些,取那一笔留底的内容;那一笔没有留底的旧签字(早先签的),内容编号与此刻相同就按与此刻相同算,
不同就认不出、按一个都没列算(往拦的方向错)。落点单元写 none 的不排队;列了几个单元的,任一个被占就开不了工。回话逐个单元写明:这个单元被谁占着(短名)、它哪天开的工、步骤还剩几步没勾、
独立复盘过没过(看最近一笔可信的复盘),完结了等提交的写「完结待提交」,没人占的单元写空着;并写明出路 —— 等它提交完、由项目经理跑开工命令,或把这一条并进它。签字区同一个判法(同一个函数):开不了工的确认区照开,顶上写同样的原因。
**计划状态表里排队是一个状态**:签了字、没开工的就是排队,排队的不算在办(读者怎么按开工认,见上「签字与开工分开」)。**没有插队的口**:修一条卡住的需求的那一条,同样只能并进去或等。签完后提示「范围重叠」的那一句留着:它只在单元不同或落点写 none、而目录逐字相同时才出得来。
占到提交完、不是到验收完结:共用一棵工作树时,同一单元的下一条一开工就会动前一条交付的文件 —— 前一条的发布会被版本比对拦住(下一条的单元在施工,全仓发不出去),它的提交里也会混进下一条还没验收的改动;占到提交完,这两件事都不会发生。等的为什么是提交、不是封版或验收,见 §十五「一条需求一次封版收得了口」。
**排队看得见**:体系守护命令的只读动作 `harness.js --action=queue`(零件 `x-harness-dev/scripts/core/plan-queue.js`;可带 `--root` 指到别的仓根)—— 不写任何文件,出五段:一、占着的 —— 每个版本单元上此刻谁占着(短名、状态、哪天开的工;完结了等提交的写「完结待提交」;读不了的那一条状态写成「计划读不了(照它最后一次签字时列的单元算占着)」);
二、排着的 —— 签了字、记成排队的计划(短名、在等什么;签字作废的另标「要重签」);三、此刻开得了工的 —— 排着的里开工条件三样此刻都满足的,下一步是项目经理(或主控)跑开工命令;四、卡在收尾、归档与提交的 —— 此刻已完结、计划还留在计划目录的每一条,与完结了等提交的每一条,它们让后面的计划开不了工,见上「清理归档硬控」③;五、判定代码此刻谁在改。
「占着」只问守卫的 `unitHolders`;「开得了工」只问开工条件那一个函数 —— 签「确认」那一支和开工命令走的也是它;
以后那边再加一道,排队动作跟着变,两边不会各走各的(有用例拿它说的去真签、真开一遍对照);「签得了签不了」(认流程、最低档、档与条数)不在排队动作里,看签字区或出题命令。
**守不到**:① 排队只挡开工,不另挡排着的会话提前往仓里写(挡它的是写前那一道:排着的需求没开工,它的办理会话不是任何在办需求的办理会话)—— 提前写进同一个单元的改动,同一个会话写的会被封进前一条的那一版,别的会话写的会让前一条完结不了;顶层四类单元有下面的围栏挡着不是办理会话的会话,
业务域的单元也有一道:排着的会话若不是任何在办需求的办理会话,写受治文件写前就拦(见下「写前按办理会话判」);挡不住的只剩一种 —— 它自己正办着另一条在办需求,写进这个单元的改动写前照放、只在收尾点名一次,这一种靠「在仓库外面写和测」的纪律。② 占着某个版本单元的那条需求不办了,队放不开:没有「作废一条需求」这句话,只能照现成的删计划那条路放开(上面「三查接关口」里讲删计划的那几句:
命令直写的删法被拦,计划被删掉之后收尾点名一次),开不了工时的回话里带着这一句(签字区、结果单抬头与排队动作里写的是同一段原因,也都带着)。这条路只放得开单元占用:
它盖过的云函数与站点,正式发布核验收完结那一道照拦 —— 计划不见了照签字时留底的范围算在办(见上「部署门认联调」④ 与守不到 ⑤)。③ 没有插队的口:一条占着单元的需求自己卡住了,修它的那一条按这道闸开不了工,只能并进它(它的签字随之作废、用户重签,已经过了的复盘作废)或等。
④ 只认版本单元:两条需求单元不同而目录重叠的(一条写 none、另一条写某个单元,或都写 none)不排队,只有范围重叠那一句提示。⑤ 机器不记先来后到:几条都排着时,前一条提交之后谁先被开工命令开上谁占上,先后由项目经理排、主控拍板。
⑥ 排队动作出的是此刻的样子、不落盘不提醒,看完之后别人开了工或提了交结论就变;它说的「开得了工」不含看板签字区是不是最新的那一道(那是点下去那一刻的事)和判与记之间别的会话恰好同刻开了工(见 ⑦);
落点表里写了版本契约不认得的名字时,占着和排着两段照原样把它当一个单元列出来,开得了工那一段才写明它不认得。
⑦ 签字与开工、或两次开工在同一刻各自判同一个空着的单元,两边都看到空着,可能两条同占:判定(读各份计划的状态)与记账(追加开工或确认那一笔)之间没有东西挡着,中间还隔着记基线与认办理会话,没有加锁;账本追加本身也没有跨进程排队,开工是账本的又一个新写入者(在项目经理、主控的会话里写)。
记上之后两条都算占着,各自重签得了、第三条开不了工,此后照上面「两份计划触及同一单元」的判法走。现实里用户一次只点一道题,一道题里的几份守卫逐条依次记、后一份判开工条件时看得见前一份,开工命令也由项目经理一条一条跑,所以它记在这里、不当成要修的毛病;加锁留给后面单立的账本加锁那一项。
⑧ 签字作废的需求改了落点表,判「占着」时认的是「此刻的或签字时留底的」,所以它不经签字就能多占一个单元 —— 往自己那份作废的计划里添一个单元,别的需求在那个单元上就开不了工(在办的需求也是这样读宽:签字之后新加、还没经主控核准的单元照占)
(围栏只认签字时留底的那一份,那一半方向是对的,见下「顶层围栏」)。
⑨ 改判定代码那一道不按单元排、按落点表里的目录(此刻的与最后一笔确认留底的并起来)碰没碰判定代码名单排(见上「认车道」③):碰到的两条单元不同也开不了第二条;名单之外的(各规范的判据与床、内核清单)不进这一道。
**办得超了点名**(ADR-94):履历里的用时与返工、「正在办」那一行的「签字至今多久」只记数、不比;比的是每档另有的两个上限(与条数上限同一张常量表):
办的时间 —— 从开工算起,不含等用户验收的那一段 —— 与独立复盘的轮数(各档是多少同样只写在项目架构设计页第十节那张表)。按最后一次签字那一笔记下的档比。
两个数取现成的那一组、不另算一套:复盘轮数就是账本里复盘的笔数(「正在办」那一行「复盘几次」、履历「独立复盘几轮」的同一个数,过、不过、不可信都算);办的时间,完结那一刻用刚封进履历的那一组数(总用时减去等用户验收的那一段),
在办的时候从开工算到此刻,「等用户验收的那一段」只在最后一笔可信的复盘是「过」时才扣(从它到此刻),最后一笔可信的复盘是「不过」、或还没有可信的复盘时不扣;按整分钟比。超了任一个:用户每次说话时守卫回的「正在办」里,这条需求自己的那一行多一句点名 —— 超了这一档的哪一个上限、上限是多少、现在是多少。
这一句单独算、单独接(`requirements.overNoteOf`):接在那一行原有的那一句(步骤数,或签字作废时催重签的那一句)之后、进度那一段之前,不跟进度那一段走(不占它二百四十字的额度、不会被截掉)——
进度那一段签字作废的不接、在办的需求多于六条时只给前六条接(上面「每次回话列进度」),点名不受这两样限制:排在第六条之后的、签字作废的,超了同样点名,签字作废的按它最后一笔确认记下的档比。
算不出时那一行写「超没超上限读不到」;签字至今还没到这一档的上限时不去算办的时间(也不装履历零件)。完结那一刻的回话里同样点名。**只点名,不拦**:超了照常签得了验收。
签字那一笔没有记档的需求(早先签的)只记数、不比、不点名。
**守不到**:① 只点名:超了没有任何东西被挡住;那一行是塞给执行者的话、只在用户说话时才出现(上面「每次回话列进度」的守不到 ⑥⑦),用户看不看得到取决于执行者转述。
② 办的时间是墙上时间:过夜、等别的需求让路都算在内,只有等用户验收的那一段不算 —— 在办的时候这一段只在最后一笔可信的复盘是「过」时才扣,是「不过」或还没有可信的复盘时不扣、全算办的时间。
③ 复盘轮数连不可信的那几轮一起数。④ 上限是拿已完结需求的记录定的,那些全是顶层需求,对业务需求没有数据;最大那一档办的时间上限是定的、不是量出来的。⑤ 把档改大,这两个上限跟着变大(重签之后按新签那一笔记下的档比)。
**办理会话**(ADR-94):一条需求的账绑在办理会话上、不绑在签字的那个会话上 —— 绑在签字的会话上的话,验收那一刻三查按当场签字的会话重算,签字作废期间只替签字的会话认范围,越界点名按「本会话签过确认」找账本,
封版前的需求对账取最近一笔确认的会话,核对命令按跑它的会话算;交给另一个会话办的需求,两次签字都得请用户去那个会话签,在主控签验收必然记不成(当场重算的单子按主控算,与他看过的那张对不上)。
签「确认」那一笔多记一栏办理会话(owner):写证据台账里最后一个把这份计划的机器镜像写成此刻这份内容的会话 —— 谁写的计划谁办理(执行体写的记在派它的会话名下,按派它的会话认);
台账里没有这样一笔、或台账读不了,就记成签字的那个会话。认这一下只在签「确认」那一刻做一次(要把各会话的台账读一遍)。签字回话里写明认成了谁(会话号前八位),以及是按「这份计划的机器镜像是它写的」认的、
还是认不出退回成签字的会话(这时回话里写着原因,并提示办理的其实是另一个会话的话,让接手的会话跑一次改派命令)。没有这一栏的旧签字,办理会话就是签那一笔的会话。
**机器不认谁是主控;办理会话可以改派**(ADR-98):办理会话先骑在「确认」那一笔上,此后可以由接手的会话用一条命令改派(见下「办理会话改派」),不必经用户重签。全仓只经一个取值函数拿(`requirements.handlerOf`:最后一次签「确认」与其后的改派,谁在后听谁的;那一笔确认没有办理会话这一栏、其后也没有改派的,就是签那一笔的会话号)。
**此后五处都按办理会话算、不按当场是哪个会话算**:① 三查核对命令 —— 签过字的计划一律按它的办理会话算归属,谁跑、带不带会话号,出的结果单同一个编号;传进来的会话号盖不过它,只在这份计划一次都没签过字时兜底;
不带计划名时几份计划各按各的办理会话;单子抬头写明办理会话是谁、单子里的「本会话」指它;「谁写的」一栏、复盘任务说明生成时同样。认不出办理会话(那一笔没记下会话号)时这张单子照「判不了」算红。
② 验收那一刻守卫当场重算的三查。③ 封版前的需求对账(越界与用例闭环两项,上面「两份计划触及同一单元」;封版命令把签那一笔的会话传给核对命令,靠核对命令里办理会话盖过传进来的会话成立)。④ 签字作废期间认谁的范围(签字时的范围只替办理会话认,上面「范围与基线」)。⑤ 越界点名记到谁的账上(「本会话是这条需求的办理会话」)。
「谁在办」那一栏与被拦几次(上面「每次回话列进度」①⑥)、下面的顶层围栏读的是同一个取值。所以一条由产品经理写计划、办理的需求,用户在另一个会话里签「确认」与「验收完结」都签得成 ——
记下的办理会话是写计划的那个会话,三查按它算,全绿照常记完结。封版在办理会话里跑(封哪些改动按跑封版的会话认;另认一种 —— 本会话办理着的需求范围里、由办理过这条需求的前任写的改动照封,见下「办理会话改派」);签字基线不绑会话(它是开工那一刻全仓受治文件的指纹)。
**守不到**:① 办理会话会认错,两种情形:用脚本(不经编辑工具)写机器镜像的没有写证据,退回成签字的会话;别的会话后来改过机器镜像(哪怕一个错别字)就认成它 —— 架构师审计划、主控过目时顺手改一处,最后写的人就成了它,
产品经理的改动全算别的会话:第三查红、封版对账那两项对这条需求不查、顶层文件它自己写不动。兜着的只有签字回话里认成了谁的那半句(X大脑 当场拿它对会话登记册里登记的这条需求的产品经理,§十五「会话登记册与恢复」)与「X大脑 和架构师不动机器镜像」的纪律;
认错了,真正办理的那个会话跑一次改派命令,或由主控、项目经理指名改派。② 签字的会话:做到的是「在主控签得成」;会话登记册登记了主控时还限定「只许在主控签」—— 别的会话里的签字说法不记不认(上「签字记录只认两条路」的说话只认主控),登记册读不出来、没登记主控时机器不限,产品经理会话里用户若真说了固定那句,机器照记,
「产品经理不自己弹签字题」仍是 §十五 的规矩。③ 连着三次复盘不过之后那一次发话,机器只认派复盘的那个会话里用户说过话(下面「复盘进关口」);派复盘的就是产品经理会话,所以这一次发话在那个会话里 —— 产品经理停下手,由 X大脑 请用户到那个会话里发话。
④ 一条需求做到一半换会话接着做(两个会话各改了几格):范围里的改动跟着需求走(见下「办理会话改派」里「改派不改历史」)—— 办理过这条需求的会话在范围里写的、此刻内容还是它那一份的,三查与封版都算这条需求的,做到一半就能换
(只认最后一次签字记下的那一个的话,前任在范围里没封的改动会按别的会话算、哪边当办理会话第三查都红)。治不了的剩两样:前任在范围外的改动(越界)记在前任名下,
新办理会话的三查不管它,只靠前任自己的收尾对账;前任交出去之前用命令行写的(没有写证据)分不出是交出之前还是之后写的。⑤ 主控记签字的同一刻,办理会话的钩子也往同一本需求账本追加(越界点名、复盘结论)会把账本的链撞断(上面「记洞不改」里讲账本追加没有跨进程排队的那一句)——
签字在主控记,这种同刻落笔因此多一种来源;靠「报完请签字就停手等回话」的规矩(§十五「怎么派工」④),没加锁。
**办理会话改派**(ADR-98):签「确认」那一刻按「机器镜像最后是谁写的」认出的办理会话,
在会话号一换(清空重开、换一个会话接手)、或别的会话写了机器镜像而由产品经理办时,就不是真正干活的那个会话 —— 不能改派的话,真正干活的会话被围栏拦在外面,出路只有重存机器镜像、请用户重签一次。
体系守护命令的改派动作 `harness.js --action=handoff --plan=<计划名> --take`(零件 `x-harness-dev/scripts/core/plan-handoff.js` 只是薄薄一层:能不能改派与记账都在守卫需求零件的 `requirements.takeOver` 里,
经守卫自己的记账口写,带链、进仓外镜像):跑它的会话成为这条需求的办理会话,需求账本追加一笔 handoff(跑命令的会话、从谁到谁、几点)。计划名认目录名、短名或需求全文(与签字那几句话同一种认法);
会话号只取环境变量(入口不设开关:接手的只能是跑命令的这个会话自己)。此后顶层围栏、写前按办理会话判、三查、越界记账、施工区的归属与副本提醒、「谁在办」那一栏都按改派后的会话算(它们取办理会话只经 `handlerOf` 一处);
原办理会话不再是它的办理会话,它没办着别的需求的话再写受治文件会被拦。**签字与改派,谁在后听谁的**:改派只作数到下一次签字为止 —— 用户再签一次「确认」,以新签那一笔认出来的为准,会盖掉之前的改派,认得不对就再跑一次;
还没签过字就出现的改派不算数。**拒绝并且什么都不动**:没带 `--take`、没写计划名、取不到会话号(环境变量是空的,或守卫记成「没有会话号」的那一种)、计划目录里没有这条计划或名字对上不止一份(已经清理归档的不再改派)、
机器镜像读不了、账本被直接改过、还没签过字、已经完结;签字作废的需求照样可以改派(作废期间也要有人办)。本来就是办理会话的照实说、不重复记,退出码零;被拒绝或没做成退出码非零。
**守卫的几句回话同批带上这条命令**(写法只有守卫导出的一份 `requirements.handoffCommand`,与改派命令自己给出的那一句由床对拍):签「确认」的回话里讲认成了谁的那半句(认对了的写「办它的其实是另一个会话的话,让那个会话跑一次改派命令:」加那条命令,
认不出的写「让接手的那个会话跑一次改派命令:」加那条命令,再接「不用重存机器镜像、也不用请用户重签」);顶层围栏拦下时(此刻有需求占着那个单元,多一句「本会话就是来办占着它的那条需求的(会话清空重开过,或换人接手):跑改派命令接手 ——」加那条命令);不是办理会话被拦时的两条出路;
写后提醒与收尾点名落进别人范围的那两句(见下「写前按办理会话判」)。
**指名改派与自助改派分开记**(ADR-116):改派命令另有一种写法 `harness.js --action=handoff --plan=<计划名> --to=<完整会话号>` —— 由主控或项目经理跑(会话登记册里登记的那两个身份),把办理会话改给指名的那个会话;账本里那一笔 `handoff` 多记 `named:true` 与 `by:<跑命令的会话号>`。谁都能跑的 `--take`(接手的会话自己成为办理会话)那一笔多记 `self:true`。两种都改 `handlerOf` 的取值,三查、顶层围栏、写前按办理会话判、越界记账都照改派后的会话算;**签字放行只认指名的、不认自助的**(环1「签字放行」):自助改派能把三查和写前拦截接过去,带不走受保护文件的放行,因为它不经任何人点头 —— 任何会话跑一条命令就成为办理会话,拿它换放行等于把签字一的授权白送。登记册里登记为这条需求产品经理的会话不用改派,放行本来就认。
**改派不改历史、改动跟着需求走**:改派那一笔不重写、不转移任何旧记录,已有的写证据归谁还归谁。做到一半换会话时,范围里已经有前任写的改动 —— 只按写证据的归属算,它们在新办理会话的单子上是「别的会话」:
落点格被判成只有别的会话改过;封版对账以为这条需求没碰过本单元;它改到的单元被归进「只有别的会话在途改到」、不判封没封 —— 这条需求变成「没改到任何版本单元」,单元没封第三查照样绿(假绿);新办理会话也封不进去(封版把它们当别的会话的在途改动、保留旧指纹)。
所以对这条需求**范围里**的文件,凡是办理过这条需求的会话(`requirements.handlersEverOf`:历次签字记下的办理会话,加签字之后历次改派接手的)写的、此刻内容还是它那一份的,封版与三查都算这条需求的。
判定器只有守卫一份(`requirements.formerHandlersWrote`):三查用它给这类改动标上「办理过这条需求的会话,算这条需求的」,三处认它 —— 这条需求动没动过手(封版对账用)、改到的单元归谁(第三查判封没封)、落点格;
统一封版命令挑「哪些别的会话的在途改动保留旧指纹」时(`x-meta-dev` 封版零件的 `keepOldOf`)对本会话办理着的需求问同一个函数,这类改动照封。重签换了办理会话、而此刻内容是前一个办理会话写的,同样算。
「是谁写的」不另立一套:先认会话归属里记着的主人(命令行写的也认得出),归属里没有这个文件才退回写证据的内容指纹。**范围外的不认**:前任的越界记在前任名下、保留旧指纹,不算到新办理会话头上。
收尾对账那一侧同一个道理:本会话交出一条需求之前当办理会话时用编辑工具写在它范围里的,不算「写进别人的范围」;交出之后还往里写的照点名(按最后一次写这个文件的时刻与交出那一笔的时刻比,`requirements.handedAwayAt`)。
**为什么不要用户重签**:换谁来办不改需求的内容(标准、用例、范围一个字没变),让用户为一件他判断不了的事再签一次,签的只是一个会话号。否决「登记办理会话」那条路的三条理由
(要去被登记的那个会话里说、多一笔换会话要重登的状态、多一个不经签字就能改的口),第一条对改派不成立 —— 它是接手的会话自己跑的一条命令,不用用户过去说话;后两条照实认下,写在下面。
**守不到**:① 改派不经用户 —— 任何会话跑这一条命令就成为办理会话(它是受治树里现成的脚本,不是办理会话的会话也跑得了),顶层围栏与写前那一道对「故意」不设防,
与整套体系防手滑不防故意同一条边界:它防的是认错人,不是防人;留下的是账本里那一笔,用户每次说话时「正在办」那一行写着此刻是谁在办;
② 会话号来自环境变量,冒充的边界同 §十三 诚实边界 ⑦;③ 往账本追加没有跨进程排队,改派那一笔与守卫同刻落笔会把链撞断
(上面「记洞不改」里讲往账本追加的那一句);④ 重签会盖掉之前的改派:用户重签那一刻又按「机器镜像是谁写的」认,认成了别的会话就要再跑一次;
⑤ 改派之后前任的范围外改动,新办理会话的三查守不到(它们在单子上是「别的会话」那一栏,只列不判),只靠前任自己的收尾对账 —— 前任不再收尾就没有人点名;
⑥ 前任交出去之前用命令行写的(没有写证据)分不出先后,收尾照点名;⑦ 「办理过这条需求的会话写的」三查与封版都只问守卫:守卫里没有那个函数(不是同一版)、或需求零件装不上,就一个都不认 ——
三查把它们当别的会话的、封版保留旧指纹,往不过的方向错,没有别的退路。守着它的床:`.claude/skills/x-harness-dev/tests/plan-handoff.test.js`。
**落点格认办理会话签字后的写证据**(ADR-94):第三查判落点表里的每一格,要它「变过、而且不全是别的会话改的」,而「谁改的」按文件此刻的内容认、后写的人赢 ——
别的会话后来在同一份文件上接着改、封了版,这一格就只剩别的会话,验收卡红、只能拿掉落点重签。所以一格里此刻的改动全归别的会话时再查一步写证据台账:
办理会话(各次「确认」记下的都算,改派记下的同样算)在第一次签字之后,对这一格里某个变过的文件有过编辑工具的写证据(执行体的写记在派它的会话名下,一样算),这一格不判坏格;结果单那一格写明有几个文件是按这一条认的。
按这一条认下的格与文件数进结果单编号;没有这种格的单子,编号与没有这一条时逐字相同。**只放宽、不收紧**:不按这一条也不判坏的照样不判坏;办理会话只在签字之前写过、从没写过、或这一格变过的文件都没有它的写证据
(命令行写的、封版命令写的锁清单)的,判坏格。封版对账用的「这条需求动没动过手」不认这一条(只按此刻的内容认人;它与落点格都另认一种 —— 此刻的内容是办理过这条需求的前任写的也算这条需求动过,见上「办理会话改派」里「改派不改历史」)。
**守不到**(治不了的三样,照实写):① 只含锁清单这类没有写证据的文件的格 —— 这一条只认编辑工具的写证据,落点表把只由命令写的文件单列一格、或办理会话全程用命令行改文件的,这一格会红。
② 别的会话在同一个单元上还没封版时,第三查「封版之后有变动」的红(设计如此,等它封)。③ 共享文件一变,已经过了的复盘作废(设计如此,靠排次序)。
另:认的是「写过」不是「此刻的内容是它的」—— 办理会话写过、又被别人整个改掉的格也按这一条认;单子上写明了是按这一条认的,由复盘者对着看。
**顶层围栏**(ADR-94):写前那一道要是只问仓里有没有在办的需求 —— 有任何一条,任何会话写宪法、本文、规则书、判据、架构页都放;业务的会话误写一个顶层文件,那条顶层需求若把它列进了范围,
收尾对账既不拦也不列,之后那条顶层需求的第三查要整单元封版后零改动、封版又不收别的会话的在途改动 —— 它验收不了,全仓发布被版本比对拦;「业务需求的产品经理不碰顶层」就只是纪律。
所以写前另有一道,编辑工具与命令行直写共用(`requirements.writeBlockWhy`,多收一个会话号;排在「账本被直接改过」之后、「本会话是办理会话才放」之前):要写的文件归整个框架、某个系统规范域、项目架构或 agent 架构这四类版本单元时(agent 架构含它的设计页、变更历史、锁清单与全部执行体文件,ADR-101:执行体文件要办着列有 agent 架构这个单元的需求才写得动,只列整个框架的写不动),
写的会话必须是某条在办或签字作废、而且落点表列有**该单元**的需求的办理会话,否则写前拦下。认的是有效范围里的单元(签字时的单元加已核准的)—— 作废之后改过、没人签过的、没核准的机器镜像不算数,
否则往自己的计划里添一个顶层单元就能给自己开门。机器镜像读不了的计划围栏不认(不拿它给哪个会话开门,回话里「此刻占着这个单元的需求」也不列它,方向是拦)。**归不归、归哪个单元只问版本契约的名册**(各单元的 owns 只看路径判,§十三「归属只有一个口径」;单元自己的变更历史与锁清单也算归它;
守卫经 `requirements.topUnitOf` 问它),守卫不另立一套判法 —— 业务域与业务总览不在这四类里(守卫里是一张层名单:名册里层是整个框架、系统规范域、项目架构、agent 架构的单元算顶层)。**按严的口径**:要那条需求的落点表列有这个文件所归的那个单元才放 —— 办着整个框架的会话,写一份它的落点表没列的规范域的文件照拦;
文件在不在落点表的格里仍归写后提醒与收尾对账,这一道不管。回话写明:这个文件归哪个单元、本会话(会话号前八位)不是办它的会话、此刻占着这个单元的是哪条需求(短名与办理会话号前八位,签字作废的注明;没有就写此刻没有),
并告诉它找主控立项。执行体按派它的会话算(它与派它的会话同一个会话号)—— X大脑 直接派的只限不动受治文件的小事,不涉及这道围栏。不归这四类单元的文件(业务代码、业务域的设计、计划与看板、运行时目录、
不归任何单元的文件)不受这道围栏影响,照写前按办理会话判(见下「写前按办理会话判」)。版本契约装不上、名册列不出、判不了归属的,按拦处理。**便宜的判断放前面,做成确定的两样**:一、守卫先用一张路径预筛表放掉不可能归这四类单元的写
(`requirements.TOP_PATH_PREFIXES`,目录前缀与整个文件两种写法;agent 架构目录 `.claude/arch/agent/` 与执行体目录 `.claude/agents/` 在 agent 架构名下),写业务文件不装版本契约(见上「挂载」里「零件用到才装」);二、预筛与名册对不对得上由一张床对拍 —— 名册里这四类单元管的任何路径落在预筛之外,床就红。
不做计时类的用例(机器忙的时候它会随机变红、卡住封版);量过一次:写业务文件前后几乎不变,写顶层文件多三十来毫秒。
**守不到**:① 脚本进程内的写不经任何写前拦截(与整套体系同一条边界,§十三 诚实边界 ⑤);命令行只挡直写落点的常见形态(与写前的需求闸同一个射程)—— 直写的目标带变量、通配或反引号时写前那个判定不判,
围栏的命令行那一半跟着看不见(这一句是读代码读出来的,没有实测);Windows 上的路径别名会不会绕过预筛,没有核实(大小写与反斜杠写法同判,有用例守着);平台另有的 PowerShell 工具、笔记本编辑工具守卫不处理(上面「守不到之处」①④)。
② 写前拦截摘下(开闸)期间这一道整个不在岗:任何会话都写得了顶层文件,事后只有收尾对账与版本契约那两样照常(都不分是不是办理会话)。③ 不归任何单元的受治文件围栏不管。最重的两样:钩子接线文件(另有脊柱写保护,对谁都拦),
守卫与技能目录下的测试 —— 版本契约把测试整个不算进单元,守卫自己的测试另有脊柱写保护,技能目录下的测试没有;§十五 说它们「跟着被测的部件算顶层」是派工的口径,围栏不认。
另有部署门登记表、治理站点的源码与构建器、官网(§十三 诚实边界 ③⑥)。
④ 认的是办理会话,所以办理会话认错时(上面「办理会话」的守不到 ①)围栏跟着错:真正干活的会话被拦在顶层之外,被认成办理会话的那个会话反而写得动。认错了跑一次改派命令就改得回;反过来,改派不经用户,任何会话跑那一条命令就写得动(见上「办理会话改派」的守不到 ①)。⑤ 围栏不认谁是主控(会话登记册只在会话命令、代签命令、签字放行、说话只认主控与定时任务通道里用到):它问的是「这个会话手上有没有一条列着该单元的在办需求」,
业务的会话自己起草一条列着顶层单元的计划、用户签了确认,它就写得动 ——「顶层的需求由主控立项」是纪律,兜着的是用户签字时看见的范围那一组与同一块排队(那个单元上正有别人占着时它开不了工)。
⑥ 一个顶层单元上同一时刻可以有不止一条需求的办理会话写得动(早先已经同占的、签字作废的都算)。⑦ 还没出生的单元名册不认:全新的技能目录、新规范的第一个文件,在名册认得它之前写它,围栏不拦。
⑧ 删除不过这道围栏(它只管写)。⑨ 写前那个判定不带会话号直接调时不判围栏(守卫里的三处调用都带;测试里有直调不带的)。
**写前按办理会话判**(ADR-98):「没签字不许写」要是只问全仓 —— 仓里只要有一条在办的需求,任何会话写受治文件、跑任何命令都放
(顶层三类单元另有围栏,别的受治文件没有);收尾对账把全部在办需求的范围合起来当「范围里」的话,写进别人在办范围的改动既不拦也不点名。所以有在办需求时问本会话:
写受治文件(编辑工具与命令行直写)与命令行闭集,只放「本会话是某条在办或签字作废的需求的办理会话」的(签了字还在排队的需求不算在办,它的办理会话和没签字时一样被拦)。这一问只住一处(`requirements.sessionGate`;办理会话的取值与顶层围栏同一个,`requirements.handlerOf`):
写前那一道(`requirements.writeBlockWhy`)与命令行闭集(`command-policy.isUnsigned`)问的是同一问。不是任何一条的办理会话:写受治文件拦,回话是「本会话(会话号前八位)不是任何在办需求的办理会话 —— 正在办的:」加每一条的短名、计划名与办理会话号前八位(最多点名六条),
再接「有在办需求时,受治文件 <路径> 只有办理会话写得了(执行体与派它的会话同一个会话号,按派它的会话算)」、两条出路(这件事属于其中哪一条,就交给它的办理会话去做,或者由本会话接手那一条 —— 给出改派命令;是另一件事,就另立一条需求、让用户签「确认」)
与「不拦的只有:计划与看板本身、.claude/tmp、仓库外的文件」;命令行照没有在办需求时那样只放闭集白名单(只读命令、受治树里已有的脚本照跑 —— 核对、排队、改派、发布这些命令都是受治树里的脚本),白名单还是那一份,
报文以「不是办理会话:」开头、出路是上面那两条(`command-policy.notHandlerWhy`)。没有在办需求时照没签字那一支判(仓里只有签字作废的需求时也走那一支,「签字作废期间本会话已经写过的文件」那条豁免在那里)。
不受此限的:计划目录、账本目录(免检面)、仓外;发布档案目录不是受治文件,命令行那一侧另开一个口 —— 有在办需求而本会话不是办理会话时(运维经理平时就是这种),落点在发布档案目录里的命令照放(清作废的档案),
档案自己的写保护另有一道、不归这里;真没有在办需求时这个口不生效。执行体按派它的会话算。**写后提醒**(`requirements.afterWriteNote` 多收会话号):盖住这个文件的全是别的会话办的需求时,不说「在设计范围里、做完记得勾掉」,
而说「落在别的会话在办的需求的设计范围里……本会话不是它的办理会话,这一笔不算在本会话的范围里,收尾对账会点名一次」,并给两条路(撤回、交给它的办理会话去改,或由本会话接手 —— 改派命令)。
**收尾对账**(`requirements.stopAudit`):只把本会话办理的需求范围当「范围里」;本会话写进别的会话在办范围里的改动,拦一次并点名落进了谁的范围、记进同一本越界账(多一栏 into;同一份内容只这一次,改了内容再点名),
回话给同样两条路。本会话交出那条需求之前写的不点名(见上「办理会话改派」)。**三查不收紧**:核对命令把落在别的在办需求范围里的改动印在「归别的需求范围」一栏、不算本需求越界 —— 这一类收尾说越界、三查不说,两处口径在这一类上不同(见上「守卫提速的几处口径」①)。
**与顶层围栏的关系**:围栏问的是「办着列有该单元的需求」,更严,两道都过才放;这一道管的是围栏管不到的业务文件与不归顶层单元的受治文件。
**守不到**:① 办着甲需求的会话写乙需求范围里的业务文件,写前照放(它是办理会话),只在写后提醒一句、收尾拦一次 —— 写前不问文件在不在自己的落点表里;
② 写前拦截摘下(开闸)期间整道不在岗;③ 脚本进程内的写、平台另有的 PowerShell 工具与笔记本编辑工具看不见(上面「守不到之处」①④);
④ 办理会话认错或改派之后,放谁拦谁跟着变(见上「办理会话改派」);⑤ 只做分析、手上没有需求的会话,在有人办需求时也写不了受治文件 —— 这是要的效果,
它同时挡住「顺手帮别的会话改一行」:要改,让办理会话改,或改派;⑥ 这一问不带会话号直接调时只问有没有在办需求(守卫里的调用都带,测试里有直调不带的)。
**收尾与复盘的几处口径**(ADR-74):没签字时收尾按归属拦本会话改过的受治文件(记 `_unsigned` 账本、同内容只拦一次);
复盘要可信(第一条提示词逐字等于程序生成的派发表头)且绑定范围内文件指纹,代码一变作废;三查核对命令与复盘说明程序进脊柱;
第三查只按本会话改到的单元判、别的会话在途改到的单列、一个单元都没改到也能完结;没有基线 / 台账读不了 / 没指定会话 / 空壳对照
判不了一律红;归属与收尾对账同一口径(借守卫的量仓与台账归属,命令行写的也认得出);签字作废期间之外没有「本会话写过就放」的豁免。(这一段里的「本会话」对签过字的计划指它的办理会话:核对命令不传会话、传别的会话,都按办理会话算,传进来的会话号只在一次都没签过字时兜底,见上「办理会话」。)
**复盘进关口**:复盘者的任务说明由程序生成(`harness.js --action=review-brief`,带任务编号),全文写进账本目录(`<名>.review-brief.md`,账 `<名>.review-brief.json` 在同目录);
**派给复盘者的提示词不是说明全文,是命令印出来的一段几行的派发表头**,复盘者自己用读文件工具去读说明文件(机器之间传大段内容,传位置加指纹,不让模型复述,ADR-122)。
表头由守卫需求零件里一个函数(`dispatchHeadOf`)按账和说明文件现算,不另存文件(清理归档认的过程文件名单不变);说明生成程序、接力命令末尾、守卫三处都调它,算法只此一份;
说明正文的内容指纹(sha256 前八位,就是任务编号)与说明第一行(标记行)的拼法也在需求零件里,全仓只此一处。
样子:第一行是说明文件的第一行(标记行:任务编号、计划名、结果单编号),空一行,接着交代三件事 —— 这是程序生成的表头、这几行之外没有别的话,说明文件在仓根下的位置(仓根相对路径、正斜杠),
请用读文件工具(要绝对路径,工作目录就是仓根)从第 1 行读到最后一行(写明共几行)、一次读不完就用 `offset` 和 `limit` 分段接着读、说明第 1 行的任务编号与表头第一行相同。表头只做认领、指路、交代怎么读,
判法、需求、标准、结论行的格式都只在说明文件里,表头一个字不抄(单一出处);表头里不写仓根(命令与守卫是两个进程,各自取仓根,盘符大小写、斜杠写法可能不同,写进去就可能逐字对不上),所以表头只随编号、计划名、结果单编号和说明的行数变。
**口径写死**:说明文件 = 标记行 + 两个换行 + 正文 + 一个换行;内容指纹算的是正文(去掉第一行、一个空行和末尾那一个换行,末尾不留换行 —— 留着末尾换行算出来是别的指纹,所有表头就都出不来);
「最后一行」N = 说明文件按换行拆开、去掉末尾空串之后的行数(`briefLinesOf`,表头里的「共 N 行」与读全的判定都用它)。
出得来表头的条件只有三个(任一不成立就没有表头,不抛):账与说明文件都读得出(编号是八位十六进制、有结果单编号);说明文件第一行逐字等于由账拼出的标记行(计划名也在这一行里);说明正文现算的内容指纹等于账里的编号 ——
所以说明文件被改过而账没动、账与文件对不上、其一不在,都出不来表头。命令的标准输出只印表头(说明全文不打印),写不进账本目录或写完现算不出表头就退出码 1、什么都不印;
接力命令七步走完,末尾把同一段原样印出来,前后各一行分隔线(「──── 派发表头(只复制这条线和下一条线之间的,原样、一个字不改)────」与「──── 派发表头到这里 ────」;表头之外还有一句说明和环的态,免得复制时多拷),最后一行仍是复盘说明的编号。只有这一种写法:说明读不了是账本目录坏了、该修,不另留缩短的全文版(缩短的全文仍是复述);
SubagentStop 只管复盘者(只按它收到的第一条提示词里的任务说明标记认;不按执行体类型、不扫整份转录:对抗审查官做普通挑刺、
或干活时读过含标记的文件,都不归这里):
最后一行必须是「复盘结论:过 / 不过 <计划名> <结果单编号>」,不对不让收尾,认出即进账本(不过也记);
同时从他最后那段话里取「遗留」一节(ADR-93;`requirements.parseLeftovers`):标题行去掉打头的井号与空白、去掉结尾的冒号之后整行恰好是「遗留」
(也认加粗的写法,冒号写在加粗里面外面都认;别的不放宽),从它到下一个标题行或结论行为止,以短横打头的行才算一条,整条是「无」的不算
(任务说明让他把「遗留」紧挨着结论行写,所以这一节到结论行之间以短横打头的行都算);随这一笔复盘结论记进账本(多一栏、不多写一笔;
每条三百字封顶、最多二十条,写多了的后面几条静默丢掉),回给领队的话里说明认出了几条;没有这一节不拦收尾、不改结论,只在回话里说没认出并写明该怎么写
(「有这一节但是空的」与「没有这一节」分开记);
**可信**要下面这些都成立:账在、提示词里的任务编号等于账里的编号、提示词逐字等于此刻现算的表头(同一个函数,等于把上面出表头的几个条件在收尾又核一遍)、账里记的内容编号等于此刻的内容编号
(复盘途中改了计划再重签,复盘者看的是旧内容)、类型恰是对抗审查执行体、结论里的结果单编号等于账里那一张、没被续跑(记录里不止一条用户提示词)、同一份说明只记一笔、**读全了**。
不可信的那一笔照记、标不可信、不计入连败,回给领队的话里点名缺哪一样(先后次序:不是对抗审查执行体、提示词不是对当前内容生成的派发表头、结果单编号不对、被续跑、同一份说明已记过、没读全)。
**读全了**(`briefReadAllIn`,放在需求零件,纯函数,自己包住、出错按没读全、不抛;守卫收尾那一支调它时再包一层,出错按「读取记录判不了」,因为守卫里任何抛错都是退出码 2、结论就丢)看复盘者的执行体记录(收尾事件里 agent_transcript_path 那一份,一行一条 JSON)。
取读取情况的那一部分单独成一个函数(`readCoverageIn`:对某个文件的读调用数、其中报错的数、各次非报错结果里认出的行号、行号 1 那一行的内容),一次性拿真记录核对读法时也直接用它:
① 找记录里读这份说明文件的调用:调用参数里的文件路径(`file_path`)归一后(反斜杠换成正斜杠;比较用守卫现成的 `keyOf`,Windows 上不分大小写、别的系统区分)与这份说明文件的仓根相对路径整串相等、或以「/」加它结尾才算 —— 只比后缀「.review-brief.md」不行(读了别的计划的说明不算);
搜索工具的参数里没有 `file_path`、命令行读也没有,所以它们读的一概不算(要的是整份看过,搜索只给片段);
② 取这些调用对应的工具结果(按工具调用编号配对),带出错标记的、没有行号的不算(单次读有上限,读大说明时中间夹一次超限报错是常态,那句报错没有行号);结果是一整串字、或文字块数组,都认;
③ 把每个结果里每行开头的「行号 + 制表符」拆出来,各次读到的行号取并集(同一次读在记录里还有请求拷贝里的副本,不按次数累计),并集要盖住 1 到最后一行,一次读完、分段读完都行;
空行在记录里是「行号 + 制表符 + 什么都没有」,不能因为没内容就丢(不能先去掉首尾空白再匹配);读到的结果会多出一个幻影行 N+1,多出来不碍事,漏最后一行 N 必须判没读全;
④ 读到的第 1 行里的任务编号等于账里的编号。
回话分五种说(缘由前面是「复盘者没有把任务说明读全:」;全对不说):「没有对说明文件的读取」;「对说明文件的读取都报了错(如超限),没有读到内容」;
「有读取但一行行号都认不出(平台记录的写法可能变了,读法可能失效,报 X大脑)」;「第 N 行起没读到」;「读到的首行编号是 xxxx,表头是 yyyy」;函数自己出错说「读取记录判不了」。
只能从执行体记录里取:钩子接线里没有接读文件工具(写前只接派执行体、命令行、写入类、选项题、云端工具等;接线文件是钥匙石,只有用户亲手改),读这件事只存在于记录里。
记录里的真形状:路径可以是带反斜杠的写法(JSON 里写成双反斜杠),也可以是正斜杠;成功的结果是一整串字,每行「行号 + 制表符 + 内容」(制表符之后可以什么都没有),分段读时第一行的行号就是起始行,
结果同一条里后面可能跟着一块系统提醒文字,出错标记可以写在内容后面;超限的结果带出错标记、是一句报错、没有行号;搜索工具的结果写成「行号:内容」、不是制表符。
**从生成到收尾,说明文件被改了或被换了怎么判**:
· 生成(命令):写说明、写账,现算表头,命令印表头。
· 派发(写前这一关):现算表头(账与文件对得上才有),提示词须逐字等于它 —— 正文被改而账没动:现算指纹与账不符,没有表头,拦;生成之后又重新生成且内容变了:手里的旧表头不等于新表头,拦;账或说明文件不在:拦。
· 读(审查官自己读):不插手(接线里没有读文件的钩子);读到的是哪一版,靠收尾那一核的首行编号认。
· 收尾(SubagentStop):再现算一次表头,须仍等于第一条提示词,再核账里的内容编号等于此刻的内容编号、再核读取记录 —— 派发之后重新生成过且内容变:编号变,提示词不等于现算的表头,记不可信;派发之后被手改:现算指纹与账不符,同上;
复盘途中改了计划再重签(说明是对旧内容生成的):内容编号对不上,记不可信;读到的是改之前的旧版:首行编号不等于表头,记不可信;读漏了行:记不可信,点名从第几行起。
· 守不到:审查官读的过程中说明被换成别的内容、读完又换回原样(要在生成程序之外写账本目录,与既有「进程内直接写」同一条边界)。
派复盘者(Agent 工具、提示词带任务说明标记)时,提示词须逐字等于此刻现算的派发表头才放(`headSlugOf`:在账本目录里找「现算的表头与提示词逐字相同、只忽略首尾空白与换行风格」的那一份计划,
计划名从那一份取、不从提示词里读 —— 改表头里的计划名绕不开连续三次不过的拦);找不到就拦:抄说明全文、表头里改一个字或加减一句话、改计划名、说明正文被改过、账或说明文件不在,都在此,报文只有一条固定话,
以「复盘任务的提示词必须原样是程序生成的派发表头」打头,后面写怎么办 —— 先跑复盘说明命令,把印出来的表头整段原样当提示词(不加字、不删字),任务说明全文在账本目录的文件里、审查官自己读,不要抄进提示词;
带名字、类型不对、需求账本被直接改过各拦(见上「派执行体通道」);连续三次不过、用户没发话 ⇒ 不让再派 —— 这一道本文叫**复盘派出那一道**(守卫报文以「环1 复盘:」打头;
别和「派发闸」混:那个名字指按名册拦的那一道,报文以「环1 派发:」打头,见上「派发闸」)。「用户发话」只认派复盘的那个会话里说的话:判法只看这一样,
不看派它的是不是办理会话,复盘者收尾记结论可不可信也不看是哪个会话派的。所以这下一次发话在派复盘的那个产品经理会话里 —— 产品经理停下手,由 X大脑 请用户到那个会话里发话,再由它派。
治理站点新鲜度传感器对不上的源只提示、不拦,不论是哪个会话改的(ADR-98),见下环3「治理站点新鲜度传感器」。
诚实边界:账本在本机、脚本能改(洞二);用户读没读就回了那句话机器不知道;复盘者读到的计划与代码是执行者写的,能被事先埋的注释误导;
派发表头与读全另有七样守不到:① 审查官读的过程中说明被换成别的内容、读完又换回原样(上面时间线的最后一条);
② 「读全」靠执行体记录里读这份说明文件的结果的写法(行号加制表符),平台改了写法,复盘会全记成不可信(往安全的方向错),要更新读法;回话里「有读取但一行行号都认不出」那一种就是这个信号,话里写明「报 X大脑」;
床里的夹具照真记录写,抓不到平台以后的变化,所以复盘者明明读了、却被记成没读全时,停下报 X大脑,不重派、不换法子;③ 读全不等于读懂、读对:读了没用上机器不判,由三查与验收兜;
④ 用搜索工具或命令行读说明的不认(它们的调用里没有 `file_path`),可能误伤按片段读的审查官,所以定义与表头里都写明用读文件工具;⑤ 平台的安全检查会不会连几行的表头也拦,这里保证不了:拦了就停下报 X大脑,不重试、不改写、不换会话、不换型号;
⑥ 派出之后不能续跑审查官(续跑记不可信),要再复盘就重派一个;⑦ 不可信的原因不落账:复盘笔里没有原因栏、不记原因码,原因只在复盘者收尾那一刻守卫回的话里;
三查里「最新复盘不可信」按可能的几种原因说、不指某一个(提示词不是程序生成的派发表头、没把说明读全、结果单编号对不上、被续跑或重复),所以读不全的复盘不会在三查里被说成「提示词不对」,要回头看当时守卫回的话;履历里「结论不可信」那一句沿用固定写法、不分原因。
· **收尾继续拦**:`stop_hook_active` 到了不直接放(直接放等于每轮只拦一次)。
每轮把红项数记进台账(事件 `sr`);被拦过之后那一次收尾照常再查 —— 红项比上一轮少
但没清零 ⇒ 继续拦(改动在往对的方向走);没减少 ⇒ 放行并说明(不无限循环,平台对连续拦另有上限);
台账里没有上一轮红数(老台账)⇒ 只拦一次。红数 = 本轮不过的检测结果条数
(不过的批次与传感器 + 基础设施异常;治理站点新鲜度那一个传感器只提示、不算),不用「没记干净的文件数」(批次之外有一处不过就一个文件
都不记干净,那个数恒等于全部改动文件数,修好别的红也显示没减少);无规范规则书的变更告知不算
红数(同一内容只出现一次,算进去什么都没修红数也会降),放行那一轮把报备的是哪本规则书说出来。
代价:同一批里只修好一部分文件不算减少,少拦一轮。继续那一轮不把写后复判标成已报(留到下一次收尾报)
· **红结论每轮再查(ADR-60)**:干净结论按内容指纹缓存,红结论不缓存 ——
一个文件合规与否不只取决于它自己的内容(注册表在别处补上、上游域改好,它一字没动也转干净);
只按内容指纹记一次,就等于「红了只能靠改自己的内容翻案」,而那正是为骗过机制去改代码。
本会话的(mine)与无主的(side)同一条规矩
· **批次报红先定位再记账(同上)**:报文认不出文件名时逐个复跑,只把真报红的记红,
干净的邻居不连坐;预算 8 次跑用尽、或逐个跑仍全绿(跨文件不变量),才退回整批算红
并在报文里说清是「定位不到」。**没跑成的一个结论都不记**(记成干净就是假绿)
· **治理站点新鲜度传感器**:本轮碰过受治树或站点源码 ⇒ spawn 构建器的
`--check`(源清单逐文件比指纹 + 产物存在性),对不上只在收尾的附注里提示一句、不拦、不算红数
(ADR-98:拦了,会话就卡在收尾等别人把站点建好,它自己就地建又可能与别的会话撞车)。
三种过期各说各的一句:有本会话改的源 ⇒「📖 治理站点过期:本会话改的 N 份源还没进产物(点名前四份)。收尾环只提示、不建站:谁改了源谁可以建一次 —— node x-harness/builder/build.js(构建器有锁,不会撞车);发布处必建,过期的产物发不出去。」;
全是别人改的 ⇒ 另一句(改它们的会话重建即可,或任何人跑一次构建,本会话不拦);构建器的报文里一份源都认不出(产物缺了之类)⇒ 照实说它没点名、带上它的原话(同样只提示)。
**传感器自己没跑成**(构建器起不来、超时)同样只提示:附注里写「治理站点新不新这一轮没查成(原因):这一项只是提示、不拦。想确认就跑 node x-harness/builder/build.js --check;发布处必建。」—— 不许静默,但查的这一项本身不拦,查不成更没有理由拦;
认「是哪几份源」靠构建器只读检查输出里「· 变了 / 新增 / 删了 <路径>」三种行的写法,也靠它不拿锁、不等(§九「谁建站点、什么时候建」):
那三种行的写法改了,这里就认不出是谁改的、落到第三句。
提示不逼着建:谁改了源谁就可以建(构建器有锁),不建只是本机产物旧一阵子,发布之前必建。**只验不建**——
向导侧执行、传感器侧只检测(宪法 §三 的控制哲学在这里劈开);站点不存在就整段跳过
(框架【操作】材料、绝不【依赖】材料)。它与装配面那两条判据同属「改了 A 忘了跑 B」类,
单文件 detector 结构性看不见,只能由 Stop 环承担
· **版本契约(ADR-69)**:增量检测带 `--wip` 跑(收尾、开发流 VERIFY 与封版的检测前置传;全量检测与发布不传),
内置的版本契约一段逐个改动文件判「属于哪个单元、封版后改过没有」,红在改的那个文件上 —— 业务代码改了没回看设计
也由这一段报、不另跑 `-m x-arch`;新的无主业务代码当场红;施工中(已加新的一版还没封)的单元只提示一行(单元与封版命令)。
另跑守卫的框架锁极简比对(`guard/framework-lock.js`,不经契约代码,只比契约判了干净的批次)。闸位选收尾
(ADR-53:拦的是改动者本人,不分端、不分发布通道)。
**误删提示**(ADR-104;零件 `guard/stop-handler.js` 的 `deletedOf` 与 `probeDeleteLines`,框架锁极简比对多交一份「删掉了」的清单):这一轮报出
「封版之后删掉(或移出)了这个文件、还没升版」(版本契约那一段的原话)或框架锁极简比对的「删掉了」,而那个文件此刻真的不在(移出单元而文件还在的不算)时,
收尾报文最前面先多几行(只出在本会话被拦下的那段报文里,替无主改动复核的那一段不出)—— 先问是不是探针误删:是,就别照后面原来那几句去升版、封版或重建站点,
先从施工区里的副本(或换入前的备份)或编辑历史把文件原样放回、指纹对上签字基线,再跑带计划名的核对;真要删的,再照原来的话升版、封版。提示里逐条给出在办需求(签过字没完结的,签字作废的
也算;先给本会话办着的,本会话一条都不办或认不出是哪个会话就给全部在办的,至多三条)签字基线里那份文件的指纹(原始字节 sha256 前 16 位,与写证据、签字基线里记的
同一算法;基线里没有它就写没有)与带这条需求名的核对命令;一条在办需求都没有时写明
没有基线可对、给不带计划名的核对命令。只加几行提示,判定一个字不变(拦不拦、红几处、原来那几段话照旧);需求零件装不上、基线读不了,照实写一句、不挡收尾。
为什么要这几行:文件被误删的那几分钟里,各会话的收尾都报「删掉了、还没升版」,只给升版的出路,照做就把一次误删封成了一版
· **测试新鲜度(ADR-61)**:本会话【全部】改动(不复用「查过干净」结论)命中的测试面,
每张床都要对当前内容全过、新建或改过的床还要咬得住(空壳对照);判定只调用 guard/test-faces.js,不另判。
账本没建立 = 一张床都没跑过,照常判。分级、归属与 MODE 见 §十六「测试闭环」。
盯盘上状态的床(ADR-103;守卫目录的名单 `guard/state-watch.json` 上登记的)只因盯的路径变了而作废的,
不算到任何会话头上:单凭它这一面不拦、只提示(报文注明「只因盯的盘上状态变了:不拦,封版前置会当场重跑;现在跑也行」),
由封版那一关当场重跑(§十六「盯盘上状态的床」)
· **两个裁判分开记账(ADR-67)**:报文分「检测(写法)」「测试(结果)」两栏;只被测试拦下时,
检测过关的文件照记干净结论(不然一个会话的测试没跑新,会让它的检测结论记不下,全仓部署门跟着冻住);
检测没全过时只记逐批干净的文件;干净结论带判据组指纹(检测引擎脚本 + 全部判据),判据或引擎一变即作废
· **收尾自身时限**:本会话这一段有 100 秒总时限,子进程按剩余时间设超时;到点没跑的批次
按基础设施异常拦(没跑不算过),下一轮只查剩下的 —— 没有总时限,钩子会被 120 秒外壳整轮杀掉,一个结论都记不下。
无主改动的复核同归这个总时限管:每批开跑前查是否到点,到点的批次记成没跑成(不记结论,
下一轮再查,落在部署门待检范围里的照拦),调检测带着剩下的时限
· **台账一轮只整读一次**:收尾开头开一轮,取上次红数、归属、规则书报备去重、未报的云端写操作、
需求对账共用内存里那一份,本进程追加的事件同步推进去;建基线那一步丢掉重读。别的进程在这一轮里
追加的记录下一轮才看见、不会丢 —— 别的会话是这样,同一会话的后台子代理也是别的进程:它在收尾跑检测
那段时间里写的受治文件、记下的云端写后复判,这一轮的需求对账与报红看不到,晚一轮。归属比对前按文件
建一次索引(命令时间窗二分取候选)
· **只提示的上游牵动面只列名字**:测试新鲜度里只经上游牵动、只提示不拦的面不逐面核,
报文写明「只列名字,没逐面核」
· **封版复核(全部单元同一口径)**:本会话改过的变更历史与锁清单,契约生效之后封过的每一版
三行指纹、标题与说明、改动清单须与本机封版记录逐项一致(手写、手改都拦),有记录却把记录行删了、锁清单不在而
台账有记录也拦;锚单元(整个 HARNESS、业务总览、x-arch)每轮都核,台账封过却从磁盘上消失即拦;不分试运行
(确定的事实);单元认定归版本契约,判定在 guard/test-faces.js 的 sealProblems;见 §十三
· **写后复判报红(同上)**:本会话记下的 {u} 逐条报红一次,报过即记 {ua} 不再拦(事后拦不回来,
但必须让人知道、去补测或回滚)
· **开闸感知(同上)**:项目 settings.json 里写前拦截是 _PreToolUse 时每轮提示一行(不拦)
▼
MCP 变更调用 ─→ 环1 静态托管发布面物理闸(ADR-51):
· 先于部署门判:manageHosting 的 upload / delete(含扁平形态 uploadFiles / deleteFiles)、
callCloudApi 的 tcb Create / ModifyHTTPServiceRoute、manageGateway 与托管域名写动作,先过
guard/mcp-policy.js 的纯函数判定(decideHostingUpload / decideHostingDelete / decideStaticRouteChange)。
通过之后进不进部署门,看这次调用往不往线上放新内容(ADR-89):
- 往线上放新内容的上传(一次调用里只要有一条来自档案的 assets / cutover)⇒ 仍 gate() 进
部署门,并把这次调用涉及的站点目录(去重)与各发布档案记的种类带给部署门算待检范围
- 一次调用里全部条目都是回滚上传(档案的 rollback/assets、rollback/cutover)、清理清单内的
删除、回滚删除清单内的删除(rollback-live 已过)⇒ 放行,结论不带 gate、只写明为什么
不进部署门。守卫里「看仓库状态」那一整段因此都不进:量仓的三种 fail-closed 拦(git
故障、生产形态下仓根不是版本库、台账首次建立)、待检清单、发布前版本比对、这一段的
部署门总时限检查,一样都不发生;写后补判走同一份代码,同样不补。回滚传的是发布前线上的
原样,清理删的是检查点算好的旧文件,都不把仓里的新东西放到线上;拦住它们只会让出了
问题时回不去(发布流程自己在首页核对通过时往入库的发布台账追加一行,收尾环给它记下
干净结论之前,进部署门的话这一行会把紧接着的清理与回滚删除拦住)。回滚并不是什么都不查:本闸
照旧每次都判 —— 不来自在用发布档案的、检查点顺序不对的、清单外的,照样拦
- 路由与域名写动作:通过的调用 gate() 进部署门(全仓)
· 数据只读:guard.js 只在 needsHostingData 为真时读注册表 x-deploy-sites.json 与 x-release
记录注入 ctx.hosting;读不到注册表、记录缺失或 JSON 坏、缺 steps 一律 fail-closed 并把原因写进报文;
守卫不 require 任何 part2 代码(工具独立于材料),verify-harness 沙箱用夹具注册表。
部署门算待检范围时加载发布库的 inputDirsOf 不在此列(ADR-89,取代 ADR-51 否决栏
「守卫依赖发布库代码」在这一处的适用):发布库是框架自研技能的脚本 —— 发布出口
publish-tests.js 受脊柱写保护、归整个 HARNESS 这个版本单元,改它就是改框架 ——
不是系统规范(part2),也不是业务材料;先例是运行时配置闸加载同一技能下的 runtime-registry.js。
加载按守卫自身位置的相对路径、放在 try 里:装不上、抛错、返回的目录不可用,一律退回全仓 ——
发布库坏了守卫只会更严,part1 仍能独立自洽、独立自测;本闸的判据仍只把注册表与发布档案当数据读。
算范围的判法本身不住发布库,住守卫自己的范围零件 guard/hosting-scope.js(不触盘、不装别的
零件,只收 gateScopeOf 装好交来的端名册与那一个函数):它装不上不走「退回全仓」,走守卫
启动失败(GUARD-BOOT,退出码 2)—— 守卫自己的零件坏了一律不放行(见上「部署门」)
· 上传:cloudPath 首段是登记网站、非根非保留;localPath 来自该站「在用发布档案」的 assets / cutover /
rollback 子目录,位置对应且大小写一致,前提检查点已通过;删除:isDir 只认缺省或 false,路径在清理清单
或回滚删除清单内;路由:登记域名只准 STATIC_STORE 且启用,Prefix 与域名登记在同一站;manageGateway
对 STATIC_STORE 的建改硬拦(该工具没有路径重写参数);发布档案整树进写保护,备份口只给 manageHosting 下载(ADR-84:备份由发布库的 backup 检查点
从公开默认域名取回、在脚本进程内写进 `<档案>/backup` 并定格,发布流程零次 MCP 下载、不走这条口;口子仍在)
· 「前提检查点已通过」里换首页的那一个前提(ADR-91):换首页的上传(cutover)以 assets 检查点
通过过为前提;这个检查点对每个入口(默认域名 + 每个访问域名)都核这一次真要写的文件(ADR-123)—— 判法在发布库,
见 §九「发布准备的全站引用核对与新文件逐入口核对」。守卫认的是发布记录里
这一步「通过过」:通过过一次之后再跑不过,发布库只记一笔失败、不撤先前那次通过,守卫照旧放行
换首页 —— 守不到,写在 §九 那一段的 ⑤
· dev server 判定只看被执行脚本的位置,检测命令参数里出现 preview.js 不拦
· 守着它的:verify-harness 的 HS / RR / RT / GW / PV 五组
· 诚实边界(对抗审查登记):ln / install / rsync / cd 后相对写与 node 脚本写盘仍可改 x-release
(档案本体 gitignore,环2.5 看不见;同级台账 RELEASES.md 进版本库、由发布脚本进程内写)——维持登记不补:
要有人刻意伪造档案才触发,守卫防误操作不防故意绕开,硬补须把复制类工具整类纳入写判定,误拦正常操作
· 同一面的另两处:win32 执行开关含 /k /r 与 Git Bash 双斜杠 //c,
PowerShell 位置参数即命令(只放 -File 与 .ps1);dev server 判定按起服务器的脚本名
(dev / start / preview 及 :变体,依据 x-admin 实测脚本表)并含 node --run、umi、bun;
包裹词含 cross-env(缺了它,任何命令名判据前加它即失明)。守着它们的:verify-harness 的 W / SV 两组
· spec 文件(只认 references 目录)→ check.js -v(含 specHash 闸)
· rule 文件(只认 rules 目录)→ 按检测引擎 check/constants/rule-books.js 三分类(validate --all 与体检 L3 同源):
有配套 spec → -v;无 spec 且登记在无规范规则书名册(元/流程/登记类)→ 按内容指纹报备一次(记在会话台账,任一会话报备过即静默);
两样都不是 = 孤儿规则书 → 每轮报违规,只有改动它的会话看得见(逼走 /x-meta-dev:补规范、删规则书或登记名册)
· 全部文件(含 spec/rule,补派不改派)→ check.js --changed 分批(argv 预算);
--changed 自带检测的语言层:本轮 js/ts 改动过一遍 oxlint,语法解析失败即红 ——
不然语言层只在恒返回 0 的全量里跑,框架自己的代码就没有检测裁判;
oxlint 在增量检测一开始就起跑,不等索引、射程与覆盖闸,结果仍在原位等、原位打印,报文次序与退出码
不变;凡在等到它之前就退出的路径(覆盖闸违规、抛错)都先收掉在跑的 oxlint 再退,不留孤儿进程
(检查器交出子进程句柄的回调就为这一收)。真提前起跑靠检查器同步找到 oxlint、同步起子进程(查找不能
await,一 await 就把起跑排到索引与射程那一长段同步活之后)。局限:路径总长超过命令行安全阈值的
慢路径分批时,同步段内只起第一轮(至多 8 批),后面几轮仍在微任务里起,增量检测的 js/ts 改动通常是
单批;oxlint 输出超过管道缓冲时,要等引擎让出事件循环才读得走;非 Windows 上经 shell 起的子进程
只杀得掉 sh(本仓只在 Windows 用)
· **射程复用**:--changed 每次都要先算全部规范的全仓射程、只为和几个改动文件求交。射程是
「引擎代码、全部规范、文件与目录清单、母本包说明」四样的纯函数(文件与目录清单取自索引,索引按路径前缀
跳过 `.claude/tmp`,里面的增删不牵动键,见 §七「路径级忽略」),四样的指纹都没变就复用上次算好的
(`check/scanners/scope-cache.js`,键的构成只有这一份定义);版本、键、校验和、形状任何一样对不上、
算不出键、现算期间四样被改过或引擎打出过告警,都当没命中现算、不落缓存 —— 绝不返回拿不准的射程。
缓存住 `.claude/tmp/.scope-cache`(脊柱写保护:只有校验和、没有签名,伪造一份射程缩小的检测就漏文件);
环境变量 X_SCOPE_CACHE_DIR 能把它改到别处(留给引擎测试床),守卫起检测引擎时从环境里去掉它。
**守不到**:脚本直接写缓存文件拦不住(与 node 脚本写盘同一类,见下「node 洞分治」);射程与缓存看的是
索引;索引与检测器自己走目录树的遍历读同一张路径级忽略表(见 §七「路径级忽略」)
· 检测命令一律带 -d;拦下报文按规范报告逐块摘出违规原因
· 无条件跑完全集,无短路聚合;违规与基础设施异常并列汇报
· 有违规 → block 逼修(反馈非自动改);放行时若有无主红项或分不清项,经 systemMessage 提示
永久回归套件:.claude/hooks/verify-harness.js 端到端固化 hook 行为(含 MCP 墙走线、写锁真拦),体系改动后必须全绿。写前 Bash、「结论只由云端策略决定」的用例与写后 Bash「认不认得出发布」的各种写法在套件进程里直接调判定(判定模块只从被测守卫目录加载),其余每条起一次守卫;端到端名单里的用例两路都跑、逐字比报文(写后那几条比台账) —— 守「守卫把命令与现场信息交给判定、按这个格式输出」的接线,每类命令判定至少留一条,需求闸与没签字的闭集白名单这两道「要守卫交现场信息才生效」的闸也在名单里。金丝雀住检测引擎面:业务树覆盖金丝雀(全仓普查与覆盖清单双向相等)查的是检测引擎的覆盖名单、和守卫无关,住检测引擎面的床 .claude/skills/x-spec-checker/tests/engine/coverage-canary.test.js(床头 @covers 点名 references 目录:改规范、扫描器、端名册、覆盖清单都会让它的记录作废、收尾要求重跑);本套件不跑它,退出码也没有「金丝雀报警」一档。
平台那一层的禁止名单(不是兜底):settings.json permissions.deny 只覆盖 git 破坏动词、解释器单行执行(node / python / perl / ruby)和几条起开发服务器的前缀,条条都在环1 写前拦截的射程里,只在写前拦截摘下(开闸)时多出一层。它按前缀比:插参数(git -C 目录 restore)、bash -c 包着、等号带值(node --eval=1)都挡不住,生产构建与 npm start 不在名单里。分词器看不见的 xargs、符号链接、./脚本 写前没有兜底(名单里一条对应的都没有);$() 只在目标整段是字面路径时才被分词器拦(cp x $(echo .claude/hooks/guard.js) 拦,cp x $(echo .claude/hooks)/guard.js 放)。与守卫文件头同一口径。
乙++ node 洞分治(ADR-14):node 脚本.js 内 fs 写结构性绕过环1(写前闸)/环2(只记 Write/Edit/MultiEdit 的内容指纹;Bash 只有时间窗)(win32 无 LSM,平台级不可达)。git 本身零会话归属,单凭它派生的 Stop 会破 §6.6(ADR-14);写证据台账给它补上归属,git 测量 + 按会话判定是环2.5/环3 的正式形态(ADR-50),node 脚本的写因此也进复核(时间窗归属)。堵法是分治 + 每洞有 owner:①内容侧由环3 Stop --changed + 部署 VALIDATE 门2(deploy-script validate/index.js 内 check.js --changed 对部署目标业务源[排除 sys/]跑全部适用 spec,file-state 读盘)自动兜底——不论坏内容由 node-fs 或 Edit 写入,部署前强制过内容检测;②控制面侧(node 重写 guard/check.js 本身)无自动闸,唯一权威=独立复盘与验收、事后按项目标签回看;③删除脚本(execute-delete.js)fail-closed 部分态报告 + git 前置闸缓解 rmSync 非事务残余(删除原子性=不可消解残余,只声明);routes.ts 删除足迹(唯一被 X-RULE 闸挡的 node-required 文件)由 x-module-del/scripts/route-surgery.js 承载(四牙链自检+原子写+三态 fail-closed,见 ADR-15)。blob-OID 进程外完整性闸=WONT-DO(结构性否决,见 ADR-15;钉值与被守护对象同信任域=自证循环,任何威胁模型下都是错答案;威胁升级正解=服务端 branch protection+CODEOWNERS)。
异常 · harness-P-03 守卫与运行器里的等待时长上限各写各的(待复盘 · 只登记不修):收尾钩子总预算 120 秒写在 settings.json;守卫里当场跑部署门 12 秒、内核核对 8 秒、忽略判断 3 秒、装配核对 20 秒、按会话归属 45 秒、工作区探针 60 秒,运行器单张床 15 分钟(带写追踪时 30 分钟)、出包门跑发布测试 10 分钟 —— 没有一处从同一个来源推出来,彼此也不对照。会出什么事:仓库越大越容易自然超时,而多数超时处报出的原因不是「超时」,是一句看上去像业务失败的话。守卫面有一张床出现过一次原因不明的失败、随后三次重跑全过,没留输出,怀疑与这类按真实时间算的预算有关(按代码推断,未复现)。动不动钱:不动。依据:.claude/hooks/guard.js(12 秒、8 秒、3 秒三处)、.claude/hooks/guard/assembly-face.js、stop-handler.js、worktree-probe.js、.claude/skills/x-harness-dev/scripts/core/bed-runner.js 各自的超时常量。状态:要修(时长上限从一处派生,超时时报「超时」)。由什么测试守着:待补测试。
异常 · harness-P-04 批量执行体运行期间,「这个改动是谁的」会判错(待复盘 · 只登记不修):归属先认内容指纹,其次认命令时间窗。批量执行体的命令几乎连成一片,这段时间里别的会话写的文件都会落进它的时间窗、被算到它头上;实例(据债务台账 D-52 的记录,本文未复现):一份测试夹具被两张并发的床写空,却记到了架构会话名下,又因为夹具不归任何规范,被记成「已复核干净」。会出什么事:别的会话的在途改动被错记成本会话的(本会话被逼着处理别人的红),或者真问题因为「已复核」而被放过。动不动钱:不动。依据:.claude/hooks/guard/session-ledger.js 的归属顺序(内容指纹 → 命令时间窗 → 无主);上面环2 的「两会话时间窗重叠归『分不清』」只处理重叠,不处理「一个会话的窗口吞掉另一个会话的写入」。状态:要修(方向待定)。由什么测试守着:待补测试。
九、L5 代码层
| 顶层物 | 开发形态 | 关键强制 |
|---|---|---|
| x-core(内核母本·非端) | 各端共享系统层的唯一母本;发布物由母本装配而来 | 母本禁手工改副本;各端禁直引副本路径;框架【操作】它、绝不【依赖】它(§十 铁律) |
| x-server | 从 templates/cloud-function-template/ 复制 6 个骨架文件 + 从 x-core/server/sys 装配 sys/,只改 MULTILINE 区 | index.js/sys/ 禁改;package.json 与模板 EXACT 等值;目录≥3段+动词后缀 |
| x-admin | 模块化(pages/services/components),types 先行,BFF 聚合 | 数据透传 camelCase 全链路;业务区禁原生 HTML(antd 等价);AUTH_META 权限声明 |
| x-client | 微信小程序原生+自建框架(端类实例:消费母本包 x-core/mobile + 端壳模板 x-mobile-dev/assets/end-shell,无 canonical) | i18n 禁动态键;goods 域与 admin 镜像域禁 antd;端内非业务面禁直改(母本改包源 → --materialize,壳改模板 → render-mobile) |
| x-technician | 微信小程序(师傅端·端类实例,与 x-client 对称:同一母本包 + 同一套端壳模板,不是镜像端) | 同上:母本包物化指纹牙(x-mirror NS-COMMON-0001)+ 端壳模板指纹牙(NS-COMMON-0002),端内零框架真相源、零「端 → 端」分发通道 |
| x-data | 文档先行(.md 8段式 + .datasource.json 同步) | 发布闸(已发布表禁重生成 JSON);字段类型变更走破坏性迁移流程 |
| x-website(官网站点·非端) | 纯静态页面 + xStatic/ 图片图标字体,无构建,发布的就是目录本身;托管目录 = 顶层目录名,挂主域名(ADR-49) | 目录闭集 / 站内引用完整 / 零外部资源 / 首页备案号(x-website 系统四件套);发布脚本托管目录单源与无空窗发布(x-deploy);不进 /x-feature-dev fan-out |
| x-harness(治理阅读站点·非端) | 阅读外壳(七个入口页 + css/js) + 构建器 builder/;构建器把受治树(条款 / 判据 / 架构页 / 变更史 / 宪法 / 业务架构)渲染成 dist/,产物不进仓、不进检测面;托管目录 = 顶层目录名 | 站点源码与构建器由 x-harness 系统四件套治;产物形态不靠规范闸——它不在扫描面里,由构建器的新鲜度自检与发布前的程序化产物检查兜;不进 /x-feature-dev fan-out
| x-test(业务端与内核母本测试·非端) | 按被测对象分桶:functions/<函数名>、consistency、kernel、tools、mobile/…;根下只留部署门入口 run-deploy-gate.js、注册表 deploy-gate.json、换空壳检查的预加载桩 deploy-gate-bite.js 与共享夹具 fixtures/ | 不进业务端 fan-out、不被引擎扫描;测试根只在工作区地图的名册「测试根」里写一份(引擎常量 test-roots.js 读它);部署门入口是登记函数床的唯一外壳(先装配内核、跑完即拆);出包门(x-core/tools 出包前)与发布出口都经它当场真跑(详 §十六) |
★为什么 x-core 是「顶层物」而不是「端」★:端是业务承载单元,进 /x-feature-dev 的 fan-out、有自己的业务模块与页面;x-core 零业务,它是被各端消费的材料母本。把它并进端集合会让按端名前缀匹配的消费点(索引扫描根 / 业务目录判定 / 覆盖闸)静默变语义——故引擎侧必须独立常量登记,不得并入端名册。
★x-website 同理是顶层物★:官网没有数据表、云函数、权限与业务模块,四阶段开发流对它无一适用;并进端名册同样会让端名前缀匹配的消费点静默变语义。引擎侧独立登记为站点类常量,与端、框架内核三者并集才是顶层物全集(覆盖闸与 L5 体检读并集,不各自手写名单)。发布复用静态托管无空窗发布库,不为官网另起发布机制。
★x-harness 是站点类的第二个成员★:治理阅读站点与官网同属站点类 —— 不是端、不是框架内核,引擎侧登记在同一个站点常量里。它与官网只差两处,而这两处决定了治理该怎么切:一是它有构建(受治树的全部条款 / 判据 / 架构页 / 变更史 / 宪法 / 业务架构渲染成站点),所以发布链要多一层「上传的是不是当次构建的产物」;二是它的发布面是产物不是目录本身,而产物被 gitignore 与引擎忽略目录双重排除、结构性不在任何判据的扫描面里 —— 所以它的系统四件套只治站点源码与构建器,产物形态交给构建器自己的两条命令。闸是「派生件进仓」的代价:进仓的派生件会在无人察觉时与来源分叉,必须锁;构建产物每次重生成、没有独立生命,只需要传感器不需要闸。
产物那一路的三道口:① 构建末尾主动清掉不属于本次构建的文件(改名会留下整个旧目录,而源清单比对全程报新鲜 —— 残留不在任何一份源的对面);② --check 答「站点旧没旧」,轻,由 L4 环3 的传感器每轮跑(见 §八;对不上只提示,不拦);③ --verify-dist 答「这份产物能不能发」,全,新鲜之外另核无残留 / 零降级 / 生成页零断链(复制进来的受治文档断链只报告不判死 —— 构建器这一道如此;紧跟其后的发布准备另有全站引用核对,这类断链在那里一律拦,见下「发布准备的全站引用核对与新文件逐入口核对」),发布链的 POST-VALIDATE 调它。两条命令不合并:一条每轮都跑必须轻,一条发出去收不回来必须全。
谁建站点、什么时候建(ADR-98):产物目录是全仓共用的。几个会话各自重建时,后一个的「清掉不属于本次构建的文件」会把前一个刚出的资产清掉 —— 两边都报已构建,产物却缺文件。靠「只让一个会话建」的规矩拦不住手滑,还让改了源的会话干等,所以构建器持一把仓库级的文件锁:要写产物的构建先拿锁,别处正在建就等它结束再建,打印谁在建(进程号、几点起的)、等了多久(每半分钟再报一次,换了持锁者立即再报);等到上限(缺省 300 秒,--lock-wait=<秒> 可改,0 是不等)仍被占就照实报错、退出码 3、产物不动,报文带上锁文件的位置。锁文件住系统临时目录、按仓根的指纹区分(不放产物目录:构建会清它),里面记着持锁的进程号与起始时刻;持锁的进程不在了锁即失效,建完(成功、失败、被打断)都放锁。这把锁构建器不自己写(x-harness/builder/build.js 的 holdBuildLock):拿法、放法与「进程在不在」的判法只有唯一运行器跑床那一份(bed-runner.acquireLock,§十六「仓库级锁、不点名」),构建器调它,各用各的锁文件 —— 建站点不等跑床;等待、打印、上限在构建器这一侧。为什么不自己写:站点规范有一条「构建器只准往产物目录写」,锁文件又不能放产物目录,在构建器里自己写锁文件,要么被那颗闸判红、要么靠变量名过闸而条款的原话不再成立。取不到锁的实现(运行器装不上、不再导出那个函数)时,要写产物的构建当场报错、退出码 2、不建,不退回「不加锁照建」。构建器另多一个开关 --root=<绝对路径> 把仓根指到别处,只供站点床在系统临时目录的假仓里起真的构建(验并发与旧锁),不拿真仓的产物目录做试验。只读的两条命令(--check、--verify-dist)不拿锁、不等:别处正在建时它们读到半成品会报过期或验收不过,那是照实报,等那一处建完再查。所以谁改了站点的源谁就可以建,不用报主控、不用排窗口(全仓静默窗口开着时除外,见 §十五「跑整面床、发布两个全仓共用的窗口」一段)。什么时候建:规范同步命令与封版命令末尾不顺带建;收尾环发现站点过期只提示一句、不拦也不建(§八 环3「治理站点新鲜度传感器」);发布之前必建 —— 发布前检查与运维经理的构建步骤照旧自己建,线上不会旧。守不到:① 改了源没建,本机产物旧一阵子,没有东西逼着建(发布处兜着线上);② 判「持锁的还在不在」只看进程号:持锁的构建被硬结束之后,进程号被系统分给别的程序,这把锁会一直被当成有人在建,等到上限才报(方向是多等,不是撞车;报文里给出锁文件的位置,看过之后删掉再跑);③ 两个构建同一刻接手同一把旧锁(持锁进程已经不在的)有一道窄缝:各自清掉旧锁再拿,后清的那一个可能把先拿到的新锁也清掉;④ 锁只管一次构建:建完之后别的会话又改了源,是新不新鲜的事(归 --check);发布流程里构建、产物验收、备档案三步之间没有锁,中间别处重建过产物它管不到;⑤ 锁文件在系统临时目录里:各会话要用同一个系统临时目录才排得上队,被人手删等于没锁;被硬结束的构建来不及放锁,靠「持锁进程不在即失效」兜;⑥ 构建器不在任何版本单元里(§十三 诚实边界 ③),这把锁改了不升版,守着它的是站点床里构建锁那一组(起真的构建进程:并发对照、旧锁与等到上限、锁的实现取不到);⑦ 构建器因此依赖运行器那份代码:取不到运行器(被挪走、改了导出的名字)时构建当场报错、不建 —— 材料依赖框架是允许的方向(反过来不行),代价是运行器一坏,站点也建不了;运行器改了锁里记的字段,等待时就报不出谁在建。另有一层反方向的依赖:收尾环认「是哪几份源过期」靠构建器只读检查输出里那三种行的写法,也靠只读检查不拿锁、不等(§八 环3「治理站点新鲜度传感器」)。
发布准备的公开内容扫描(ADR-89):治理站点发出去的不只是站点目录里的文件,还有它渲染的受治文档,发布即公网可读。发布链的 POST-VALIDATE 在产物验收通过之后、打发布档案之前,当场对受治文档树(.claude)与站点目录(x-harness)各跑一遍治理规范 x-governance 的扫描(含查真实手机号、证件号、密钥、邮箱的那一条),两段结果都打印,任一次退出码非零就不准备发布、线上零改动(有违规、目标一个文件都没匹配上、检测引擎没跑起来都在内)。每次发布准备都对这两处里治理规范管得到的 md 与 html 重新判一遍(存没存进版本库都判),不读台账里的旧结论 —— 这是部署门的待检清单对治理站点只数站点目录(§八)之后,受治文档那一半的交代:归版本单元的文档由发布前版本比对守(没封、封后改过照拦),不归任何单元的(在办的需求履历)里人读的那一份 md 由这一步兜。不把这些文档放进待检范围的理由见 ADR-89。代价:它跑的是整份治理规范、不只查敏感数据那一条,所以别的会话在受治文档里任何一处在途的红,都会挡住治理站点发布 —— 卡的是要公开的内容,但它仍是「等别人改好」的缩小版,没有根除。守不到:① 扫描只管 md 与 html。取材面里的 json 它够不着 —— 需求履历的 record.json(原样印进页面)与 releases.json、项目架构目录下其余 json、架构设计模板名册,各单元的锁清单与系统架构页的链路图数据同属这一类;.claude 之外只把版本号印上页面的文件也够不着 —— x-core/server/package.json、x-admin/package.json、移动端母本包各包的 package.json、各端的工程配置。这些文件两次扫描都不看,也都不在治理站点的待检范围里(待检范围只有 x-harness/)。② 扫描只装在治理站点的发布准备里,别的站点不渲染受治文档、没有这一步。
发布准备的全站引用核对与新文件逐入口核对(ADR-91):「发布后把整站按页面里写的引用查一遍」做进发布库现成的两步(发布准备、换首页之前),不靠会话临时写仓库外的脚本(没有在办的需求时守卫不让跑仓库外的脚本:它只看得见命令、看不见脚本里写了什么)。后台、手机网页版、官网、治理站点共用同一个发布库、同一套判法,没有例外名单、不按站点分支。
- ① 准备时在本机核引用(发布库
release/stage.js的发布准备调纯计算零件release/site-refs.js,不读盘、不联网):首页按内容改名、改写之后,读线上与建档案目录之前,把本版每张网页(.html)、每份样式表(.css)里写死的站内引用逐条解析 —— 网页只认真标签上的 href 与 src(注释、脚本块、样式块这些浏览器只当字读的地方不算),样式表认 url() 与 @import;空的、只有锚点的、带协议的、以两个斜杠开头的不核 —— 其余每一条必须逐字(区分大小写)等于本版发布清单里的一个文件,或正好是站点根目录。核的是这一版上线后的样子(文件名用改名之后的、首页用改写之后的),所以「首页的脚本样式发布时改了名、别的页面还指着旧名字」判得出。不过的分五类:以 / 开头、爬出站点根、指向目录、只差大小写、发布清单里没有;有一条不过就不准备档案 —— 不留下发布档案、线上零改动、连线上都不去读,报文点名文件、引用与类别。通过时把核了几张网页、几份样式表、几条引用记进发布记录的准备那一步;零件交回的结果里一张网页都没有(首页一定是一张)同样拒绝 —— 核对没真跑起来不当通过。指向目录只放行正好回站点根的那一种,别的目录下面有 index.html 也不过(静态托管没有可靠的目录首页,线上六页 404 就是指向目录);首页同样只认真标签上的 href 与 src —— 注释、脚本块、样式块里出现的字样,真标签上带前缀或别名的属性(data-src、xlink:href这类),都不拦。 - ② 换首页之前逐入口核这一次真要写的文件(
release/release.js的 backup 与 assets 两个检查点;只核这一次写的,ADR-123):这一次真要写的文件由备份那一步已记下的线上指纹与本版发布清单现算 —— 清单里首页那一组(首页、构建名片、发布清单)之外、线上没有或指纹不同的才是(首次上线就是全部),现算、不另存一栏进发布记录。备份仍读全站(发布清单里的全部路径加首页那一组)、仍留完整的回滚底本;备份的全部检查都过了,才把发布档案的 assets 目录收窄到只剩这些文件(没变的删掉、删空的目录清掉),发布清单与记录里的清单照旧记全站,换首页、清理、回滚都按清单算。收窄是幂等的:已定格的备份重跑时,上次崩在中途的在这里补完。上传从 assets 目录传(守卫的上传档案闸认的就是这个目录);要写的是零个就不传,assets 检查点照跑、核零个就过。assets 检查点对发布档案里记下的每个入口(准备发布时定下并记进档案的:默认域名 + 网站注册表登记的每个访问域名),把这些文件逐个取回、逐字节一致,首页那一组留给切首页那一步核;没变的文件不传、不核 —— 备份那一步从默认域名读到的就是本版要的内容,上传又碰不到它们。先默认域名,它不过这一次就不再问访问域名(读的是同一个桶);每个访问域名先取一个文件探路,取不到回答(连不上、超时,或重试用完仍是服务器出错)就判这个入口不通、其余文件不再逐个试(入口卡死时逐个试要干等几个小时),拿到了回答(哪怕是 404)才逐个比。任何一个入口有一个文件不过,这一次不记通过;通过时发布记录的这一步记下每个入口各核了多少个文件(就是要写的个数)。不过的出路分两种:默认域名上有文件不过是桶里不对,重新上传;默认域名全过、只有访问域名不过是桶里对、访问域名那一头不对,重传没用 —— 不要换首页,先原样重跑一次(核的只是这一次写的文件),两次都不过再查该域名的网关路由。 - 为什么是这两半:引用指向哪个文件在本机算得出来(引用写死在文件里,文件清单是发布库自己定的),不用联网、不用爬;文件取不取得到、内容对不对才要联网。两半合起来,加上原有的 live 检查点(每个入口的首页、发布清单、构建名片与入口脚本样式),等于「按页面里写的引用,这一次写的文件在每个入口都取得到、而且内容对;没变的文件线上本来就是本版要的内容,备份那一步从默认域名读到过、逐字节核对过」。联网那一半放在换首页之前:首页之外的页面在传新文件那一步就已经原地换成新版,等换完首页才发现访问域名上取不到,访客已经拿着新首页去要取不到的文件。否决了什么(放松守卫、把临时脚本原样搬进仓、新增检查点、并进 live 检查点、设例外名单)见 ADR-91。
- 与构建器产物验收的关系(治理站点):这一道比
--verify-dist严,最要紧的一处 —— 复制进产物的受治文档里的断链,构建器只提示不拦(源里本来就断,不归构建器修),这里一律拦(另外样式表里的引用、只差大小写、不带引号的属性值,构建器那一臂不核或核得松,这里都核):受治文档里写断一条链接,治理站点就备不出发布档案,而且要到发布准备那一步才被拦、不是构建时;反过来构建器另核生成页的锚点存不存在,这里不核。两道都留着。 - 代价:新站点第一次发布时访问域名要先接通,否则停在 assets 这一步;一次发多个手机端时逐端准备档案,后面的端引用不过,前面的端已备好的那份档案留在盘上(它自己是干净的)、整条命令退出码 1。
- 守不到(全表在 x-deploy 架构页的诚实边界与
site-refs.js文件头,这里只点最要紧的几类;不许读成「不会漏」):① 只核写死的引用。页面脚本运行时才拼出来的地址核不到 —— 治理站点从入口页点进各文档页的地址、后台与网页版按需加载的脚本名字对不对,都在此列。② 只读 .html 与 .css 两种文件,只认 href、src、url() 与 @import:图片的多尺寸写法、行内 style 与<style>块里的 url()、表单地址、<object data>、poster 不看,带前缀或别名的属性不看(其中xlink:href是真会去取文件的),<noscript>里的引用不核,<base>不当解析的基准,锚点存不存在不核。③ 读法只照浏览器分词的规矩认哪些是标签、哪些只是字,不模拟它把标签搭成页面的那一层:那几种只当字读的标签写成自闭合时、内嵌<svg>/<math>与<select>里面,判定可能与浏览器不一致(多报、漏报都可能)。④ 「注释里的不算」只在发布准备这一道里成立:四个部署脚本产物闸里原有的、按文本扫「以 / 开头」的检查没动,排在它前面 —— 注释或脚本块里双引号写的那种字样,仍会被前面那道拦下。⑤ assets 检查点通过过一次之后再跑不过,只记一笔失败、不撤掉先前那次通过;live 检查点的前提与守卫的上传档案闸认的都是「通过过」,提示写着不要换首页,这时没有机器挡。准确的说法只到这里:从没通过过这一步的档案,换首页的上传(守卫写前在岗时)与 live 检查点被挡住。⑥ 入口只认档案里记下的那一组:网站注册表没登记的域名不核,档案准备之后注册表再改也不追;访问域名上 4xx 是线上的真实回答、不重试,网关若对连续请求限流,这一步会判成访问域名不过(提示里叫做的第一件事就是先原样重跑一次)。⑦ 两步看的都是「此刻」:核对带防缓存参数直接回源,各缓存节点此刻的副本、上传那一两分钟里新旧页面混杂、核对通过之后线上再被改动,都不在射程里;站外链接活不活、入口地址不带末尾斜杠的访问、页面画得对不对、脚本跑不跑得起来同样不在。⑧ 没变的文件不核(ADR-123):它在访问域名那一头若被缓存弄坏,这一次核不到(它上一次变的那次核过);备份那一步只证明默认域名上它就是本版要的内容。⑨ 「这一次要写的文件」是备份那一刻算的:备份到上传之间线上被别人换过版本,算出来的就不准;备份那一步已有的「线上换过版本就拒绝」照旧,但它只管档案准备到备份之间。同一时刻只有运维经理一处发布,这一段靠纪律。⑩ 默认域名整个不通时等得久:访问域名有探路、默认域名没有,默认域名不通时核对要对这一次写的每个文件各等满超时与重试才报(按约 90 个文件、6 路同时、每个等满 3 次 × 60 秒算,约 45 分钟);它直通桶,很少出这种事。连接一直有零星字节进来、却迟迟传不完的,没动静超时抓不到。
发布之前先只读查部署门(ADR-98):部署门「待检范围里有没复核的改动就拦」那一臂(§八 环1「部署门」)是守卫在上传那一步判的;只靠它,静态站点的发布要走完检测、当场跑床、构建、备档案,到上传才知道被拦,再回头让点名的会话结束一轮、从头来过,云函数的脚本发布通道又不经守卫的这一臂。所以部署技能的发布命令有一个只读开关 --sources(会往线上放东西的五个目标认它:云函数、后台、手机网页版、官网、治理站点;别的目标给了就拒绝):列出这次要发的原料目录里哪些改动还没经收尾环复核、是哪个会话改的,退出码 0、不建台账、不记账、不推进任何结论(唯一会落盘的是当场重查起的检测引擎照常写它自己的射程缓存)。各发布入口正式跑时的第一步是同一个查法(x-deploy-dev/scripts/release/sources.js):有没复核的当场停,后面的检测、测试、构建、上传一步都不走。云函数的脚本通道同样先查(放在预部署验证之前;批量发布的两个入口在上传之前各再查一次,直接跑它们也躲不开)。只验证不发布、只装配看效果的用法不往线上放东西,不查。发布入口那一步最多列十条(与守卫部署门的报文同数),只读开关全列。判法只有守卫那一份:量工作区与三种「测不出来」、定待检范围,住守卫的一个零件(.claude/hooks/guard/gate-measure.js,measure 与 scopeOf 两个导出;当场重查的总入口 recheckPending 也住这里,见下)—— 守卫主文件(收尾环与部署门)与这里调的是同一份(照着另装一份迟早两边各走各的),数待检清单是台账零件那一个函数,部署脚本一处都不另算。那个函数认「主人已不在线、内容曾查过干净」(ADR-102;§八 环3 分账 ②):这里先查与守卫是同一个判法、报文同一句;问清单的会话号取跑发布命令的那个会话(环境变量 CLAUDE_CODE_SESSION_ID,上传那一刻守卫用的是同一个会话号),判「主人不在线」时同样核它自己在名册里在线(取不到会话号就不核这一样)。这里先查出来的,就是上传那一步守卫会拦的:治理站点、官网、名册里的手机端只数各自的原料目录,后台、名册外的端、云函数照全仓数。当场重查:数完待检清单,收窄到原料目录的站点发布交给同一个总入口 recheckPending 当场按当前判据重查 —— 别的会话名下、内容没变、以前在任一判据组下查过干净、也没记过红的那几条(收不收窄、哪几条能重查、时限都只在那里判;跑发布命令的会话自己名下的不替它重查,要它自己结束一轮);给的是 record:false,只查不记:过了的不列、也不记成干净结论,上传那一刻守卫用同一个判法再查一次、过了才记成无主的干净结论;没过的、没跑完的照列,原因写「当场重查没过」「当场重查没跑完」,跑不完一律按没过。时限用那个零件的缺省(床可用 X_RECHECK_MS 调短),检测引擎取本仓那一份。台账还没建时不重查(守卫在上传那一步也是先建台账并拦一次、走不到重查),照旧按没过算;后台与云函数照全仓数、不重查。打印的第一行是「部署门先查(只查不记)」,重查过的多一行「当场重查了 N 个:过了几个(只查不记,上传那一刻守卫用同一个判法再查一次)、没过几个、没跑完几个」;没过时「怎么办」那一句分开说:从没查干净过的、记过红的、跑发布的会话自己名下的、无主的照旧让点名的会话结束一轮,重查没过的交点名的那个会话照检测报的改掉,没跑完的过一会儿再发或让点名的会话结束一轮。正式发布的第一步是同一个查法,没过就停,后面的检测、测试、构建、上传一步都不走。测不出来不等于干净:守卫零件装不上(或缺了要用的五个导出之一)、工作区量不出来、仓根不是版本库、待检清单数不出来、当场重查判不了,一律「判不了」—— 只读开关照实打印,发布入口按没过停。台账还没建而工作树里已有改动这一样,两边交给同一个函数的是两种做法、同一个结论:守卫当场建、把当前的改动记成存量、只拦这一次;只读查只看不建(不写台账,这时也不当场重查),照实说台账还没建并按没过算。这一查是提前说,墙仍是上传那一刻守卫的那一臂、发布前版本比对与当场跑的测试。云函数脚本通道照全仓看:仓里任何目录有改动还没复核,云函数经脚本就发不出去,与经 MCP 发云函数同一个严格程度。守不到:① 只查到跑的这一刻,查完到上传之间又有人改了原料目录,由上传那一步守卫的部署门挡;② 紧跟在待检清单后面的两道不在这里查 —— 发布前版本比对(发布前测试那一步开头就比),以及排在它前面的「联调还是正式发布」(要发的东西被在办需求签过字的落点表盖住,要到云函数过门那一步、静态站点发布前测试那一步开头才报,§八「部署门认联调」);③ 这本账只看得见工作区里还没存进版本库的改动(与部署门同一条边界);④ 「第一步在场」没有规范的闸守(部署规范的闸不判它),只有部署技能的床守;这一查住在部署脚本里,那份脚本不在写保护名单上,改得动;⑤ 一次发两个手机端时,先查按两个端的原料目录合起来数一次,守卫按每一次上传各数各的,两边报出的清单不一定逐条相同;⑥ 量仓零件另有两处直接调用(统一封版命令与三查脚本),不经这一个零件,它们各自判「测不出来」;⑦ 这里当场重查过了的,上传那一刻守卫剩下的预算不够重查(不到 8 秒不起子进程)时照样拦,当场重查只做检测、不含测试。守着这个零件的床:.claude/hooks/tests/gate-measure.test.js;先查这一边的床:.claude/skills/x-deploy-dev/tests/deploy-release-pipeline.test.js(H 组)。
移动端 backend 层(ADR-34):移动端四件套(js / json / wxml / wxss)是唯一母本,被三个 backend 消费——微信基础库、Donut(平台提供)、H5(自建,住 x-core/mobile/backends/web,基于微信官方 MIT 组件框架 glass-easel:Rust WXML/WXSS 编译器 + 组件适配器 + webpack 插件;缺的 App / 页面栈 / wx shim / 内置组件由本层补)。H5 不是第三份代码,是第三个 backend;编译单位是端,一个装配器 x-core/tools/mobile.js 住 x-core(零依赖、只用内置模块,与 manifest.js 同铁律),名册从各端 env.config.js + app.json 自发现(与引擎 CLIENT_CLASS_ENDS 同判据,金丝雀锁等值),新增端零 H5 专属文件。生成物只落 <端>/dist/web 与 <端>/.cache/web-src(与引擎 IGNORED_DIRS 同名,对治理面与镜像牙免疫,是设计不是盲区);weapp 物化产物 <端>/miniprogram_npm/@wowoway/* 同在 IGNORED_DIRS 内但不免疫——x-mirror NS-COMMON-0001 内容指纹牙以包 package.json 为锚自探盘、逐字节比对包源 ⇔ 落点(ADR-37):IGNORED 只是「不被 spec 适用面扫到」,不等于「没有牙咬得到」。两本规范锁住两头:x-surface 锁母本侧语言面闭集(WXML 指令 / 标签 / open-type / wx.* 令牌,伴生注册表 x-surface-whitelist.json,棘轮只收不放:新增一项先证明三个 backend 都吃得下);x-backend 锁 backend 侧(目录形态 / 引擎隐身名禁入 / 内置组件禁自嵌套 / shim 键集 ⊇ 注册表 wx.tokens / 装配器零端硬编码)。D12(wx 就是平台面):真仓 IoC 接缝本在全局 wx(source-injector 运行时劫持 callFunction),不另开 adapter 层;可移植性 = 「用到的 wx 令牌是闭集」+「每个 backend 实现该闭集」,注册表同时是 shim 的实现清单。诚实边界:静态闸判形不判行为,运行时正确性由 x-test/mobile/backends/web/mobile-web-backend.test.js(shim 逐令牌 / 双槽 × 真适配器 / 固件端真 webpack 端到端)承接;对真实端执行装配属生产构建(宪法 §六-3),AI 只提请;身份 / 支付 / 地域 / 内容四条地基归框架层适配器,与 backend 层正交。
闭集五维 + 传输定型(ADR-35):闭集另要盖住两维 —— 母本的值形态(cloud:// 是平台专有地址,微信 / Donut 原生认得、浏览器不认)与组件实例 API(this.animate 等实例方法 / 生命周期钩子 / options):不在注册表,backend 就无义务实现、测试床也不红(登录页 11 个碎图就是这么来的)。所以 x-surface 注册表有 schemes(每个协议标 kind / resolver / 接收入口)与 componentApis(methods / lifecycle / options)两表,母本侧两颗闸(NS-MOBILE-0004 值形态闭集 / NS-MOBILE-0005 组件实例 API 闭集)+ 元闸两臂;backend 侧两颗闸锁兑现:NS-COMMON-0007 要求标 resolver:true 的协议在 backend 有唯一换算点 runtime/resolver.js 且注册表登记的每个接收入口必经它(内置组件 / wx 令牌方法体),NS-COMMON-0008 要求 runtime/capabilities.js 逐项声明 adapter / runtime / degraded 且键集 ≡ 注册表(degraded 须在注册表 _notes 写明降级形态)。传输(D14):服务端只从 Authorization 头取 JWT(SDK 通道无身份路径)⇒ H5 云函数调用走 admin 同一条 HTTP 网关(runtime/transport.js:路径由函数名派生、来源 web-{端} 由 env.config.end 派生、Bearer 来自 CloudBase 会话、body.source 双钉、母本原子层的 data._apiVersion 上提为 X-API-Version 头——HTTP 通道的 handler 只读头,真网关实测不带即 MISSING_API_VERSION),服务端策略表从渠道名册派生 web-{端} → ['token'](web 来源不入名册、不是端),handler 对已认证 web 来源不做 xfile 令牌化,file-url-read 开明文分支;本地预览 --serve --gateway 反代 /api/*。否决:改 cloudAsset 吐 https / 服务端吐 https / Service Worker 拦截 / 另造请求层——都把换算点从 backend 挪到母本或第二处。诚实边界:两颗 backend 闸只判「接入 / 声明」,换算结果与声明属实归行为床 + 浏览器 img.complete && naturalWidth > 0 实测;web 来源到端身份表的映射与短信登录归阶段 S,桶收紧时只换 resolver 的签名分支(接管点 setResolver),入口零改。
业务码内的 X-RULE 标记是检测锚点:删/改名/换诱饵在环1 当场被拦——这是"规范长在代码里"的物理形态。测试跟着被测对象放(§十六):业务端与内核母本的测试住 x-test/(不被引擎扫描,不污染四端);治理体系自己的测试住 .claude 里各自被测部件旁的 tests/。
各端外部技术栈参考文档(如 x-admin 的 antd6/ProComponents/AntV X6)归 .claude/docs/{端}/ 端优先归类(admin/client…镜像四端命名),由对应 rule 承重引用(x-antd-rule → .claude/docs/admin/)使其"被引用即不孤儿"(防迁移误删);端优先杜绝 admin/client 前端文档错乱。
十、治理拓扑(框架三件套 · 系统四件套)
part1 框架三件套:元规范 + 元规则 + guard hook
职责 = 强制三条主流程(业务流程 / 规范流程 / Harness 流程)
框架治理业务,也递归治理自己(元规范受 -v,guard 受 verify-harness,执法测试的机制 —— 测试面判定、收尾核对、封版前置、运行器、部署门入口 —— 各有自己的床)
part2 系统四件套:每个系统规范域 = 设计(架构页)+ 条款(规则书)+ 判据(规范·内嵌 detector)+ 执法(guard)
元规范 x-standard 的设计留在本文档(§五、§七),不设架构页;业务架构(arch/business)以代码为锚,不设四件套
铁律:框架【操作】系统四件套,但绝不【依赖】它们——
part1 必须独立自洽、独立自测,与有没有 part2 系统规范无关。
x-core 在本拓扑中的位置:x-core 是 L5 被治材料,不是第五类受治工件、不是端、不改本拓扑——铁律对它同样成立:框架【操作】x-core,绝不【依赖】它。判据是「若 x-core 整个消失,part1 框架能否独立自洽自测」——答案是能(guard / 元规范 / verify-harness 均不 require x-core 任何文件),故它是材料不是工具。
为什么这个定性承重:若把 x-core 当成工具层(或新工件类),就会出现「框架依赖材料」的倒置——届时删/改 x-core 会连带瘫痪检测能力,而检测能力本该是独立于被检测物的。
server 内核母本已归位:x-core/server/sys 38 文件是 server 内核母本;云函数模板只有 6 个业务骨架文件,sys/ 由 x-core/tools/manifest.js 从母本装配。装配原语零依赖(仅 Node 内置)、不反向依赖 .claude 治理树——这正是「材料不得反噬工具」在实现层的体现。
包形态大一统:x-core 是 monorepo(pnpm workspace),内核具备包身份 @wowoway/server-kernel(包目录=x-core/server/,含 sys/;version 由「改内核必 semver bump」纪律演进,见 x-meta-rule 场景C 2.5 步)。server 消费边界=平台物理裁定:真云 PoC 四路实证 MCP 通道对第一方包全死(打包器硬剥 node_modules / ignore 参数覆盖不了 / NODE_PATH 平台明禁 / zipFile 参数实现坏),且云端 node_modules=「上传包∪registry 云装」合成 ⇒ 非 registry 包经 MCP 更新必丢。故包身份在源头,发布面保持 sys/ 装配(本节机制原样)。消费边界按 backend 分档(ADR-36):① 物化消费——server(sys/ 装配)与 mobile-weapp(x-core/tools/mobile.js --materialize --backend weapp 把 x-core/mobile/{core,kits/*,biz/*} 各包的 miniprogram 源逐文件写到端的 <x-materialize.dest>/<包名>,即 miniprogram_npm/@wowoway/*,gitignore、devtools 直接读、零「构建 npm」);② 本机构建器解析——admin(umi/webpack 经 workspace)与 mobile-web(装配器把同一包源直拷进 staging 同一落点,webpack resolve.modules 加 staging 里的 miniprogram_npm)。三档源码侧都写裸包名 @wowoway/<pkg>/<保形路径>,差别只在「谁把包放到运行时读得到的位置」。包声明 x-materialize { dest, ends } 是四方(装配器 / auth-scanner / x-mirror 内容指纹牙 / x-auth 0010)共读的唯一一张表;物化三语义(delta / prune / 原子写)与 sys/ 同款(manifest.js 原语复用),--verify 三态(缺 / 异 / 多)+ --closure(端 + 消费包虚拟树上 require / usingComponents / @import / wxml import 零悬空)是它的两颗自检牙。运输三档(workspace→自有 git→registry)切档只改消费端 package.json,不改本边界。
治理面前置:治理面看得见包源——① L3 射程:terminals.js 双形态导出母本源根(MOBILE_SRC_ROOT_GLOBS = core/src ∪ domains/*/src 供 {mobile} 令牌展开;resolveMobileSrcRoots() 实存列表供 fs 消费者与 tools.mobileSrcRoots),显式不含 backends/(内置组件模板不是母本);{mobile} 令牌展开为「各端根 ∪ 包源根」,母本在包里仍被同一批规则治理;{mobile-end} 端根限定令牌给端级规则(xStatic 顶层 / 孤儿目录等端自留地判据,detector 以 split('/')[0] 推端根、落包源会推出 x-core 而误咬);编译面 x-core 段含 wxss / wxml;报表「文件失败」端无关(x-core 文件归 x-common,按端算会把 MOBILE 规则失败静默吞掉)。② L4 闸:command-policy.isGeneratedArtifact 把 <端>/miniprogram_npm/**、dist/web/**、.cache/web-src/** 三处装配产物设为 Write/Edit/Bash/MCP 四通道只读(手改即被下次装配覆盖,且 IGNORED_DIRS 使任何 spec 看不见);isBizSource 后缀含 html/css/wxs。③ L1 派生:rule frontmatter paths: 不手写——x-meta-dev 的 deriveRulePaths(聚合 + 引擎同一 expandMobileClassCoverage 展开 + 目录形态补 /**),sync --paths 只重写 paths 块、validate 1b 集合相等阻断,无 paths: 块 = 全局规则书豁免(手写的字面 x-client/ 盖不住别的端;{mobile} 写进 paths 恒不命中)。④ 闭包唯一实现**:x-mobile-dev 的 startup-closure 是薄壳、委托 mobile.js closure();它也跟 require.async(只跟 require( 会漏掉孵化端 app.js 残留的 goods-sub 悬空),transformAppJs 剥除这类残留。
治理面前置·规范半边(ADR-37):规范要能咬住包源——① x-backend 闭合形态收进母本包骨架:NS-COMMON-0001 对 core/** 判 (core | domains/<kebab>)/{package.json, src/**}(骨架之外一律违规;src 内容归 {mobile} 各规范经令牌第二半射程,x-backend 只认领骨架——保 COVERAGE-GATE 又不与业务规范双重射程);NS-COMMON-0002 锚含 core/package.json 与 domains/*/package.json,但用独立 HIDDEN_PKG 表 = IGNORED_DIRS ∪ {sys, templates},显式不含 locales / xType / xStyles(它们在包源里是母本正当子树,经 co-owner 机制照常独占扫描;单表通吃 = 把母本自己判违规),并校验 miniprogram 字段实存(缺字段 = 装配器与指纹牙同时失明)。② x-mirror 物化不变量:NS-COMMON-0001 内容指纹牙(锚 package.json → 读 x-materialize { dest, ends } → 对每个消费端走 src/** ⇔ <端>/<dest>/<包名>/** 两棵树逐字节 equals;缺失 / 不同步 / 多余三臂按 (包, 端) 聚合各报一条,落点不存在 = 端未装配独立错误,名册外端 / 缺字段 / 源目录不存在 fail-loud)。「IGNORED_DIRS ≠ 免疫」:miniprogram_npm 不被任何 spec 适用面扫到,却被本牙自探盘咬住。③ 三处派生源根优先:x-surface NS-MOBILE-0002 的端根派生先匹配 tools.mobileSrcRoots,命中即读全部消费端 app.json(包源里的组件被哪个端用都算);x-marker NS-COMMON-0002 射程改 {mobile} 令牌形态;x-standard 有效键快照含 mobileSrcRoots。④ 治理面边角:宪法 rule paths 含 x-core/**;x-client-engineer 写域 = x-core/mobile/{core,kits/*,biz/*}/src/**(母本源),backends/** 与装配器不归它;x-exception / x-structure 两本规则书的 STD/NS 引用齐全(validate 全过的前提)。详 ADR-37。
治理面前置·射程闭合:detector 不能把包源文件当「被全部端消费」,也不能用 split('/')[0] 推端根(会得到 x-core;x-i18n 0003 废弃键假红、x-api 0108 BFF 死导出假红、x-icon 0003 对 npm 落点 /<dest>/<包>/…png 全盲、x-route 0009「宿主恒主包」对落分包的包失真、x-tools 0024 包内相对/bare 反向依赖零射程,都是这一类)。消费面由引擎原语派生:terminals.js resolveMobilePackages()(读各包 x-materialize {dest, ends},"all" → 名册;resolveMobileSrcRoots 由同一枚举口派生,两形态不可能失同步)+ 注入 tools.mobilePackages / tools.mobileEndsOf(rel)(包源文件 ⇒ 所属包 ends;端文件 ⇒ [端根];其余 null),五条 detector 经它派生消费面;令牌三分:{mobile}=端根∪包源根、{mobile-end}=端根、{mobile-src}=包源根(x-standard NS-COMMON-0018 白名单);目录模式基根自检(scanners/file.js 把 basePath 自身作模块候选——端根 custom-tab-bar/ 壳因此在 x-structure 射程里)+ x-structure MOBILE_SRC 全树令牌化(域包 product-card / product-detail / product-list 三族在目标集里)。架构事实:业务域包形态定形(x-core/mobile/{kits,biz}/<包>/package.json 自声明消费端与落点;分包落点 <分包root>/miniprogram_npm;域包只依赖 core 与被声明上游域包;包→包 bare @wowoway/<pkg>/<保形路径>;微信分包 npm 寻址 = 相对 → 本目录 npm → 逐级父目录 → 根,主包/他分包只能根绝对 + require.async);IoC 七键(tabbar 接管者,x-auth NS-MOBILE-0013 第五注入行);H5 阶段 S 身份(内核:token 策略按来源分流到该端身份表 cloudbaseUserId、handler 第 5 步对公开接口透出平台身份、公开函数 signup-web-create 首登建号;登录页 web 分支 OTP,isWebBackend() 唯一判端入口,x-surface 闭集含这一支用到的两个令牌,x-jwt 臂④ 四落点锁;验证深度床级,真会话 / 云函数重发 / 数据模型导入归用户)。
端内非业务面的真相源在端外(ADR-38):系统层母本是 x-core/mobile 包,端壳是 x-mobile-dev assets/end-shell 模板的渲染产物;x-mirror 的两颗牙(母本包物化内容指纹、端壳模板指纹)锁住它们,机制见 x-mirror 系统架构页。引擎侧零端名字面量:含 {mobile-end} 令牌的扫描模板块由 extractScanConfigByTerminal 按名册逐端展开成同构块;client 阶段的检测集在端根之外追加母本包检查组(x-feature-dev roadmap 的 MOBILE_PKG_RULES × MOBILE_PKG_ROOT:母本包物化内容指纹牙 x-mirror NS-COMMON-0001 锚在包 package.json,按端根扫不到)。诚实边界:client 阶段 VERIFY 对母本包源只跑 x-mirror 一组,其余 {mobile} 令牌规则书对包源只在全量检测兑现(登记,归 x-feature-dev 治理);端内私加且无模板的点文件在端锚视野外(引擎 dot 过滤,verify-mobile ② 走盘兜)。
拆包复盘收口(ADR-46):① 改了包源忘跑 --materialize——x-mirror NS-COMMON-0001 锚在包 package.json,--changed <包源文件> 结构性带不出它,不兜就要等 6 分钟全量才红。兜它的不是一颗 spec 闸(单文件 detector 看不见「改了 A 忘了跑 B」),而是 L4 Stop 环第二条装配判据:改动集命中容器闭集内任一包的 src/**(谓词由引擎 MOBILE_SRC_ROOT_GLOBS 派生,不写死容器)⇒ spawn 装配器自己的 --verify --end all(实测 1.2s),不一致即拦、报文给 --materialize;装配器缺失 fail-loud。两条装配判据的引擎名册懒加载(只在候选命中 <端>/app.json 形态或包源时才 require 名册)——无条件加载会让没有引擎的工作区(L4 自测沙盒)每一轮都 infra-failure,闸从「装配面才响」变成「永远响」。② 写前拦截层关闭态(_PreToolUse)属用户主权,由用户关闸。另几处落在流程、用例与文档上:孵化器 deriveAppJson 按本端消费的落分包的包自动派生 subpackages(不派生,对 ends:"all" 且落分包的包新端出生即半成品);x-feature-dev IMPLEMENT 提示是铁律两条命令;guard 生成物只读有嵌套落点用例;师傅端 lazyCodeLoading 与客户端对称(x-route 0005 静态判据通过,运行时归用户);.gitignore 用裸目录行 miniprogram_npm/(x-mirror 0005 按路径段咬合,新增落分包的包零改该文件);mobile ARCH 保鲜面含 kits/**(kit 是系统工具包,没有业务 arch 可归)。
装配 ≠ 依赖注入:云函数上传的是目录快照、运行时在云端,物理上够不到仓库里的 x-core,故 server 内核必须在打包前物化进每个函数目录(与 npm 依赖的「声明式 + 云端安装」不同)。物化的三条语义(delta / prune / 原子写)缺一即产生陈旧内核静默上生产。
运行时锚:母本增 base/integrity.js + kernel-manifest.json 锚清单(由 manifest.js --stamp 生成,记录除自身外全部内核文件 sha256;manifest() 对 canonical 母本强制锚新鲜度,改内核忘 --stamp 则装配/校验/打包全线 fail-loud)。handler.js 冷启动第一行校验锚:缺失/漂移/多余(清单外文件即红——防旧残留经 Node LOAD_AS_FILE 遮蔽目录模块)→ 抛 KERNEL_INTEGRITY。它是手工 tcb / 开发者工具上传、cwd 不在仓库根、Bash 直跑这三条本地闸全部够不着的通道的唯一防线(真云实测:含锚冷启动 1596ms,与无锚基线同量级)。
诚实边界(x-core 检测面):业务域代码锁步(x-arch NS-COMMON-0003)的 describes 按端键分组,但 glob 本身可以指向 x-core 路径(system/mobile/ARCH.md 的 describes.client 加入 x-core/mobile/** 后,-m x-arch 立即报陈旧并给出实算指纹),真实边界是没有 arch 文档把 x-core 路径写进 describes 时才不可达。server 内核 x-core/server/sys 至今无业务域认领(它冻结在业务总览的无主业务代码基线里,只减不增),内核语义变化不让任何业务域升版,真相由 sys-check 字节等值三臂 + 本文档变更历史承载;移动端 backend 层则已由 system/mobile 认领。内核语义正确性静态检测仍不可达(B4 既有边界),由 x-test 常驻床 + 运行时锚 + 「只有 40 份 review 面」承接。
十一、架构决策记录(ADR)
全表已外迁 →harness/ADR.md(不可变追加,正文各处的ADR-NN引用均指向该文件)。
本节只保留存在性声明:ADR 是本体系「为什么这么定」的唯一记录载体,新决策追加到该表,禁止写回本文件。
十二、体系有效性的五条链路(审计基线)
任何对本体系的全面审查,按这五条链路验证(每条都要活体证据,不接受"读代码看起来对"):
- 规则先行:写码前对应 rule 是否被 paths-scoped 自动加载(覆盖四端无真空;宪法原则书同样按 paths 加载,不是全域兜底);
- 条款↔判据双向对齐、派生部分锁步:篡改 spec 任一字符,specHash 闸必爆;条款书声明 clauses-v1 后,新增闸无条款认领、条款引用不存在的闸、直接改规则书或架构页派生区、判据变了没升版,均当轮或全量报红;
- spec↔hook 深度捆绑:改 spec/rule/业务码,三环必按设计拦截或复检(含孤儿 rule、引擎/脊柱写锁);
- 乱写必炸:四端任意反规范代码(含 MULTILINE 内部、跨行形态、负向锚等历史假绿位)必被 -m/--changed 抓出。
- 测试闭环:改被测对象、测试本身或它们依赖的上游 → 对应面的旧「跑过」记录作废(收尾报出是哪一份变了)→ 统一封版命令的测试前置拒绝(直到对当前内容重跑全过)→ 发布不认记录、当场真跑,并核对传上去的就是测过的那一份。活体证据要四样:改一行被测代码后收尾报该面作废;作废期间统一封版命令被拒且零写入;重跑全过后封版写入测试指纹、收尾复核零问题;发布侧上传内容与测过的指纹不符时被拦(见 §十六)。另两样:新建或改过的床没做空壳对照、或换成空壳仍全绿,收尾与定版都不认它通过;判据或检测引擎改一个字,旧的「检测干净」结论作废、下一轮收尾重查(两个裁判同构,§一)。
十三、版本契约与更新触发
版本契约(ADR-69 · 三层统一、硬控):整个 HARNESS、系统规范域、业务域三层的版本同一种写法、同一份判定代码、同一个封版命令流程 —— 各管各的,同一件事就有几种标题写法、几套解析、几种页面,整个 HARNESS 的版本锁还得借一份系统规范的闸。
单元(名册每次按磁盘现算,新建一个规范目录或业务域出生即是单元):
| 单元 | 版本号写在 | 变更历史 | 锁住的原件(设计 / 内容) | 封版命令 |
|---|---|---|---|---|
| 整个 HARNESS(1) | 本文文首「版本」一行 | harness/CHANGELOG.md | 设计:本文、宪法、决策记录、没配对系统架构目录的规则书、自研技能的说明与参考文档 / 内容:守卫 .claude/hooks/、自研技能的脚本与模板资产(assets/)、元规范与引擎文档、部署门入口与空壳对照(x-test/run-deploy-gate.js、deploy-gate-bite.js)(测试不算) | meta.js --action=seal --unit=framework:harness |
| 系统规范域(每份有架构目录的规范一个) | 判据规范简介 | arch/system/<规范>/CHANGELOG.md | 设计:架构页原件(派生区换成占位名)与 assets/(x-arch 另含 arch/standards/ 与 arch/assets/)/ 内容:判据正文、同前缀注册表、条款书的条款(文档头与派生区不算) | meta.js --action=seal --unit=spec:<规范> |
| 业务域(每个域一个) | 域 ARCH.md 文档头 version | 域目录 CHANGELOG.md | 设计:域目录里的文件 / 内容:describes 所指目录下按端取的代码(后台 .ts .tsx、小程序 .js .wxml、云函数 .js、数据表 .datasource.json,比对视图见下;自动生成的文件、测试根与部署门登记过的床不算 —— 别处叫 tests 的目录与 *.test.js 照样算,它们会随包上传) | x-feature-dev arch/seal.js --unit=domain:<中心>/<域> |
| 业务总览(1) | _context-map.md 文档头 version | arch/business/CHANGELOG.md | 设计:跨域关系图与注册表 _index.md;另冻结不归任何域的业务代码(只减不增) | arch/seal.js --unit=business:overview |
| 项目架构(1,ADR-83) | 设计页 arch/project/ARCH.html 页头的 version 标记 | arch/project/CHANGELOG.md | 设计:设计页本身 / 内容:无;requirements/**(需求履历)显式不进锁清单;另记阶段五关口的基线 frozenBefore(每个单元取锁清单里的版本,没有锁的不进基线;第一次封时写、之后原样抄进下一版、记指纹) | meta.js --action=seal --unit=project:overview |
| agent 架构(1,ADR-101) | 设计页 arch/agent/ARCH.html 页头的 version 标记(与项目架构同一种读法) | arch/agent/CHANGELOG.md | 设计:设计页本身 / 内容:执行体文件 —— .claude/agents/ 下一层的 .md(含名册注册表 _registry.md;子目录里的、不是 .md 的不算),封版的改动一行里这一组叫「执行体文件」。锚只认设计页:没有设计页的仓(夹具、沙箱)里没有这个单元,执行体文件那时不归任何单元。锁清单不带名册、也不带阶段五关口的基线 | meta.js --action=seal --unit=agent:overview |
「三层」这个叫法:「三层」指整个 HARNESS、系统规范域、业务域;单元是上表六行 —— 另有业务总览、项目架构与 agent 架构三个总览单元,守的是同一份契约。本文别处说「三层同一种写法」「三层同一个封版命令」,指的都是全部版本单元。
两个封版入口,同一个核心(ADR-99):元治理入口 meta.js --action=seal 封上表全部六类单元;开发流入口 x-feature-dev arch/seal.js 只封业务两类(业务域与业务总览),别的单元给它会被拒并指回元治理入口。两个入口转调同一份核心(x-meta-dev core/seal.js),业务两类用哪一个都行 —— 二选一,结果相同。改框架、改项目架构与改 agent 架构没有专属工作流,封版用元治理入口。
执行体文件换了单元(ADR-101):执行体文件 .claude/agents/*.md 是 agent:overview 的内容:改一份执行体只升 agent 架构的版本,不带动整个 HARNESS(算在整个 HARNESS 里,改一份执行体就得升整个框架的版,还与框架上别的需求互相排队);整个 HARNESS 的 owns 与「列全部文件」不认它们,一份执行体文件至多归一个单元。锁法与别的单元相同:逐个文件记指纹、改了没升版当轮红在那个文件上、封版走同一个命令。封它的测试指纹如实写 none —— 设计页没有代码;执行体文件由 x-agent 规范的闸在检测前置里判(封版以来改过的文件跑增量检测,不另跑规范自测与结构验证),守着那些闸的床随 x-agent 规范自己封版时核。执行体目录照旧在守卫的写保护名单上(§八 环1),改执行体文件由办理会话在签字放行内写(执行体目录属脊柱,列在签过字的落点里就放行;手动开闸只在急救时用)。
一个文件被两个单元认领,两个都要升。文件自带的格式版本(元规范判据标题里的版本、注册表里的 version、代码包的版本号、技能说明文档头的 version)不是单元版本,由各自的规则管。
写法:变更历史文档头只放 title(以「变更历史」结尾)/ unit / kind: changelog;每个二级标题都是一版:## v主.次.补 · YYYY-MM-DD · 一句标题,新的在最上面、版本严格变小、日期不倒挂;一次只升一步:契约生效之后相邻两版之间只能是某一位加一、它后面的位归零;契约生效之后的每一版必须有标题、有说明(之前的旧条目可以没有标题,正文一字不动)。标题行下紧跟的记录行只由封版命令写:> 设计指纹: > 内容指纹: > 测试指纹: > 改动: > 需求:(最后这一行绑的是哪条需求见下「为了哪条需求」)。锁清单 <单元目录>/version-lock.json 逐个文件记指纹(FNV-1a 两路,只判「内容变没变」,不当密码学用途),另记 contractSince(本单元迁入契约的那一版),以及这一版封版时的日期、标题与说明的指纹、测试指纹行、改动清单与这一版到文件末尾的整段历史指纹 —— 封过的一版与它下面的全部旧版一个字都不能再改(钉整段,不只钉第一节:只钉第一节,删掉旧版的记录行就能改它、没闭合的代码块能把已封版吞掉、最旧的一版删了也没人报);锁清单缺这几样就是按旧契约封的,第一节已封就报、要升版重封(施工中不拦,封新的一版时补齐)。持名册的单元另记名册:x-arch 记系统规范域、业务总览记业务域,新增或删掉一个都要它升版。锚单元不许消失:整个 HARNESS、业务总览、x-arch 是其余单元的锚(另两层单元的名册住在后两者的锁清单里),本机台账封过、磁盘上却找不到了(目录或定义它的文件被删、被挪走),收尾与发布都红,守卫的框架锁极简比对也不再把「框架目录没了」当成不适用。封过契约的单元必须有锁清单:变更历史里有按契约封过的版本(带「改动」一行)、或本机台账里有这个单元的封版记录(只看变更历史,删掉「改动」行就能骗过),锁清单却不在或坏了,收尾与发布都红,封版命令也拒绝把它当成首次封版(不然删掉业务总览的锁清单,下次封版就把无主基线从头冻结)。
为了哪条需求(ADR-83):契约生效之后封的每一版,标题下的正文第一行写 > 为了:<短名> —— 一句说明(短名打头,冒号全角半角都认;短名后接「——」或括号起的说明;分隔规则只在契约代码里定一次),封版命令把短名解析到恰好一条需求 —— 在办的查需求账本(签过字、开了工、签字没作废、账本链完好;签了字还在排队的报「还没开工」,不绑),已完结的查需求履历(arch/project/requirements/<需求名>/record.json);解析不出、对上多条、那条需求的落点表没列本单元,一律拒封。封得成时把需求名、短名与签字编号写进锁清单的需求字段,并写进记录行,两处互核、改一边红。阶段五的关口:发布前比对对每个单元核「锁清单的版本高于基线里记的版本(或单元不在基线里)⇒ 锁清单必须带需求字段」,缺了算问题;基线 frozenBefore 住项目架构单元的锁清单,还没写之前这一项不判、提示不进问题数组、只走脚本通道的标准错误输出(守卫通道只拦不看 —— 它对非空问题数组只有拦这一种出口,没有「提示」)。基线之后封的每一版逐版核记录行的需求绑定(不只核锁清单的当前版本):中间漏绑的一版会一直点名,封版命令不放漏绑的版本,报了就是绕过了它。立契约之前的旧写法由回填的别名表(按单元与版本建键、不按文本)对回需求,只给站点渲染用。
唯一实现:检测引擎 check/version-contract.js —— 单元名册、写法解析、比对视图、逐文件与整单元判定、封版的核心计算都在这一份;别处禁止另写标题正则、指纹算法或单元名册。谁调用它:增量与全量检测(内置「版本契约」一段)、x-arch 的四颗单元级闸(0003 业务域代码锁步 · 0009 系统规范域 · 0014 业务域 · 0015 业务总览与无主业务代码,经引擎注入的 tools.versionContract,闸只是薄壳)、统一封版命令、守卫的收尾复核、各条发布通道共用的发布前比对 guard/release-versions.js、治理站点构建器;守卫写前的顶层围栏也问它(只取单元名册、按路径判归属,不读锁清单,§八「顶层围栏」)。契约住框架、不住 x-arch —— 反过来放就是框架依赖系统四件套。归属只有一个口径:一个文件归哪个单元、归设计组还是内容组,由各单元的 owns 只看路径判(业务代码另读一次判是不是自动生成的);列一个单元的全部文件只是把候选目录走一遍再过 owns,两条路算出同一个集合由床对拍 —— 所以判几个文件不必先把全部单元的文件列全、读全(收尾与增量检测每次都付这笔)。调用方取引擎按自己住在哪取,不按被判的仓取(被判的可以是沙箱或夹具)。
比对视图(机器生成、机器会重刷的部分不进指纹,它们从原件算出、另有闸看着):条款书的文档头与派生区、架构页的派生区换成占位名;业务代码原文比(只统一换行符):注释、空白、import 顺序改了都算改(去注释怎么去都骗得过 —— JSX 文本里的 // 与 /*、正则字面量;挪动 require、改字符串里的空白也看不见;去注释省下的那点麻烦不值这些漏洞);数据表按完整结构比(键排序后的规范形,字段、必填、唯一、选项集、长度一律算)。换视图的那一次,各业务域补丁升版重封。
四道关口:
- 写入时:锁清单受守卫脊柱写保护,手改直接拦。
- 收尾:增量检测逐个改动文件问「属于哪个单元、封版后改过没有」—— 改了却没在变更历史最上面加新的一版,当场红在那个文件上(删掉、改名、只改大小写的文件同样判;删掉的那一种收尾先提示是不是误删、给出签字基线里的指纹与核对命令(ADR-104),见 §八 环3「版本契约」里的误删提示);新的无主业务代码当场红;改了哪个单元的变更历史、锁清单或版本号所在的文件,就把那个单元整单元核一遍(写法、次序、一步一升、两处一致、封过的一版没被改;全部单元都核;持名册的单元在名册成员新增或删掉时也整单元核),并核对封版记录(三行指纹、标题说明、改动清单、测试行、日期逐项与本机台账一致,手写或手改都拦;有记录却把记录行删了也拦;锁清单不在或坏了、台账却有这个单元的封版记录也拦)。施工中:已在最上面加了新的一版、还没封,带
--wip开关只放过这一种,并提示单元与封版命令 —— 它不是警告级(原则 6):收尾、开发流 VERIFY 与封版的检测前置带它,全量检测与发布一律不认(开发期联调上线不是发布:那一次的发布前比对只放过那条需求落点表里的单元施工中,见第 4 关)。 - 封版:统一封版命令(元治理
meta.js --action=seal与开发流arch/seal.js转调同一份x-meta-dev core/seal.js,后者只放行业务层单元)依次核:写法与版本、一次只升一步、标题与说明、日期是今天(封版不收--date)、没封过、封过契约的单元锁清单在(变更历史的「改动」行或本机台账任一处说封过,就不许当首次封版) → 检测零红(封版以来改过的文件跑增量检测,带--wip:与本单元共用文件的别的单元正施工中不算问题 —— 82 个业务文件同时归两个域,只放被封的那一个会让两边谁都封不了;施工中的单元发布一律拦(联调除外,见第 4 关);系统规范域另跑-t/-v)→ 测试全过(整个 HARNESS:守卫、检测引擎、技能三类测试面;系统规范域:规范面与覆盖它的床;业务域:本域代码所在的测试面,没有覆盖如实写none;业务总览、项目架构与 agent 架构没有被测代码,同样如实写none;前三类执行时先把只因盯的路径变了而作废的床交唯一运行器当场重跑一遍、预览只列出会重跑哪几张(ADR-103),见 §十六「封版的测试前置」)→ 先记封版记录、再写记录行与锁清单 → 回读零问题;系统规范域封前封后各刷新一次派生区。按归属封版:别的会话在途、无主的改动保留旧指纹不封进这一版、继续对它们报红;--adopt=路径显式认领无主改动;删除的自动认领(ADR-103;判法住封版命令core/seal.js的claimDeletions,不动检测引擎):无主一栏里的删除 —— 台账里没有任何会话的写证据(主人会话已结束、或主人已不在线而按无主处理的那几种不算,它们有主人;开闸期间删掉的就没有写证据)、文件此刻已不在盘上 —— 同时落在这一版「为了」解析到的那条在办需求此刻的落点表里(与三查认「范围里」同一个判法)、又在本单元的锁清单里,不用带认领开关、照封,不再留旧指纹。封版报文写明认了哪几个(预览说「将自动认领」,封完说「已自动认领」),封版记录多一栏认领清单(§十六「封版记录」);锁清单照旧只由检测引擎写、不记这一项。「为了」那条需求不在办(已完结、签字作废、账本被改过、还没开工)、需求零件装不上、锁清单读不了,一个都不认、保留旧指纹。不自动认领,锁清单里就留着一份已经不在盘上的文件的旧指纹,这个单元一封完就又是改过的、只能再升一版带认领开关重封。落点表之外的删除照旧算无主,无主的修改(文件还在)照旧要带认领开关;拿不到本会话身份就不封,会话身份也不能在命令里冒充(写前拦截拦「设会话身份环境变量」的命令)。改动清单由封版命令比对前后锁清单算出。 - 发布:每条发布通道 —— MCP 部署门、云函数脚本出口(
/x-deploy-dev的deployer.gateFunctions)、四个静态站点出口的发布准备(release/publish-tests.js,后台、手机网页版、官网、治理站点共用)—— 调同一个发布前比对guard/release-versions.js(静态站点在打包之前再比一次):版本契约整体比对全部单元(施工中也拦)、守卫的框架锁极简比对、全部单元契约生效之后每一个封过的版本逐版对台账里的封版记录、锁清单不在而台账有记录的单元、基线之后封的版本锁清单缺需求字段(见上「为了哪条需求」);判不了一律拦。联调与正式发布(ADR-100):这一比对之前,三条通道先判这一次是联调还是正式发布 —— 同一个判定,住守卫的联调零件(§八「部署门认联调」)。正式发布:要发的云函数或站点源码被在办需求签过字的落点表盖住就拦(核验收完结),比对照旧核全部单元。联调(只限云函数与数据表;有口径、那条需求在办、要上线的全部东西都落在它签过字的落点表里):比对多收一份「放过哪些单元的施工中」的名单 —— 只有那条需求落点表里的单元、只有施工中这一种状态被放过,这些单元别的毛病与别的单元照拦。问题行带封版命令:比对给出的每一行(判不了那一行除外)末尾带上那个单元的封版命令,三条通道原样打印,被拦的人不用再查该跑哪一条。经 MCP 的静态托管调用里不往线上放新内容的那几种(回滚上传、回滚删除、清理清单内的删除)不进部署门、因而不比(ADR-89,见 §八):它们不把仓里的任何东西放到线上。五个发布入口(云函数脚本通道、后台、手机网页版、官网、治理站点)在这一比对之前先只读查一遍部署门的待检清单(ADR-98),有没复核的停在第一步(§九「发布之前先只读查部署门」);它不是第五道关口,判法是守卫部署门那一份。
锁自己:契约代码本身是框架代码,改它就是改框架、要升整个 HARNESS。守卫另留一段不经契约代码的框架锁极简比对(guard/framework-lock.js,同一个指纹算法、只读框架锁清单逐个比对锁住的文件):契约实现被改松时,收尾与发布仍看得见已锁住的框架文件被改或删掉(新增的框架文件只归契约那一段);两份指纹同值由守卫床对拍。干净结论的判据组指纹带上各单元锁清单与变更历史第一节的状态,封了版、进出施工中,旧的「查过干净」即作废。
无主业务代码:业务代码(四端与内核母本顶层目录下按端取的文件;测试、依赖、构建与装配产物、自动生成的不算)必须归某个业务域。存量无主代码(后台公共组件、语言包、各端系统层、内核等)冻结在业务总览的锁清单里,只减不增 —— 新出现一个即红,封版命令拒绝把本会话新添的冻进去,已归位或删掉的下次封版自动划掉。存量在逐域回归时归位。
页面:治理站点的三层变更历史统一渲染成同一个「版本台账」(版本、日期、级别、标题、三行指纹、改动清单、封版态,页头一格是构建那一刻的整单元核对),叫法统一为「变更历史」;整个 HARNESS 另有「版本」页签按大版本展开。
升哪一位:改写既有契约升第一位(治理拓扑、威胁模型、既有工件类的契约被改写);新增一类东西(闸、视图、工作流、表、云函数)升第二位;订正、或设计内容没变只改写法与记账方式升第三位。一次只升一步:升了哪一位,它后面的位归零。机器保证必须升、一次只升一步、两处一致、封过的一版不能改;升哪一位要看改动的性质,机器判不了,由改的人按这张表判断并写进那一版。域与规范域的版本不带动整个 HARNESS 的版本(否则总版本每天升几十次,真正改框架的那几版被淹没);项目架构与 agent 架构的版本同样各管各的(改执行体文件升的是 agent 架构的版本)。
诚实边界:① 锁步证「改了、升了版、封了」,不证「设计还对、说明属实」—— 回看靠人;② 无主业务代码只受「只减不增」管,存量文件在归位之前改了不会让任何设计升版(存量里有内核鉴权、支付、后台路由与权限扫描这类要紧代码,逐域回归时归位);③ 部署门注册表 x-test/deploy-gate.json(业务开发要改的数据)、钩子接线 .claude/settings.json(开闸关闸由用户定)、代签设置文件 .claude/sign-settings.json(只经用户的固定话或手改变化,守卫写保护、工作区地图声明它所在的区)、型号配置文件 .claude/model-settings.json(只经用户的固定话驱动的受信命令变化,守卫写保护、工作区地图声明它所在的区)与治理站点构建器 x-harness/builder/(发布验收 --verify-dist 的结果被发布档案信任)不在任何单元里,改它们不升版,挂载状态由体检派生显示;④ 本机台账可以被故意伪造(写脚本绕过写前拦截),与整套体系的其它锁同一条边界;⑤ node 进程内直接写文件不经任何写前拦截(node 洞);⑥ 业务代码只取上表四类文件:样式与页面配置不在任何单元里,改它们不升版;文件头自称「自动生成」的文件不进任何单元;⑦ 会话身份来自环境变量:写前拦截拦命令里出现这个名字的一切改写,把名字拆开再拼接拦不住 —— 与④同一条边界(故意伪造本机状态);⑧ 收尾只看 git 报出来的改动(已提交或拉下来的改动、Windows 上 git 忽略大小写时只改文件名大小写的重命名,收尾看不见),Claude Code 在同一串停止里第二次调收尾时不再拦 —— 这两处都由发布前的整体比对兜住;⑨ 开闸期间经 MCP 的云端写,写后补判用写前同一套判法(待检清单与版本比对两臂都判;两臂之间的「联调还是正式发布」同样补判),但只记一笔、收尾报红,事后拦不回来;回滚与清理旧文件的仓库状态写前写后都不看(云函数脚本出口与静态站点发布准备的比对在脚本里,开闸也照样比;见 §十六 诚实边界 ⑤);⑩ 封版的检测前置放过别的单元的施工中(共用文件时的互等),它们在发布前被拦;⑪ 删除的自动认领不问是谁删的:没有写证据,分不出是这条需求删的还是别人误删的,只要落在落点表里就封进这一版 —— 落点表写得越宽,误认的面越大;认领了哪几个只记在封版报文与本机的封版记录里,锁清单与变更历史都不标哪个是认领进来的,本机账本清过之后就查不到了(收尾环报「删掉了」时先提示是不是误删,见 §八 环3 误删提示 —— 那只是收尾时的一句话,封版那一刻的认领不问)。
必须更新本文档的触发清单(触发而不更新 = 违反宪法强制规则):
- 任一层(L0–L5)职责或边界变化;
- 强制闸门新增/退役(hook 谓词、检测模式、exit 语义、部署门类);
- 工作流增删或生命周期阶段重构;
- 威胁模型 / 安全边界 / 提交纪律变化;
- 治理拓扑(part1/part2 关系)变化;
- 重大 ADR 产生(追加 ADR 行)。
同批回看站点入口页:上面任一条触发成立时,治理阅读站点的七个入口页(x-harness/index.html 理念、agent.html agent 架构、business.html 业务、system.html 系统、framework.html 框架、project.html 项目架构、version.html 版本)同批回看,把说法改齐。它们是原件、不从本文派生(agent 架构那一页是壳,正文由构建器从 agent 架构设计页切出来 —— 那一栏要回看的是设计页);构建器的新鲜度只看得出「源文件变没变」,看不出入口页的说法有没有过时。一句话的说法对不对齐没有可抓的形态,硬造一道「页面里出现了哪几个词」的检查只会是假闸,所以这一条靠触发清单承担,不靠机器。病历:统一模型写进宪法与本文之后,框架页仍写「统一裁判」、理念页仍写「绕过流程,不等于绕过检测」,直到用户在线上读到才发现。
更新流程:改本文、宪法、决策记录或框架的任何一份原件,都是一条「改框架」的需求 —— 走需求流水线(计划、签字一、封版、独立复盘、三查、验收完结),没有专属工作流;落点单元是 framework:harness,封版用元治理的封版命令(§十七「五类需求入口表」;ADR-99)。/x-meta-dev 管的是系统规范(判据、条款、架构页)的变更。两件事分开管:改了框架有没有升版,由上面的版本契约用机器逼着;这次改动要不要改本文的描述,仍是语义判断,由宪法「强制规则」与上面的触发清单承担(hook 只能识别文件与命令,判不了"这次改动是否架构性")—— 版本契约让它不再能被悄悄跳过:改了框架就得升版并封版,封版时就得在变更历史里写这一版的标题与说明,顺手就会回看本文。
十四、架构层(arch/system 系统架构 · arch/business 业务架构 · arch/project 项目架构 · arch/agent agent 架构)
动机:Harness架构(本文档)与系统规范(判据 + 条款)均有强制保鲜;业务领域端到端设计真相(登录/订单/派单…)没有载体、没有保鲜闸就会随代码演化静默过时,所以 .claude/arch/business/ 是业务架构常青真相源;系统规范的设计件住 .claude/arch/system/,是系统四件套的设计件。
三层文档分类:
- Harness架构 = 本文档(单文件,L0–L5 控制系统;元规范 x-standard 的设计也住这里——它的规则书是条款书、「设计」行指向本文档,不建系统架构目录,见 §五)。
- 系统四件套 = 每个有自己规范文件的系统规范域:设计
arch/system/<规范>/ARCH.html(+CHANGELOG.md)· 条款rules/x-*-rule.md· 判据x-*-spec.md· 执法 guard(锁步见 §五)。 - 业务架构 =
arch/business/(DDD bounded context,按后台菜单四大中心分「中心/域」两层,ADR-59;以代码为锚、由锁清单逐文件锁步(版本契约),不设四件套;代码目录不跟着分类搬,域经 describes 认领代码)。 - 项目架构 =
arch/project/(ADR-83):「需求 → 实现 → 部署」这条流水线自己的设计页ARCH.html(版本单元project:overview:一条需求的状态机、六个阶段(阶段六是「收尾与归档」,ADR-97)各写关口卡在哪、守卫在哪拦、证据记在哪、守不到之处、开闸期间在不在岗、守着它的床,与三类架构的接口,终点与发布状态按格判的规则,发布之后清理归档这个环节,诚实边界;机制指向本文不抄,这一分工没有机器闸)与需求履历requirements/<需求名>/(封存记录,钩子一次写成,不进锁清单;签字一建、验收完结封(封的那一刻写「用时与返工」「遗留」两栏,§八「履历多两栏」)、发布段只由体系守护的 record-release 动作追加)。它不是业务端、不是规范,是受治文件类里的「项目架构」那一类(名单见 §十五「受治文件类」,不按序数叫);治理站点「项目架构」一栏展示它。 - agent 架构 =
arch/agent/(ADR-101):执行体这一侧的设计页ARCH.html(版本单元agent:overview:X大脑与三类会话、一条需求里谁做什么、执行体名册与每一位的分工、队形、场景地图、与另外四类架构的联动、硬控清单与诚实边界;机制指向本文不抄)。它的内容是执行体文件.claude/agents/*.md(§十五),像业务代码之于业务架构:设计页描述它们,同一个单元一起定版。设计页里的名册表是执行体名册的真相源 —— x-agent 规范的名册闸拿它与执行体目录下的文件两边互核(§十五 NS-7);名册注册表_registry.md里那张表只是指针。它是宪法 §三 说的自上而下五层里的一层(答「谁来做」),不是六层之外的又一层(§十五「定位」);治理站点「agent 架构」一栏展示它,正文由构建器从设计页切节而来,与项目架构那一栏同一种做法。
设计只写当前这一版(宪法 §二 版本契约;决策 ADR-105):五类架构的设计 —— 业务域文档、系统规范的架构页、项目架构设计页、agent 架构设计页与本文 —— 只写当前这一版的完整内容。正文里不写版本号,不写「原来是」「某一版起」这类讲经过的历史:一个单元改过什么、为什么改,只写在它的变更历史与决策记录里。机制细节(判法、时限、字段、命令)只写在本文一处,各设计页写一句指向、不抄;设计页讲「这一处是什么、关口在哪、证据在哪、守不到什么」。
项目架构环的十态与启动、收尾(ADR-98):一条需求在「需求 → 实现 → 测试 → 部署 → 清理归档」这一圈里走到哪,由机器定义成十个态(账散在需求账本、需求履历、三查结果单、发布段、归档目录几处,不定义就没有名字、也没有一处查得到,主控只能靠自己记),体系守护命令的 loop 动作判出此刻是哪一态并打印下一步该谁做什么(机制见 §八「环的十态」)。它不是 agent,也不是新的账:判定是机器读现成的账,agent 只办不确定的活(实施、复盘);主控是会话的角色,不是派出去的执行体(它有一份只用来启动主会话的执行体定义「X大脑」,§十五 角色表;环走到哪一态照旧由机器读账判,不由它判)。排队(签了字、还没开工)并进第 2 态「已立项」,不加态。启动 = 开工那一刻 —— 开得了工的,就是守卫记下签字一那一笔并建出需求履历的那一刻;排队的,是开工命令记下开工那一笔的那一刻。收尾 = 已发布与已归档两样都成立的那一刻。会话清空机器看不见,不入态。
| 次序 | 态 | 什么算到了这一态 | 下一步该谁做什么 |
|---|---|---|---|
| 1 | 未立项 | 计划目录与归档目录里都没有这条需求的计划,需求账本里也没有它的签字 | 主控 —— 立项:拍板做不做、走哪条流程、定档、排第几(含判「验收谁签」),交项目经理起一位产品经理会话;设计由对应的架构师出,计划由产品经理写 |
| 2 | 已立项 | 计划目录里有它的机器镜像,还没开工(没签字一,或签了字一在排队) | 没签字一的下一步(三条):①主控:弹确认题:计划合不合设计由对应的架构师审,成条与难事的题弹出之前先请复杂化审查官做减法审(产品经理先跑核对命令刷新签字区:node .claude/skills/x-harness-dev/scripts/harness.js --action=reconcile --plan=<计划名>)②用户:签「确认 <短名>」③机器:守卫在那一刻记下签字一、建出需求履历:此刻开得了工就当场开工、记基线 —— 环从这一刻启动;开不了就记成排队(不占单元、不放行写)。签了字一、在排队的下一步(两条):①主控:排到它(开工条件满足)就由项目经理(或主控自己)跑开工命令(node .claude/skills/x-harness-dev/scripts/harness.js --action=start --plan=<计划名>,不带 --execute 先看预览),叫醒这条需求的产品经理 ②机器:守卫在那一刻记下开工那一笔与开工基线 —— 环从这一刻启动 |
| 3 | 在办实施 | 开了工(签字一当场开了工,或开工命令记下了「开工」那一笔;环已启动,需求履历已建出),还没走到后面几态 | 产品经理 —— 照计划实施、勾步骤;做完跑接力命令(node .claude/skills/x-harness-dev/scripts/harness.js --action=run --plan=<计划名>):增量检测、按改动跑床、规范同步、封版、固定检查、三查、生成复盘说明 |
| 4 | 已封版 | 落盘的最新三查结果单第三查是绿的:改到的版本单元都封了版、封后没再动、落点表里每一格都变过 | 产品经理 —— 拿接力命令末尾印出的派发表头派独立复盘,等复盘结论入账 |
| 5 | 复盘过 | 需求账本里最后一笔可信的独立复盘是「过」,是对当前内容做的,之后用户没有说过「不过」 | 产品经理 —— 再跑同一条接力命令(node .claude/skills/x-harness-dev/scripts/harness.js --action=run --plan=<计划名>):三查、开验收区、起草收尾单;末尾出现「可以弹验收题」就报主控 |
| 6 | 待验收 | 看板签字区此刻开着的是「验收完结」那一道(三查全绿才开得出来) | 主控 —— 看这条需求的「验收谁签」:亲签就弹验收题(题目正文带看板的完整路径与「签字」页签);代签就先逐条核验收清单、把每条的证据写进看板验收区,再跑代签命令(node .claude/skills/x-harness-dev/scripts/harness.js --action=sign --plan=<计划名> --kind=验收完结 --as=代签);用户 —— 亲签的:照清单亲手验过,签「验收完结 <短名>」;代签的:随时也能亲自签,说同一句;机器 —— 守卫在那一刻当场重算三查,全绿就记「已完结」并封死需求履历(代签的,履历里写明「X大脑 代签」) |
| 7 | 已完结 | 需求账本里有「已完结」那一笔(签字二那一刻三查全绿,需求履历已封死);它该发的格还没发完,计划也还没搬进归档 | 运维经理 —— 把这条需求该发的格发掉(验收完结这一签已授权这条需求该发的每一格各发一次,出问题立刻回滚算同一次:亲签的凭 X大脑 转来的验收原话,代签的凭代签记录;不随验收的发布、生产构建、开发中途的联调另要单次授权),发完跑发布登记(node .claude/skills/x-harness-dev/scripts/harness.js --action=record-release);数据表与微信原生包在体系之外发(控制台、微信开发者工具),不算进该发的格;产品经理 —— 跑一次接力命令收尾(node .claude/skills/x-harness-dev/scripts/harness.js --action=run --plan=<计划名>):它刷新收尾单、预览清理归档,没人在跑床或建站就归档,归档不了照实说原因;复盘与去向不挡,在后台办。这两件事先后不限 |
| 8 | 已发布 | 已完结,需求履历的发布段是「已发布」(它该发的每一格都发了;一格该发的都没有的也算);计划还没搬进归档 | 产品经理 —— 跑一次接力命令收尾(node .claude/skills/x-harness-dev/scripts/harness.js --action=run --plan=<计划名>):它刷新收尾单、预览清理归档,没人在跑床或建站就归档,归档不了照实说原因;归档成了环就收尾。复盘与去向不挡,在后台办 |
| 9 | 已归档 | 已完结,计划已经搬进归档目录;需求履历的发布段还不是「已发布」 | 运维经理 —— 把还没发的格发掉(验收完结这一签已授权这条需求该发的每一格各发一次,出问题立刻回滚算同一次:亲签的凭 X大脑 转来的验收原话,代签的凭代签记录;不随验收的发布、生产构建、开发中途的联调另要单次授权),发完跑发布登记(node .claude/skills/x-harness-dev/scripts/harness.js --action=record-release);数据表与微信原生包在体系之外发(控制台、微信开发者工具),不算进该发的格;发布段翻成「已发布」环就收尾 |
| 10 | 环收尾 | 「已发布」与「已归档」两样都成立(后成立的那一样成立的那一刻,环收尾) | 主控 —— 跑提交命令(先不带 --execute 看预览,带了才做;命令全文 node .claude/skills/x-harness-dev/scripts/harness.js --action=commit --plan=<计划名>);提交之后交项目经理——拿结案报告(十态命令带计划名查这条)转 X大脑、关掉它的产品经理会话、删掉会话登记册里那一行 |
表里十个态名与后两栏的字,逐字抄零件里那张常量表(x-harness-dev/scripts/core/plan-loop.js 的 STATES;命令与固定句加了代码记号,字没动;「下一步」一栏里谁只有五种:用户、主控、产品经理、运维经理、机器);项目架构设计页第一节只列这十个态名(逐字相同、次序相同),怎样算到了与下一步该谁做什么只写在这张表。次序就是环走的次序,但已发布与已归档没有固定的先后 —— 机器只要求已完结,先发还是先清由主控排(§八「清理归档」②「不等发布」)—— 所以第八、第九两态谁先到都可以,环收尾只在两样都成立之后出现。签字作废、账本被直接改过这几种不另立态,见 §八「环的十态」。表里第 1、2、7、9 态的「下一步」照的是提速的八条规矩(产品经理从立项起写计划与机器镜像;验收完结那一签已授权这条需求该发的每一格各发一次),规矩的明文在 §十五「提速的八条规矩」;第 10 态的「下一步」写的是提交与结案报告,见下一段。第 7、8 态里产品经理那一项与守卫的完结回话说的是同一件事:跑接力命令收尾,没人在跑床或建站就归档,复盘与去向不挡、在后台办(两处都被床逐字钉着;§八「接力命令」「后台收尾」)。两个「终点」别混:「已发布」是发布状态的终点(宪法 §六.8:这条需求该发的每一格都发了才算已发布 —— 该发的格不含在体系之外发的数据表与微信原生包、也不含联调那一格,一格该发的都没有的验收完结即已发布,ADR-100,§八「收尾单与治理站点一格」里「发布登记的新记法」);「环收尾」是这条需求在环里的终点,比已发布多要一样已归档。守不到见 §八「环的十态」。
环收尾之后的提交与结案报告(ADR-118):环收尾是这条需求在环里的终点,但还差一步才进库 —— 由主控跑提交命令,把这条需求验收过的那一份按项目名提交进版本库、打项目标签 req/<需求名>、推到远程(只推主干与这个标签、只许正常推)。授权不另问:验收完结那一签(亲签,或照代签设置代签)同时授权了这条需求的发布与提交,命令核的是完结那一笔记着「要提交」与环收尾成立。命令不带 --execute 只预览(印出要提交的文件分几类各几个、提交说明、标签名、哪几样核不过),带了才做;核哪几样、提交哪些文件、说明与标签的写法、推送失败怎么办、做到一半怎么续做,写在 §八「提交命令」。提交做完,账本里记「提交」那一笔,十态命令带计划名查这条需求时多一行提交(要等环收尾 / 待提交 / 提交号、标签与推没推到远程),查一条已提交的需求时末尾印结案报告(交付了什么、发了哪几格、还要用户自己上传的端、遗留去了哪、代签凭什么,加一行提交号,新式专项最末另多一栏后台收尾;除这一栏取自复盘记录,其余全取自履历、发布段、收尾单与账本,§八「结案报告」)。项目经理拿结案报告转 X大脑、记总账一行,X大脑 原样转用户;之后项目经理关那位产品经理的会话、删登记册那一行(会话清空机器看不见,不入态)。提交不是又一个态:十个态名不变,环收尾仍是环的终点,提交是环收尾之后的一件事,不进「已发布」「环收尾」的认法。钥匙石与代签设置不由机器提交,与库里不一样时每次提交点一次名,由用户亲手看、亲手提交(§二)。守不到:见 §八「提交命令」「结案报告」。
分界判据(可由仓库推导):有自己规范文件 ⇒ 系统四件套;以代码为锚、没有自己规范文件 ⇒ 业务架构(arch/business/randd/mobile 描述移动端底座却没有自己的规范,故归业务架构;business/randd/ 是后台菜单「研发中心」这一类业务,与系统架构无关)。
原件与派生件:整套 harness 由 AI 撰写、用户拍板(两次签字),故文件不按「谁写」分,而按「能否机械算出」分——原件需判断(判据、条款、架构页原件区、业务架构正文、变更历史条目),由对应执行者经工作流撰写、由闸核对;派生件可机械算出(条款书的标准写法行号索引与速查、架构页派生区、规则书 specHash 与 rule paths),只准脚本产出,AI 也禁直接改;变更历史每一版的记录行与锁清单是封版记录,只准统一封版命令写(§十三)。迁移或改写时内容的去向也有判据:写码当下要用的操作性内容留条款,只有设计理由去架构页;来历只进变更历史与决策记录(§五「阶段三复盘整改」)。
写权分工:arch/business/** 归 x-architect(开发流收尾 ARCH-SYNC 派出);arch/system/**、规则书与规范归 x-meta-governor(经 /x-meta-dev,预载 x-meta-dev 与 x-spec-checker),系统架构的公共部件 arch/standards/** 与 arch/assets/** 同归它(它们算在 x-arch 那个规范域里,§十三 单元表);开发流不写 arch/system/。项目架构 arch/project/** 的设计页归 x-framework-architect(ADR-99;走需求流水线,落点单元 project:overview);其中需求履历 requirements/** 谁都不手写 —— 只由钩子与发布登记写,目录受脊柱写保护。agent 架构 arch/agent/** 的设计页同归 x-framework-architect(ADR-101;走需求流水线,落点单元 agent:overview);它的内容 —— 执行体文件 .claude/agents/*.md —— 照旧归 x-meta-governor(§十五「生命周期」)。
arch/business/ 结构:
_index.md:声明式注册表。「四大中心」一节登记中心(营销marketing客户流 / 电商ecommerce订单流 / 服务service工单流 / 研发randd系统、不对外;代号 = 后台菜单国际化键的第一段),「已固化业务域」一节登记域 → 架构文档。双向闭合:登记的域必有文档,磁盘上有ARCH.md的目录也必须登记(不然未登记域不受存在性闸约束,留下「建了不登记」的口子)。_context-map.md:DDD Context Map(跨域依赖 + 集成模式)。{中心}/{域}/ARCH.md:各业务域架构(域目录化),frontmatter 契约(title/layer/status/version/describes 四端 glob/specRefs/sourceOfTruth);describes 只接受「目录/」一种写法。关系域**(跨域关系自成的一块,与域同级)另写kind: relation与relates: [两端所在的域]。{中心}/{域}/CHANGELOG.md:该域变更历史(日志载体分离:不写进 ARCH.md frontmatter 的version-log),写法同三层版本契约(§十三):分节## v主.次.补 · YYYY-MM-DD · 一句标题,frontmatter 只放 title/unit/kind,禁真相源身份键。可选子目录parts/(分支架构)/adr/(架构决策记录)/assets/(可视化产物),白名单外条目即违规。- 身份锚点:含
ARCH.md的目录 = 域目录,门牌恰好两段中心/域;中心目录只分组、不放文档(业务按流分类,一个域认领的代码可以跨 x-data 的归类层,比如工单域归服务中心、它的表住x-data/ecommerce/dispatch)。同构 x-client「含pages/的模块index.js必需存在」的身份锚点范式。 - 域目录化动机:一个域会产出多份异质文档(设计正文 / 版本日志 / 分支架构 / ADR / 可视化产物),单文件形态承载不下;目录是「一个 bounded context 一个容器」的物理落实。注册表第 2 列登记
{中心}/{域}/ARCH.md,必须恰好等于「门牌/ARCH.md」(NS-COMMON-0001:门牌两段、中心已登记、路径即门牌、磁盘目录全登记)。_index.md/_context-map.md留 arch 根(它们是名册与跨域图,非域),继续由两条字面路径排除豁免文档头闸。
x-arch 业务组(纯 NS,照 x-fallback 骨架):
- 存在性闸(NS-COMMON-0001,四臂):登记域必有对应文档 · 中心名册自洽 · 门牌两段且中心已登记、文档路径即门牌 · 磁盘上的域目录必须登记(防登记↔文档两个方向失同步)。
- 文档头完整性闸:frontmatter 七字段 + describes 四端键(N/A 显式 null)+ layer=business(框架详图归本文档不进 arch/)+ status 枚举 + specRefs 非空则正文须引用(I2 句法代理:arch 引用系统架构 rule 而不复述技术契约,防第二真相源漂移)。
- 域目录成套闸 + 日志载体分离闸(双臂) + 域目录白名单闸:成套=有
ARCH.md必有同级CHANGELOG.md(日志无处可去必然回流文档头);分离臂A=ARCH.mdfrontmatter 禁version-log键与退役的srcHash键、臂B=CHANGELOG.mdfrontmatter 禁describes/srcHash/sourceOfTruth(防日志变第二真相源);白名单=域目录只允许登记的文件(含锁清单version-lock.json)与子目录,穷举零豁免(未登记形态=不受任何闸保护却坐在真相源旁边的野文件)。三闸均经反向注入实证咬合。 - 诚实边界(治理面定义):日志分离闸的适用面 = 域文档(
**/ARCH.md)。_index.md(注册表)与_context-map.md(跨域图)是 arch 根的元文件非域,天然不匹配身份锚点。两者合成单元「业务总览」,变更历史在 business 根的CHANGELOG.md,写法与封版与业务域相同(x-arch NS-COMMON-0015)。 - 业务域代码锁步(ADR-69):NS-COMMON-0003,锚在各域
ARCH.md,调版本契约:封版时域描述的每个代码文件(代码原文比;数据表按完整结构比;自动生成的不算)与域目录里的设计文件逐个记进锁清单,之后改过、新增、删掉而没升版即红;逐文件的报红由引擎内置的版本契约一段在改动当轮承担。诚实边界:证"被改了、升了版、封了",不证"设计对";多会话下封版按会话归属写锁清单。 - 业务结构放置闸(ADR-54):NS-COMMON-0013,锚在每张表文档上(不锚注册表 —— 锚注册表的红会被收尾环按域过滤整段丢掉)。四臂:归属唯一(恰好一个域的 describes.data 覆盖)· 上级写明(子表在「上游/下游关系」段写「上级」、关系表写「两端」,声明必须能在字段里找到对应关联 —— 上级靠声明不靠推,推出来的是猜的)· 放对一层(子与上级同域;关系两端同域则同域,跨域则归
kind: relation且relates与两端所在域一致的关系域,关系域不许拥有主表)· 名册自洽(存量的两份豁免名单,改好必须划掉;判据里冻结一份清单,名册只许是它的子集 ⇒ 只减不增由机器管)。锚在表文档上 ⇒ 改表当场增量门可见、自动按会话归属,收尾环零改动;域文档那一面只报 describes 决定的两件事(重叠认领、放错层),不替别的表转报。加固:「关联」只认字段表格行里真实存在的字段、声明与关联先剥注释与代码块、关系表两端必须恰好是字段里关联的全部表、同名多份表文档即红、上级未归域直接报红(豁免不外溢)、describes 路径必须是唯一规范写法。诚实边界:检测器跑在引擎沙箱(只给 fs / path),拿不到上一版 ⇒ describes 改窄、删域文档、挪动或改名上级表致失配只有全量检测看得见;主业务编进哪个域是业务判断,不判对错。 - 业务域版本锁步闸(调版本契约):NS-COMMON-0014,锚在各域
ARCH.md+CHANGELOG.md:写法、ARCH.md的 version 等于第一节、已封版且锁清单一致。封版走统一封版命令(开发流入口arch/seal.js)。已闭环域(客户、企业信息、菜单)的整体可控性由真实仓闭环床business-arch-closure验(探针 ⇒ 真收尾环在探针上点名本域 ⇒ 封版命令拒绝 ⇒ 删掉即放行)。 - 业务总览与无主业务代码(ADR-69):NS-COMMON-0015,锚在 business 根的
CHANGELOG.md与_context-map.md:业务总览单元的写法、版本与封版;不归任何业务域的业务代码冻结在它的锁清单里、只减不增(新出现即红,已归位或删掉的下次封版自动划掉)。 - 业务域遵循架构设计模板闸(ADR-56):NS-COMMON-0012,锚在各域
ARCH.md+ 视图页parts/*.html+ 同前缀名册x-arch-design-template.json。业务架构的组织单位是业务域,一个域 = 七个视图(架构设计 / 流程设计 / 前端设计 / 服务设计 / 数据设计 / 测试设计六页住parts/,变更历史就是CHANGELOG.md;测试设计见 ADR-66)。四臂:域(名册里的视图页齐全、旧形态modules/·ARCH.html·CHANGELOG.html退场、parts/只放视图页;视图数目从名册派生,判据代码不写死)· 视图页骨架(节取自名册、顺序一致、必填齐全;流程设计每个场景先流程图、后分步操作,顺序也判)· 表达层(前两份样式表依次落在共用底座与视图画法,按落点判)· 名册自洽(登记为 pending 的域冻结成清单,只减不增;pending 只豁免「缺视图 / 旧形态」,视图页一出生就受判)。站点的页签清单取自同一份名册(构建器不另抄),按parts/实际有哪几页给每个域出页签,导航不列数据表。散文版《架构设计模板》住.claude/arch/standards/architecture-design-template.html,菜单域是第一个样板。 - 框架不依赖业务(part1 不引具体业务 arch):没有单独的一颗闸。铁律由构造保证(detector 域无关,读注册表/frontmatter 零硬编码域),并有一张活体证明的床 —— 框架独立性床
x-meta-dev/tests/tetrad-framework-independence.test.js:副本工作区里除元规范外一份规范都没有,元治理自测、元规范验证与新建一整套规范照样通过。守不到:这张床证的是「没有系统规范,框架照样自洽」,不查框架代码有没有引某个具体业务域的文件。
x-arch 系统组(纯 NS):成套(NS-COMMON-0007:规范 ↔ arch/system/ 目录一一对应;迁移名册已清零、ceiling 为 0,成套闸处于严格态,注册表文件保留作全局锚点)· 架构页派生区保鲜(0008:戳记核对)· 版本锁步(0009:锚在系统组注册表,全量检测)· 原件完整与测试床验真(0010:原件区无占位符、每颗闸被测试床点名、点名的床存在且写明闸号;另两臂——不标 data-bed-kind 的床必须真调用引擎,只守不变量的床写 data-bed-kind="invariant";点名兼收「规范名:ARCH-条款号」,条款须在条款书里存在);业务组 NS-COMMON-0002 另有约束臂:specRefs 名字必须是存在的规范。锁步机制总述见 §五。
真相源引用完整性(part1 治理):真相源集(宪法/rules/arch/harness-eng)禁引易逝 plan(x-governance NS-COMMON-0004 方向闸,glob 元描述豁免;射程含架构页 .html);ADR 编号唯一由 x-governance NS-COMMON-0005 锁;plan 长期结论固化进 arch/ 或本文档,backlog 转 MEMORY。
生命周期:一条需求从提出走到环收尾,以项目架构的状态机为准(设计页 .claude/arch/project/ARCH.html;十态与启动、收尾见上「项目架构环的十态与启动、收尾」)—— 立项与计划、签字一、实施、封版、独立复盘、三查与验收完结(签字二)、发布、清理归档,六个阶段的关口各卡一处;本节不另画一条。业务需求在「实施到封版」这一段里碰架构层的次序照旧:查 arch(有则读+增量、与 specRefs 系统架构一致;无则登记新建)→ 实施(Data 永远第一)→ VERIFY(增量检测内置的版本契约一段当轮报出改了哪个域的代码)→ ARCH-SYNC 收尾硬步(spawn x-architect:回看设计 + 更新正文 + 在同级变更历史最上面加新的一版并升版、标题下写「为了:<短名>」那一行 + 用 arch/seal.js 封版;触及已建档域跳过=生命周期未闭环禁入 DEPLOY,x-feature-dev 已接线);封版之后是独立复盘与验收完结,验收完结之后才交运维经理发布、清理归档(plan 整份搬进归档、不删,§八「清理归档」)。实施之后到开出验收区的机器节点可由接力命令一条走完(§八「接力命令」)。业务 arch 内容更新留 /x-feature-dev 收尾;x-arch 治理机器变更走 /x-meta-dev。
诚实上限:机械能强制 arch 文档"被改/被重看",强制不了"设计对不对"——语义正确性只有人评审能判,是三层模型不可消除天花板。
十五、agent 架构的内容:执行工件类(受治工件类 · x-agent 治理规范)与角色
动机:官方实证 Workflow(JS)只能编排 subagent、Skill 不能干净调 Skill,而 subagent 可调 Skill——agent 是"工作流触达 skill"的唯一干净适配器,也是第三方 skill(web-design-engineer 等)进入编排体系的唯一合法入口。agent(.claude/agents/*.md subagent 身份文件)是一类受治文件(执行工件类)。
定位(非 L6):六层是控制海拔(L0 法→L4 传感器,L5 代码是被治材料在最底),"L6 在代码之下"语义倒置(等于代码控制 agent)。agent 是纵贯多层的执行者:被 L2 编排、读 L3 规则、受 L4 拦截、产 L5 代码——是工件类不是层。它扩的是工件类、不是层号(同 ADR-09 arch/ 先例)。
它的设计住哪、归哪个单元(ADR-101):agent 架构是宪法 §三 说的一类架构 —— 五类架构是自上而下的五层,它是第四层,答「谁来做」(ADR-105),讲清有哪些执行体、谁派谁、怎么组队、受谁管 —— 设计页 .claude/arch/agent/ARCH.html(§十四),版本单元 agent:overview(§十三 单元表);执行工件是它的内容,像业务代码之于业务架构:设计页描述它们,执行体文件随这个单元定版,不归整个 HARNESS(§十三「执行体文件换了单元」)。「架构的一类」说的是它是五层里的一层;agent 仍是纵贯多层的执行者,不是六层里的一层、不占层号 —— 上面否决「L6」的理由照样成立。本节往下讲的治理规范、角色表、派工与交接是机制;有哪些执行体、每一位的分工、队形与场景只写在 agent 架构设计页,本文不抄。
受治文件类:Harness架构 = 本文档;系统四件套 = arch/system + rules + spec + guard;业务架构 = arch/business;项目架构 = arch/project(§十四);agent 架构 = arch/agent(§十四);执行工件 = agents/(本节;agent 架构的内容)。与「五类架构」的区别:宪法 §三 说的五类架构是自上而下的五层 —— 业务架构、系统架构、项目架构、agent 架构、Harness架构,各答一个问题:就是上面的业务架构、系统四件套里的设计件(系统架构,arch/system)、项目架构、agent 架构与Harness架构;系统四件套里的条款、判据、执法与执行工件都不是架构:前三样是照设计立的规矩与把关,执行工件是照着这些干活的执行者 —— 讲它们的那份设计(agent 架构设计页)才是架构,执行体文件自己不是。
x-agent 治理规范(纯 NS,照 x-arch 骨架):
- NS-1 薄 agent 闸:agent 正文禁内联 X-RULE 块/STD 模板片段/规范复述,只准指针引用(去调 skill 遵守之,不抄规则进来)。这是反漂移承重墙——薄 agent 不囤重复真相→skill 改了它不随之过时(漂移构造性根治,同 arch I2 specRefs 防第二真相源)。
- NS-2 死指针存在性闸:frontmatter
skills:绑定的每个 skill 必须真实存在(.claude/skills/{name}/SKILL.md),引用即指纹(镜像 x-governance NS-COMMON-0003)。 - NS-3 第三方登记闸:绑定的非 x- 前缀 skill 必须 ∈ x-thirdparty-skill-rule.md 登记表且非"默认禁用"(gpt-image-2 已卸载,登记行保留、仍标默认禁用,所以绑定照拦);detector 读登记表零硬编码 skill 名。
- NS-4 新能力覆盖认领闸:每个
.claude/skills/*/SKILL.md必须被某 agent 的skills:认领,或在_registry.md豁免白名单显式登记(reason+date,禁整域豁免)——正面答"新 skill 诞生 agent 要同步知道"(镜像 coverage-gate,全量点强制)。 - NS-5 model 只许 inherit(ADR-127):frontmatter
model若写了,只许inherit(跟着派它的会话走)。判据里一个具体型号名都没有:型号与推理档的值只住型号配置(§十五「型号与推理档」),官方出新型号、换模型都不用改判据。能派出去的执行体都写model: inherit(NS-9),这一颗实际咬的主要是只作主会话的那一类写了 inherit 以外的值。只核文件里写的字:平台认不认、实际跑什么型号它核不了。条款在 x-agent 条款书 ARCH-A02。 - NS-6 闭环三行(ADR-75):每份 agent 正文有「闭环」一节,写明写域、输出经谁核、结论记在哪;缺哪一行检测点名哪一行。只判在不在,写域是不是属实归人审,执行体真去写别处由 L4 需求对账拦(守卫收尾时另按这一行里反引号包住的目录点名越出去的那一笔,只点名、不拦,§八「写域点名」)。
- NS-7 名册与文件一一对应(ADR-101;x-agent NS-COMMON-0007):执行体名册的真相源是 agent 架构设计页里的名册表;闸把表里的执行体名与
.claude/agents/下的执行体文件(注册表_registry.md不算)两边互核 —— 名册多一行没有文件、文件多一份没进名册都报,报文写明多出的是哪一边、哪个名字。X大脑是名册里的一行(项目经理、产品经理也是,只作会话用的三位)。只核名字对不对得上:每一位的分工写得对不对归人审(名册里的每一位都有文件)。 - NS-8 注册表与设计页名册一致(ADR-102;x-agent NS-COMMON-0008):注册表里「已建 agent」那张指针表与设计页名册表的名字集合不等就报,报文写明多出的是哪一边、哪几个名字;两份文件任一份读不到、任一张表认不出或一个名字都读不到,同样报(读空不算一致)。只核名字集合:注册表里每一位归哪一类写得对不对,不核。条款在 x-agent 条款书 ARCH-C04。
- NS-9 推理档与型号只写一处(x-agent NS-COMMON-0009;ADR-127:只核写法、不核值):型号与推理档的值只住型号配置(§十五「型号与推理档」),执行体文件里不写值。闸先读设计页名册表里每位执行体的类别(读法同 NS-7,行上另带
data-main-session属性的算「只作主会话」,只认属性在不在、不看值),再判身份文件:名册里没标「只作主会话」的执行体(名册里没有这个名字的也按这一类判),frontmatter 里要有且只有一行model: inherit、不许有任何effort行;标了「只作主会话」的不许写effort,它的model照旧归 NS-5(带标记的有哪几位以设计页名册表为准,判法不变)。设计页读不到、名册表认不出、名册表读空都报,不放行;豁免只认名册上的标记,检测器里没有任何执行体名字。只核文件里写的字:平台实际跑什么型号、什么推理档它核不了;包含面是身份文件、不含设计页,所以只改设计页的那一轮不触发,要等全量检测或下一次改那份身份文件。条款在 x-agent 条款书 ARCH-A05。
角色与六层各归谁(ADR-75、ADR-90、ADR-93、ADR-94、ADR-98、ADR-100、ADR-102、ADR-116):先看谁是谁、各做什么不做什么,再看执行体按层归谁。
| 角色 | 是谁 | 做什么 | 不做什么 |
|---|---|---|---|
| 需求方 | 用户(别处有的叫 BOSS,指同一个人) | 提需求、签字一(需求确认,永远本人签、从不代签);验收完结与开发中途的联调上线的点头按他的代签设置 —— 设成亲签的那一类由他本人来,设成代签的那一类由 X大脑 代他点头,他随时能亲自签(说「全选执行:验收完结 <短名>」照样算,ADR-116);改代签设置、改型号配置、手动开闸(只在急救时用)、叫停与恢复都由他发话,只对主控说;改设置与改型号配置不经立项;他签的「验收完结」那一签同时授权这条需求该发的每一格各发一次与它的提交,不随验收的发布与生产构建另要他的单次授权;钥匙石与代签设置这两个只归他的文件,机器不提交,每次提交点一次名,由他亲手看、亲手提交 | —— |
| 关口 | 这套体系本身(计划、守卫的各道门、三查、封版、验收单;ADR-102)。「项目经理」指的是下面那一位,不是这一面 | 管放行 | 不和用户对话(它对用户说的只有收尾时的提示)、不是执行体 |
| 主控 | 用户平时说话的那个会话,只有一个,即 X大脑(首席产品官,管产品)。由执行体定义「X大脑」启动(ADR-101):在仓根运行 claude --agent x-brain --name X大脑 --model <型号> --effort <推理档>(两个值照型号配置里 X大脑 那一行的有效值:单独设了用它自己的,没设随主控类;整行由型号配置命令的 show 印出、登记主控时也印,那一行是 gpt 时整行另带代理设置;§十五「型号与推理档」),定义在 .claude/agents/x-brain.md;这份定义只作主会话用,不当执行体派出去。这样启动的窗口开场照常收到守卫的开工提示(守卫在岗、宪法照常加载),问它是谁、它自报是 X大脑(这个项目的主控会话),窗口标题是「X大脑」(用户亲手验过)。守卫不核一个窗口是不是这样启动的。「主控」是角色的叫法,X大脑是它的会话名与执行体名;它是交互窗口,不在 agent view 里。开新窗口的例行三步见下「主控怎么交接」 | 管产品,只做七样:① 和用户谈需求,拍板做不做、走哪条流程(先认车道:先由落点认出流程、再按大小定档,见下「先分级、再选路」)、排第几;设计要点由对应的架构师出,它不出设计;② 统管各专项的产品经理:每个专项一位产品经理会话,由项目经理按它定下的短名、类别、档自动发起;③ 弹签字题给用户签(签字一的题里摆「验收谁签」、受保护文件的那句人话和签了之后是当场开工还是排队;题目正文带看板完整路径与「签字」页签)—— 确认可以提前签:设计定了一份就弹一份,不等前一条做完;几条的确认可以合成一道多选题,同一个版本单元上的也行,先记的那份开得了工就当场开工、后面的排队(§八「一题签几条、每道题都核地址」「签字与开工分开」);④ 代签验收:代签设置允许这一类、这条的「验收谁签」也是代签时,先逐条核验收清单、把证据写进看板验收区,再跑受信的代签命令点最后一下,之后向用户报一句(哪一条、凭什么签的、证据在哪);⑤ 代授权发布与联调:同样的条件下把代签记录转给运维经理(不是用户的原话),用户本人授权的仍逐字转他的原话;⑥ 改代签设置与型号配置:只在用户说了固定的话之后跑受信命令(代签设置四句、型号配置每类或每个角色一行,§十五「型号与推理档」),从不自己改;⑦ 提交与转结案报告:环收尾之后跑提交命令(先预览、带 --execute 才做;核什么、提交哪些文件见 §八「提交命令」),提交完项目经理拿结案报告转给它,它原样转用户;命令末尾印出这一次放开了哪些单元、此刻开得了工的是谁,它转给项目经理排下一条的开工。仍要用户定的只剩六类:需求确认与验收(照代签设置)、线上写入的授权、做不做与先后、只有用户能判的(喜好、要表达的意思、要亲眼看过才算数的)、只归用户的设置(型号配置、代签设置、项目设置、手动开闸、提交钥匙石)、花钱的事(加用量、买服务);其余技术取舍 X大脑 听取架构师的结论与理由后直接定、不再转问,定了写进「我替你拿的主意」、当场告知、实施仍签字一(纯技术取舍按最佳最合适;按需读取,用不上的不硬控)。另:不动受治文件的小事(写计划目录、总账、待立项目清单、设计稿,只读分析)直接派一位执行体(派发时带执行类的推理档,§十五「型号与推理档」);各线发现的 Harness 瑕疵走固定通道(下「遇到顶层问题的两种走法」);复盘经理报来的过程复盘发现和完结那句回话列的遗留一起由它逐条定去向、定完交项目经理记(归档之后的后台办,不挡归档;判法同在那一段);在遗留定去向之前、成条与难事的签字题弹出之前、待立项目清单更新之前派复杂化审查官(下「取舍原则与复杂化审查官」);跑整面床、发布两个全仓共用的窗口谁先谁后由它定,验收只排同一处(排法由项目经理出,见下「跑整面床、发布两个全仓共用的窗口」一段;验收完结之后清理归档的先后同此,§八「清理归档」);用户的话只对它说 —— 签字、授权、改设置、叫停与恢复,由它逐字转给该收的会话,转的是用户的原话(登记了主控之后,用户的签字也只认它的窗口:别的会话里的签字说法不记不认,§八「签字记录只认两条路」);独立复盘连着三次不过之后,它请用户到那个产品经理会话里发话(见下「这张表今天靠什么」③) | 不出设计(归两位架构师)、不记会话号、不盯进度(归项目经理);不起草计划正文、不写任何需求的机器镜像(谁最后写它,签「确认」那一刻就被认成办理会话,它一写就丢了核准资格,此后每个过程改动都要用户重签;改「验收谁签」由它通知产品经理去改);不写代码、不跑测试;不亲手做运行面的事 —— 立项排期、起关会话、握手内容、总账、催问、遗留去向台账归项目经理,它过目、拍板;不替关口放行,不替别的会话决定停与走;从不代签签字一(需求确认,同时是受保护文件放行的授权),也不代改代签设置、不替用户提交钥匙石与代签设置、不经命令行跑那两条只给用户用「!」跑的脚本(§十五「要 BOSS 亲手做的事」);只有代签设置与这一条的「验收谁签」都允许时才代签验收、代授权,先核证据再签;没有代签设置兜着的发布,它不替用户授权 —— 用户的授权只对它说,它逐字转给运维经理,转的是用户的原话,不是它自己的话(验收完结这一签的授权同样:亲签的,它弹验收题,题目正文由出题命令生成、写明「这一签同时授权发布与提交」和会发的格,让用户点之前看清,签完把那句话原样转给运维经理;代签的不弹题,它逐条核证据后跑代签命令,把代签记录转给运维经理) |
| 项目经理 | 常驻后台会话,管项目(ADR-116),定义在 .claude/agents/x-project-manager.md;名册里归治理类(流水线运行面)。名字固定叫「项目经理」,由主控起(开新窗口的例行三步发现不在就恢复,新电脑上用发起子动作);靠自己二三十分钟一次的定时巡检保持在线。体系本身那一面叫「关口」,不叫项目经理(上面) | 立项排期:照 X大脑 拍板的档与入口排先后(同一处的并成一条、互不相干的并行、同一处同一时刻只开工一条,下一条先签好排着),记总账与待立项目清单(清单更新之前先拿复杂化审查官的判断)。排开工:照 X大脑 定下的先后,同一单元一条接一条;看见一条排队的需求排到了(排队一览第三段、十态命令查得到)就跑开工命令、叫醒它的产品经理(开工命令打印下一步并经会话之间的消息告诉它开工);提交命令末尾印出放开了哪些单元、此刻开得了工的是谁,X大脑 转来后照着排,不用等下一次巡检。环收尾之后请主控提交:看见一条需求环收尾(十态命令查得到),就请主控跑提交命令;提交完拿结案报告(十态命令带计划名查这条)转 X大脑、记总账一行。起、关会话:用会话命令按 X大脑 定下的短名、类别、档起每个专项的产品经理会话,握手内容由发起命令打印、它照原样经会话之间的消息送出;专项提交之后关掉那位产品经理的会话、删登记册那一行;一条专项验收完结就起一位复盘经理(会话命令带专项名,和发布同时进行、不加等待;几条同时完结时让这一位接着做下一条,都做完、它报完结果之后关掉它、删登记册那一行);档变了(用户签「确认」时改了档)用「改名」子动作照新档改名。跟进度、催超时:每次巡检核登记册对会话列表、核各条需求看板的状态栏、谁过了约好的时刻没回报就叫人;十态命令对在办的需求多打了红旗那一行的,当场报主控(§八「过程复盘的耗时表与红旗」);不带计划名的十态清单里挂着「后台还在办」的,照着催 —— 催复盘经理写结论、提醒主控定去向(§八「后台收尾」);列表里 state=blocked 的会话报主控;单个会话掉了由它的巡检拉(整批死机后由主控跑恢复,它自己也在被拉回的名单里)。风险与资源:跑整面床、发布两个窗口怎么排、一次起几位、撞上用量上限先停哪几位再按什么次序重起、静默时段 —— 它出排法,主控拍板。遗留去向台账:验收完结之后把遗留与过程复盘的发现逐条记进去向台账(去向由主控定、先过复杂化审查官,定完交它记;在归档之后的后台办,不挡归档):并进或排进清单的记待立项目清单,各线一览那一行写「N 条:并 a、不立 b」,不立而值得留理由的记总账里按「禁止复杂化」不立的那张表;记完在这条专项复盘记录的末尾补一行「去向:…」(没有遗留也没有发现的写「去向:无」)。写域是计划目录与总账(含主控线的复盘记录目录);巡检的创建时刻落盘记下,每次醒来先列一遍现有的定时任务,满 6 天前删了重建(循环定时任务 7 天到期);巡检的提示词一字不改,取自守卫常量里的巡检固定句(重建时同样):说话钩子遇到它不记、不认作签字,环1 对登记着的会话建的定时任务也只放它,建别的一律拦(§八 环1「定时任务通道」) | 不决策、不签字、不弹题、不出设计、不写代码、不写受治文件、不写任何需求的机器镜像(常驻不是办理会话)、不替关口放行;不和用户说话;不往线上放东西;不提交、不推送(提交只由主控跑提交命令)。这些做没做,机器不核 |
| 产品经理 | 每个专项一位的后台会话,用 --agent x-product-manager 起(ADR-116);定义在 .claude/agents/x-product-manager.md,只作会话用、不当执行体派出去;名字是「需求短名-类别-档」。一个专项一位,从立项到归档端到端负责到底 | 请对应的架构师出设计(业务需求请产品架构师,Harness 流程与规范流程请 Harness架构师)、写计划(把主控判定的「验收谁签」写进计划),在自己的会话里跑立项命令 —— 所以从写第一笔计划起它就是这条需求的办理会话(§八「办理会话」);请架构师审计划合不合设计;报主控请用户签字确认(题由主控弹;确认可以提前签,回话写明是当场开工还是排队,排队的等项目经理跑开工命令叫醒);开了工才带执行体实施与测试(只派得出名册里的:名册外的类型、平台内置的通用类型,守卫写前就拦;该派谁照立项命令按落点单元打印的那份名单)、跑接力命令(增量检测、跑床、同步、封版、固定检查、三查、生成复盘说明一条命令走完,§八「接力命令」)、派独立复盘、复盘入账后再跑同一条命令(三查、开验收区、起草收尾单 —— 收尾单的起草不等验收)、报主控请用户签字验收(或照代签设置由主控代签);验收完结之后申请发布(报主控,由运维经理发)、跑一次接力命令收尾归档(它刷新收尾单、预览清理归档,没人在跑床或建站就归档,归档不了照实说原因;§八「接力命令」),归档做完先结束一轮、再报「没有待办」;复盘记录归复盘经理写(它不写、不替写)、去向归主控定,都在归档之后的后台办(§八「后台收尾」),它不转遗留清单、不等复盘记录、不改收尾单第三栏,会话也不用等后台办完;环收尾之后由主控提交、项目经理关它的会话;自己带 agent(可以组队,见下);改了治理站点的源可以自己建(构建器有锁,不用报主控,§九「谁建站点、什么时候建」);每个回报节点除了发消息,同时把看板的状态栏改成现状(收件的会话停着时消息发不出去、也不补发,看板才是落盘的状态);做到一半遇到顶层问题照下面的两种走法办;独立复盘连续三轮不过时停下手,由主控请用户到这个会话里发话,不自己往下闯 | 不写别的需求的机器镜像;落在同一处(版本单元相同或目录重叠)的两条需求不同时往仓里落 —— 后到的产品经理签了字也只是排队,只做准备(写计划目录、在仓库外面写与测),等项目经理跑开工命令叫醒它才动受治文件,开工要等前一条提交完(§八「签字与开工分开」「同一块排队」);业务需求的产品经理不碰顶层(写前有顶层围栏,§八「顶层围栏」);要用户动手的事(签字、授权)不自己找用户,先报主控;不自己弹签字题;不自己往线上放东西(归运维经理);不提交、不推送(提交只由主控跑提交命令);不替关口放行 |
| 运维经理 | 常驻后台会话,管部署(ADR-116、ADR-94),定义在 .claude/agents/x-ops-deployer.md(加了常驻一段;工具列全,含 ToolSearch 与要用的云端工具);名字固定叫「运维经理」 | 一切线上写入都在它的会话里做(ADR-99)—— 云函数、数据表与数据模型、网关路由、静态站点的发布,线上资源的删除,开发期的联调上线(§六「五类需求各从哪进」)都算;联调上线先跑联调开始、带需求名(ADR-100;脚本通道在发布命令上带需求名与联调两个开关),放行面按那条需求签过字的落点表 —— 要上线的函数与表落在表里才按联调判,没开的一律按正式发布判;联调上线成功由机器自动记进这条需求的「联调」一格,不用手跑(§八「部署门认联调」);照发布技能自己动手,量大派运维发布专家(ADR-102);正式发完把发布段记进需求履历(体系守护的 record-release 动作;它只给已完结的需求记已发布);别的会话要往线上放东西,向主控要窗口,由主控告诉它发什么、为什么;发了或被拦了回给主控,由主控转回要上线的那个会话。每次上线都要授权:用户的授权,或照代签设置由 X大脑 代授权;它认代签记录(凭 X大脑 转来的代签记录,命令里显式带需求名与「代授权」标记,机器只核带标记的这一条路);只认发件名是 X大脑 的跨会话消息当授权或代签中转,别的发件人转来的一律不动手。开工先核云端工具:被发起、叫醒、恢复的第一回合和每次接部署或联调的活之前,加载 mcp__cloudbase__auth 并调一次 status,云端工具不在就用 SendMessage 报 X大脑 并停手(它重启不了自己,由 X大脑 或项目经理停掉再不带参数叫醒);会话命令另核并重开一次,见下「运维经理的云端工具自愈」 | 没有授权不发 —— 用户的授权原话(主控逐字转)或主控转来的代签记录,两样都没有不动手;授权单次有效、不跨轮,这一次发布出了问题立刻回滚算同一次授权。授权在哪说、谁动手(ADR-102、ADR-116):用户的授权只对 X大脑 说,X大脑 逐字转给运维经理;照代签设置由 X大脑 代授权的,凭 X大脑 转来的代签记录;运维经理以转来的原话或代签记录为准、两样都没有不动手,照发布技能自己动手、量大派运维发布专家,机器只核带「代授权」标记的这一条路(用户本人授权的,机器不核)。这一句里 X大脑 就是主控。该发的格的授权就是验收完结那一签:这条需求该发的每一格,授权就是用户对主控签的「验收完结 <短名>」那句话本身(由主控原样转来;验收是代签的,凭代签记录),各发一次,出问题立刻回滚算同一次;同一次发布捎带的其余已完结需求随发布登记翻格,不另要授权;不随验收的发布(重发、每天的站点、静态站点回滚到更早的版本)、生产构建、开发中途的联调另要授权;一条需求验收完结之前不正式发它的云函数与站点(机器核:被在办需求签过字的落点表盖住的发不出去,验收之前要上线只走联调);不改仓里的受治文件(平时它不是办理会话,守卫写前就拦);不提交(提交只由主控跑提交命令,这一签同时授权的提交不归它);不替关口放行 |
| 复盘经理 | 用时起、用完关的后台会话,管过程复盘(验收完结之后复盘这一程,补上 PDCA 里的 A);不常驻,也不是任何需求的办理会话;定义在 .claude/agents/x-retro-manager.md,只作会话用、不当执行体派出去;名字固定叫「复盘经理」。谁起谁关:项目经理看到一条专项验收完结就起它(会话命令带专项名,握手内容写明复盘哪一条),和发布同时进行、不加等待;它报完结果,项目经理关它、删登记册那一行;几条专项同时验收完结时,一位接着做下一条,都做完再关 | 跑耗时表那条只读命令(体系守护的 retro 动作,§八「过程复盘的耗时表与红旗」)出表与红旗;照这条专项的档复盘(小事一句结论、红旗只照实写成发现;成条的事有红旗才深挖;难事一律深挖;细则在它的定义);写结论与发现,只写主控线复盘记录目录里这条专项的过程复盘记录(文件名是需求名加 .md;归档那一步先建好骨架,已在就接着写、不在就自己建;表不抄进去,收尾单里的表由接力命令每次从账本现算、在归档那一刻定格;归档之后读表怎么取,见 §十六「跑床分道并发」里「每次跑床记一行」那一条);做完用会话之间的消息把结论与发现报 X大脑,发现的去向由 X大脑 定(判法只写在下「遇到顶层问题的两种走法」),查出要改框架的经 X大脑 交 Harness架构师出改法,改法不挡归档 | 不定去向(复盘记录末尾的「去向:」一行由项目经理补,它不写)、不派执行体(定义里没有 Agent 工具)、不改复盘记录以外的任何文件、不碰线上、不提交、不签字、不归档、不替关口放行,不写任何需求的机器镜像;独立复盘(判交付对不对)仍只派对抗审查官,两样不混,整套体系的体检仍归体系体检官,它只看这一条专项走过的这一程。它的复盘在归档之后的后台办,不挡归档、提交和下一条开工:结论写没写机器只在十态清单与结案报告里显示(§八「后台收尾」),写得对不对、挖得深不深机器不判 |
| 产品架构师 | 常驻后台会话,管业务(ADR-116);显示名是产品架构师,执行体文件 .claude/agents/x-architect.md 的 id 与文件名不变;也照旧能被临时派 | 拥有整个业务架构(.claude/arch/business/**):业务需求从逻辑链、数据链、功能链出产品设计;审计划合不合设计;实施后回看业务架构有没有同步。做设计的第一条要求写在定义最前面:取舍只问最佳最合适,规模与成本不作为取舍的理由,禁止复杂化。常驻提供设计与审查的连续上下文 | 不是任何需求的办理会话、不写任何需求的机器镜像;受治文件由办理会话(产品经理)派执行体写,它自己只写计划目录(设计稿);不替关口放行 |
| Harness架构师 | 常驻后台会话,管框架(ADR-116);显示名是 Harness架构师,执行体文件 .claude/agents/x-framework-architect.md 的 id 与文件名不变;也照旧能被临时派 | 拥有整个 Harness(宪法、五类架构、L0–L5):Harness 流程与规范流程的需求出设计(规范流程的设计也归它);各条线报上来的 Harness 毛病由它分析、出方案(固定通道见下「遇到顶层问题的两种走法」);审计划合不合设计。第一条要求同产品架构师 | 同产品架构师 |
| agent(执行体) | 主控或产品经理派出去的执行者,按层配齐(下表);主控自己直接派的只限不动受治文件的小事 | 在自己的写域里干具体的活,把结果交回派它的会话 | 不和用户说话、不认签字;不替关口放行 |
要 BOSS 亲手做的事,一律做成一条受信脚本命令,由 BOSS 在 X大脑 窗口以「!」开头粘贴运行;脚本做事并打印结果(先预览、再执行,打印改前改后),X大脑 读输出核对;不让 BOSS 开编辑器、找行号。这类命令只许 BOSS 用「!」跑:守卫拦模型经 Bash 工具跑它们。
要 BOSS 亲手做的事怎么落(ADR-127):命令做的事是代码里登记的闭集,一条命令一件事。现有两条,都在体系守护技能里(core/project-settings.js、core/settings-commit.js,经 harness.js 路由,进脊柱写保护,不接 --root):项目设置改法(--action=project-settings --edit=<改法名>)只登记一种「去掉执行体型号强制」—— 拿掉项目设置里 env 的子代理型号与它的强制开关两个键,做法是按文本删那两个键所在的行、保留文件原有的换行风格与缩进,删完解析一遍,必须只少这两个键、其余键值逐项相同、写前拦截的接线还在,做不到就拒绝、不整份重排;设置提交(--action=settings-commit)提交代码里一处常量名单上的文件 —— 项目设置(钥匙石)与型号配置文件,一份文件一个提交、暂存区里别的东西不带、不推送,代签设置文件不在名单里。两条都先打印预览(改前改后)、--do=apply 才动手,可以用 && 连成一行、BOSS 粘一次。守卫拦模型经 Bash 工具跑这两条(含预览,主控、常驻会话、执行体一律拦,报文写「这条只给 BOSS 在 X大脑 窗口用「!」跑」),「!」不经写前钩子,所以只有 BOSS 跑得了。守不到:用脚本转一道去跑,守卫看不见;两条命令都是闭集,做的正是 BOSS 要的那件事,绕过去也无害;「!」是不是真由 BOSS 敲的机器不核;改完项目设置只管以后读设置的进程、不撤已应用的变量,已在跑的会话与已带着它们的后台作业都不变(会话命令起新作业时洗掉继承来的变量,见「型号与推理档」);代签设置文件的提交不并进来,仍由 BOSS 手敲。命令的用法见体系守护技能说明的 project-settings 与 settings-commit 一节。
提速的八条规矩(ADR-98):一条需求从签字到归档,节点之间由机器接力(§八「接力命令」),要用户动手的地方才停下来等他。下面八条是相应的做法,各写明今天靠机器还是靠纪律。
| # | 规矩 | 今天靠什么 | 细说在哪 |
|---|---|---|---|
| 1 | 设计由对应的架构师出(业务的产品架构师,Harness 流程与规范流程的 Harness架构师),计划由产品经理写 | 纪律(机器不认谁是架构师);机器核的是看板与机器镜像对得上、谁是办理会话 | 上表产品经理一行、下「怎么派工」① |
| 2 | 产品经理从立项起就写机器镜像(立项命令在它自己的会话里跑),所以第一笔计划起它就是办理会话 | 一半机器:签「确认」那一刻守卫核看板与机器镜像对得上,并按「机器镜像是谁写的」认办理会话;认错了跑改派命令,或由主控、项目经理指名改派 | 上表产品经理一行、§八「办理会话」「办理会话改派」 |
| 3 | 立项时告诉用户:起哪几位产品经理、各叫什么、谁先谁后(用户不开窗口,在 agent view 里看) | 纪律 | 下「怎么派工」⓪ |
| 4 | 每个专项一位产品经理,办完归档并提交由项目经理关会话、删登记册那一行 —— 不连办、不清空会话(ADR-116:会话由命令自动发起,冷启动不是负担) | 机器:发起命令挡同一条需求已有活着的产品经理;同一个版本单元上一条提交完下一条才开工(§八「同一块排队」);关会话与删登记册那一行是项目经理的纪律 | 上表产品经理一行、下「常驻会话与会话命令」 |
| 5 | 复盘与收尾单起草并行 —— 起草不等验收:复盘入账之后机器就起草一次,验收完结之后再刷一次 | 两次都是机器起草(接力命令第二段起草一次,完结之后那一段刷新一次、照办理会话写的去向);验收完结之后跑没跑那一次接力命令是纪律 | §八「接力命令」「收尾单与治理站点一格」② |
| 6 | 治理站点谁改谁建 | 不撞车是机器(构建器的锁);建不建是纪律 —— 收尾环只提示不建,发布之前必建 | §九「谁建站点、什么时候建」 |
| 7 | 几条的确认可以一题签,同一个版本单元上的也行(先记的当场开工,后面的排队) | 机器(确认题多选,每条各记一笔、各核各的;验收完结不做多选) | §八「一题签几条、每道题都核地址」 |
| 8 | 验收完结那一签(亲签,或照代签设置代签)同时授权这条需求该发的每一格各发一次与它的提交,出问题立刻回滚算同一次 —— 验收题只在亲签时由主控弹,题目正文由出题命令生成,写明「这一签同时授权发布与提交」和会发的格;代签的主控逐条核证据后跑代签命令、不弹题;亲签的凭主控转来的验收原话,代签的凭代签记录;同一次发布捎带的其余已完结需求不另要授权;不随验收的发布(重发、每天的站点、静态站点回滚到更早的版本)、生产构建、开发中途的联调授权照旧另要单次授权 | 纪律(转来的是不是用户的原话机器不核;机器核的只有带「代授权」标记的那一条路,§八「部署门认联调」⑮);题目正文里的授权句与会发的格由出题命令照发布登记的推格法生成;条款在部署规范 | 下「跑整面床、发布两个全仓共用的窗口」一段里「谁来发布、怎么授权」 |
称呼对应与顶层的范围(名词的定义集中在 §十七「术语表」,这里讲称呼与顶层怎么划):「领队」「主会话」指一个会话里派执行体的那条主线 —— 主控与产品经理在各自的会话里都是领队,本文与守卫代码里的「领队」都是这个意思(「领队只派活、不替关口放行」对两种会话都成立)。顶层指整个 HARNESS、各系统规范域、项目架构、agent 架构这四类版本单元锁住的东西(单元表见 §十三:宪法、本文、决策记录、守卫、检测引擎、工作流与技能、规范与条款、系统架构页、项目架构设计页、agent 架构设计页与执行体文件);业务域与业务总览是业务的,随业务需求线走;守着这四类单元的测试不进锁清单(单元表「测试不算」),跟着被测的部件算顶层(这是派工的口径;机器的顶层围栏只认名册里的文件,测试围不到,§八「顶层围栏」的守不到 ③);其余不在任何单元里的文件(§十三 诚实边界③⑥)按目录认流程:业务各端、官网、x-core、x-test 与业务架构目录走业务流程(x-test 里两个部署门入口除外),别的走 Harness 流程 —— 官网走业务流程的小事那一档,不归任何版本单元、没有封版那一步(全量检测在复盘之前跑一次),不走开发规则书的四端流程;签「确认」那一刻守卫照这个认(§八「认车道」①)。需求分析不设专人:和用户对话的只能是会话的主线,换一个执行体转述只会多丢一层意思。
这张表今天靠什么:一个事件是谁发出的,守卫只分两种 —— 带执行体编号的是 agent,不带的是会话的主线(零件 guard/team.js;agent 之间另按编号与名字分,复盘者还认执行体类型);哪个会话是主控、哪个是产品经理,守卫的各道关口不分;读会话登记册的有四处(ADR-116)—— 签字放行认「登记为这条需求产品经理的会话」(§八 环1「签字放行」),受信的会话命令与代签命令认登记册里的主控与项目经理(身份取自会话环境里的会话号,§十五「常驻会话与会话命令」),说话钩子认签字只认登记册里的主控(§八「签字记录只认两条路」),环1 的定时任务通道认登记着的非主控会话(§八 环1「定时任务通道」);常驻会话在守卫眼里就是普通会话,不是任何需求的办理会话。主控由执行体定义「X大脑」启动(ADR-101),守卫不核窗口是不是用那条命令启动的,「每次开工先开 X大脑」是纪律,机器管到的只有那份定义本身(它是一份执行体文件,过 x-agent 规范的闸,也在名册里)。派执行体那一下守卫另认一样:派出去的类型在不在名册(ADR-102)—— 不在、不写类型、平台内置的通用类型都拦(内置的那几种先于名册判,名册里有同名的一行也拦,ADR-103),只放平台自带的两个工具型;它只核在不在名册、定义文件在不在,不核派得对不对,不经派执行体那个工具起的执行体不过这道闸(§八「派发闸」)。它另认两样(ADR-94):一条需求的办理会话(签「确认」那一刻按「计划的机器镜像是谁写的」记下),与一个文件归不归顶层四类版本单元(问版本契约的名册)—— 一条需求是不是顶层的,就看它的落点表列没列这四类单元;各道关口仍然不认谁是主控(登记册只在上面说的四处用)。所以:① 主控不办实施、专项的活交给产品经理与 agent,靠纪律;看得见的只有三查结果单「谁写的」一栏 —— 它只读这条需求的办理会话的写证据:这条需求改过的文件里,有哪个此刻的内容出自执行体的编辑工具(或有两个执行体都写过的)才出现,列的是领队与各执行体名下各几个文件(只列不拦;执行体写过又被领队重写或删掉的不算在它名下);执行体越没越出写域,这张单子不判(单子上只有各自的个数与共写的文件、看不出越没越界,§八「组队与执行体」);收尾环另点名一次、不拦(§八「写域点名」)。② 业务需求的产品经理不碰顶层,写前有机器拦:要写的文件归整个框架、某个系统规范域、项目架构或 agent 架构时,写的会话必须是某条在办或签字作废、落点表列有该单元的需求的办理会话,否则写前拦下并告诉它找主控立项(§八「顶层围栏」)。拦不到的照实说 —— 脚本进程内的写;命令行直写里目标带变量、通配或反引号的(读代码读出来的,没有实测);开闸期间的写;不归任何单元的受治文件(最重的两样是钩子接线文件、守卫与技能目录下的测试,另有部署门登记表、治理站点源码、官网);办理会话认错的时候。机器不核一条列着顶层单元的计划是不是经主控立项而来 —— 业务的会话自己起草一条列着顶层单元的计划、用户签了确认,它就写得动,「顶层的需求由主控立项」仍是纪律。围栏之外另有一道(ADR-98):有在办需求时,不是任何在办需求的办理会话的会话,写受治文件、跑白名单之外的命令写前就拦(§八「写前按办理会话判」)。文件在不在落点表的格里写前仍不问,写后提醒才说;收尾对账只认本会话办理的需求范围 —— 范围外的拦一次,写进别的会话在办范围里的点名一次(收尾里的版本契约照常查这些文件,治理站点新鲜度只提示;都不分主控与产品经理)。对谁都拦的是写保护名单上的那些(守卫整棵、钩子接线、检测引擎、封版命令、各单元锁清单、执行体定义、测试运行器、发布出口等,全名单在 guard/command-policy.js 的 isProtectedWriteTarget —— 脊柱、检测引擎、保护区、生成物、发布档案直接拦,业务源码的裸写另拦(§八 环1);写前拦截在岗时),与是不是主控无关(其中脊柱与检测引擎承牙这两类对签过字的办理会话放行它签过的文件,§八 环1「签字放行」,别的会话、别的文件照拦);宪法、本文、决策记录、规范与条款、架构页都不在名单里(这几样归上面的顶层围栏管:不是对谁都拦,是只放办它的会话)。③ 两次签字在哪个会话签:交给另一个会话办的需求,需求确认与验收完结两次都在主控签(ADR-94)—— 题由主控弹,用户不用去别的窗口(每条需求都由产品经理会话办,用户从不进那些会话,除非独立复盘连着三轮不过、要他到那个会话里发话);验收完结按代签设置也可以由主控跑代签命令代签(下「签字机制:两条路」)。几条的确认可以合成一道多选题,同一个版本单元上的也行(守卫逐条各记一笔、各核各的档与上限、各判各的开不开得了工,§八「一题签几条、每道题都核地址」)。签字记录只认两条路 —— 用户在当场那个会话里说的话(会话之间转发的话不算用户说的),和代签命令记的代签;账按办理会话记:签「确认」那一笔记下办理会话,三查核对命令、验收那一刻当场重算的三查、封版前的需求对账、签字作废期间认谁的范围、越界点名记到谁账上,五处都按办理会话算、不按当场是哪个会话算(§八「办理会话」)—— 所以两次签字都不用请用户去办这条需求的会话。核对命令谁跑结果都一样:签过字的计划它一律按办理会话算,主控跑、产品经理跑、带不带会话号,出的是同一张单子、同一个编号(传进来的会话号只在一次都没签过字时兜底;不带计划名时几份计划各按各的办理会话)—— 主控弹题之前被守卫拦下「签字区不是最新的」时,自己带着计划名重跑一次即可。主控不用自己去读也看得见大概:用户每说一句话,守卫在「正在办」那一行把每条在办需求走到哪列给当场的会话,读的是落盘的那张结果单、不重算,行里带着它是几点算的(§八「每次回话列进度」)。仍然靠纪律的:「签字题由主控弹」没有机器拦(机器核的是签字题只能由领队弹,而产品经理在自己的会话里也是领队);签字发生在哪个会话,登记了主控时机器核、只认主控窗口里说的(§八「签字记录只认两条路」),登记册读不出来、没登记主控时不核,产品经理会话里照旧签得成;办理会话会认错(别的会话顺手改了机器镜像就认成它,§八「办理会话」的守不到 ①),主控签完要拿回话里的办理会话对会话登记册里这条需求的产品经理;认错了由真正办理的会话跑一次改派命令,或由主控、项目经理指名改派;独立复盘连着三次不过之后的那一次发话仍只认派复盘的那个会话 —— 派复盘的就是产品经理会话,所以产品经理停下手,由主控请用户到那个会话里发话,再由它派(机器不把派复盘绑在办理会话上,三查取复盘记录也不按会话筛);主控记签字的同一刻,产品经理别往账上落笔(报完请签字就停手等回话)。
执行体按层配齐。名册的真相源是 agent 架构设计页的名册表;注册表 .claude/agents/_registry.md 是与它对着的指针表(两张表之间有闸,NS-8):
| 层 | 原件 | 归谁 |
|---|---|---|
| L0 宪法 · 架构详图 · 决策记录 · 工作流说明与参考文档 | Harness架构的设计 | Harness架构师 |
| 项目架构设计页(ADR-99) | 流水线自己的设计(.claude/arch/project/** 里的设计页;需求履历只由钩子与发布登记写) | Harness架构师 |
| 项目架构的运行面(ADR-102) | 流水线跑起来的那些事:立项排期、起关专项的会话、握手内容、回报与催问的账、遗留去向台账(立项命令与验收完结之后的收尾归档由产品经理在自己的会话里跑);账都在计划目录与总账里,不是受治文件 | 项目经理(常驻会话;不签字、不弹题、不写代码、不替关口放行) |
| agent 架构设计页(ADR-101) | 执行体这一侧的设计(.claude/arch/agent/** 里的设计页与变更历史的说明;它的内容 —— 执行体文件 —— 归下面的元治理专家) | Harness架构师 |
| 设计页里的图与预览稿(ADR-102) | 给用户看的图、预览稿与走查清单(两张设计页里只改图,不改正文) | 视觉设计师 |
| L1 元治理(规范 / 规则 / 系统四件套 / 执行体文件) | 判据、条款、架构页与系统架构公共部件;执行体文件与注册表;没配对规范的规则书 | 元治理专家 |
| L2 工作流脚本与技能资产 · L3 检测引擎 · L4 守卫 | 框架实现(技能资产含计划模板与端壳模板;另有项目设置里的钩子接线) | 体系工程师 |
| 治理站点的源码与构建器 · 官网(ADR-102) | 两个站点(不归任何版本单元) | 站点工程师 |
| L3 两个裁判 | 检测与测试床的运行 | 机器:接力命令、执行体停下那道关、收尾环、封版命令、部署门(不设专人) |
| L3 测试 | 把用例落成测试床、验床咬不咬得住 | 测试工程师(只写测试,不写被测代码);各位工程师改了被测代码,守着它的测试自己同批改 |
| L5 四端与内核母本 | 业务代码 | 数据表专家 · 云函数专家(含服务端内核母本、骨架模板与内核的装配、闭包工具) · 后台前端专家(含后台参考文档) · 小程序前端专家(含移动端母本、各 backend、移动端装配器与小程序参考文档;端壳与生成物不手改) · 支付专家(只写支付网关与支付对账定时器两个函数目录) |
| 业务架构 | 域设计 | 产品架构师 |
| 独立复盘 · 体检 | 找毛病(只读) | 对抗审查官(一条需求的复盘) · 体系体检官(整套体系的体检) |
| 过程复盘 | 验收完结之后看这一程时间花在哪、哪里卡、哪里反复,写结论与发现(耗时表与红旗由机器出;只写主控线复盘记录目录里这条专项的复盘记录) | 复盘经理(用时起、用完关的会话,只作会话用;不定去向、不派执行体、不碰线上) |
| 取舍与复杂化(ADR-116) | 待立项目进门前分诊、成条与难事的计划签字前做减法审、待立项目清单更新前瘦身(只读,只出判断) | 复杂化审查官 |
| 查证与调研(ADR-102) | 先查清再定的事(只读) | 调研员 |
| 发布与下线 | 线上写入 | 运维经理照发布技能自己动手;量大时派运维发布专家(发布、网关路由、线上资源的删除,都在运维经理的会话里、授权之后做 —— 用户的单次授权,或照代签设置由 X大脑 代授权) · 模块下线专家(只出清单、只删仓内文件,线上删除移交运维经理) |
四块写域的归属(ADR-99;没有执行体认领,主控派活时只能超出执行体自己写明的写域):① 项目架构设计页 .claude/arch/project/** 归Harness架构师 —— 其中需求履历 requirements/** 不在内,只由钩子与发布登记写(锁清单也不在内,只由封版命令写;他写的是设计页的字与变更历史的说明);② 系统架构的公共部件 .claude/arch/standards/** 与 .claude/arch/assets/** 归元治理专家(它们算在 x-arch 那个规范域里);③ 自研技能的 references/** 归Harness架构师(检测引擎技能下的判据不在内,那是元治理专家的),assets/**(含计划模板与端壳模板)归体系工程师;④ 移动端的 x-core/mobile/backends/** 与装配器 x-core/tools/mobile.js 归小程序前端专家,x-core/tools/manifest.js 与 x-core/tools/closure.js 归云函数专家。各执行体文件「闭环」一节的写域一行照此写。另加一块(ADR-101):agent 架构的设计页 .claude/arch/agent/** 归Harness架构师;执行体文件 .claude/agents/*.md 归元治理专家(它们在 agent 架构的单元里)。再加(ADR-102):治理站点的源码与构建器、官网归站点工程师;设计页里的图与预览稿归视觉设计师;移动端内核、网页版运行时、服务端内核不单设执行体,那几块写域在小程序前端专家与云函数专家名下。各执行体文件「写域」一行里的目录一律用反引号包住。今天靠什么:检测只判写域那一行在不在(NS-6),写得属不属实归人审。执行体真去写别处:拦它的是需求对账(文件在不在这条需求的范围里)与顶层围栏,不是写域那一行;收尾环另说一句 —— 执行体用编辑工具写到了它那一行反引号包住的目录之外,点名那一笔、不拦(命令行与脚本写的看不见;判法见 §八「写域点名」)。
遇到顶层问题的两种走法(ADR-90;宪法 §五):产品经理做到一半发现顶层有问题,不看问题大小,只问一句 —— 继续做,会不会让手上的需求做错或做不下去。会,是红灯:发现的会话当场自己停,把问题记进自己计划「决策与遗留」页签的「欠下的」一栏(一条一行),告诉主控;顶层先修(另一条小需求,由主控立项、交给一位产品经理办到验收完结);修完由用户发话恢复,接着做。不会(别扭但能照规矩做对),是黄灯:记一笔、不停,手上的做完、封到这一小步,顶层的修排到后面。红灯的例子:守卫把一笔正当的写入错拦了、检测误报、流水线某一步走不通;黄灯的例子:文档没写清、要多跑一条命令、提示看不懂但照着能过去。停与走不由主控替别的会话定:发现的会话自己停,暂停与恢复由用户发话 —— 放行权归体系,不归任何一个会话(与「领队不替关口放行」同一条)。今天靠什么:全靠纪律,没有机器在拦。守卫里没有「暂停」这个状态 —— 一条被叫停的线接着写,写前拦截照放(它不认暂停:问的是本会话是不是某条在办需求的办理会话,对顶层文件另问是不是办着列有该单元的需求 —— 被叫停的线自己正是办理会话,照放;§八 需求对账「守不到之处」「顶层围栏」);谁叫的停、恢复了没有,机器不认:用户的话逐字记进需求账本(带会话号与时刻),但不认成暂停或恢复、也不挂到哪条需求上;会话之间转发的话不记成用户原话。「记一笔」(红灯黄灯都一样)写在计划「决策与遗留」页签的「欠下的」一栏,一条一行。验收完结那一刻钩子把这一栏与复盘者写的遗留逐条写进需求履历的「遗留」一栏(ADR-93)—— 计划搬进归档之后它还在,完结那句回话里逐条列一次、交主控定去向(§八「履历多两栏」)。仍然没有机器核的是去向:哪一条后来立成了哪条需求、哪一条搁置了,机器不记;写在「欠下的」一栏之外的、只在对话里说过的进不了履历;没有在办需求的会话发现的问题没有登记口。长期的结论照旧固化进本文(「守不到」「记洞不改」)或变更历史的「守不到」,待办转进备忘(宪法 §六.5 的两条去向)。各线发现的 Harness 瑕疵走固定通道(ADR-116;红灯黄灯一样):报主控,主控交 Harness架构师分析、出方案,方案先过复杂化审查官的判断,再由主控拿给用户定,定了要修的才立项。这条通道今天全靠纪律,机器不核。过程复盘的发现走同一个口径(ADR-120):每个专项验收完结之后,复盘经理把这一程的结论与发现报 X大脑(它怎么做、做多深见它的定义;表与红旗见 §八「过程复盘的耗时表与红旗」)。发现不直接定去向,先过一次减法审:X大脑 把发现和这条专项本来的遗留一起交复杂化审查官,只过这一次,就是「遗留定去向之前」那个时点 —— 它只砍不必要的(用不上、极少发生、不做也没有风险),不拿规模、工作量、成本当理由,所以被写大、写复杂的发现在这里收回原样(下「取舍原则与复杂化审查官」)。再由 X大脑 逐条定去向,只有三种:下一步开工前插一条优化(立成一条需求,先认车道,排在项目经理排好的下一条开工之前)、排进清单(写进待立项目清单,只写名字、不引计划路径)、不立。插队只认两种:红灯(接下来几步照现在这样做会做错,或做不下去);提速(做了立刻让后面所有项目都提速的,像测试优化)。其余 —— 别扭但能照规矩做对的、文档小错、单条流程的小改进、新功能 —— 一律排进清单、不插队(像黄灯,记一笔、修排到后面);连清单都够不上的不立。红灯里有三种按下面「刹车规矩」办:被平台的安全检查拦下、同样的失败连着两次、修法要改自己占着的判定代码或守卫。发现里要改框架的,走上面那条固定通道(X大脑 交 Harness架构师分析、出方案,先过复杂化审查官,再由用户定),改法不挡这条专项归档。去向在归档之后的后台办,不挡这条专项的归档、提交和下一条开工,遗留的去向同此办:X大脑 定完交项目经理,并进或排进清单的记待立项目清单、各线一览那一行写「N 条:并 a、不立 b」,不立而值得留理由的记总账里按「禁止复杂化」不立的那张表,记完在复盘记录末尾补一行「去向:…」(没有遗留也没有发现的写「去向:无」);收尾单第三栏的去向默认写「后台办理中」,不回头改(§八「后台收尾」)。在办的专项,十态命令多打的红旗那一行(§八「过程复盘的耗时表与红旗」)项目经理见到当场报 X大脑,也照这个口径定。过程复盘这一条今天靠什么:全靠纪律 —— 减法审过没过、去向定得对不对机器不核;机器只看复盘记录里「结论:」与「去向:」两行写了没有,显示在十态清单和结案报告里,不挡任何事(§八「后台收尾」)。
刹车规矩(宪法 §六.10 只写定性,怎么认、怎么停、怎么报、怎么接着办写在这里):什么算被平台的安全检查拦下:工具调用没有执行,返回里写明是平台的安全检查拒绝。守卫(环1、需求对账、部署门这些我们自己的关口)的拦不算 —— 它的报文写明是哪一道、怎么改,照报文改一次写法再跑;命令自己的退出码也不算。拿不准按拦下处理,连原话报上去让 X大脑 判。停:被拦的动作,和对同一目标的别的写法(换命令、换路径、改写成脚本、拆成几步),都不再试;不换会话、不换型号去做同一件事;手上不相干的事照常做。报:一条消息写清哪条需求、哪个动作、被拦的原话、已经试过几次、手上还有什么没做完;有看板的会话(产品经理)同时把看板状态栏改成「停手等回话:被平台安全检查拦下(动作一句话)」;派出去的执行体把这些写进交回的报告,由领队转报 X大脑;X大脑 自己遇到就告诉用户。被拦下、同样的失败连着两次、修法要改自己占着的判定代码或守卫,这三样都算红灯(上「遇到顶层问题的两种走法」),已含在下「怎么派工」③ 里「任何时候的红灯与黄灯」的红灯里,不另列。同样的失败连着两次:不分是不是平台拦的(命令报错、关口拒绝、工具出错都算),第二次失败就停、上报,不试第三种写法。修法要改自己占着的判定代码或守卫(这条需求的落点占着它,或这一步要把它加进落点;判定代码指下「跨流程的五条规矩」⑤ 里列的那几类):当场报 X大脑,带两个选项 —— 并进本条重签(把这个文件加进本条需求的落点、请用户重签)、急救开闸(只在急救时、只归用户;永不放行名单里的文件〔各本账、各单元的锁清单、项目设置、代签设置之类〕只有这一个);不先自己绕,不用脚本绕过写保护、不换路径写、不换会话写。要靠诀窍才过得去的机器关口:记下诀窍的同时,按「各线发现的 Harness 瑕疵走固定通道」那一条报一条框架毛病(报 X大脑,由 Harness架构师判修不修,后面照那条通道走);只记诀窍不报,下一个会话还得再摸一遍。被拦过的会话不再叫醒:它的上下文里还挂着被拦的那一步,一醒就接着撞。项目经理巡检看到看板状态栏写着「停手等回话」同样不叫醒、不重发握手,先看 X大脑 回了没有。X大脑 定了接着办:项目经理先用会话命令的 rm 把被拦的那位停掉删掉,按原短名、类别、档起新的产品经理会话,再用指名改派(--to,主控和项目经理跑得了;完整小写号读会话登记册、命令打印的是短号;体系守护技能说明 handoff 一节)把办理会话交给它,办完报 X大脑;新会话从计划看板和账本接手;照原样送出握手之后,另加一句写明新会话不碰被拦的那段内容(不读、不生成、不看旧对话记录),也不把那段内容转进它的消息或握手。「不换会话」管的是被拦的会话自己不去别的会话重试同一步,不拦这条上报之后由 X大脑 定的接手。机器之间传大段内容,传位置加指纹,不让模型复述:要交给另一个会话或执行体的大段内容,给文件位置(与指纹),不叫模型整段抄。今天靠什么:字在宪法和每份执行体定义「禁区」里统一的「通则」一行,另有一张床核这些字在场;行为靠纪律。守不到:① 平台的安全检查拦下这件事守卫看不见 —— 钩子接线里没有接这类事件,接线文件只有用户亲手改,所以「拦一次就停」靠上面两处同一句话,机器只核字在场;② 「同样的失败连着两次」只有守卫自己的拦有拦截留痕可数,命令退出码、工具报错没有统一出口,不数;③ 「诀窍」是语义,机器认不出,只管「报」的出口;④ 压缩与叫醒之后「我刚被拦过」这个状态只靠看板状态栏和巡检不叫醒,会话自己不写状态栏就丢;⑤ 办理会话占着判定代码时可以用脚本绕过写保护(既有边界),「不绕」靠规矩;⑥ 「不再叫醒」,和接手时握手之后另加的那一句(写明不碰被拦的内容)写没写,靠项目经理与 X大脑 的纪律,会话命令不看被叫醒的会话是不是被拦过、也不核另加了什么;会话命令的恢复(recover --execute)会把停着的会话拉回来,同样不看它是不是被拦过,也靠纪律;⑦ 字在场不等于照做。记录这一类(下「记录分几类、放哪」)的守不到也写在这里:⑧ 「不写来历」的检测只认几种字面写法(公历日期、版本号注记、带时点的月日与几个讲经过的固定词),讲经过却不带这些字的句子它认不出,靠独立复盘对着标准核;⑨ 过程文件放没放对地方、设计稿有没有放进耐久处,机器不核,放进系统临时目录的设计稿被清掉,要到引用它的计划或清单找不到文件才发现;⑩ 草稿什么时候变成被计划或清单引用的设计稿(被引用的那一刻)是语义,机器不判;⑪ 主控线目录里不再被引用的设计稿没有会话清得掉(守卫把那里的文件当没签字的计划护着),能放计划目录的放计划目录、随计划归档;⑫ 心得写没写进报告、有没有人自己写记忆,机器不核;⑬ 判定代码按不按日志的内容判,机器不核,靠写法规矩与复盘。
记录分几类、放哪(宪法 §六.11 只写定性):记录只留将来溯源、复盘用得上的,能不写就不写。记录分状态与日志两类,工作区地图给每个记录路径标出类别(属性「记录」,§十八),一个路径只属于一类:① 状态:判定代码按内容判的那一份,只写现在、能小就小;② 日志:只供复查,只追加或封死,住日志区(子目录或 .log),和状态分路径存。到时点挪进日志区的两样:需求账本在提交并推送成功之后进 requirements/done/;会话台账在会话结束且写过的都已提交之后进 ledger/ended/。判定代码不按日志内容判:判定代码读日志的地方只有写者、完整性核对、写保护与跳过、当场用法四种;床不把记录盖进上游、不读真仓的日志(§十六)。写法规矩:说明书、注释、规则书都只写当前,来历只进变更历史、决策记录、需求履历、发布记录与提交;真相源(宪法、本文、规则书、设计页、技能说明、执行体定义)不引计划路径。记录之外的东西放哪:计划与账(看板、机器镜像、收尾单)随计划走、完结归档;主控线(总账、待立项目清单、记忆索引、复盘记录,位置见项目架构设计页「换主控怎么交接」)只放要留的,不放过程文件;设计稿(架构师出的设计要点、毛病的分析与方案 —— 只要计划或待立项目清单还引用着它):被计划或清单引用的设计稿不算过程文件,有计划的放计划目录,还没立计划的放主控线的设计目录(主控线目录里放设计稿的 designs 子目录),不放系统临时目录(那里久未访问的文件会被系统的存储感知清掉);过程文件(用完就扔的草稿、探针、中间拼装):放系统临时目录(写字面绝对路径,不用变量)或这条需求自己的施工区,不进计划目录与主控线目录,用完即清,也不叫用户去删 —— 进了那两处的文件不是随手能清的;草稿一旦被计划或清单引用,就按设计稿放,挪进耐久处;要留给复盘看的记录(耗时、前后对比、改坏对照)是例外,写计划目录;被计划引用的备料草稿同样放计划目录,不算过程文件。心得(做事时摸出的诀窍和坑):执行体写进交回的报告,转 X大脑;X大脑 的记忆只记现状与指路,不记来历;要靠诀窍才过的机器关口另报框架毛病(上「刹车规矩」)。今天靠什么:记录路径的类别由地图标;床把没把记录盖进上游由运行器的卫生检查常驻核,床读不读真仓的日志在交付时查一次(§十六);说明书里的来历由「真相源不写来历」那道检测核几种字面写法(认不出的见上「刹车规矩」守不到 ⑧);判定代码不按日志内容判,靠写法规矩与复盘;宪法与每份定义「通则」里的字有一张床核在场;清理归档删过程文件是既有的机器。守不到:写全在上「刹车规矩」一段的「守不到」里(记录类的是 ⑧ 到 ⑬),这里不重复。
先分级、再选路(ADR-93、ADR-105):车道 = 流程 × 档。宪法 §四 按落点分五条流程 —— Harness 流程、规范流程、业务流程三条主流程,运维流程、分析流程两条辅助 —— 每条按大小分三档,一共十五条车道,下表一行一条。每条需求都带着一套固定的手续 —— 一份计划、两次签字、封版、一轮独立复盘、三查全绿、验收,改守卫的还要受保护文件的放行(签字一授权)、把框架面的测试对新内容全跑一遍。把一件事切成八条,这套手续就走八遍;一件小事派三路人审计划、落地前再审一轮、封版后再复盘,审着审着需求自己就长大了(都是真事:一条线被切成过八条;「签字题带地址」从一件事审成过八条标准、十条用例)。所以主控接到一件事先认车道 —— 先由落点认出流程,再按大小定档 —— 手续的轻重跟着车道走;认出的车道与凭什么(落点认出的流程、中了哪几个风险标记、为什么定这一档、要不要高保真)写进计划「设计」页签最顶上的「场景判定」一块,日后复盘照它对,这一块是写计划的人写的,机器不读,也不拿它与自己认的车道比;三条主流程签「确认」那一刻,机器按落点再认一遍流程、按七个风险标记算出最低档、管住改判定代码的同一时刻只开工一条(§八「认车道」),认不对、写低了的签不上;运维与分析两条不签字,认流程靠纪律;种类不同的事套同一条流水线同样冗余缓慢,所以先分流程、流程里再分档。机器规定必须走的只有五样:用户确认、封版、一轮可信的独立复盘、三查全绿、验收(用户签,或照代签设置由主控代签),外加每轮收尾的检测与测试 —— 三条主流程哪一档都不省(宪法 §六.8);运维与分析两条辅助流程不立需求,这五样都不走,一改仓里的文件就回到主流程。其余(配不配图、派几路人审计划、落地前另审不审、要不要仓库外面的副本、单独发不发站点)是习惯,按车道取舍。审查只留两层:架构师审计划合不合设计(自己看机器镜像里的标准、用例、落点三样,难事才派多路;看板与机器镜像对得上 —— 签字那一刻守卫还会再核一遍),封版后的独立复盘。另有一道只做减法的审:成条与难事的计划在签字题弹出之前过复杂化审查官(下「取舍原则与复杂化审查官」),它审的是该不该做这么多、不判设计对不对,不算第三层审查。
| 车道 | 是什么 | 走哪几步 | 跑哪些床 | 复盘 | 谁来做 | 今天靠什么 |
|---|---|---|---|---|---|---|
| Harness 流程 · 小事 | 只改文字:宪法、本文、决策记录、没配对规范的规则书、自研技能的说明与参考文档、项目架构与 agent 架构两张设计页的正文;不碰写保护文件,不碰代码与测试面 | 产品经理写一页计划、用户确认、开工(签字一之后开得了工当场开,开不了排队;开了工才动受治文件)、产品经理派一位执行体改(动受治文件的事再小也交一位产品经理;不动受治文件的小事由 X大脑 直接派一位执行体,不在这条车道里)、增量检测、变更历史加一版并封版、一轮复盘、验收(用户看改后那段字,验收谁签按代签设置与这条计划的那一栏)。同一处上正有一条在办时不单立,搭进下一条当一条标准(它本来也得排队等那一条提交完)。几条的确认可以一题签,同一处的也行(先记的当场开工,后面的排队)。省掉:图、多路核对、仓库外面的副本、单独发站点 | 点名这份文档的那几张床,只补跑不新鲜的(§十六「只跑不新鲜的」) | 一轮 | 产品经理 x-product-manager(办理会话)派 Harness架构师 x-framework-architect 改文字(规则书归元治理专家 x-meta-governor);独立复盘只派对抗审查官 x-adversarial-reviewer | 机器:签「确认」那一刻按落点认流程、按七个风险标记算最低档(写低了签不上)、按档核条数上限;写保护文件只在签字放行内写得进(小事一般不碰)。纪律:X大脑 先认车道、定成小事,产品经理派谁、省掉哪几样 |
| Harness 流程 · 成条的事 | 改机制,设计清楚:守卫一处判法、一条流水线命令、执行体定义、计划模板 —— 落点里有写保护文件;碰到判决依据的归难事 | Harness架构师出设计要点、按文件列分工;产品经理写计划(看板与机器镜像)、签字一之后开工(开得了工当场开,开不了排队)再落地,计划在签字题弹出之前过复杂化审查官的减法审;落在同一批文件上的几块并成一条,几个执行体按文件并行(热点文件只给一个);落点里的受保护文件签字一就是放行的授权,实施时机器对办理会话放行、真仓直改,不做仓库外面的副本;封版、复盘、验收。省掉:多路核对、落地前另派一轮审查(改成领队对着标准逐条过)、图 | 改到的那一面全跑;封框架之前守卫、检测引擎、技能三类框架面对新内容全部新鲜;新床与改过的床做空壳对照(§十六) | 一到两轮 | 产品经理 x-product-manager(办理会话)派:体系工程师 x-harness-engineer(守卫、检测引擎、流水线脚本、技能资产)、测试工程师 x-test-engineer(床)、Harness架构师 x-framework-architect(文字;设计也由它出)、元治理专家 x-meta-governor(执行体文件、没配对规范的规则书);复杂化审查官 x-complexity-reviewer 做签字前的减法审;项目经理 x-project-manager 接运行面;独立复盘只派对抗审查官 | 机器:签「确认」那一刻认流程、算最低档、按档核条数上限,再判开不开得了工(改判定代码同一时刻只开工一条,后到的签得上、记成排队);受保护文件的写只对签字放行内、开了工的办理会话放行;封版前三类框架面新鲜由封版命令核。纪律:X大脑 先认车道 |
| Harness 流程 · 难事 | 改判定口径与流程本身:判决依据(三查、复盘说明、封版命令、发布出口、版本契约)、签字与复盘的规矩、端壳模板、流程本身;设计有取舍,动记账,涉及替签或钱 | 同成条的事,另加:签字之前 Harness架构师派多路只读设计一次,决策记录草稿写进看板、随签字一一起签(不加第三次签字);按批落(受保护文件签字一授权、开工后到时放行);改判定代码的全仓同一时刻只开工一条(下面「跨流程的五条规矩」⑤) | 同成条的事,另加:封版前全量跑一次 | 至多三轮 | 同成条的事;多路只读设计由 Harness架构师 派调研员 x-researcher,签字之前的预审派对抗审查官 | 机器:签「确认」那一刻认流程、算最低档、按档核条数上限(这一档前三样不封顶),再判开不开得了工(改判定代码同一时刻只开工一条)。纪律:X大脑 先认车道 |
| 规范流程 · 小事 | 只改一份系统规范的条款书或系统架构页的文字,判据不动 | 产品经理写一页计划、用户确认、开工(签字一之后开得了工当场开,开不了排队;开了工才动受治文件)、产品经理派元治理专家改(动受治文件的事再小也交一位产品经理);规范同步刷新派生部分;封版、一轮复盘、验收。七个环节走「写得出」「读得到」「守不到的写明」三个 | 本规范的床(判据没动的多半沿用旧记录) | 一轮 | 产品经理 x-product-manager(办理会话)派元治理专家 x-meta-governor;独立复盘只派对抗审查官 | 机器:签「确认」那一刻认流程、算最低档、按档核条数上限;派生部分由内容指纹逼着刷新。纪律:X大脑 先认车道 |
| 规范流程 · 成条的事 | 改一颗或几颗闸的判据:收紧、放宽、修误报漏报 | Harness架构师出设计(规范流程的设计也归它);产品经理写计划、签字一之后开工(开得了工当场开,开不了排队)、带执行体办;七个环节全走 —— 签字之前对全仓跑一遍这份规范、数清会红多少处与落在哪几个域(射得准),会红的三选一处置(不留旧账),每颗改过的闸有床证明真红真绿(咬得住);规范同步、封版、复盘、验收 | 本规范面全过;每颗改过的闸做咬合证明 | 一到两轮(重点看误报与漏报) | 产品经理 x-product-manager(办理会话)派元治理专家 x-meta-governor、测试工程师 x-test-engineer;复杂化审查官 x-complexity-reviewer 做签字前的减法审;独立复盘只派对抗审查官 | 机器:签「确认」那一刻认流程、算最低档、按档核条数上限;规范同步与指纹锁步;检测在停下、收尾、封版、发布四个时刻叫到。纪律:X大脑 先认车道;射得准、不留旧账、咬合证明三个环节(以后单立一条需求上机) |
| 规范流程 · 难事 | 新建或删除一份规范;扩射程;改判定口径。动到检测引擎就并进 Harness 流程(按 Harness 难事走,这份规范照规范流程多走咬得住、射得准、不留旧账三个环节) | 同成条的事,另加:签字之前多路只读设计一次;新建的照模板建齐四件套 | 同成条的事,另加:五条检测命令全跑(自测、验证、扫描、规范校验、覆盖) | 至多三轮 | 同成条的事;多路只读设计由 Harness架构师 派调研员,签字之前的预审派对抗审查官;动到检测引擎加体系工程师 x-harness-engineer | 机器:签「确认」那一刻认流程、算最低档、按档核条数上限。纪律:X大脑 先认车道 |
| 业务流程 · 小事 | 只改展示:文案、样式、布局、多语言文案;官网 | 产品经理写一页业务计划;改界面的,签字之前出要改的那一屏的高保真,用户点过头的那一版放进这条需求自己的 preview 目录(被否的几版留着、名字带第几版,不盖不删),嵌进看板「设计」「签字」两个页签,对着它的标准写明本计划 preview 目录里的文件名与内容指纹;签字一之后开工(开得了工当场开,开不了排队);一位产品经理会话改那一端;增量检测,封版前全量检测一次;封域(官网不归任何版本单元,没有封版这一步)、一轮复盘;用户在本地预览或网页版里看那一屏、验收;要上线的那一端由运维经理发(授权就是验收完结那一签) | 增量检测;改到的代码多半没有床,如实写「没有测试覆盖」;封版前全量检测一次 | 一轮(暂不免:宪法 §六.8 不改,等业务实跑有了数据再议) | 产品经理 x-product-manager(办理会话)派那一端的开发专家一位:后台前端专家 x-admin-engineer、小程序前端专家 x-client-engineer,官网是站点工程师 x-site-engineer;要预览时视觉设计师 x-visual-designer;独立复盘只派对抗审查官 | 机器:签「确认」那一刻认流程、算最低档、按档核条数上限;业务的会话写不进顶层文件(§八「顶层围栏」)。纪律:X大脑 先认车道 |
| 业务流程 · 成条的事 | 一个功能跨几端:表、云函数、后台、小程序(比如用户地址的增改) | 产品架构师出设计要点,产品经理起草计划、产品架构师审计划合不合设计,计划在签字题弹出之前过复杂化审查官的减法审;签字之前附需求清单、字段与接口表;改界面的,签字之前出高保真,用户点过头的那一版放进这条需求自己的 preview 目录(被否的几版留着、名字带第几版,不盖不删),嵌进看板「设计」「签字」两个页签,对着它的标准写明本计划 preview 目录里的文件名与内容指纹;签字一之后开工(开得了工当场开,开不了排队);产品架构师 x-architect(执行体)先在本域变更历史加新的一版;四端次序、数据先行(开发规则书);中途要上线联调的经运维经理、在授权下做(用户的单次授权,或照代签设置由 X大脑 代授权)(§八「部署门认联调」);封域、复盘、验收;每个该发的格各发一次(授权就是验收完结那一签),表在控制台由用户导入 | 本域的函数床与一致性床;新函数补床;封版前全量检测一次 | 一到两轮 | 产品经理 x-product-manager(办理会话)带业务团队按端并行:数据表专家 x-data-engineer、云函数专家 x-server-engineer、后台前端专家 x-admin-engineer、小程序前端专家 x-client-engineer;产品架构师 x-architect(域设计);视觉设计师 x-visual-designer;测试工程师 x-test-engineer;复杂化审查官 x-complexity-reviewer 做签字前的减法审;项目经理 x-project-manager;独立复盘只派对抗审查官 | 机器:签「确认」那一刻认流程、算最低档、按档核条数上限;联调与正式发布由部署门分开判。纪律:X大脑 先认车道 |
| 业务流程 · 难事 | 动钱;权限与身份;已发布表改字段类型(五步破坏性迁移);删功能;母本与内核、云函数骨架模板 | 同成条的事,另加:产品架构师先出域设计;签字之前多路只读设计,写明迁移的备份与回滚办法;删功能由模块下线专家出清单、删仓内文件,线上残留转运维流程 | 全部消费端:改服务端内核跑全部函数床,改移动端母本跑手机端与装配床;动钱跑资损面的床 | 至多三轮 | 同成条的事,另加:动钱加支付专家 x-payment-specialist;删功能加模块下线专家 x-module-terminator | 机器:签「确认」那一刻认流程、算最低档、按档核条数上限;动钱的需求一条自动用例都没有就签不上(§八 需求对账)。纪律:X大脑 先认车道 |
| 运维流程 · 例行 | 重发同一版;每天发一次治理站点;静态站点回滚到更早的版本 | 用户一句授权(对主控说,主控逐字转给运维经理;运维流程不立需求、没有验收签字,不在代签设置之内);运维经理照发布技能动手;发布登记(哪条需求、哪一版、几点上线)。不立需求:没有计划、签字、封版、三查、复盘、清理归档;要改仓里任何一个文件就回到主流程 | 发布出口按被发布物当场真跑,不认旧记录;传上去的就是测过的那一份 | 不复盘 | 运维经理;量大派运维发布专家 x-ops-deployer | 机器:部署门逐个比对全部单元封着且一致、每一版写着为了哪条需求,发布前测试与上传核对。纪律:授权在哪说、谁在发;认流程 |
| 运维流程 · 常规 | 线上数据修正;控制台配置(菜单、角色授权、选项集、云存储);网关路由与证书 | 一张操作单(做什么、事前备份、怎么核对、出事怎么回滚)加用户一句授权;做完记一行、回报 | 照操作单写的办法核 | 不复盘 | 运维经理;运维发布专家 x-ops-deployer;往库里写数据由运维经理自己做,数据表专家 x-data-engineer 出语句与核对清单 | 机器:线上写入照原来的关口判。纪律:操作单写没写、写得全不全;认流程 |
| 运维流程 · 紧急 | 线上出事:站点回滚到上一版,云函数重发上一版 | 用户一句「回滚」;之后按对应主流程立一条修复需求补齐 | 站点回滚由上传档案闸把关;云函数重发上一版照常过部署门 | 回滚本身不复盘;补的修复需求照它的车道复盘 | 运维经理;运维发布专家 x-ops-deployer | 机器:上传档案闸与部署门。纪律:事后补立修复需求;认流程 |
| 分析流程 · 快问 | 一问一答 | 主控自己答;花了力气的结论落进计划目录里的看板 | 不跑 | 不复盘 | 主控(X大脑)自己 | 机器:非办理会话写受治文件,写前就拦。纪律:只读、不签字,要改受治文件就转主流程;认流程 |
| 分析流程 · 分析与体检 | 体检、调研、挑刺 | 派一到四路只读执行体,产出计划目录里的一块看板 | 体检要跑的照跑,只读 | 对抗审查官挑一轮 | 调研员 x-researcher、体系体检官 x-harness-auditor;挑刺派对抗审查官 | 机器:非办理会话写受治文件,写前就拦。纪律:只读、不签字,要改受治文件就转主流程;认流程 |
| 分析流程 · 需求整理 | 大方案、架构复盘(系统架构复盘、业务架构复盘)、业务的新需求 | 并行出稿,产出方案页加一张需求清单,每条写明车道与依据;需求清单进门前先过复杂化审查官的分诊(立、并、不立、问你),主控拿结果和用户定;用户定了才立项 | 不跑 | 对抗审查官挑两轮以内 | 产品架构师 x-architect、视觉设计师 x-visual-designer、调研员 x-researcher 并行出稿;复杂化审查官 x-complexity-reviewer 分诊;各端开发专家只读评估可行性与工作量;挑刺派对抗审查官;项目经理 x-project-manager 排期 | 机器:非办理会话写受治文件,写前就拦。纪律:只读、不签字,用户定了才立项;认流程 |
谁照抄这张表:立项命令把这条车道「走哪几步」那一格照抄进看板「步骤」页签(那一格以「同成条的事,另加」打头的,先接同一流程成条的事那一格),复盘说明照抄这条车道「复盘」那一格 —— 两处都是运行时读本文,由守卫需求零件的 laneCell 认表头逐字是上面那一行的这张表、按「车道」一格(「流程 · 档」)找行、按栏名取格。所以表头、行名与「走哪几步」「复盘」两栏的写法改了,要同批回看 laneCell 与立项命令、复盘说明的床。立项命令只在新建那一刻按给的单元与档填:没给单元、只有 none 或认不出流程的,那一段留方括号占位、照实打印一句;落点后来变了、签字那一刻认出的车道与填的不同,要写计划的人照这张表自己改那一段。
七个风险标记定最低档:签「确认」那一刻由守卫算,看签字那一刻落点表里的目录(落点表里的目录加用例点名的测试,§八「认车道」②)—— ① 有写保护文件 → 至少成条的事(守卫写前直接拦的脊柱文件、检测引擎与保护区三类 —— 守卫、测试运行器、执行体定义、封版命令、各单元锁清单等;单元的变更历史与锁清单、守卫的运行账本与生成物、需求履历不算);② 有判决依据 → 难事(只指五样:三查(核对命令、核准命令与开工命令)、复盘说明、两条封版命令、发布出口 —— 云函数与静态站点两条发布出口、x-test 两个部署门入口、守卫一侧的发布前版本比对与提交命令 —— 与版本契约);③ 有母本、内核、云函数骨架模板或端壳模板 → 难事(算一个标记;母本与内核只算 x-core 的服务端内核、移动端的核心包、工具包与运行时、x-core 工具与根上的共用声明,移动端的业务域包不算;模板指 x-server 的云函数骨架模板与移动端开发技能的端壳模板);④ 版本单元多于两个 → 难事(这一样同时也由签字那一刻的条数上限挡着:小事与成条的事版本单元的上限都是两个);⑤ 动钱 → 难事;⑥ 动权限与身份 → 难事;⑦ 已发布表改字段类型或删功能 → 难事。⑤⑥⑦ 读机器镜像里自报的三栏(money、permission、breaking),机器不对着代码核。写的档可以比最低档高,不能比它低 —— 低了签不上,回话点名中了哪几个标记。通配目录按它此刻展开出的文件逐个判,所以小事的落点要写到文件那一级(写整棵技能目录会盖住三查与测试运行器、被算成难事),none 那一行也写到子目录那一级(写 x-test/** 会盖住两个部署门入口)。两份名单住工作区地图的名册「裁判五样」「判定代码」,守卫需求零件按名册取,本文不抄文件名。
规范流程的七个环节:规范流程的出口不是把规范写出来,是这份规范此刻真的管住了业务代码。① 写得出:四件套(设计、条款、判据、床)一起改,派生部分由脚本刷新、指纹锁步;② 读得到:改哪个目录的文件,管那个目录的条款书就自动带进来;③ 拦得住:判据里嵌着检测器,执行体停下、每轮收尾、封版、发布四个时刻都叫它;④ 守不到的写明:判不了的条款写明没有机器闸与理由,系统架构页写诚实边界 —— 这四个今天就有。⑤ 咬得住:每颗新闸或改过的闸有一张床证明违规样本真红、正确样本真绿;⑥ 射得准:签字之前把这份规范对全仓跑一遍,数清现有代码会红多少处、在哪几个域;⑦ 不留旧账:会红的三选一 —— 顶层文件当场改,业务代码登记成基线、只拦新增,或列成整改清单转业务流程 —— 这三个今天靠纪律,要等以后单立一条需求上机(先要让检测引擎读得了仓外的草稿规范)。
跨流程的五条规矩:① 流程由落点认、不由人选 —— 改守卫的事挑不了轻的车道走;三条主流程签「确认」那一刻由守卫按落点认(§八「认车道」);主控先认车道、运维与分析两条认流程,靠纪律。② 一条需求只走一条流程:Harness 加规范可以同走一条(按 Harness 走,那份规范照规范流程多走咬得住、射得准、不留旧账三个环节);业务不和 Harness、规范混在一条,拆开办(签「确认」那一刻机器核,混在一条签不上、回话写明怎么拆)。③ 规范收紧带出的业务整改不在规范流程里改:规范流程只登记基线或出整改清单,业务代码按域转成业务流程的需求。④ 裁判不降级:改了守卫、检测引擎、测试运行器,封框架之前守卫、检测引擎、技能三类面必须对新内容全部通过(封版命令核);省掉的只是内容没变、已经通过的床不陪着重跑。⑤ 判定代码同一时刻只换一处:落点表里的目录碰到判定代码的需求全仓同一时刻只开工一条 —— 判定代码 = 判决依据五样(三查(核对命令、核准命令与开工命令)、复盘说明、两条封版命令、发布出口〔含提交命令〕、版本契约)加守卫整棵(含它的床与回归套件)、检测引擎(check.js 与 check/ 整棵,不含各规范的判据与床)、测试运行器(bed-runner.js 与 bite/),名单住工作区地图的名册「裁判五样」「判定代码」;开工那一刻机器核,另一条签得上、记成排队、回话点名被谁占着(§八「认车道」③);改执行体、改设计页、改文字的按单元排队,可以和它并行。
每条车道是什么样的事,定义只写在上表「是什么」一栏(宪法只说「每条流程按大小分三档」,项目架构设计页写「见架构详图 §十五」,都不另写一份 —— 几处各写各的,边界就对不上)。三条主流程的三档就是机器镜像里「档」那一栏的三个值(小事、成条的事、难事),三条主流程用同一张上限表;运维、分析两条的档名(例行、常规、紧急;快问、分析与体检、需求整理)不进机器镜像 —— 它们不立需求。每一档标准、用例、版本单元最多几条,办多久、复盘几轮算慢:这些数是守卫里的判据(一张常量表),判法见 §八「定档与上限」「办得超了点名」;数字仍只写在项目架构设计页(签字核的四个数在阶段一,全部在第十节「先分级」一行),这里不抄 —— 设计页上的数与守卫那张常量表一不一致没有机器对拍。小事为什么限在「不碰测试面」:一碰测试面,办它的会话每一轮收尾都会被要求把那一面的测试跑到全过 —— 那已经不是只改文字的小事该有的手续。一个冻结面哪一档都一样(ADR-98;派复盘之前步骤要勾全,那是第一查要的):复盘派出之后到用户验收之间,签字锁住的内容(五样)、范围里的受治文件、签字之后的过程改动(核准记录与待核准清单)别动(复盘与验收单绑着它们,动了这一轮复盘作废、验收单换号);看板的状态列 —— 改状态栏、填固化对照表与发布表、写决策与遗留、补勾步骤 —— 照常动(§八「复盘之后看板的状态列可以动」)。今天靠什么:一半是机器(ADR-94)。机器管的:签「确认」那一刻按落点认流程、按七个风险标记算出最低档(写低了签不上)、碰到判定代码的同一时刻只开工一条(§八「认车道」);档写进计划的机器镜像(没写按小事),签「确认」那一刻按档核四个数 —— 标准、用例、其中要用户亲手验的、版本单元 —— 超了签不上,回话点名超在哪并给两条出路(拆,或改档);签过字之后升档要重签,用户在签字区看得见「改了」(§八「定档与上限」)。办的时间或复盘轮数超了这一档,「正在办」那一行与完结那句回话里点名,只点名不拦(§八「办得超了点名」)。仍然靠纪律的:X大脑 先认车道(那时还没有计划);运维、分析两条不签字,认流程靠纪律;写得比最低档高时该是哪一档(机器不判,超了把档改大就签得上,难事前三样不封顶);两栏自报(动权限与身份、改已发布字段或删功能)机器不对着代码核;签字时不核格里的目录归不归旁边那个单元(写计划的人能借单元名挑流程,业务域封版时版本契约照旧会挡);单条标准写得宽不宽(条数挡不住五件事写进一条);各档走哪几步、派几路人审计划、落地前审不审,机器看不见;验收完结之后跑没跑那一次接力命令机器不催(阶段六的关口挡下一条的签字);冻结面没有机器守(动了的后果是复盘作废、单子变了要重签,事后才报)。
一条需求一次封版收得了口;落在同一处的几件事并成一条(ADR-90、ADR-93):一条需求要一次封版就收得了口(封版之后还有独立复盘与验收,到验收完结才算办完)。怎么切:不是一件小事一条 —— 落在同一批文件上的几件事并成一条(一次封版、一轮复盘),标准第一次就写准、实现细节放进步骤(步骤不在签字锁住的内容里)。两条需求不可能共用一版(每一版的「为了」只认一条需求),所以要并只能在签字之前并;签了字的不再往里并(往里并要动需求那一句话或亲手验的清单,锁住的五样一改签字就作废)。大战线是一串这样的需求。同一处一次只走一条:同一个版本单元上,开工、进仓、封版、复盘、验收完结、提交是一条走完再上下一条;这一条之外的事不用排队、可以提前并行 —— 架构师出设计、产品经理起草计划(看板与机器镜像)、架构师审计划、出预览、只读分析,下一条的确认也可以提前签好、记成排队等着。等的是提交,不是封版或验收:下一条的开工与任何受治文件(含测试)进仓,要等上一条提交完;下一条的确认可以提前签好、记成排队,排着的时候不动受治文件,也不挡上一条的封版与验收(排队的不算在办)。上一条验收那一刻三查要它改到的单元整单元封版之后零改动,下一条一加新的一版、一改单元里的文件它就红;下一条的受治文件落进上一条的范围、或动了上一条改到的单元,上一条用户刚看过的那张就作废(落在上一条范围之外、也不在它改到的单元里的不让编号变);所以下一条要等开工之后才动手。排着的确认锁住的五样改了,签字照旧作废、状态仍是排队、另带「要重签」。固定做法:下一条的计划写好就签、排着,上一条提交完项目经理就开工(落点里有受保护文件的,签字一就是放行的授权,开工后到时放行)。不连办(ADR-116):每个专项一位产品经理会话,办完一条(验收完结、收尾单交出、清理归档跑完、提交完)由项目经理关掉它的会话、删登记册那一行,下一条再起新的 —— 会话由命令自动发起,冷启动不是负担。同一个版本单元上的小事也是一条走完再上下一条;一道确认题可以一题签几条,同一个单元上的也行 —— 先记的那一条当场开工,后面的排队(同一个单元上一次只开工一条,§八「同一块排队」)。能不能多开会话只看两样:两条需求的落点表里版本单元有没有相同的、目录有没有重叠。都没有,各起各的产品经理会话、各封各的版;有,要么并成一条(一个会话里几个 agent 按文件并行),要么一个会话落地、另一个会话只做准备。多开会话帮不了同一处的落地(账按会话记:同一个单元上别的会话没封的改动会让这条需求完结不了),只帮得了准备。这样红灯停线也是停在封好的那一步之后,等待有上限;反过来一条大需求挂着不封:它已经在变更历史最上面加了新的一版时,同一个单元上别的需求一般连封都封不了;还没加时,别的需求封得了自己的改动、却过不了验收;全仓往线上放新内容的发布也一直被版本比对拦着(它自己的开发期联调除外 —— 联调只放过它落点表里的单元施工中;开闸期间直接经 MCP 的那条拦不住,见下一段)。今天靠什么:两头都有机器。签字与开工那一头:一条需求有多大按档核四个数(§八「定档与上限」,签字那一刻核);同一个版本单元上已有别的需求占着(开了工没完结的、完结了还没提交的,签字作废、账本被直接改过、等用户验收的那一段也算),后到的那一条签得上、开不了工,记成排队,谁占着、谁排着有一条只读命令看(§八「同一块排队」)—— 并不并仍由项目经理排、主控拍板,机器只保证不并就得等。封版那一头照旧,而且只管到同一个版本单元:封版只认最上面一版,而且它得是已封那一版的下一步:叠在没封的一版上面的第二版一般因此封不了,只有下面那版升的位更低时这一道拦不住(订正上面叠新增或改写、新增上面叠改写),那时下面那版从此压在已封的历史里封不上;每一版的「为了」要解析到恰好一条签过字的需求;别的会话还没提交的改动不封进这一版(已提交的不分是谁的,一并封进去);落点表列有本单元而签字作废的在办需求,让任何会话都封不了这个单元(签字之后有没经主控核准的过程改动,办理会话动过手的同样挡封版,§八「签字只锁五样、过程由主控核准」;§十三 第 3 关与「为了哪条需求」、§八「两份计划触及同一单元」;签字作废挡封版那一条写在项目架构设计页阶段四「守不到之处」);验收那一刻,这条需求的办理会话改到的单元(没有写证据的改动也算它的;按办理会话算)要整单元封版之后零改动,别的会话在同一个单元上还有没封的改动,这条需求就完结不了(三查第三查)。机器不管的:两条顶层需求落在不同的版本单元时互不排队(这正是可以多开会话的那一种);单元不同而目录重叠的(落点写 none 的)不排队,签字时仍只提示一句范围重叠;排队只挡开工;排着的会话提前往仓里写,多半挡得住 —— 顶层四类单元的文件有围栏(§八「顶层围栏」),别的受治文件有「写前按办理会话判」:排着的会话不是任何在办需求的办理会话,写前就拦。挡不住的只剩一种:它自己正办着另一条在办需求,提前写进这个单元的改动写前照放、收尾点名一次 —— 同一个会话写的会被封进前一条的那一版,别的会话写的会让前一条完结不了,这一种「下一条不提前进仓」仍是纪律;占着单元的那条需求不办了,队放不开 —— 没有「作废一条需求」这句话,只能照现成的删计划那条路放开(§八「同一块排队」的守不到 ②);卡住的那一条没有插队的口;谁和谁能并行,排队那个只读动作的占着、排着两段看得出各占哪些单元,目录重不重叠仍由主控拿两份落点表比;「顶层的需求只由主控立项」没有机器认 —— 这几道关口不认谁是主控,它们认的是办理会话与文件归哪个单元。并不并只看是不是改同一处;互不相干的不并 —— 各立一条、各按自己真实的档走,小事就是小事、难事就是难事(把小事并进难事,小事就替难事扛下全套手续,两样都慢)。
跑整面床、发布两个全仓共用的窗口由主控排;验收只排同一处;开闸只在急救时(ADR-90、ADR-93、ADR-98、ADR-116;受保护文件的放行跟着签字走,见 §八 环1「签字放行」,手动开闸只留作急救):手动开闸只有用户能开,救完提醒关,关闸可以由主控代关(用户授权过),核一眼接线文件再改回。这两样是全仓共用的,一个会话用了,别的会话都受影响;开闸更不分会话(钩子接线全仓一份;开闸期间写前那一道整个不在岗,写保护与部署门的写前拦截都拦不住;设置会热加载,那一刻全部在跑的会话同时失去守卫,所以急救第一步先停掉常驻会话与各位产品经理);发布往线上放的是仓里封过版的那一份,任一个版本单元在施工,新内容就发不出去;跑整面床全仓一把锁。所以这两个窗口谁先谁后由主控排(排法由项目经理出)、并告诉用户;产品经理要用,向主控要窗口,不各自起全量。全仓静默窗口:发布、跑整面床这两个窗口开着的时候,以及单跑站点床的那几分钟,全仓静默(验收那一小段不算,它只排同一处,见下)。除被放行的那一位,仓内任何文件都不写(计划目录、research、总账、待立项目清单、记忆都算,建站和别的命令替你写的也算),也不跑全仓搜索、普查、跑床这类重命令;要备的料(「怎么派工」⑦)和要记的话只写系统临时目录,窗口一结束第一件事再落进仓里。原因:站点床收尾会把取材面在床运行期间的变动判成漂移而红;发布要的是封着的那一份,窗口里有单元进了施工中就发不出去;机器上多一个重命令,池里的床就慢,顶到单张床的超时上限会被杀成红。窗口从被放行的那一位报「命令真起了」才算开始,它报「做完了」、并且那条命令真退出了才算结束;宣布窗口开始、作废或结束之前,先确认跑着的那条命令真的已经起了或停了。被放行的那一位停不了自己起的后台命令时如实报,不换工具绕;命令还在跑,窗口就没有结束,也谈不上作废。今天靠什么:纪律,加项目经理、运维经理定义里的字(一张床核字在场)。守不到:机器不拦窗口里的写和重命令,事后红出来才发现;窗口算没算开始、结束只凭被放行的那一位的报,机器不核;字在场不等于照做。治理站点的构建不是又一个全仓共用的窗口(ADR-98):产物目录也是全仓共用的,但它不用主控排 —— 构建器自己有锁,谁改了源谁就可以建,撞上了后来的等前一个建完(§九「谁建站点、什么时候建」)。验收只排同一处(ADR-98):从核对命令出结果单、开出验收区,到用户签字的这一小段,别的会话改别处不让验收单作废(§八「复盘之后看板的状态列可以动」);会让它作废的只有两样 —— 这条需求范围里的受治文件变了(范围里的改动进编号),它改到的单元有人动了(第三查要整单元封版之后零改动)。所以只排同一处:同一个版本单元、同一批范围上的事在这一小段里让路,别处的照常干;办理会话自己在这几分钟里别写文件(它自己的范围外改动照旧进编号、让第一查红)。发布攒到一段落再发一次:框架、规范、项目架构落盘即生效,没有「发布」这一步,不必每完结一条就单独发一次治理站点(攒着不发,线上的站点会落后于仓里,不影响任何一道关口)。每条需求有一格「治理站点」(ADR-96):站点在这条需求完结之后发过一次、再跑一次发布登记,它才算已发布;没发之前守卫每次回话点名「待发布」—— 仍然可以攒着发,只是不会被忘(§八「收尾单与治理站点一格」)。只有业务域落点、又没有哪一行业务域只改业务设计页的需求(落点表里除了不归任何单元的那几行,单元全是业务域,而且没碰治理站点自己的源码)不带这一格(ADR-100);业务域那一行的目录至少写了一条、而且条条都落在业务架构目录下的(只改业务设计页)不按端推格,有一行这样的,需求就带上这一格,随站点上线就走得到环收尾(ADR-108);数据表与微信原生包在体系之外发(控制台、微信开发者工具),不算进该发的格。谁来发布、怎么授权(ADR-94、ADR-102):往线上放东西只在运维经理的会话里做 —— 一切线上写入都算:云函数、数据表与数据模型、网关路由、静态站点的发布,线上资源的删除(模块下线专家只出清单、只删仓内文件),开发期的联调上线(§六「五类需求各从哪进」)。联调上线有机器认得的口径(ADR-100):运维经理先跑联调开始、带需求名,放行面是那条需求签过字的落点表;没开联调的一律按正式发布判,正式发布由机器核验收完结(§八「部署门认联调」)—— 口径不顶替授权,授权仍是授权的那一句话(用户的话,或照代签设置由 X大脑 转来的代签记录)。授权在哪说、谁动手(ADR-102、ADR-116):用户的授权只对 X大脑 说,X大脑 逐字转给运维经理;照代签设置由 X大脑 代授权的,凭 X大脑 转来的代签记录;运维经理以转来的原话或代签记录为准、两样都没有不动手,照发布技能自己动手、量大派运维发布专家,机器只核带「代授权」标记的这一条路(用户本人授权的,机器不核)。这一句里 X大脑 就是主控;同一个说法还写在 agent 架构设计页「联动与硬控」、项目架构设计页阶段五、发布技能说明顶部、开发规则书开篇与部署规范的条款里。每一次线上写入都要授权:这条需求该发的格,授权就是它验收完结的那一签,每一格各发一次;不随验收的线上写入,授权单次有效、不跨轮;这一次发布出了问题立刻回滚算同一次授权;主控转用户的授权时转的是用户的原话、不是它自己的话;代授权时转的是代签记录(验收谁签是代签、设置此刻也允许这一类,才有这一条路);运维经理动手之前,用户的原话照项目架构设计页里转达的通则到原话账本只读核一遍那一句,核到就办、核不到回主控(这一步是纪律,见下「今天靠什么」);代授权的凭代签记录,命令里显式带需求名与「代授权」标记,机器核。运维经理只认发件名是 X大脑 的跨会话消息当授权或代签中转,别的发件人转来的一律不动手。别的会话要发布向主控要窗口,由主控告诉运维经理发什么、为什么;发了或被拦了,运维经理回给主控,主控转回要上线的那个会话。验收完结那一签就是该发的格与提交的授权(亲签或代签都一样):用户签的「验收完结 <短名>」那句话(也是对主控说的),或照代签设置由 X大脑 代签,同时授权这条需求该发的每一格各发一次与它的提交;亲签的,主控弹验收题,题目正文由出题命令生成,写明「这一签同时授权发布与提交」和会发的格(照发布登记的推格法推,不靠人写),让他点之前看清,不要求他在那句话里另写(一键签的固定句里没有这几个字);代签的不弹题,主控逐条核证据后跑代签命令。签完主控把那句话原样转给运维经理(转的是用户的原话;验收是代签的,转的是代签记录),运维经理凭它把这些格各发一次,不再请用户说第三次。提交不是线上写入,不归运维经理:发完、归档完(环收尾)之后由主控跑提交命令,把这条需求验收过的那一份按项目名提交进版本库、打项目标签、推主干与这个标签(§八「提交命令」);授权同样是这一签,代签的也一样,不另问用户。几条攒着一起发的时候:同一次发布捎带的其余已完结需求,随发布登记翻格,不另要授权。不随验收的发布(重发同一版、每天发一次治理站点、静态站点回滚到更早的版本 —— 都是运维流程,没有验收签字,不在代签设置之内)和开发中途的联调授权,验收那一签管不到,仍要授权:发布要用户说出明确指令(同样对主控说、由主控逐字转),联调另可照代签设置由 X大脑 代授权;生产构建(后台构建、手机网页版装配,宪法 §六.3)不论哪条需求,构建那一下仍要用户的单次显式发话。条款在部署规范。今天靠什么:一半是机器,排先后靠纪律。全量测试有机器:经唯一运行器或部署门入口跑床,每次先拿仓库级的锁,别处在跑就排队等,等到上限仍被占才失败(§十六「仓库级锁、不点名」;带「只跑不新鲜的」开关、选中的床对当前内容都新鲜时一张不起、也不拿锁);直接用 node 单跑一张床,只有床里自己调了持锁函数的才拿;谁先拿到锁,机器不管。发布有机器:每条发布通道往线上放新内容之前做同一个版本比对,任一单元没封、封后改过、施工中一律拦(§十三 第 4 关;各发布入口在这之前先只读查一遍部署门的待检清单,有没复核的停在第一步,§九「发布之前先只读查部署门」;已关掉的会话名下没复核的改动不干等 24 小时(ADR-102)—— 主人会话不在线(本机的会话名册里没有它,或它的进程已经不在)、这个文件此刻的内容曾经查过干净的,任一会话收尾时就按无主替它复核、结论按内容记回,只读查看那一侧用同一个判法、报文写明主人已不在线,会话名册读不了时按 24 小时判(§八 环3 分账 ②);这一比对之前先判联调还是正式发布 —— 正式发布另核验收完结,联调只放过那条需求落点表里的单元施工中,§八「部署门认联调」)—— 所以一条顶层需求在施工,全仓经部署门与发布脚本出口往线上放新内容的正式发布都发不出去(别的需求的联调同样被它拦住:联调只放过自己落点表里的单元),这正是要排窗口的原因(小程序包由用户在微信开发者工具上传,在本体系之外、不经这道比对,§十六 诚实边界㉑);开闸期间经 MCP 的发布写前不拦,写后用写前同一套判法(含这道比对)补判,判出本该拦的记一笔、收尾报红一次(§八 环2),脚本出口的比对照常。授权大多没有机器(代授权那一条路例外,见下「机器核的只有代授权这一条路」):守卫不核用户有没有授权,也不核是哪个会话在发 —— 部署门核的是没复核的改动、这一次是联调还是正式发布、版本比对、发布前测试与上传档案;发布脚本出口谁都跑得起来,脚本里「须用户单次授权」只是提示的字。别的会话跑发布脚本机器不拦,拦它的只有发布前的检测、测试、核验收完结与版本比对;「只在运维经理的会话里发」「没有授权不发」都是纪律。联调的口径同样不认人:联调标记谁都开得了,机器只认它有没有效,不认是不是运维经理开的、授没授权;它记着是哪个会话开的,凭它上线过的会话收尾时被点名一次(只说、不拦)。授权一律由主控转来,转的是不是用户的原话没有机器核:运维经理收到的是主控转来的话(会话之间转发的话机器不记成用户原话),守卫不认它是不是原话。运维经理自己能做的是照转达的通则到原话账本只读核一遍(那里记着用户在主控窗口说的每一句),核到就办、核不到回主控;核没核机器不管。授权那一句里「以转来的原话为准」指的是只认用户的原话、不认转述,也不用用户再去运维经理的会话里说一遍 —— 不是转来什么就办什么。验收完结那一签同理:题目正文里的授权句写没写守卫不认;运维经理自己核得了的是两样 —— 原话账本里有没有那一句,与这条需求确已完结(环的十态查得到,§十四)。机器核的只有代授权这一条路(ADR-116):代授权的发布与联调在命令里显式带需求名与「代授权」标记,部署门与各条发布出口只核带标记的 —— 这条需求的验收是代签、设置此刻仍允许这一类、要发的内容指纹等于验收那一刻的,才放行(§八「部署门认联调」⑮);设置改成亲签之后带标记的被拦,那一类的发布与联调都照旧要用户单次授权 —— 亲签关掉的是代授权这条路,不是门强制用户在场。手动开闸(只在急救时用)的机器只挡顺手的路,保证不了「只有用户开得了」:闸关着时钩子接线文件受脊柱写保护,编辑工具与直写路径的命令改不了它;别的命令写法拦不全(写前拦截只防手滑),脚本进程内写绕得过(与整套体系同一条边界,§十三 诚实边界⑤),平台另有的 PowerShell 工具守卫不处理(§八 需求对账「守不到之处」④);闸开着的时候,每个会话开工被告知并记一笔当时闸的状态、每轮收尾提示一行;接线文件的改动,平台把配置变更事件送到在跑的会话时留一笔。什么时候开、为谁开、开多久,机器不管。验收这一处没有机器排:别的会话在那一小段里写了这条需求范围里或它改到的单元里的受治文件,机器不拦它(它若不是任何在办需求的办理会话,写前就拦了),只在用户签字那一刻照实判成单子变了或三查红了、不记完结(方向是多签一次,不是放过);写在别处的不再让单子变。办理会话自己那几分钟里写没写文件,机器也不拦,同样在签字那一刻照实判。
怎么派工:架构师出设计、项目经理起会话并握手、产品经理按节点回报(ADR-93、ADR-116):取舍的先后是先省 token,再在不多花 token 的前提下吃满电脑资源提速。⓪ 立项时先把会话怎么排告诉用户(ADR-98;会话由项目经理自动发起,用户不开窗口、在 agent view 里看)—— 起哪几位产品经理、各叫什么、谁先谁后,由主控定、一次说清;不把「要不要起、起几个」当问题抛回给用户。① 设计先于派工,计划由产品经理写 —— 成条的事与难事,主控拍板车道与入口之后,由对应的架构师出设计要点(动哪个文件的哪一处、口径是什么、按文件怎么分工):业务需求请产品架构师,Harness 流程与规范流程请 Harness架构师;主控不出设计。产品经理照着设计在自己的会话里跑立项命令、写计划(看板与机器镜像,把主控判定的「验收谁签」写进去),所以从写第一笔计划起它就是办理会话;计划写好后请架构师审合不合设计,成条与难事的计划在签字题弹出之前另过复杂化审查官的减法审(下「取舍原则与复杂化审查官」)。小事产品经理自己写一页计划。一次只派眼下这一条。② 先握手 —— 发起命令只送固定句进新会话;握手内容(先用会话之间的消息给项目经理回一句「已连通」并带上自己的会话编号,收到回执之前别动任何文件,再跑立项命令)由发起命令打印、项目经理照原样经会话之间的消息送出;立项命令打印的派工底稿没有握手一段(只有回报节点、共用资源规矩、执行体名单三段)。没有回执,项目经理自己查(登记册对会话列表)、如实告诉主控,不请用户去那个会话看一眼。③ 按节点回报,同时改看板状态栏 —— 派工里写明到哪些节点要回报,每条一两句:读完(报预计多久送审)、计划送审(机器镜像补好)、要请用户签字之前、已签字、接力命令每一次停下来(红在第几步、为什么;走到了复盘说明;末尾打印可以弹验收题)、复盘派出与结论、验收完结;任何时候的红灯与黄灯、等用户超过十分钟没动静、要偏离已定口径之前。清单只留要主控或用户接手的节点,不是每一步都报。每个回报节点除了发消息,同时把看板的状态栏改成现状:收件的会话停着时消息发不出去、也不补发,看板才是落盘的状态;项目经理的巡检读各条需求看板的状态栏。④ 要用户动手的事先报主控 —— 签字、授权,产品经理先报主控、报完停手等回话,由主控告诉用户做什么;签字题由主控弹(ADR-94):产品经理跑完核对命令(验收题是接力命令末尾打印「可以弹验收题」之后),把题目正文(带看板的完整路径与「签字」页签)报给主控,主控弹题、用户在主控签,签完主控把守卫回的那一行(带着认成的办理会话和当场开工还是排队)转给产品经理,产品经理核一眼「开了工、办理会话是自己」再动手(回话写排队的,等项目经理跑开工命令叫醒它再动手);验收谁签是代签、设置此刻也允许的,主控先逐条核验收清单、把证据写进看板验收区,再跑代签命令,不弹验收题(下「代签设置、验收谁签与代签命令」)。连没连上、走到哪一步由项目经理盯、主控过目,不叫用户去别的会话看。⑤ 产品经理怎么对用户说话(会话在自己窗口里写一句「此刻仍然能签」、又没有对话框,用户会以为被要求签字又找不到选项)—— 用户一般不进产品经理的会话(在 agent view 里看);用户真进来时(独立复盘连着三轮不过,要他到这个会话里发话),产品经理在自己窗口里每次停下来,最后那段话的第一句只许是这两种之一:「现在不需要你做任何事。」或「请你现在做:……(对话框已经弹出)」;别处不写「能签」「请签字」「等你」这类会被读成要他动手的话,机器核过签得了这类状态只报主控、不写给用户看。要用户动手只用对话框(选项),弹之前先报主控,由主控告诉用户去哪、做什么,不用一段文字请他做事。用户不用盯别的窗口:只有主控说「对话框已经弹在某某窗口」时他才过去(签字题不在此列 —— 它弹在主控,见 ④)。主控这一侧:签字题用弹窗(选项);除签字题外不弹窗等回话 —— 弹窗开着,主控整个会话停住,别的会话的消息也接不了。要用户回话的非签字事项用文字问、写成好回的选项,并在主控每一轮回复(包括处理完别的会话消息的那一轮)的最后附一张「待你回话」小卡片:1、2、3 列着,用户回了哪条才拿掉哪条,没有待回的就不附。会话之间的消息只是传话:不进用户的原话记录,也不算用户说的话(§八 需求对账)。⑥ 等用户回话时不空等:要用户在几个选项里定的时候,每次停下来等他之前先问一句 —— 等他的这段时间里,哪些活不管他怎么定都要做(出设计、取证、备计划)?先派出去,不等他回话。已签字、开了工的需求要并进新内容、等用户重签时(签字作废,办理会话仍是办理会话):办理会话先在自己施工区(x-test/zz-work/<需求名>/)的副本里开建 —— 几位执行体同时干、各改各的文件,真仓一个字不动;重签之后才用换入帮手换进真仓(放行要签字有效、在办,所以换入必须等重签);会让签字作废的几样(需求那一句话、要用户亲手验的清单、三个自报、档、流程,见 §八「签字只锁五样、过程由主控核准」)放最后写,写完当场报主控、请它弹重签题。排队的需求没有施工区可写(施工区开了工才活),它只做准备(备料见 ⑦):写计划目录、跑受治脚本,不动受治文件。派执行体按文件分人并行,不让两位改同一个文件(热点文件只给一位);几组之间有先后的(比如措辞定稿在前、对着字的床在后)在派工里写明。⑦ 排队的需求提前备料:签了字、在排队的需求,在前一条测试、验收、发布的这段时间里提前备料:最终文字、代码和测试的草稿先写在系统临时目录或计划目录,前一条封版之后再对着它的最终版预套共享文件;开工当场只核指纹、落笔、跑床。今天靠什么:全靠纪律 —— 握没握手、带没带设计、报没报节点、状态栏改没改、等用户时派没派活、备料派没派,没有机器核;机器看得见的只有账本里的签字、复盘、完结,落盘的结果单,与会话台账里的拦截。机器帮得上的一样是:用户每对主控说一句话,守卫在「正在办」那一行把每条在办需求走到哪、谁在办、那个会话最后一次动静多久之前、被拦了几次列给它(§八「每次回话列进度」)—— 主控不用等回报也看得见大概。但那一行只在用户说话时才有:产品经理卡住了、超过预计时间没回报,机器不提醒,靠项目经理的定时巡检(核登记册对会话列表、核各条需求看板的状态栏、超时叫人)。用量上限会把所有会话连同它们的 agent 一起打断,恢复之后不会自己续上 —— 由主控跑恢复命令拉回(下「会话登记册与恢复」)。握手回执里的会话编号,主控拿它对「正在办」那一行里「谁在办」的编号、对签字回话里认成的办理会话、对会话登记册里这条需求的产品经理。
常驻会话与会话命令(ADR-102、ADR-116;运行面的事归项目经理,见角色表项目经理一行):谁是常驻:项目经理、运维经理、产品架构师、Harness架构师四位,各管一摊(角色表);都是官方后台会话,用 --agent 起(项目经理 x-project-manager、运维经理 x-ops-deployer、产品架构师 x-architect、Harness架构师 x-framework-architect,每个专项的产品经理 x-product-manager),名字固定,由主控起(开新窗口的例行三步里发现不在就恢复,新电脑上用发起子动作,见下「主控怎么交接」);X大脑 本人是交互窗口,不在 agent view 里。另有一类「用时起、用完关」的会话:复盘经理(x-retro-manager),不常驻 —— 项目经理看到一条专项验收完结才起它(会话命令带专项名,握手内容写明复盘哪一条,名字固定叫「复盘经理」,同一时刻只有一位,几条专项接着做),它报完结果项目经理就关它;所以列会话时不点名它不在,恢复时不自动拉它。它和常驻会话一样不是任何需求的办理会话。型号与推理档(ADR-127、ADR-130;ADR-127 取代 ADR-117 讲会话型号的那一半):各角色的型号与推理档见型号配置 .claude/model-settings.json,那份文件是唯一出处 —— 守卫、会话命令、规范、各份执行体定义里都不写任何具体型号与推理档。两类,另可按角色单独设:每类一对「型号 + 推理档」,各记自己的最后改动与用过的原话;主控类是 X大脑、产品架构师、Harness架构师,执行类是其余会话角色(项目经理、运维经理、产品经理、复盘经理)与全部执行体;哪几位算主控类只写在 core/model-settings.js 的一份常量里,会话命令与守卫都读它,这里照它写、以它为准。七个会话角色(X大脑、产品架构师、Harness架构师、产品经理、项目经理、复盘经理、运维经理)每一位都可按角色单独设一行(配置里可选的「按角色」那一栏,一位一行,各记自己的最后改动与用过的原话;七个角色的名单只住守卫的固定话常量 guard/session-phrases.js 一处):单独设了的用它自己那一行的型号与推理档,没写的随它所属那一类的值;「按角色」一行都没写时,每个角色读出的值与只分两类时逐个相同。单独设的角色仍归原来的类:认主控类会话、派发闸都照旧只认主控类名单与执行类的推理档,不看「按角色」;执行体不单独设,跟着派它的会话走(下)。有效值只有一处算:型号配置命令导出一个取有效值的函数,给一个角色,答型号、推理档、快速型号、上下文宽度、走哪条路(官方,或本机代理与它的地址)、来自哪里(逐列答),会话命令与查看命令都只用它。走哪条路由型号推出:型号写法以 gpt 打头的经本机代理(代理是用户在本机起的 x-proxy/claude-code-proxy.exe,会话命令不替他起),其余走官方;路不进固定话 —— 官方没有 gpt 型号,Claude 型号经代理会被代理换成别的型号,这两种组合之外的写法本来就不能用,让人写路只多一处写错的机会。代理地址住型号配置文件:顶层「代理」那一栏(地址与它自己的最后改动),全文件一个值、不按角色分;代码里不写地址,也没有缺省值。快速型号与上下文宽度两列只设在角色行上:七个会话角色各自那一行可以多写两列「快速型号」(会话里给轻活用的型号,带进环境变量 ANTHROPIC_DEFAULT_HAIKU_MODEL,写法同「型号」)与「上下文宽度」(客户端本地压缩的工作窗口,带进 CLAUDE_CODE_AUTO_COMPACT_WINDOW,整数);两类那一行不设这两列 —— 同一类里各角色走的路不一样,类上设哪一族的快速型号都会让走另一条路的那几位被族核对拒掉,宽度也跟着路走。角色那一行写了就用;没写的,走代理的拒绝起会话,报「〈角色〉走代理,没设快速型号或上下文宽度」并附补设的固定话,不退回写死的值、也不用客户端的缺省(客户端缺省的快速型号是 Claude 型号,过代理会被换掉或拒;缺省的压缩窗口超过上游收得下的长度);走官方的两项都不带,由客户端用它自己的缺省。型号与推理档照旧随所属的那一类。两条核对:快速型号要与这个会话走的路同一族(走代理的 gpt 打头、走官方的 claude 打头);上下文宽度是整数,下限 10 万,上限走代理的 90 万、走官方的 100 万;不对就拒并点名。执行体不看这两列(下)。查看命令印一张逐行的有效表:harness.js --action=model-settings(show,缺省,谁都能看)表头上方印代理地址,表里七个角色加执行体每个一行 —— 角色、路(官方,或本机代理加地址)、型号、推理档、快速型号、上下文宽度、来自哪里(逐列写:型号与推理档写单独设或随哪一类,快速型号与上下文宽度写单独设或客户端缺省,客户端缺省只在走官方而没写时出现);类那两行与执行体那一行不印快速型号、上下文宽度;执行体那一行就是执行类的推理档,与派发闸读的是同一个值。「哪个会话、走哪条路、哪个型号、哪个推理档、快速型号、上下文宽度」看这张表。改配置只有一条路:BOSS 对 X大脑 说固定话 —— 「型号配置:<类> <型号写法> <档>」定一类(类写主控类或执行类;带了「快速」「宽度」的整句不收,并说明这两列只设在角色行上);「型号配置:<角色> <型号写法> <档>」单独设一个角色,后面可带「快速 <型号写法>」「宽度 <数>」(宽度也认 900k 这种写法),也能只说其中一列(如「型号配置:项目经理 宽度 900k」),只改说到的列、别的列原样;「型号配置:<角色> 跟随」去掉这个角色单独设的四列(型号、推理档、快速型号、上下文宽度),型号、推理档回到它所属的那一类(它的最后改动留着,免得说过的旧句被重放);「型号配置:代理 <地址>」改代理地址。按行认:一条消息里可以连说几行、每类或每个角色一行,每行独占一整行、整行逐字原样,行首尾空白不算,行里夹别的字或写在行中间的不认,别的行(空行、闲话)忽略,同一条消息里两类与各个角色可以各用一次、用过的行号按类与按角色各记各的;句式与七个角色的名单只住 .claude/hooks/guard/session-phrases.js 一处。X大脑 照每一行各跑一次 harness.js --action=model-settings --do=set(定一类带 --class,定一个角色带 --role,两样二选一;跟随那一句带 --role 与 --follow;快速型号、上下文宽度与代理地址各有对应的参数,写法照命令的用法),命令在原话账本里核到 BOSS 在本会话里说的(登记了主控时还只认主控会话里说的)、晚于这一类、这个角色或代理地址自己最后改动、没用过、是这一类、这个角色或代理里最后一行的那一行,而且行里说到的各项与命令参数逐项相同(跟随那一行只比角色),才原子写;值没变不写(跟随一个本来就没单独设的角色也算没变)、那一行也不算用掉;改一个角色只写它那一行与它的最后改动,两类、别的角色与代理地址原样留着。改配置那一刻也核:照一句话改完,有角色算下来走代理却缺快速型号或上下文宽度、或者文件里没有代理地址,这句话不收、文件一个字不动,点名是哪几个角色并附补设的固定话 —— 与起会话同一个判法;不在这里核,改一下类的型号就可能有角色要等到被起会话时才被拒,接力断在半路。换族时两列清空:一句话说完,哪个角色算下来走的路变了(gpt 与 claude 互换,不论是改了它自己那一行还是改了它所属的类),它那一行这句没说到的快速型号、上下文宽度清空 —— 所以「型号配置:项目经理 claude-opus-5-5 xhigh」一句就切回 Claude;切到代理的同一句里必须带快速与宽度,否则照上一条不收,整类切到代理只能逐个角色说;跟随清空之后算下来走代理的,同样不收。改代理地址那一句只核地址本身:只认 http:// 或 https:// 开头,不许带用户名或口令(这份文件会提交进版本库,口令写进去就进了提交历史),不许带空格和引号,这几样在同一处核,不对就不收并点名;不因为别的角色缺快速型号、上下文宽度被拒 —— 只加或换一个地址造不出坏掉的角色行,设代理很少、切型号常有,两样各一句、互不卡。没有代理地址而有角色算下来走代理:起走代理的那几位拒绝(走官方的照常起),改型号配置的那一句不收,都提示先说「型号配置:代理 <地址>」,不退回写死的地址。改表里的值不立需求、不升版、不封版,随时改;改表的样子(加一列、加一种角色、改句式)是改代码,才走需求。任何会话的写文件工具与命令行都写不了这份文件(写保护、永不放行名单、工作区地图一区),执行体跑不了 set(守卫按 agent_id 拦)。推理档只许 low、medium、high、xhigh、max;型号写法认四种 —— 人话「族名 版本」(规整成 claude- 加族名小写、版本里的点换成横线)、完整型号名、官方别名、gpt 那一族的写法(如 gpt-6.1-sol[1m]),不对着型号名单核,所以换新模型不用改代码;读不出、JSON 坏、缺一类、推理档不在五个里、型号规整不出来,会话命令与守卫一律拒绝并点名怎么修,不退回写死的旧值;「按角色」里一个角色那一行写坏(型号规整不出来、推理档不在五个里、这一行不是对象)只挡这一位:起它的会话拒绝并点名坏在哪、怎么修,不退回类的值;「按角色」里有认不出的角色名、或「按角色」整个不是对象,七个角色都挡:取有效值对任何一位都答不行,会话命令起任何一位都拒绝,点名哪个名字认不出(或这一栏不是对象)、怎么修(改对名字或从版本库取回,「跟随」改不了它);这两样都不挡两类的读法与派发闸,查看命令照样点名;改配置遇到「按角色」不是对象直接拒绝,设置提交脚本遇到认不出的角色拒绝提交;首次 set 可以只写一类,缺一类按「缺一类」拒绝,两类都 set 完才生效。读配置的地方每次读盘、不缓存:改完新起的会话与新派的执行体照新的,已在跑的不动。会话:会话命令发起时按这位角色的有效值带 --model、--effort(单独设了用它自己那一行,没设随所属的类),起完照横幅核同一个值(配置是完整型号名就比族名加版本,是官方别名只比族名,gpt 那一族比型号名本身、不含 [1m] 这类变体,推理档逐字比,认不出宁拒勿放:停删并点名读到的开头)。先洗掉继承来的代理六项:会话命令发起、叫醒、恢复任何会话之前(三条路都经同一处),先把从父进程继承来的代理那六项 —— ANTHROPIC_BASE_URL、ANTHROPIC_AUTH_TOKEN、ANTHROPIC_DEFAULT_HAIKU_MODEL、CLAUDE_CODE_AUTO_COMPACT_WINDOW、CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC、CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK —— 一律洗掉(并进 SCRUBBED_ENV),所以 Codex 会话发起、叫醒、恢复走官方的会话也不会悄悄进代理。要走代理的那一位:洗完之后,起会话那份内联设置(--settings)的环境变量里照本行配置带齐六项 —— 代理地址(取自型号配置文件)、占位令牌 ANTHROPIC_AUTH_TOKEN=unused、快速型号、上下文宽度、CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1、CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK=1;占位令牌与两项开关写死在代理那条路的常量里、不进配置(它们是代理这条路能正常工作的条件,不是谁的偏好:杂项请求与流式失败后改走的非流式请求,代理接不住);不在父会话的值上叠(父会话的快速型号与宽度是它自己那一行的),起会话的回话里列出带了哪几项。代理地址只能这样带,写在命令前的环境变量不管用(后台会话由常驻后台服务起,作业不带起它那条命令的环境)。走官方的那一位只带设了的快速型号、上下文宽度,都没设的不多带一项。叫醒、恢复不重发设置(设置随会话保留,与 MCP_TIMEOUT 一样)。代理不通当场拒绝、不退回 Claude:发起、叫醒、恢复要走代理的那一位之前,会话命令先向本机代理发一次最小的真请求(只花一点 Codex 的用量);请求没成(连不上,或代理回的是错误)就不起、不叫、不拉这一位,报文写明连的是哪个地址、附上代理的原话,并同时附三句:先双击启动 x-proxy/claude-code-proxy.exe 再重跑;授权过期的,粘贴运行重新授权的「!」命令(带 claude-code-proxy.exe 的完整路径、后接 codex auth login,路径用正斜杠、不带 &,在 Git Bash 里跑得了);地址不对就说「型号配置:代理 <地址>」。不单独认是不是授权问题,不悄悄改走官方;走官方的那几位不发这次请求。叫醒、恢复按此刻配置里那一行判走不走代理,不另记它起的时候走的哪条路。起 claude 子进程前先洗掉继承来的子代理型号、强制开关与推理档四个环境变量(CLAUDE_CODE_SUBAGENT_MODEL、CLAUDE_CODE_SUBAGENT_MODEL_FORCE、CLAUDE_CODE_SUBAGENT_EFFORT、CLAUDE_CODE_EFFORT_LEVEL;所有 claude 调用都经 spawnClaude 这一个口,见 §八「会话命令与敏感命令」),所以不管从哪个会话起新作业,新会话与它派的执行体都只跟型号配置走;X大脑 窗口是用户手起的,它的启动命令由配置里 X大脑 那一行的有效值算出,型号配置命令的 show 与登记主控的报文都印整行(见角色表主控一行);那一行是 gpt 时,整行另带同样的代理设置(内联设置里那六项,代理地址取自型号配置文件,含快速型号、上下文宽度与两项开关),起之前核代理这一步机器不做。执行体跟着派它的会话走:执行体文件只写 model: inherit、不写 effort,项目设置里不强制子代理型号;执行类会话派的执行体继承的就是派它那一位自己的型号与推理档(没单独设的就是执行类的,单独设了的就是它那一行的;走代理的会话派的执行体同样走代理);执行体不看快速型号与上下文宽度两列,用的是派它的那个会话的环境(执行体跑在那个会话进程里,没有自己单独的环境);主控类会话派的执行体推理档跑执行类,所以派发时必须显式带执行类的推理档(型号继承派它那一位的)。守卫的派发闸(§八 环3「需求对账」里「派发的型号与推理档」一段)核这一条:派执行体不带型号(不写或写 inherit 放,写了别的一律拦);带推理档的只放等于配置里执行类推理档的;主控类会话派执行体必须带它、不带也拦,报文写明该带什么;配置读不出时,执行类会话不带参数的派发照放(本来就是继承),其余拦。守不到:BOSS 用编辑器手改文件,机器认不出是谁改的、也不提示(手改不动最后改动,所以手改之前说过、还没用掉的固定话仍算新鲜);原话账本只在本机,换电脑后要 BOSS 再说一次;型号名格式对而平台不认,要等下一次起会话的横幅核对才抓到;派发带的推理档平台照不照办、执行体的推理档在对话记录里看不看得到,只能靠平台;两类型号不同、或派它的那一位单独设了型号时,执行体的型号跟派它那一位走、守卫只核推理档;单独设了的执行类角色派执行体不带推理档照放,执行体跑的是那一位自己那一行的推理档;已在跑的会话改不了(型号在起会话那一刻定;叫醒、恢复、改名都不带型号与推理档、续上沿用平台存下的,要换只能删了再发起),常驻会话要等重起才跟新配置;已经带着那四个环境变量的旧作业(会话命令洗不到它们身上)叫醒时仍重放旧值,已在跑的会话(含 X大脑 的窗口,按新启动命令重开才干净)自己派的执行体仍被强制,要换新只能删了再发起;平台以后再有别的会把型号或推理档带进新会话的变量,名字要补进 SCRUBBED_ENV 那份名单;洗环境这一条没有真环境的实测,只有床里用假 claude 看环境。走 Codex 的会话:Codex 写的中文与对规矩的遵从和 Claude 不同,守卫、检测、测试拦得住做错的动作,拦不住「说得不清楚」,它给 X大脑 的报告 X大脑 照常核;干到一半代理掉线或授权过期,会话停在报错上,要用户修好代理后叫醒接着做,机器不自动切回 Claude;起之前那次真请求只判成没成,不分辨是代理没开、授权失效还是回答的型号不对,没成就附代理的原话;代理与客户端升级之后横幅的样子可能变,认不出就当场拒绝、点名读到的开头,不会悄悄放过;叫醒、恢复按此刻配置里那一行判走不走代理,会话起了之后配置又改过的那一位会判错一次 —— 多核一次代理,或少核一次(最坏是叫醒后第一回合报连不上,同样是请用户启动代理);X大脑 窗口是用户手起的,它那一行设成 gpt 时代理通不通机器不核,代理没开窗口第一回合就报错;上下文宽度走代理的上限照实测定(约 92 万能过、约 95 万被上游拒),上游收得下的长度变了要跟着改,机器不知道;走官方而没写两列时客户端用它自己的缺省,那是什么机器不核;两项开关是平台的环境变量,平台改了名字或不再认,机器不知道;对话内容送到哪见 §二「对话内容送到哪」。工具白名单:--agent 起的会话严格守定义里的工具白名单(免确认权限档也挡),延迟加载的工具白名单里没有 ToolSearch 就加载不了,所以常驻和产品经理的定义把用到的工具列全 —— 产品经理要有 Agent(不然派不了执行体)、Skill、Bash 与读写那一套;项目经理要有定时任务三件;运维经理要有 ToolSearch 与要用的云端工具(清单照部署技能和开发规则书逐个列,含 modifyDataModel、manageDataModel;另有 mcp__cloudbase__auth —— 云端工具服务规定的第一步是先调它的 status,两份文档不点名,单列);常驻会话、产品经理与复盘经理的定义都有 SendMessage。运维经理是常驻后台会话:免确认档的后台会话连没批准的项目级云端工具服务也能用(实测),项目设置里批准了项目级云端工具服务,其余权限档遇到没批准的服务会静默卡死(state=blocked、没有进程、首句不提交),所以受信命令和项目经理的巡检把 state=blocked 当成要报主控的事。闲着的常驻:官方约一小时后会把闲着的会话进程收掉,agent view 里显示「做完」,对话还在,叫一声(叫醒子动作,或会话之间的消息)就从原处接着干;只有项目经理靠自己二三十分钟一次的定时巡检常醒 —— 循环定时任务 7 天到期,所以巡检的创建时刻落盘记下,每次醒来先列一遍现有的定时任务,满 6 天前删了重建。会话命令(体系守护技能,一个入口九个子动作;实现住 core/session-ctl.js 与登记册模块 core/session-registry.js):node .claude/skills/x-harness-dev/scripts/harness.js --action=session --do=<子动作> [参数];守卫照现行白名单放行这个脚本,脚本内部再调官方的 claude 命令(任何会话直接跑 claude 都拦,只有经这个脚本才行);身份取自会话环境里的会话号(只取环境变量,不设开关让人报名),对着会话登记册认。九个子动作:
| 子动作 | 谁能跑 | 做什么与要点 |
|---|---|---|
register-main 登记主控 | 谁都能跑,但只有会话列表里种类是交互、名字叫 X大脑 的那个会话登得上 | 登成主控;重复登记无妨;登记册里的主控已死、调用者又是这样的会话时,发起与恢复会自动补登;旧主控还活着时,换主控要用户在新窗口亲口说那句固定的话(认法照签字的认法,查原话账本;只认最近 10 分钟内说的、同一笔不能用第二次)。交互会话在会话列表里带种类和名字,名字人能改,所以这一步只防得住 AI 自己冒 |
start 发起 | 主控、项目经理 | 遇到任何一个活着的同名会话一律拒绝再起;常驻四位按固定名字起;每个专项的产品经理会话,短名、类别、档由主控定下后作为显式参数带进来(--role=产品经理 --short= --category= --tier= --plan=;立项在签字一之前,这时计划目录还没有,不读机器镜像),同一条需求已有活着的产品经理时拒绝再起;复盘经理按固定名字起、要带专项名(不带拒绝),握手内容写明复盘哪一条。命令固定一种形状、全部参数在发起时带齐:claude --bg --name <名字> --agent <执行体> --model <型号配置里这位的有效型号> --effort <这位的有效推理档> --permission-mode bypassPermissions --settings <不进工作树的设置> "<固定句>";脚本用参数数组直接起、不经 shell(Git Bash 会把以斜杠开头的参数改写成路径),提示词放在可变长参数的前面;起之前先洗掉继承来的子代理型号、强制开关与推理档四个环境变量(见上「型号与推理档」)。写前拦截没接上线(项目设置里读不到守卫的钩子接线)时发起、叫醒、恢复一律拒绝。发起后核对会话列表里真有这一位、型号与推理档(按配置里这位的有效值核)看 claude logs 开头的横幅(列表里没有型号字段,横幅里的 @名字 也要对上;读横幅的等待单设时限,缺省 120 秒 —— 会话开机要先等项目级云端工具服务连上,慢的时候 20 秒读不出,会被误当成没起来而停删),再把完整小写会话号、名字、角色、哪条需求记进登记册;握手内容由命令打印、项目经理照原样经会话之间的消息送出,开头直接写上会话自己的短号(前八位),会话不用自己去读环境变量里的会话号 —— 命令里写出变量名会被环1 当成改写会话身份拦掉;打印给人看的只带短号;运维经理另核云端工具连上没有(下「运维经理的云端工具自愈」)。命令带的内联设置里,除不进工作树之外多一项 MCP_TIMEOUT(90 秒);起之前先洗掉继承来的代理六项,要走代理的那一位再照本行配置带齐那六项、起之前先核代理,走官方的只多带设了的快速型号、上下文宽度(见上「型号与推理档」) |
wake 叫醒 | 主控、项目经理 | claude --resume <完整小写会话号> --bg <固定句>,不带任何别的参数 —— 会话号不变、对话接得上,型号、推理档、设置、权限档、名字全保留;只认登记册里的完整号(短号会复制出副本);带任何参数续上都会复制出同名副本,判副本两种法并用:回执里出现「started a copy」、或会话列表里同名的会话多出一个且短号对不上登记册,任一出现都当失败 —— 把副本停掉删掉、报主控;还在跑的会话不续上、改发消息;运维经理被叫醒之后另核云端工具(下「运维经理的云端工具自愈」);续上不带任何参数,内联设置不重发(MCP_TIMEOUT 是否随会话保留、生不生效,见下「运维经理的云端工具自愈」的守不到);停了再叫醒会话号不变,但会话之间消息的收件地址每次都换、旧地址作废,给常驻发消息一律写名字、不存地址;要走代理的那一位,续上之前先核代理,没成就不叫(见上「型号与推理档」) |
stop 停 | 主控、项目经理 | claude stop <短号>(官方的 stop、rm 吃的是 --bg 打印、agents 列出的前八位短号;没成再换完整号试一次);停着的会话收不到消息,也不补发 |
rm 删 | 主控、项目经理 | claude rm <短号>(同 stop);专项提交之后,项目经理用它关掉那位产品经理的会话、删登记册那一行,复盘经理报完结果之后同样由它关掉(不等专项提交);会话不进工作树,没有「没提交的改动」要保护,对话记录留在盘上 |
recover 恢复 | 预览谁都能看;执行主控、项目经理 | 默认只预览:列出登记册里谁该拉;带执行开关才拉:只拉停了、失败、干着活的,有进程的跳过、已完成的不拉、复盘经理不拉(它是用时才起的,不是常驻);每个先 stop、再用叫醒那个不带参数的形状续上(要走代理的那一位先核代理,没成就不拉它、照实列出),首句是固定句,提醒会话先核被打断的那一步生没生效;拉到运维经理时,全部拉完之后另核它的云端工具(下「运维经理的云端工具自愈」);停服务本身(claude daemon stop --any)是用户的动作,不在这条命令里 |
list 列表 | 谁都能跑,只读 | 登记册对照会话列表现查的状态,列出名字、角色、状态、有没有进程,登记册里没有复盘经理时不点名它不在;官方输出缺字段时报错并写明缺哪个、不硬猜;state=blocked 的当成要报主控的事 |
rebuild 重建登记册 | 要用户在 X大脑 窗口亲口说一句固定的话才跑(认法照签字的认法;只认最近 10 分钟内说的、同一笔不能用第二次),不看调用者在不在登记册里(登记册可用且登记了主控时,那句话还得是主控窗口里说的;登记册读不出来或两处对不上时,守卫当没有登记主控,哪个窗口里说的都认) | 两处都坏、换了电脑时,按会话列表里的名字重建(只认名字对得上的常驻、产品经理与复盘经理);重建出来与现查对不上的行如实列出,不硬补 |
rename 改名 | 主控、项目经理 | 档变了(用户签「确认」时改了档)照新档改名:脚本按命名规则用登记册里的短名、当前类别和新档拼出新名,不收自由文本;先 claude stop,再用不带任何别的参数的 claude --resume <完整号> --bg 加一句「/rename 新名」续上 —— 会话号不变,斜杠命令不触发说话钩子;带 --name 续上不是改名而是复制出副本,所以绝不带;改完登记册里的名字跟着更新;拼出的新名对不上命名规则就拒绝 |
运维经理的云端工具自愈(ADR-116):事实:运维经理头一次开机时,项目级云端工具服务(.mcp.json 里配的 cloudbase,用 npx @cloudbase/cloudbase-mcp@latest 起)连接超时(30 秒),会话里一个云端工具都没有;后台会话没人能点 /mcp 重连,stdio 方式的服务启动失败官方也没有自动重试(只有手动 /mcp reconnect);恢复演练换了新进程之后连上了,14 个云端工具都在。三层:① 机器自己治 —— 工具白名单补 mcp__cloudbase__auth;运维经理定义里写明被发起、叫醒、恢复的第一回合和每次接部署或联调的活之前,先核云端工具在不在(ToolSearch 加载 auth、调 status),不在就用 SendMessage 报 X大脑 并停手(它重启不了自己,由 X大脑 或项目经理停掉再不带参数叫醒);会话命令在运维经理被发起、叫醒、恢复(拉到它的时候)成功、会话有了进程之后,读它自己的会话记录文件,等一个明确的结论(时限缺省 180 秒,床里随等待缩短)—— 记录里 type 为 attachment、attachment.type 为 deferred_tools_delta 的条目是平台每次发请求前追加的,failedMcpServers 里有名叫 cloudbase 的 ⇒ 没连上,addedNames 或 readdedNames 里有 mcp__cloudbase__ 打头的名字 ⇒ 连上了,以最后一个有结论的条目为准,只读发起或叫醒之前的字节数往后的部分(旧进程留下的结论不算);连上了打印用时;没连上就停掉(等到会话列表里没有它的进程才续上)、再不带参数叫醒一次(叫醒固定句、沿用副本检查,换一个新进程重连)再核一遍,还没连上才当失败报主控(会话活着但没有云端工具,不删会话、不改登记册);等到时限仍没有结论算「核不出」,不算失败(会话可能还没跑过带工具调用的回合,握手回执里它自己报)。别的角色一概不读记录文件。② 治根 —— 发起命令带的内联设置里加 MCP_TIMEOUT(90 秒;官方环境变量,管 MCP 服务单次启动的连接时限,缺省 30 秒;官方文档写明它能放进设置的环境变量、也认内联设置);项目设置不动。③ 最后兜底,用户动手 —— X大脑 告诉用户两次都没连上时,用户在 agent view 里选中运维经理,发 /mcp reconnect cloudbase(官方文档写明这条在 agent view 里不用点进会话也能发,本机没实测过;不行就点进会话打 /mcp 选重连),平时用不上。守不到:记录文件的路径(用户目录下按仓根键分目录、以完整小写会话号命名)与条目格式是官方没承诺的内部形态,读不出就说「核不出」、不乱判;claude logs 里有没有这类提示官方文档没写;MCP_TIMEOUT 是不是在 MCP 连接之前生效、后台会话带不带着内联设置里的环境变量、叫醒与恢复(不重发设置)之后它还在不在,文档没写;本机六轮重启实测(删了重起三轮、停了叫醒三轮)都连上了(16 到 49 秒)、一轮没连上的都没有,所以没测出来,要等某一次真出现「没连上」、原因里带 N 毫秒才分得出;「连上了」只说明平台记下云端工具名可用,不等于 status 正常、环境绑好,那是运维经理开工自检的事;核对期间整个子动作占着登记册的锁(最长要等两个时限加一次停和叫醒,缺省约 6 分半钟),别的改登记册的命令那段时间会被拒;运维经理有没有照定义自检,机器不核。这一件是软的 —— 靠定义与命令,不是硬控。守着它的床:.claude/skills/x-harness-dev/tests/session-ctl.test.js。
送进会话的话与会话命名(ADR-116):送进会话的话只许是一处常量里的固定句(发起首句、叫醒、恢复各一句,放在守卫目录 guard/session-phrases.js,守卫与受信命令共用;另有第四句巡检固定句,是项目经理建定时巡检时的提示词、不是会话命令送的,同一待遇),不含任何签字说法、不带自由文本;握手内容、转话、叫醒的原因一律经会话之间的消息送(实测首句、续上的话、收到的消息都会触发说话钩子,所以守卫精确匹配固定句、不记它,见 §八「签字记录只认两条路」)。会话命名:四位常驻叫项目经理、运维经理、产品架构师、Harness架构师,复盘经理固定叫「复盘经理」(同一时刻只有一位);每个专项的产品经理叫「需求短名-类别-档」—— 类别:业务流程写产品、Harness 流程写 Harness、规范流程写规范;档:小事、成条、难事(成条的事写成条);例:地图立起来-Harness-难事。角色人人一样,不进名字;发起命令和改名子动作都按这条规则起名,对不上规则的拒绝;会话名必须唯一 —— 同名的会话能并存,但按名字发消息会被平台拒绝(要带 ref),所以发起遇到任何一个活着的同名会话一律拒绝。守不到:见 §二「后台会话、代签与签字放行的边界」;会话列表的字段、横幅的写法是本机 Claude Code 2.1.310 实测的,命令里留了字段自检,对不上就报错不硬做。守着它的床:.claude/skills/x-harness-dev/tests/session-ctl.test.js(对一个假的 claude 命令行逐个子动作断言它收到的参数)与 session-registry.test.js。
会话登记册与恢复(ADR-116):会话登记册(和平台自己的会话名册是两回事 —— 后者是平台放在用户目录里、记会话文件的名册,这一份是我们自己登记谁是谁)记每一位常驻、每个专项的产品经理和用时起、用完关的复盘经理 —— 完整小写会话号、名字、角色、哪条需求(以及短名、类别、档;复盘经理这一行不带需求:这一回复盘哪条专项只写在握手内容里、不进登记册,一位接着做几条时记在行里的会过期);主控单记一行;状态不存,现查会话列表(claude agents --json --all;不带 --all 不列已停的后台会话)。仓里 .claude/tmp/sessions/registry.json 一份,用户目录里镜像一份(与需求账本的镜像同一个办法);写入是原子的(先写临时文件再改名,带递增序号);两处只差一格时按新的那处补,别的情况一律拒绝并写明原因;锁里写进程号和时刻,过期可抢,存活判断复用会话台账里现成的那一份。登记册目录进守卫的写保护名单、只许受信脚本写,.gitignore 加一行(不入库);登记册只在本机有效,换电脑要重新起四位常驻或用重建命令(项目架构设计页的换电脑清单)。除登记主控、列表和恢复预览(只读,谁都能跑)、重建登记册(靠用户亲口说的固定话放行)之外,每个子动作只有登记册里的主控或项目经理跑得了。守卫那一侧只读登记册,读法就是会话命令的读法(requirements.js 的 registryOf 经登记册模块的 readState;读不了、形状不对、两处对不上都一律按「没有登记的会话」算 —— 这时说话只认主控、定时任务的巡检限制都不启用,新窗口里说「会话登记册:重建」在任何窗口都记得上,免得换电脑时只拷了仓里那份登记册、登记主控与重建互相指圈),用来判主控、判项目经理、判某个会话是不是登记为某条需求的产品经理(放行用,§八 环1「签字放行」)。死机之后怎么拉回:重开 X大脑 窗口和 agent view,由主控跑恢复命令(项目经理自己也在被拉回的名单里,第一步不能指望它);四位常驻回来之后,单个会话掉了由项目经理的巡检去拉。对每个要拉的会话先 stop、再按完整号用不带参数的形状续上(原会话还活着、或带了任何参数时,续上都会复制出同名副本);只拉该拉的 —— 状态是停了、失败、干着活的才拉,已完成的(只是进程被官方收掉)不拉、要用时叫醒,有进程的跳过,复盘经理不拉(它是用时才起的);被打断的那一步,官方会在记录里标成结果未知,会话自己会重做,有副作用的步骤要先查生没生效,所以固定句写明让它先核;在办的会话按原会话号接着做。恢复演练实测过的:停掉五个会话(四位常驻加一个演练用的)再拉回(已闲着收了进程的两位架构师用叫醒),会话号全没变,答得出工具名,记得停之前的对话;不带参数续上之后仍能写主仓;固定句没有进原话账本;横幅里的型号与 @名字 靠发起命令里那一步核(主控自己直接跑 claude logs 会被守卫拦)。真重启电脑的恢复没演过。用户亲口说的固定话(重建登记册、换主控、改代签设置、改型号配置)认法一样:去原话账本里找用户确实说过的那一句(机器话、固定句和整段是标签的跨会话消息本来就不进原话账本),只认最近 10 分钟内说的(改代签设置与改型号配置不看这个时限,只认晚于设置文件里这一类最后改动的那一句,型号配置里单独设一个角色的认这个角色自己的最后改动,改代理地址的认地址自己的最后改动),同一笔原话不能用第二次(用过的位置各记各的账:登记册的 used、两份设置文件各自的「最后改动」);前三种要整条消息恰是那一句,改型号配置那一种按行认(一条消息里可以连说几行、每类或每个角色一行,每行独占一整行、整行逐字原样,行首尾空白不算,行里夹别的字或写在行中间的不认,别的行忽略,同一条消息里两类与各个角色可以各用一次);登记册可用而且登记了主控时,重建登记册、改代签设置与改型号配置三种还只认主控会话里说的那一笔(换主控不看,新窗口登记之前它是唯一的出口,§八「签字记录只认两条路」);这一份认法全仓只写一处。立项和收尾谁跑:立项和起产品经理会话都在用户签「确认」之前;立项命令由产品经理在自己的会话里跑;收尾单由它起草、清理归档由它跑;遗留的去向由主控定(先过复杂化审查官),写进验收题;待立项目清单和总账仍归项目经理,环收尾之后由主控提交、提交之后由项目经理关会话、删登记册那一行;用户签「确认」时档要是变了,由项目经理用改名子动作照新档改名并在登记册里记上新档。守不到:见 §二「后台会话、代签与签字放行的边界」⑤⑩⑪。
取舍原则与复杂化审查官(ADR-116;宪法 §六 第 9 条「禁止复杂化」只写定性,谁来判、几个时点、四种判断写在这里):原则:取舍只问最佳最合适,规模与成本(工作量、工期、要改多少行)不作为取舍的理由;只禁止复杂化 —— 用不上的、极少发生的、不做也没有风险的事,不立项、不留账;拿不准才问用户;用户当场拍板的事不在其内。两位架构师做设计的第一条要求就是这一句(写在执行体定义最前面),复杂化审查官的边界里也是同一句;比较方案时标出哪一版最佳最合适、不标哪一版最省。谁来判:复杂化审查官 x-complexity-reviewer(执行体,只读、只出判断,没有写文件的工具,型号与推理档跟着派它的会话走:文件写 model: inherit、不写 effort);它只砍「不必要」的,不拿规模、工作量、成本当砍的理由;不碰用户当场拍板的事、不提新活、不替独立复盘官判过不过。三个时点:① 待立项目进门前分诊 —— 验收完结后的遗留要定去向、新的想法要进待立项目清单,进门之前先过它一遍(主控在遗留定去向之前派它;复盘经理的发现随这条专项的遗留一起过这一遍,不另过一次);② 成条与难事的计划在签字题弹出之前做减法审 —— 产品经理写好计划、架构师审过合不合设计之后,主控在弹签字题之前派它,砍掉标准、用例、落点里不必要的部分;③ 待立项目清单更新前瘦身 —— 主控在清单更新之前派它,项目经理写清单之前先拿到它的判断。四种判断:立;并(写并进哪一条、为什么是同一处);不立(三个理由选一个:用不上、极少发生、不做也没有风险);问你(写拿不准在哪)。交回一张表(条目、判断、理由一句、并进哪条),末行计数。守不到:判得对不对、有没有人偷偷拿成本当理由,机器判不了,靠独立复盘和用户抽查;审查官只是建议,拍板的是主控和用户。
签字机制:两条路(ADR-116;宪法 §六.8 只写定性):签字记录 —— 需求账本里签字一的 confirm、签字二的 accept 与 closed —— 只认两条路:① 用户的原话(用户在当场那个会话里说的话:看板签字区「复制结论」贴回、打固定句、选项题一键签,这一整套在 §八「需求对账」;会话之间转发的话不算用户说的);② 代签命令(harness.js --action=sign --plan=<名> --kind=验收完结 --as=代签,只主控本人的会话跑得了,只签签字二)。别的写法 —— 比如手写进账本的一笔 —— 一律不算。签字一(需求确认)只有第一条路:永远用户本人签、从不代签,它同时是受保护文件放行的授权(§八 环1「签字放行」),可以提前签、一次签好几份 —— 签的那一刻开得了工就当场开工,开不了记成排队,开了工才占版本单元、放行才生效(§八「签字与开工分开」);改代签设置不经立项、也不代,只归用户。验收完结(这一签同时授权这条需求的发布与提交)与开发中途的联调上线的点头,按用户的代签设置由用户本人或主控来:设成亲签的那一类由用户本人,设成代签的那一类由 X大脑 代他点头(这条的「验收谁签」也得是代签)。用户本人随时能签 —— 就算定了代签,他说「全选执行:验收完结 <短名>」照样算。账本里代签那两笔的记法与履历写明「X大脑 代签」见 §八「签字记录只认两条路」。
代签设置、验收谁签与代签命令(ADR-116):代签设置:两个开关,按专项类别分开管、互不影响 —— 产品专项(类别写「产品」的需求,即业务流程,设计归产品架构师)、Harness专项(类别写「Harness」或「规范」的需求,即 Harness 流程与规范流程,设计都归 Harness架构师)。每个开关两个值:代签(这一类里本该用户点头的事,除了签字一,都由 X大脑 代他点头 —— 验收完结〔这一签同时授权这条需求的发布与提交〕、开发中途的联调上线授权)、亲签(这些都要用户本人来)。运维、分析两条辅助流程没有验收签字,不在其内。只归用户、不代的有两样:签字一、改代签设置(手动开闸只在急救时用,也只归用户)。设置放在 .claude/sign-settings.json:不归任何版本单元,不升版不封版;工作区地图声明它所在的区 —— 不受治、受保护(任何会话的写文件工具和命令行都不许写)、入库(随仓走,换电脑带着);文件缺了、读不出或写得不对一律按亲签算(宁严不松)。读与改只经体系守护技能的 core/sign-settings.js:读设置(缺了或坏了两个开关都按亲签,附一个设置指纹)、按流程认类别(业务流程归产品,Harness 流程与规范流程归 Harness,运维与分析不归任何一类)、按固定话改设置。改设置不立项,两条路:一是用户在 X大脑 窗口说一句固定的话 ——「代签设置:产品 亲签」「代签设置:产品 代签」「代签设置:Harness 亲签」「代签设置:Harness 代签」四句之一(句式放在 guard/session-phrases.js 一处常量里)—— X大脑 跑受信命令(harness.js --action=sign-settings --do=set --class=<产品或 Harness> --value=<亲签或代签>;带 --do=show 只读看现状),命令在原话账本里核到这句话确实是用户说的(认法照签字的认法)才改;这句话要新鲜、一次一用 —— 只认晚于设置文件里「最后改动」时刻的那一句,用过的那一笔原话在账本里的位置记在设置文件里、同一笔不能再用,翻出旧账本里的老句子重放不行;改的时刻与那一笔原话的位置也记在设置文件里(「最后改动」一栏:时刻、来源、原话位置、用过的位置)。二是用户自己用编辑器改设置文件 —— 守卫拦不住也不该拦用户本人,下一次读设置就照新值;文件里「最后改动」一栏与账本对不上时,读设置提示一句。不经用户的原话,任何会话(包括 X大脑)都改不了。设置是上限:签字一之后用户把某一类改成亲签,那一类在办的需求一律按亲签算,以读设置那一刻为准。验收谁签(每条计划一栏):计划的看板与机器镜像(acceptBy:亲签或代签,acceptWhy:一句理由)多一栏;主控写设计要点时判断,产品经理照着写进计划,签字一的题里摆给用户看(需求确认区)。判断规则:那一类设成亲签,只能亲签;设成代签,默认代签,验收清单里有只有用户能判的项(他的喜好、他要表达的意思、要他亲眼看过才算数的)就定亲签并写明理由。用户签「确认」时加一句「这条我自己验」,就改成亲签 —— 主控通知这条需求的产品经理改看板和机器镜像、刷新签字区。这一栏随签字一锁住:放宽(亲签改代签)算实质,要用户说(重签);收紧(代签改亲签)主控随时可以让产品经理改,走过程核准、不用重签;主控自己从不写机器镜像(它一写就丢了核准资格)。没有这一栏的计划,验收由用户签。代签命令(体系守护技能的 core/sign-delegate.js):关口一个不少,最后那一下由 X大脑 点 —— 关口和用户签时同一套核对、同一段代码(三查全绿、独立复盘过、看板与机器镜像对得上);X大脑 先逐条核验收清单,每条的证据写进看板验收区(亲手验的清单照旧写成用户看得懂的话,代签时由 X大脑 代验),验收区没有证据就签不了。命令再核三件事:调用的会话是会话登记册里登记的主控;设置此刻允许这一类代签;这条计划的「验收谁签」是代签。三样都对,才照常记「验收完结」,签字人写「X大脑 代签」,带上设置的指纹和验收区证据的指纹;之后的履历、发布段、归档和用户签的一样走,履历里写明「X大脑 代签」。被拦的每种 —— 设置不许、这条定了亲签、调用者不是主控、关口没过、验收区没有证据 —— 各写明原因。带执行体编号的会话(X大脑 派出去的执行体)跑不了这条命令(§八 环1)。代签之后 X大脑 向用户报一句:哪一条、凭什么签的、证据在哪,以及待立项目清单这次加了、拿走了哪几条(代签的需求,清单的增减由这句报告告诉用户)。代签连带发布、提交与联调:代签的那条需求,验收完结那一签同时授权这条需求该发的每一格各发一次(出问题立刻回滚算同一次)与它的提交 —— X大脑 把代签记录转给运维经理(不是用户的原话),运维经理照发;提交由 X大脑 在环收尾之后跑提交命令,命令核的是完结那一笔记着要提交与环收尾成立,不另问用户;开发中途的联调上线另按同一个设置由 X大脑 代用户授权,同样办。不随这条需求验收的发布与生产构建不在其内,要用户的单次授权。机器核:代授权的发布与联调在命令里显式带需求名和「代授权」标记,部署门和各条发布出口只核带标记的这条路(§八「部署门认联调」⑮);不带标记的(用户本人授权的)照旧,机器不核、靠纪律。设置改成亲签之后,带标记的被拦,那一类的发布、联调都照旧要用户单次授权。守不到:见 §二「后台会话、代签与签字放行的边界」④⑤⑥;设置里允许不等于代验得对,证据留在看板验收区、用户随时抽查。守着它的床:.claude/skills/x-harness-dev/tests/sign-settings.test.js、sign-delegate.test.js 与 .claude/hooks/tests/delegated-signoff.test.js。
主控怎么交接(ADR-90、ADR-94、ADR-116):主控要记住的东西不靠上下文 —— 顶层的状态落在受治文件与账本里:在办的需求在计划目录与需求账本,各单元封没封在变更历史与锁清单,定下的规矩与取舍在宪法、本文与决策记录,流水线怎么走在项目架构设计页,谁是谁、谁在办哪条线在会话登记册。新的主控照项目架构设计页「怎么开一条需求」接手。开新 X大脑 窗口的例行三步:① 登记主控(--action=session --do=register-main:会话列表里种类是交互、名字叫 X大脑 的那个会话登得上;重复登记无妨;登记册里的主控已死而调用者是这样的会话时,发起与恢复会自动补登;旧主控还活着时,换主控要用户在新窗口亲口说那句固定的话;登记册里记着主控时用户的签字只认主控窗口,新窗口没登记之前他在里面说的签字不记);② 看四位常驻在不在(--do=list);③ 不在就预览恢复(--do=recover,默认只预览;确认之后带执行开关拉回)。再跑环的十态与排队两条只读命令,看每条需求在哪一态、下一步该谁做。不用交接的:在办的需求、签字、各单元封没封都在仓里,新会话开工时守卫逐条告诉它;谁在办哪条线查会话登记册。会丢的只有主控脑子里的两样 —— 哪些事等用户定、排了哪些窗口:它们记在项目经理的总账页里(计划目录下的子目录,不放机器镜像),所以主控每次醒来先问项目经理核一遍。今天靠什么:三步是纪律,没有机器核;机器帮得上的有:计划与需求账本在仓里、不跟会话走,新会话开工时守卫把正在办的、排队的、签字作废的、没签字的计划逐条告诉它(§八 挂载一段的开工注入);用户对它说每一句话,守卫在「正在办」那一行把每条在办需求走到哪、谁在办列给它(§八「每次回话列进度」);每个版本单元上谁占着、谁排着有一条只读命令(§八「同一块排队」);每条需求在环的哪一态、下一步该谁做什么有一条只读命令(§十四「项目架构环的十态与启动、收尾」);会话登记册对会话列表现查每位的状态。账是按会话记的,所以:办理会话是产品经理、不是 X大脑 —— 换 X大脑 窗口不牵动任何一条需求的账(验收那一刻三查、封版前对账、越界点名都按办理会话算,§八「办理会话」);办理会话要换人时由接手的会话跑一次改派命令,或由主控、项目经理指名改派。暂停着的线,今天没有机器的账;发现的问题完结时进那条需求的履历(§八「履历多两栏」),去没去向仍没有账。总账页是计划目录里的普通文件,不受治,没有机器核它新不新,开工注入也不列它。
组队(ADR-77):团队开关在项目设置的环境变量里。领队固定是主会话,一个会话一个团队,队友不能再建团队;队友就是名册里的执行体,派的时候点名用哪份定义并起一个名字。
适合组队的活:互不依赖、各管一块文件的并行工作(数据表定下来之后三端并行、逐域回归一域一个队友、多视角预审)。不组队的:有先后依赖的、改同一批文件的、改守卫的、正式复盘
(复盘者单独派、不带名字)。队友过的关与领队相同(写前拦截、需求对账),另加停下来那道关与「同时改同一个文件」那一关;放行仍只由关口决定,领队不替关口放行。
停队友用它的名字停(守卫据此记它放手了;用平台的任务编号停的认不出)。代价:用量随队友人数涨;实验特性;本机只有单窗口显示;断线重连恢复不了队友。
注册表:.claude/agents/_registry.md,registry opt-in(照 arch/business/_index.md),只存不可派生数据(豁免白名单等),禁复述 agent 职责(职责唯一源=agent 文件 frontmatter,防第二真相源)。
反漂移边界(诚实):承重墙=薄 agent(构造性根治);唯一未闭合维=第三方 skill 供应链:npx/plugin/cp 装升走 Bash 落盘,不在 L4 写保护谓词与脏队列覆盖面→"skill 变→绑定 agent 复检"只在下次全量检测/部署门保证,非当轮实时。要升级为实时须 Phase2(脏队列/部署门加 .claude/skills 面 + Task 派发新鲜度闸,属脊柱变更须单次授权 + verify-harness 金丝雀)。诚实上限:机械强制文件结构与"被认领",强制不了提示词语义正确,归独立复盘与验收、事后按项目标签抽看(同 arch 天花板)。
否决清单(经对抗审查证伪):① 逐依赖 specHash 指纹(agent→skill 是引用非派生,派生才需锁步指纹;逐字节钉=橡皮图章疲劳,真阳率≈0);② coordinator agent(与 x-feature-dev 双编排器冗余,编排留主会话/L2;官方现行默认允许主会话之下最多三层子代理嵌套,可由 CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH 调整,否决理由只在冗余这一条);③ x-meta-dev --domain=agent 专属签发(part1 长出 part2 专属代码路径,违框架禁依赖业务铁律)。X大脑不是 ② 否决的那一种(ADR-101):它不是被派出去统筹别人的执行体,是主会话自己的定义 —— 编排照旧在主会话与 L2,没有多出第二个编排者;这份定义被当成子代理派出去时,它照定义回一句不接派工就停。项目经理也不是 ② 否决的那一种(ADR-102;它是常驻会话):它不编排一条需求里的执行体、不放行,只管运行面的账、底稿与会话的起关 —— 编排照旧在产品经理会话与 L2,放行照旧只归关口。产品经理与另三位常驻同理:产品经理是办一条需求的会话,编排一条需求里的执行体是它的本职,不是又一个 coordinator;常驻架构师只出设计与审查,不编排、不放行。
生命周期(ADR-99、ADR-101):建或改执行体文件(.claude/agents/*.md)、改 agent 架构设计页,是改 agent 架构 —— 走需求流水线,没有专属工作流:落点单元 agent:overview,设计页由 Harness架构师写,执行体文件由元治理专家写(执行体目录受守卫写保护,办理会话在签字放行内写得进),封版用元治理的封版命令。新增或下线一位执行体,同一轮改设计页的名册表、执行体文件与注册表三处(NS-7、NS-8 各核一边;能派出去的新执行体文件还要写 model: inherit、不写 effort,只作会话用的(X大脑、项目经理、产品经理与复盘经理)在名册那一行加 data-main-session 标记、文件里不写 effort,由 NS-9 核)。改 x-agent 四件套(设计、条款、判据、执法)是改系统规范 —— 走 /x-meta-dev,落点单元是它自己的规范域。两种都照 §十七「五类需求入口表」。agent 文件本身变更由 L4 环3(--changed × x-agent glob)复检;新 skill 认领由 NS-4 全量点强制。
十六、测试放置与测试闭环(测试根 · 唯一运行器;ADR-55、ADR-57、ADR-58、ADR-61、ADR-62、ADR-63、ADR-64、ADR-65、ADR-67)
原则:测试跟着被测对象放;放在哪就由谁跑(按位置收床,不靠名单);一次性的探针与验证脚本放这条需求自己的施工区(签字之前放系统临时目录),不进仓库。临时的业务产品测试放仓根 x-temp/,测完即删:唯一运行器把 x-temp/ 当临时区,不收床、不查死链(bed-runner.js 的 HISTORY_RES);它不是 x-test/ 的一部分 —— x-test/ 只放业务端与内核母本的长期回归测试与部署门入口,与宪法的定义一致。
| 测试根 | 放什么 | 谁维护 |
|---|---|---|
.claude/skills/x-spec-checker/tests/<规范名>/ | 该规范的判据床(拿真检测器喂反向样本),以及只给这些床用的夹具与说明 | 改该规范的人(/x-meta-dev) |
.claude/skills/x-spec-checker/tests/engine/ | 检测引擎原子(词法、解析器、端名册)的床 | 检测引擎的维护者 |
.claude/skills/x-<技能>/tests/ | 自研技能自己的测试(四件套引擎、发布工具、移动端工具……);第三方技能按上游原样安装,它自带的 tests 不属于本仓测试体系 | 该技能的维护者 |
.claude/hooks/tests/ | L4 guard、收尾环、写证据台账的床 | 在签字放行内维护脊柱的办理会话 |
x-test/ | L5 业务端与内核母本的测试,按被测对象分桶:functions/<函数名>/(目录名 = 部署门注册表的键 = x-server 里的云函数名)、consistency/(几个对象之间的等值与一致性)、kernel/(内核母本 x-core/server/sys)、tools/(构建期工具 x-core/tools)、mobile/{core, biz/<域>, backends/<后端>}/(移动端母本,与 x-core/mobile 的容器逐级对应);根下只留部署门入口(run-deploy-gate.js + deploy-gate.json + 换空壳检查的预加载桩 deploy-gate-bite.js)与共享夹具 fixtures/ | 业务开发 |
x-test 分桶的判据(ADR-58):按被测对象分,不按写它的人或批次分 —— 桶就是被测对象在仓里的位置,测谁一眼可见,删谁时它的床跟着走。床文件名不改,只挪目录:散落在各处的裸床名全部继续有效。一段测试的判断依据里只要用到治理件(判据原文、检测引擎常量),它守的就是治理本身,归判据床目录 x-spec-checker/tests/<规范>/;只看业务代码的留在 x-test(首例:移动端网页 backend 行为床里三条拿引擎常量对账的臂,拆成 x-backend 的判据床)。报告脚本不是测试,归所属技能的 scripts/。桶名避开顶层物名与 sys / templates / build。
测试根的唯一真相源:工作区地图的名册「测试根」(§十八);检测引擎常量 check/constants/test-roots.js 加载时读它算出正则。四处同源消费,禁各自手抄:唯一运行器按它收床、判游离;引擎索引器按它把测试根排出扫描面 —— 夹具里故意写的违规永远不被任何判据判到;x-arch NS-COMMON-0010 按它判床点名位置;guard 的业务目录判定按它排除(测试目录与顶层物同名,如 tests/x-data/,不算业务源码;按仓根相对路径判,业务树里自建一个与测试根同名的子目录绕不过写保护)。业务源码判定本身也按仓根相对路径的第一段锚定(对路径任一段同名即中的话,发布档案备份目录里 x-release/<档案>/backup/x-harness/… 这类与顶层同名的子目录会被当成业务源码、托管下载落点全拦;换不成仓根相对路径的仓外、另一棵工作副本照旧按任一段判,不放松;本来就是相对写法的落点 —— 没有盘符、不以 / 开头、且没有以 .. 越出起点 —— 当作仓根相对、同样只看第一段,不回退到任一段判 —— 回退的话手敲相对路径会误拦;以 .. 越出起点的相对写法落在哪取决于当前目录,守卫不知道,照旧按任一段判 —— 把 ../<仓目录名>/x-admin/… 折叠成 x/x-admin/… 再按第一段判会放过它;按第一段判的前提是整条路径都是字面量(只含字母、数字、点、下划线、连字符、斜杠与盘符)—— $PWD/x-admin/…、~+/x-admin/…、<仓根>/$X/x-admin/…,以及第一段是字面量、后面某一段带变量的 docs/$A/x-admin/…(变量里装着 ..)—— 任一段算不出落在哪,整条就算不出,照旧按任一段判 —— 只要有一段不是字面量就不能当作仓根相对。守不到的一条(记洞不改):守卫按路径字面判、不解析符号链接 —— 在 x-release 下建一条指向业务目录的链接再往里写,字面上仍是 x-release;建链接本身是命令,归命令策略既有的判法)。
唯一运行器:node .claude/skills/x-harness-dev/scripts/harness.js --action=beds。按位置收床:测试根下的 *.test.js 都会被跑到(夹具目录、依赖目录与以「.」「zz」开头的目录不进)。筛选 --spec(住在该规范目录)/ --guards(守护该规范,含住在别处的床)/ --root / --suite / --only,--list 只列,--coverage --spec=<规范名> 对拍该规范每颗闸有没有床提到,--quiet 把每张床输出落 .claude/tmp/beds-last/,--jobs=N 指定路数(不写时缺省按整机预算开池,机制见下「跑床分道并发」)。一张都没选中按失败处理。跑床只经唯一运行器:要证明一张床「过没过」,只有经这个入口跑出来的结果算数 —— 跳过口径、残留检查、空壳对照、按张记账、每次跑床记一行,都只在运行器里做;要看一张床就用 --only 点它。直接 node 某张床不记账、不记行、不进耗时表,不能当通过的依据;直跑运行器与守卫都不拦,只是不被数到(数与拦的机器级办法归待立项目「同时进池」)。几条取舍(各有实测病历):
- 跳过不是通过:床输出里单独一行
#BED-STATUS: SKIP <原因>记为跳过;只有登记在运行器SKIP_EXEMPT名单(本机缺外部环境)里的记SKIP-EXEMPT、画 ⏭、不让运行器报红,其余跳过一律算没过,绝不并进「全部床通过」。 - 输出走临时文件、标准输入给空:管道收集会被挂着不退的子孙进程拖住、超时也杀不掉;收尾环床曾因此挂了两个多小时,改写文件后 55 秒通过。
- 仓库级锁、不点名:任何一次跑床都拿同一把锁(系统临时目录、按仓根区分,子进程经环境变量得知锁已由父进程持有);哪些床会动真仓,靠人工点名一定会漏。拿不到锁先排队:别处在跑就等,缺省最多等 45 分钟,
--lock-wait=<分钟>改上限,0 = 不等;等到上限仍被占才失败,持锁的进程已经不在的锁直接接管。 - 套件只认床头独占一行的
@suite <名>:入册必须是刻意的。选中整个assembly套件时写装配面新鲜度戳(格式与判定归 guard 的 assembly-face 模块),套件里任一张没通过(含跳过)写「未过」。发布时跑哪些床不按套件取,由被发布物推导(见下「外部闸门取床」);@suite mobile只剩手动选床的用处。 - 卫生检查只在不带筛选的全量运行里做,做了就计失败:别人的在途卫生问题不该让定向检查变红。带筛选的运行(按规范、按根、按套件、按名字、按面、按改动选床,含只列不跑)连查都不查 —— 它要拉全仓文件清单逐个看,照查就是每次定向跑床白扫一遍全仓;没查不等于没有,卫生问题由全量运行报。
- 只跑不新鲜的
--stale:选完床之后、起床之前,把账本里「对当前内容已经通过、该做的空壳对照也做过」的床挑出来不跑,汇总里写明沿用了几张 —— 全体床跑一遍里大半是对同一份内容原样重跑。认法只有一处:判定模块的面状态(收尾与封版认的同一份账本、同一个状态),状态是「通过」才沿用;从没跑过、内容变过、上次没过、跳过、登记豁免、还没做空壳对照、没咬住、床头写坏的,以及判不出状态的,一律照常跑。床里调了持锁函数、自报会临时改真仓的照旧跑(见诚实边界③)。登记在部署门的函数床按函数整体交给部署门入口,同一个函数下只要有一张要跑,这个函数登记的床都归到要跑的那边 —— 报成沿用的床必须是真的没起过进程。选中的全都新鲜时一张不起、不拿锁、退出码 0;一张都没选中照旧按失败处理(全都新鲜不等于没选中)。不带这个开关时选中多少跑多少。它只在判定口径区之外加了一步筛选,不改一张床「过没过、记成什么」;发布前测试与部署门不带它(发布不认旧记录、当场真跑);装配套件里有床被沿用时本次跑的不是整套,装配面新鲜度戳不写(戳的口径没动)。登记在盯状态名单上的床(ADR-103),它盯的路径一变旧「通过」就作废、这里照常跑 —— 认法仍是同一个面状态,没有另加一道(见下「盯盘上状态的床」)。
卫生检查:① 游离测试 —— 测试根以外的 *.test.js(按 git 视角:已跟踪 ∪ 未跟踪且未被忽略)没有任何运行器会跑到它,「有床没人跑」由结构排除;在册例外只有微信支付云函数(上游模板原样搬入,与第三方技能同类,被采纳的那张登记在部署门注册表);② 墓碑 —— 已迁出 / 已退役的旧路径(x-harness-dev/references/bed-tombstones.json)又冒出来,说明有人还在往旧位置写,新旧两份会各报各的绿;③ 床头「运行:node <路径>」必须是床自己的路径;④ 判据床文件名里写的规则编号必须真在该判据里、且床里写着(重编号后名字不会悄悄过期);⑤ 现行文件里写的测试床引用必须指得到东西 —— 床文件、床目录、以 .test.js 结尾的通配三种形态都认(只认完整的 .test.js 路径会漏掉目录形态的死链),占位写法与非床文件不在射程(历史记录不查 —— 需求履历也在内:它是钩子一次写成的封存记录,一条删掉某个测试目录的需求完结之后,履历里照实写着那个旧路径,当成死床路径报红会让全量跑床从此过不去;业务代码只报告不计失败,业务树由业务开发流去改 —— 只改注释不动业务架构指纹,但改的若是移动端包源仍要重新物化);⑥ 盯盘上状态的床名单对得上(ADR-103,运行器的 stateWatchProblems 问判定模块)—— 名单里点名的床盘上都在、名单读得懂:床搬家或删掉时名单没跟上,那一行就成了没人盯的空条目;名单写坏了照判定模块报的那一句报。只核点名的床在不在,不核该登记的床登没登记。⑦ 床的上游不盖记录(卫生检查常驻,每一次不带筛选的全量运行都核)—— 床头 @covers 与盯状态名单里的条目盖到地图里标状态或日志的路径(属性「记录」,§十八),就判不过并点名路径;盯状态名单里盯记录区的条目只许盯「在不在、是什么类型」(path),不许盯一层名字(list);记录区的路径前缀问地图,运行器里不写路径字面量。例外只有一张:只追加小床 records-append-only(它的本职就是对着版本库基线守决策记录只追加),例外名单只准删不准加,要加先报 X大脑 核准。
床不读真仓的记录:床的结论不该随别的会话签一次字、封一次版、提交一次就作废或变红,所以床的上游不盖记录、床不读真仓的日志 —— 要用记录就读夹具与假仓里的(记录 = 地图属性「记录」是状态或日志的路径,§十八)。两道核法:① 床不许把记录盖进上游,运行器的卫生检查常驻核(上面 ⑦);② 床不读真仓的日志,不设常驻的拦,交付时用日志换空对照查一次 —— 两份整仓副本同时整仓跑,一份原样,一份把地图里标日志的文件内容换空、文件留着,换空那一份红而原样那一份不红的床,就是靠真仓日志的内容才绿的,这样的床要为零;对照用施工区里的一次性脚本,不进运行器。列目录、核在不在、数名字不算读;状态类记录的真仓一致性核对是那几张床的本职(真仓那一侧另有全量检测与版本契约),不在此列。两张例外,读这些记录是它们的本职:站点床(治理站点本来就是这些记录的读者;它跑前跑后的真仓指纹只核站点源码与构建器,上游不盖记录)与只追加小床 records-append-only。守不到:以后新写的床不写明依赖、直接读真仓日志的,机器不当场拦,要等下一次跑日志换空对照才看得见;程序运行时拼出来的记录路径,卫生检查看不见。
要外壳的床:登记在部署门注册表里的函数级床加载真实云函数代码,而云函数的内核 sys/ 按零副本设计不在源码树 —— 单独启动当场找不到模块。唯一运行器不单独启动它们,而是按函数名调用部署门入口(它先用内核母本装配、跑完即拆),结果记回每张床;装配逻辑只有部署门入口一份,运行器不复刻。
外部闸门取床:部署门按 deploy-gate.json 登记的函数名取床,入口 x-test/run-deploy-gate.js 留在 x-test/(它跑的是业务代码测试)。入口的 --verify 另核床放置,规则从注册表结构推、不写例外名单:只被一个函数键登记的床住 x-test/functions/<该键>/ 或该函数自己的目录(上游模板随函数带来的测试);被多个键共用的住 x-test/consistency/;__kernel__ 的住 x-test/kernel/。发布时跑哪些床由被发布物推导:云函数传上去的是函数目录 + 内核母本,这些文件 → 测试面(判定模块 facesOfFile,只取直接命中)→ 这些面的全部床(选床复用唯一运行器的 selectByFaces),注册表登记的床并进来作「额外必跑」,推不出归属的床 fail-closed;四个静态出口按各自的输入目录同样推导(release/publish-tests.js),结论写进发布档案 checks。推导出零张照样记账、如实写 [] —— 零床不等于测过,只等于没有测试。床读了发布输入却没写 @covers,推导就看不见它(首例:治理站点构建器的床)。收尾环发现本轮改过装配面时,给出的命令是同一个运行器的 --suite=assembly,选中整个装配套件跑完即写装配面新鲜度戳。套件只由床头 @suite 标签决定:床放进测试根、打上标签即入套件,没有第二份名单(ADR-57)。测收尾环本身的 assembly-face 床(住 .claude/hooks/tests/)不入任何套件 —— 它测的是收尾环,不是装配面。
出包门:x-core/tools/manifest.js 命令行的 --bundle 与 --materialize 出包之前,先经 shipGate 按函数名调部署门入口当场真跑该函数登记的床(没登记的只跑内核级床);没过、缺床或跑床锁被占,一律不出包、退出码 1。它是写前拦截停着时唯一还在岗的「发布前测试」;只装在命令行这一层 —— 函数层给部署门入口自己装配内核用,装在那里会自己拦自己。它跑完到真正打包之间不再核目录指纹(脚本出口 deployer 会核),这一段靠写前的上传内容闸补,而那道闸同样依赖写前拦截挂着。
生命周期闭环:新建规范时,x-meta-dev 的条款书骨架「验证」一节自带 --guards=<规范> 跑床命令,架构页骨架写明床建在 x-spec-checker/tests/<规范>/;删规范时判据床目录随判据与条款书一起删(/x-meta-dev delete);删云函数时,x-module-del 按 x-server 的「侧 / 中心 / 模块」三层扫出函数(admin / client 两侧都查,侧名从目录读),扫描清单列出该函数的部署门键、随它整目录删的 x-test/functions/<函数名>/、住在别处的登记床与共用族床(只删登记)、以及治理文档里点名这些床的地方(架构页的测试床条目与正文、条款书、判据与注册表);执行脚本在 x-test 下只准整目录删 x-test/functions/<函数名>,其余按单张床文件删(分桶目录里住着别的对象的床),禁删共用件(部署门入口与注册表、共享夹具)。规范自检第⑤项:条款书「验证」一节里 node 指向的文件必须真实存在 —— 脚本退役、床搬家后照抄的旧命令当场现形。
改过的测试怎么证明仍咬得住(宪法 §六.7 · ADR-67):空壳对照 —— 一张床新建或改过(床自身或夹具变了),记「通过」之前,把它的被测对象换成空壳再跑一遍,必须变红;没有「咬得住」结论的床,收尾、定版、发布都不算它通过(状态 unbitten;做了但没咬住是 toothless)。
- 谁做:唯一运行器在床通过之后、记账之前做(
bed-runner.js的判定口径区,结论随床记进账本bite,带计划键);登记在部署门的函数床由部署门入口--bite做(运行器把--bite传过去,入口先对照、后记账)。收尾、VERIFY 不自己跑对照,只读账本里的结论 —— 没结论就是没通过,逼人去跑运行器。 - 空壳怎么造(唯一定义
test-faces.bitePlan,运行器与部署门入口只照计划执行):fn函数床,把被测函数的service.js换成导出都返回空对象的空壳;spec判据床,把该规范每颗非标闸的检测器换成恒返回空数组、标准写法一侧恒判合规,床@covers的代码一并掏空(按文件分辨);module其余床(守卫面的床在内),被测文件里的模块一律掏空(函数恒返回 undefined、数据清成同型空值、以主脚本身份运行时什么都不做),当文本读出来是空;推不出被测对象是none。spec与module都由预加载桩做,床拿到被测文件的每一条路 —— 加载、当文本读、复制出去 —— 看到的都是同一份空壳:床用copyFileSync或cpSync把被测文件抄进自己的沙箱(守卫床都把守卫整棵复制进沙箱再跑),抄出去的就是空壳(.js写一份被加载就记命中的通用空壳体,不是.js的复制那一刻算命中);床、守卫、守卫旁边的技能目录、设置、依赖都留在原地,不另造孤立的守卫副本、不设GUARD_HOOKS_DIR—— 孤立副本旁边什么都没有,床与守卫按「守卫目录的上一级」找技能目录、设置、依赖时崩成红,没牙的床也冒充咬住;桩自己换不成就让那一份照原样复制、不记命中,往「没过」那边错。空壳不抛错 —— 一抛错,没牙的床也会崩成红,就看不出它没牙了。对照期间禁止写被测文件,前后比被测文件指纹,变了按error报并点名(对照绝不能把真仓写坏)。 - 结论:
bites(变红且桩命中)与off(登记不做)算过;nobite(命中却仍全绿)、miss(桩没命中 = 床根本没碰被测对象)、none、error都不算。计划键 = 床自身 + 夹具 + 空壳范围,床没变时重跑沿用旧结论,被测对象改了不要求重做对照(那是「跑过」记录的事)。 - 不做对照只有登记制:运行器判定口径区里的
BITE_OFF(床 → 为什么不做);床头自己写@bite off不再算数 —— 那等于让床的作者自己豁免自己。改这张表就是改判定口径,全部旧记录作废,动静够大,登记不会悄悄发生。 - 老床不追溯:起算基线
guard/bite-baseline.json冻结空壳对照上岗时每张床的「床自身:夹具」指纹,与基线相同的老床不要求对照;床或夹具一改就要做。上岗时对当时全部床做过一次人工突变审计,是老床的事后证据,不是机制。 - 它证明的只是「咬得住」:空壳让被测对象什么都不做,一张真在查行为的床必然红;它证明不了床查得全、断言写得对 —— 那是诚实边界⑮与 harness-P-01。
- 改坏对照按点跑(比空壳对照更细的一问:被测对象少了这一处,床红不红):入口是
harness.js --action=beds --bite-list=<改坏清单文件>(--only按床或被改文件的路径片段挑点,--jobs指定路数,没写取整机预算与点数的小者)。计划目录里的一份改坏清单列出改坏点,一行一个、竖线隔开五段:床路径、被改文件(仓根相对)、类(模块 / 判据;写别的报「类只认 模块 / 判据」)、原文、替换成,#打头的行是注释,原文里要写竖线写成\|;原文必须在被改文件里恰好出现一次,零次或多次的点记「出错」、不记咬不咬住。运行器拿跑床锁,在沙箱里按点替换着跑那张床。造法沿用空壳对照现成的预加载桩:模块与判据(判据文档里内嵌着检测器)都由桩把被改文件的读取、加载与复制(copyFileSync、cpSync抄出去的那一份)换成替换后的内容,真文件原样;守卫面的床照模块一类做,不另造守卫副本;桩禁止写被改文件,对照前后比被改文件的内容指纹,对不上记「出错」并点名;登记在部署门的函数床不做(要动部署门入口)。结论三种:咬住(床变红且桩确实被命中)、没咬住(桩命中、床仍全绿)、出错。几路同时跑的只有准入册里判过干净、没自报持锁、不经部署门的床,其余一张接一张。只对账本里对当前内容已经通过的床做 —— 不是的先带--stale经运行器跑绿,否则它的点记「出错」、不入账。结论按床与被改文件此刻的内容指纹记在床账的改坏栏:每张床的记录上有一个points对象,键是<被改文件仓根相对路径>@<被改文件内容指纹前 8 位>#<点号>(点号是把「类 + 原文 + 替换成」拼起来取 sha256 的前 8 位),值是咬住、没咬住或出错,带时刻与点位简述;判定模块导出bitePointId(点号)、bitePointFresh(账里已有此刻床指纹与被改文件指纹下这个点的结论,就不用重跑,运行器打「沿用」并把账里的旧结论带出来 —— 旧结论是没咬住或出错的,沿用也算未过)与recordBitePoint(把结论写进改坏栏;账里这张床没有对当前内容的记录就没处记、抛),运行器只调用它们;账本读写没有自己的锁,靠调用方已持仓库级跑床锁。出错里只有内容决定的才记(原文不是恰好一次、类与被改文件对不上、桩没命中);超时、进程异常、床本身红、被改文件在对照期间被改了这类可能是一时的,只报不记(记了会把重跑挡住)。内容没变的点不重跑:被改文件一变,键里的指纹就变、点要重跑;床自己的指纹一变,整条记录作废重来,改坏栏跟着清空。改坏栏只记结论,不参与「通过与否」的判定 —— 收尾、封版、发布认的仍是空壳对照;这个动作不碰床账里各床的红绿与空壳对照、不写准入册,没咬住与出错退出码 1。
面族 → 闭环点与两个裁判:每一类面「在哪里被逼着对当前内容全过」—— 这决定了收尾对它是拦还是只提示;检测一列是这类对象的写法由谁判,空壳一列是它的床怎么证明咬得住。
| 面族 | 闭环点 | 收尾对它 | 检测裁判 | 空壳对照 |
|---|---|---|---|---|
规范面 spec:<规范> | 规范封版(统一封版命令:测试前置 + 检测前置 -t/-v 与增量检测) | 本会话直接碰过就拦,重也不降级(封版可以一直不做,不能让它只提示) | 元规范(-v)、判据自测(-t);判据床本身走语言层 | spec(掏检测器;@covers 的代码一并掏) |
| 函数面、一致性面 | 业务域封版(arch/seal.js 前置)与发布门(当场真跑) | 快面拦,重面只提示 | 语言层 + 该端规范层(--changed) | 函数床 fn(部署门入口 --bite);一致性床 module |
| 手机端包面、装配面、工具面 | 业务域封版与网页版发布(推导出的床当场真跑);装配面另有旧新鲜度戳硬拦(诚实边界⑫) | 同上 | 同上 | module |
| 内核面 | 只有发布门(内核不属于任何业务域,没有定版点) | 同上 | 同上 | module |
| 守卫面、检测引擎面、自研技能面 | 整个 HARNESS 封版(统一封版命令,三类面全过)与收尾 | 直接碰过、或经上游牵动(本会话改了检测引擎或运行器),都拦且不因「重」降级 | 语言层(--changed 自带) | module(守卫床在内) |
| 元规范 x-standard 的规范面 | 整个 HARNESS 封版(元规范是框架锁定面的一部分)与收尾 | 按规范面处理 | 同规范面 | spec |
| 没有测试的对象:后台、端业务模块、官网与治理站点的页面源码、数据表文档 | 无测试闭环点;发布时推导出零张床照样发、档案如实写 [] | 不判(零床的面不在射程) | 只有检测一个裁判:语言层 + 各自规范层 | —— |
执法模式为硬拦(MODE = 'block'),当前值由体检的「测试闭环」横切行派生,不抄进本文。
跑床分道并发(整机预算 · --jobs · 写追踪 · 准入 · 污染窗口 · 池里红 · 记一行 · 守卫主自测拆块)
一句话:并发数只由一份整机预算定 —— 跑床的命令行入口缺省按它开池同时跑,写 --jobs=N 才指定路数;运行器的进程内调用不带路数时缺省仍一张接一张(部署门入口就是这样),只有发布前测试在调用时明给同一份整机预算、同样开池。能一起跑的前提是「这张床不碰真仓」—— 这件事不靠人工点名、不靠床自报,靠运行器让每一张床都带上写追踪,按追踪看到的写入分道:证明干净的床进池一起跑,其余的独占;池里谁越界,同一段时间里跑过的床红绿都不算、独占重跑;池里红的绝不改成绿。它只决定「能不能和别人一起跑」,不决定「过没过」:每张床照样每次真跑,判定口径、跳过口径、空壳对照一个字不变。它也不是「认旧的干净结论」:追踪结论绑的是床文件加夹具、不绑被测物,池里又常开追踪,越界当场作废、独占重跑。
- 开关与整机预算:
--jobs=N,N 是 1 到 16 的整数,2 路、3 路也是合法的池。跑床的命令行入口(harness.js跑床那一段)不带这个开关时,取整机预算交给运行器当缺省路数的上限,运行器再与这一轮真要跑的张数(--stale沿用掉的不算)取小者。整机预算是按本机逻辑核数算的路数与按空闲内存算的路数(先留一块给系统与别的程序)两者的小者,夹在 1 到 16 之间;函数与系数只写在core/machine-budget.js一处:它在运行器的判定口径区之外、也不在运行器的上游组里,运行器自己也不问它,改系数不作废别的床的旧记录;系数的定法是机器静时整仓各跑 8、12、16 路、量出拐点,缺省取比拐点略小的保守值(宁可慢一点,也不把机器压死),只改这一处的常数;量出的拐点、选定的值和依据记在这一处的头注与决策记录 ADR-121 里,换了机器或床的数目与构成大变,按同样的定法再量一次。只选中一张时照旧一张接一张、不带追踪(封版前置逐张补跑因此一字不变);两张以上的小批照下面「小批不起池」的判断走。运行器的进程内调用不带路数,缺省是 1(部署门入口就是不带的)。--jobs=1与这个缺省逐字相同:不起池、不注入追踪、不学准入、不读写准入册与快照。N 大于等于 2 时,这一轮全部床都带写追踪,池里的、独占道的都带;判定模块(准入键与指纹都归它)或追踪器不在,运行器说明一句、退回一张接一张。接力命令里按改动跑床那一步、开发流 VERIFY、命令行全量起床时都不写死路数,吃命令行入口的缺省。发布前测试(发布库release/publish-tests.js,后台、手机网页版、官网、治理站点四个静态托管出口共用)走运行器的进程内调用,调用时经o.jobsAuto(连同o.jobsAutoNote)交进同一份整机预算:预算脚本在这一刻才载入(守卫另有一处也会载入发布前测试脚本,顶层多一个载入会连累它),读不出、或给的路数不是 1 以上的整数,就直接报错,不退回一张接一张(读不出是预算脚本坏了,该让人看见);运行器自己再与这一轮真要跑的张数取小者,只剩一张就是一张接一张、不带追踪。池只决定哪些床一起跑,每张床发布前照样当场真跑 —— 「全部通过才放行」「跳过不算通过」「测过的源码指纹前后比」一个字不变,池里越界作废独占重跑、池里红绝不改绿的规矩同样管它;池整体作废时退回一张接一张重跑,那一遍比不开池还慢。部署门入口(x-test/run-deploy-gate.js与函数床)不带路数,缺省仍是 1,照旧一张接一张、当场真跑:函数床要在真函数目录里装配内核,不合批。路数别手工开大:检测引擎自己还带着多路并行,池开得过大会与它抢核,收益未必再涨;缺省的预算取在拐点略下,再往上开收益很小。池和池里的床都在运行器已拿的那一把仓库级锁之内,不另拿锁。 - 准入:默认全部独占。能进池的床,是在路数大于等于 2 的一轮里独占跑通过、写追踪判它干净的床;跑红的床不学干净结论(只有已经写过仓的证据才记脏)。干净要四样都满足,缺一样都算脏:追踪器写过载入行;没写真仓(豁免只有两处目录前缀与床自己的仓内沙箱,见下);没起会碰真仓的非 node 子进程;起的 worker 线程都被注入了追踪。非 node 子进程里认得的干净只有两种:① 床起的只读 git —— 子命令取自追踪器自己的只读名单(
status、ls-files、rev-parse、check-ignore之类;它只许是守卫只读 git 名单command-policy.js导出的GIT_RO的子集,由一张床核),子命令之前的-c 键=值只放显示类、只读类的键(白名单:core.quotepath、core.excludesFile、user.name、user.email、commit.gpgsign=false、color.*、status.*等),能让 git 起别的程序的键(core.fsmonitor、alias.*、diff.external、core.pager指向别的程序之类)和子命令之后的-c、--output、-O、--ext-diff照旧判脏;追踪器给它注入不写索引的环境变量(不要求命令自带);它的工作目录在仓内、参数带仓根路径也不判脏;② 检测引擎起的、不带改写开关(--fix一系、--output一系、--init、--write)的 oxlint。接得上追踪的 node 进程另有两种:③ shell 形态起的命令,整串只是一条 node 命令(不含与号、竖线、分号、小于号、大于号、反引号、美元符、括号、脱字符、百分号、感叹号和换行)的,和换了环境变量的 node 子进程一样接上追踪,带这些符号的照旧判脏;④ 床里再起的运行器沿用外层这张床的令牌:外层追踪器照常给内层床注入追踪,内层床的写记进外层同一份日志、由外层这张床一并判(内层床自己的追踪读不到日志,既不判干净也不判脏)。别的非 node 程序(不在只读名单里的 git 子命令 —— add、commit、init 之类 —— 而工作目录在仓内或参数带仓内路径的,taskkill 与 PowerShell 之类)和建符号链接指向仓内的床,照旧判脏,不开白名单;工作目录在仓外(例如驱动在系统临时目录里建的小仓)又不带仓根路径的,本来就不算碰真仓。这份结论绑「床文件 + 夹具」的指纹、不绑被测物:被测物改了照样可以进池(安全靠池里的追踪兜),所以--stale挑出来的、被测物刚改过的床也吃得到并发;床或夹具一改,结论作废、回到独占。新床、改过的床、没有追踪结论的床一律先独占跑一遍,所以头一次起池的一轮全是独占 —— 那一轮在学准入、不提速。床头不许自报豁免(那等于让床的作者自己豁免自己,与空壳对照只认登记同一个道理);反过来,经部署门外壳起的函数床、自报会临时改真仓(床里调了持锁函数)的床、床文件读不到的床永远走独占道,不看也不学追踪结论;准入键算不出(夹具读不了之类)的床同样走独占道、不学结论。已进池的床若这一次的追踪不可信(没有载入行、日志读不懂等),这一次的结果只有第二道快照护着,准入结论作废、下一轮回独占道重新取。准入结论住.claude/tmp/ledger/bed-trace.json(与账本同目录,运行器写,先写临时文件再改名):每张床一条(绑定的指纹、干净与否、时刻、最近一次独占用时、为什么脏、是否登记独占),另有「追踪册」—— 任何床任何时候被追踪到写过的仓内路径(写之前没有、床跑完也没有的建了又删的临时路径不记;册子有条数上限,超了丢最老的)。准入册记口径版本:追踪器怎样判干净的口径一变,准入册版本加一,每条结论带它判时的那一版;运行器里一张口径表写明每一版是放宽还是收紧 —— 跨过的全是放宽时,只作废判脏的结论(放宽之后原来判脏的床可能变干净了,要重判)、判干净的不动;跨过收紧的,全部作废(原来判干净的床现在可能脏了)。 - 写追踪(
bite/下的预加载文件write-trace.js,床进程启动时预加载,同步、不依赖任何业务代码):① 载入证明 —— 一载入先写一行「已载入」,带本床令牌与进程号;运行器收床时没看到这一行就判脏、不发干净结论(预加载没载进去、床整体改写了NODE_OPTIONS时日志是空的,「没有记录」绝不等于「没写过」)。② 令牌 —— 每张床这一次跑一个唯一令牌,经环境变量传给子孙进程,日志每行带令牌、时刻、操作、路径。③ 落盘 —— 逐笔同步追加(床被超时杀也不丢),日志放系统临时目录、文件名唯一;追踪器自己写日志走启动时存下的低层原函数(打开、写、关闭),不走被钩住的入口,也不用appendFileSync(它在 Node 里会回头调导出对象上此刻的writeFileSync:追踪器自己钩过之后是无限递归,排在追踪器后面载入的围栏把那个入口换成只许写沙箱的版本之后,追踪器的日志被它拦下、写不出去);追踪器任何情况下不往床的标准输出和标准错误写一个字(站点床把两路输出拼起来当 JSON 读);日志写不进(目录没了、没权限)时,退出前补一笔失败标记,补不上就把日志整个删掉,运行器见到失败标记、或读不到载入行,一律判脏;围栏排在追踪器前面载入时日志本来就写不出去,这时不出声,运行器照没有载入行判脏;日志大到离谱时只读开头、按脏算(写这么多仓内路径的床本来就不该进池)。④ 覆盖面 —— 运行时枚举fs、fs.promises、FileHandle的全部导出,逐个归为读、写、不涉及,没归类的一律算写;写入口逐个直接钩,不靠只钩open与write(字符串形态的writeFileSync、appendFileSync、复制、改名、删除、建目录、fs.promises.*都不经过那两个低层入口),钩完同步 ESM 的具名导出;Node 升级新加了入口,对账床会红、不会静默漏。⑤ 子进程与线程 —— node 子进程经环境变量带上追踪器(调用方清空或剥掉预加载的NODE_OPTIONS也照补,嵌套运行器起的内层床因此仍在追踪里:嵌套运行器沿用外层这张床的同一个令牌,内层床的写记进外层的日志);非 node 的可执行文件,工作目录或参数落在真仓里的算脏(只读 git、不带改写开关的 oxlint、整串只是一条 node 命令的 shell 形态除外,见「准入」);worker 线程在构造处把追踪器并进去,并不进去的算脏;嵌套的追踪会话(被追踪的床里又用另一个令牌起带追踪的运行器会话,运行器自测才有;沿用外层令牌的不在此列)不覆盖内层环境,往外层日志记一笔标脏的起子进程,这样的床永远只走独占道。⑥ 盯父进程 —— 运行器没了床就退(否则运行器被杀之后,孤儿还在写真仓),定时器不拖住进程退出。⑦ 同一路径第一次被写之前的样子(不存在、目录、文件的短哈希)也记下,污染窗口里「有没有还原」靠它验。⑧ 记什么 —— 路径恒是被改的那个,另一端只供对照:复制只记目标,rename 与 link 两端各记一行各带写前的样子;递归建目录时,调用前仓内此刻还不存在的祖先目录也各记一行(写前的样子是不存在),自上而下,最后才记给定路径本身,已存在的祖先、仓外的祖先不记 —— 床建一棵探针树、事后整棵删掉,才判得出已还原;记的是「要写」不是「写成了」(删一个不存在的路径、建一个已有的目录也各记一行),先都按写算,宁可多判脏。 - 追踪里的豁免是两处目录前缀,加床自己的仓内沙箱。两处目录前缀都是床里正常调用留下的:引擎落射程缓存的目录
.claude/tmp/.scope-cache/,与床里再起运行器落床输出的目录.claude/tmp/beds-last/(文件名唯一),都含目录本身的创建。射程缓存写成目录前缀、不是只豁免一个文件:引擎落缓存是四笔(建缓存目录、写临时文件、改名两端),只豁免最后那个文件名,会把每张碰到引擎没命中缓存的床判脏;该目录里只有射程缓存一个文件,读缓存时校验和、版本、键任一对不上就当没命中,写坏了也只是少命中一次,并发写不坏。别的一律算写真仓,含台账目录、需求账与计划目录 —— 它们是别的裁判的判决依据与输入,没有哪张床该写真仓里的这几处;它们只在下面的快照里放过,因为那里要排除的是别的会话的编辑与运行器自己落的账。床自己的仓内沙箱:x-test第一层里按现成写法建的临时目录 ——zzharness-…-<进程号>、zzmeta-…-<进程号>(与运行器跑完自己清的是同一种认法,§八「清理归档硬控」④)—— 里面的写不算写真仓,两个条件都要满足:名字里的进程号在这张床的进程树里(追踪日志里有它的载入行,或就是起床的那个进程;床起的驱动之类子进程的进程号也认得);运行器读日志的那一刻这个目录已经不在了(驱动崩了、目录没删干净,这张床就判脏)。豁免按字面路径判、不解析联接;沙箱目录里起的非 node 进程(非只读 git、PowerShell、taskkill 之类),工作目录在仓内的仍判脏;其余在仓内的写照旧算写真仓。 - 一轮的次序与两道快照:池先跑、独占道后跑(池里的床按准入不该写真仓,先跑,它们若越界,池后那道快照当场就看得见;独占道里是还没证明干净的床,放在后面,它们留下的东西污染不到池)。追踪是第一道;第二道是快照,兜追踪看不见的写:轮首取一次,池后取一次,独占道后再核一次(只在这一轮学到了干净结论时才取)。轮首取不到 git 状态,第二道就没法核:这一轮不起池、也不学新的准入结论,全部床在独占道一张接一张跑。快照有两部分:
git status --porcelain -uall列出的每条路径加内容哈希(-uall因为默认把未入库的目录折成一行,往已有的未入库目录里加文件看不见;内容哈希因为已经脏着的受治文件被原地改,只比路径集合看不见);被忽略目录的清单,从追踪册派生 —— 凡任何床任何时候被追踪到写过的路径都在内,逐个核在不在、变没变。两次快照之间变了的路径必须有来历:这段时间里某张床的追踪里写过它(或它的祖先、子孙目录);会话台账的写证据(k:'w',带文件键与时刻)里有别的会话在这段时间写过它 —— 多会话的仓里,它们和床的越界长得一模一样;或者它属于放过的区域:追踪里的两处豁免前缀,加台账目录、需求账目录、计划目录(运行器这一轮自己按批落的账、准入册都落在台账目录里);这几处只在快照这一道放过。说不出来历的,处置见下「污染窗口与作废重跑」。独占道后那一次核的是这一轮学到的干净结论:解释不了的变化按修改时间落在哪张床的运行时段里,就只作废那几张床学到的结论;路径已不在、看不出是谁写的,这一轮学到的全部作废;修改时间都落在任何一张床的运行时段之外的,当别人写的、不连累床;各床的红绿不受影响。 - 小批不起池:池里各床的独占用时加起来,并发省下的时间抵不过起池的固定开销(池后一次快照、每张床取两遍指纹,开销是运行器里按实测估的常量),或者池里只剩一张,就并进独占道一张接一张跑 —— 开发期按改动跑的那几张小批大多如此。只许从池挪进独占道、不许反过来;挪进去的床照样带追踪、照样学准入结论;判定不变(床照跑、照记账),省的只是起池。
- 污染窗口与作废重跑:某张池里的床写了真仓,从那条路径第一次被越界写起,到它被还原、或到轮末为止,是污染窗口。窗口内跑过的池里的床那一次的红绿都不算,全部独占重跑,以重跑为准。越界的那张先独占重跑 —— 重跑能让它自己留下的残留(探针之类)被它收拾掉,后面的床才不在窗口里 —— 并登记独占(键是床文件加夹具:追踪再判它干净也不翻回去,床或夹具一改自然失效)并点名;重跑之后残留仍在(路径的样子与被碰之前不同,或还原不了判不出)的,这一轮记未过并点名残留,其后落定的各床不落账(残留在中途被还原了,之后落定的行照常记账):它们是在带着残留的环境里跑的。不能只按「时间重叠」作废:越界床崩在写与删之间(被超时杀),留下的残留会污染之后派发、时间并不重叠的床。还原与否用追踪写集合验:池收完后,逐路径比「第一次被碰之前」与「此刻」的存在与内容哈希(没还原的窗口,在独占重跑之后、之后每一行落定时各重核一次);认不出路径的越界(认不出的写、没归类的入口、碰仓的非 node 进程、没注入上的 worker)和写之前的样子取不到的路径,永远算没还原。三种情形整池作废一次并点名:快照多出来、追踪里找不到是谁写的、会话台账也排除不掉的变化;池协调器没交出结果;池后快照取不到。池里这些床改在独占道一张接一张重跑,本轮不再起池,不无限重试;整池因解释不了的变化作废时,独占重跑逐张盯着那几条路径,重跑里重写了它们(样子或修改时间变了)的那张床追到了,登记独占。
- 池里红:没被作废的池里红,独占复跑一次归因 —— 账上这一轮仍记红,绝不红改绿。池里红而独占绿的,登记独占(键同上)并点名,下一次跑才变绿,多走一轮,接受;池里红、独占复跑也红的,是床自己红,不是并发造成的。池里那次的输出另存一个名字,不被独占重跑的输出盖掉,留着归因。
- 输出与账:输出文件名用单调计数器加进程号,同一个进程里所有起床的地方(池、独占道、重跑、回退)共用一个计数器,追踪日志与池回传结果的文件同样用唯一名。池的结果走文件回传、不走标准输出(
spawnSync默认只收 1MB,超了会杀子进程)。床的指纹在派发那一刻取;复算前在做复算的那个进程里先invalidate()、比整条 sha,变了记 ERROR。落账按批原子写:池阶段处置完记一批,独占道每满一批或每个函数门记一批,每张床只记一次;中途断了(机器睡眠、会话超时),已记的批不丢,下一次带--stale只补没落账的。要做空壳对照的床(新建或改过的)排到轮末再对照再记:对照会把被测对象换成空壳再跑一遍床,夹在独占道中间会让第二道比对说不清。一轮收完兜底对账:结果里的床去重后恰好是这一轮要跑的床、各出现一次,且每张床恰好交给记账一次(跑在未清的残留里、没记账的除外);对不上点名并计入未过,以后改动引入漏记或重记当场露出来。池里的床用时照记,账本记录另带并发路数(这张床实际在几路的池里跑)与它最近一次独占跑的用时;重面(整面超过 5 分钟)的阈值求和时有独占用时就用它,免得被并发抬高的用时误触发「重面降级」。 - 每次跑床记一行(数得出并行度、CPU 占用和同一张床跑了几次):运行器每真跑了床(
n大于 0;--stale全都沿用、只列不跑的不记),就往.claude/tmp/ledger/bed-runs/<YYYY-MM-DD>.log追加一行 JSON。放在账本目录下的子目录里、后缀.log,不叫.jsonl、也不放在账本目录根上 —— 会话台账把账本目录根里每个.jsonl都当会话账读;同一个仓根里一次只有一个运行器在跑(跑床锁),追加不会交错;写入用进程内的文件写、不经守卫,目录由运行器自己建。清法照会话台账:写入时顺手把文件名日期早于 30 天前的.log删掉,只清这个子目录。一行的字段全必填、数值都是整数:v(格式版本)、t0(拿到跑床锁、真开始跑的那一刻,排锁等的时间不算进墙钟,免得并行度被稀释成假低)与t1(床全跑完、账记完的那一刻,卫生检查之前;都是毫秒时间戳)、jobs(池的路数;没起池是 1,小批并进独占道也是 1)、n(真跑了几张,--stale沿用掉的不算)、pool(真进了池的张数,池里作废后独占重跑的也算)与solo(独占几张:持锁、判脏、单独一张接一张跑的;二者之和等于n)、beds(最终结果里的床,一张床一次,沿用的不在内;仓根相对、正斜杠)、bedMs(最终结果的用时之和;池里作废重跑的取重跑那次)、cpu(这段时间整机 CPU 占用,0 到 100 的整数,取开跑和跑完两次os.cpus()的差)、sid(哪个会话跑的,取环境变量里的会话号,取不到是空串)、root(在哪个仓根跑的:仓根不在x-test/zz-work/里面写repo,在里面写copy:<计划目录名>/<副本名>)。读它的是过程复盘的耗时表(§八「过程复盘的耗时表与红旗」):跑床并行度 = 各行bedMs之和除以各行t1 - t0之和,跑床期间 CPU 占用 = 按t1 - t0加权平均的cpu,同一张床跑了几次 = 这条需求的行里beds出现该床路径的次数;真仓里的行按sid属于这条需求的办理会话认(含它派的执行体,同一个会话号),副本里记的行留在副本自己的账本目录里,耗时表在清理归档之前就地读这条需求施工区里各副本的那一份。专项已经归档的,归档把施工区副本整份删了,现跑的表读不到副本里的跑床行:跑床那几项(含由它们亮的红旗)以归档里收尾单第一栏「过程复盘」一节定格的表为准,别的段以现跑的为准;定格的那张是归档那一刻的,发布、归档、提交几段那时多半还没发生,显示「—」。两张表对着看,结论里写明各取了哪一张。只记经运行器跑的:直跑不记行(跳过口径、残留检查、空壳对照都在运行器里,直跑也记账就多了第二个裁判),所以耗时表的跑床各项是「按运行器记的行算,直跑的不在内」。命令行入口与进程内调用(发布前测试、部署门入口)都写,部署门入口的行jobs是 1,发布前测试的行是它取到的路数;换了判定模块或锁文件的自测演练不写(不然每跑一次自测就往真仓账里多写几行假行),自测要核记行本身的,明传runLog: true。写不进(目录不可写、磁盘满)只打印一行,不影响这一轮床的结论与退出码。 - 池放在哪:运行器
run对外仍同步 —— 池放进运行器自己的子进程(运行器被当主脚本起来、带池协调器参数就是协调器),盯着父进程,父进程没了就杀掉在跑的床自己退;父进程同步等结果,协调器崩了、它起的床成了孤儿时,只等它们自己收工(最多 60 秒)、不凭进程号去杀(进程号很快被复用),等满仍没收工的在报告里点名这几个进程号。池的逻辑写在判定口径区(VERDICT-CORE)里;bite/下的写追踪预加载文件是判定代码、受写保护;运行器的上游组补上整个bite/目录(见下「按张记录」),运行器自己的床守着「池调度与追踪注入的关键符号都在框内」。单张床的超时上限:带写追踪起的床(起池这一轮的独占道、池、部署门外壳)30 分钟,不带追踪的路径(--jobs=1、只选中一张、运行器进程内调用的缺省)15 分钟 —— 追踪给床里每一笔写、每个起的进程都加开销,机器一忙,整套守卫回归这样的重床就会顶到 15 分钟被误杀成红;上限只是防挂死的保险。 - 仍不并发的:登记在部署门的函数床不合批,仍一个函数一个函数交部署门入口、走独占道 —— 入口自己也记账,合批的红、回退的绿会把红洗成绿;入口代码不动,追踪经起入口进程的命令行
--require与环境变量进入。空壳对照仍在池外、排到轮末一张接一张做。 - 守卫主自测拆块:守卫主自测的驱动(
.claude/hooks/verify-harness.js)是一份顺序脚本,整套经一张床一次跑完太长,独占着一路墙钟,所以按组拆成几张薄壳床同时跑。驱动按组挑着跑:--groups=甲,乙只跑点名的组(按组表先后),--list-groups印组表,点了表外的名字退出码 2;组表写在驱动开头,每一组各有一个闸。床是这几张:原路径verify-harness.test.js一块(留给签字作废、清理归档、验收回话、定档排队与顶层围栏、施工区、车道上机这几组)、verify-harness-blk1到blk5五块(blk1 需求对账起头、复盘者、签字题、执行体与组队;blk2 零件用到才装、零件坏了、故障注入对照表;blk3 脊柱、静态托管发布面、命令行直接发布、新运作命令、路由闸、命令判定后段;blk4 命令判定前段、孤儿规则书、部署与 DDL 门及钩子、MCP 墙、剥离臂与代码推送面;blk5 联调与发布门、部署门总预算、射程缓存、开工注入),每块是薄壳加点名名单,点名自己那几组;往真仓里放东西的两组(种临时判据与条款书的h1-real、手建内核夹具的mg24)单拎成探针小床verify-harness-probe.test.js,持锁、永远独占;另有核对床verify-harness-groups.test.js,只读文件、不起用例。其余六块不持锁,进不进池照追踪的准入结论定(判干净的进池同时跑,判脏的留在独占道)。按组之间的依赖拆:共用同一批定义的组并进同一块(共用的定义挪到驱动开头一段、只是定义不带状态);共用同一条沙箱状态链的组并进同一块 —— 拆不开的两处是静态托管发布面五节(共用发布档案夹具、网站注册表夹具与床门桩文件的先后状态)和零件三节(共用一份守卫副本与两张缓存);只靠前一组留下的状态的两组,各在本组开头自己摆好那个状态。驱动自己建、跑完就删的目录全在x-test/下,名字是zzharness-<标签>-<进程号>(进程号是驱动进程的,驱动是床的子进程),各块互不相同,能同时跑。核对床钉着:各块点名的组合起来恰好是全部组,每组恰好一处闸,持锁的只能是探针小床;它的被测只有驱动,而驱动在空壳对照的永不掏空名单里掏不到,所以床头@covers点名各块床的源码,空壳把它们读成空、本床即红,空壳对照才有目标。不按改动挑块:守卫入口一次装全部零件,块床的被测文件仍是整个守卫,守卫一改,各块的旧记录一起作废。块床不手搭检测引擎、不新增把引擎整树抄进沙箱的写法。
守不到见诚实边界 ㉘、㉙;取舍与否决过的做法见决策记录 ADR-110 与 ADR-121(ADR-121 取代 ADR-110 里命令行入口缺省一张接一张的那一半与「干净」的两处口径);发布前测试开池见 ADR-123(取代 ADR-121 与 ADR-110 里发布前测试照旧一张接一张的那一半)。
测试闭环(按张记录 · 收尾新鲜度 · 发布绑定上传内容 · 写后复判;ADR-61)
一句话:测试不单独发版本号,跟着它守护的规范或业务域定版;「跑」和「验」分开 —— 测试在平时干活时跑,每跑完一张记一笔「对哪份内容跑过、过没过」;收尾只核这笔记录,所以不拖慢收尾;发布时不认记录,当场真跑,还要核对「测过的代码就是传上去的代码」。
测试面(唯一定义 guard/test-faces.js):每张床按「它测的是谁」归到一个或几个面,十个面族 —— 函数面 fn:<函数名>(部署门注册表登记的床,与 x-test/functions/<函数名>/)、内核面、手机端包面 mobile:<包>、工具面、一致性面、装配面(@suite assembly,文件清单仍归 assembly-face.js)、技能面 skill:<技能>、守卫面、规范面 spec:<规范>、检测引擎面。归属从目录约定与部署门注册表推出,不建名单;床读了别处的代码就在床头前 40 行独占一行写 @covers <路径>…(点名的路径不存在直接报错 —— 写错了就静默不触发,比不写更坏);一致性床没有 @covers 推不出面,报错。推不出面的床由唯一运行器卫生检查「无归属的床」计入失败。运行器 --face=<面或面族> 按面选床,--changed=<文件> 按「改这个文件会让哪些面的记录作废」选床。选床以带上游的「文件 → 面」反查(facesOfFile)为准:一个面的被测范围(算进指纹的文件)必须都能被这份反查反查回这个面,否则就会有某个文件一改、这个面的记录判旧,而按改动选床却选不到它的床(典型是改一份判据,技能说明那张床的记录跟着判旧,按改动选床却看不见它)。一张对拍床在真仓上核:每个面的被测范围里的每个文件,带上游的反查都得反查到这个面,零不一致才过,不设「已知不一致」的登记、也不留遗留。跑出不一致的修法只有两种:默认补反查(只会多选床、不会漏选,这些床的新鲜度本来就盯着那个文件,迟早要重跑);只有证明了床根本不读那个文件,才收窄被测范围。检测引擎技能自己的技能面据此只把床真读的 SKILL.md 与 scripts/ 算作被测;它的 references/(各规范的判据与注册表)归各自的规范面,assets/ 里的脚手架模板那张床不读,都不算被测。
按张记录:账本 .claude/tmp/ledger/beds.json —— 本机状态(该目录已被 .gitignore 排除;进版本库就会出现 clone 下来的假通过),写前拦截在岗时整个 ledger 目录受脊柱写保护,会话台账只读 .jsonl 不会误读它;写账本的判定代码(唯一运行器、空壳桩与对照、部署门入口)同样受脊柱写保护 —— 改它们就能让没咬住的床记成咬住、没跑的床记成跑过(部署门注册表不锁,那是业务开发要改的数据)。每张床一条 { sha, parts, status, ms, at, bite }(bite = 空壳对照结论与计划键;池里跑的床另带并发路数与最近一次独占用时,见上「跑床分道并发」):指纹 sha256 = 床自身 + 夹具(床的家目录里的非床文件,跳过以「.」或「zz」开头的目录:运行日志、沙箱与对拍台的 zz-tools、zz-fixtures,它们不算夹具,要靠床头 @covers 点名才让床的记录跟着作废)+ 被测文件 + 上游组,登记在盯状态名单上的床再加它盯的路径此刻的样子(见下一段「盯盘上状态的床」);上游组按面族挂 —— 检测引擎挂规范、技能、守卫、引擎面(这一组除引擎脚本目录外,另含工作区地图的引擎段数据文件与读取模块、地板、匹配函数三件代码,余段不在其内,见 §十八「测试面上游」),内核挂函数面,部署门入口挂登记在部署门的床,运行器挂全部;各组的目录与文件取自工作区地图的属性「测试面上游」、不抄在判定模块里;运行器组算 bed-runner.js 里 VERDICT-CORE-BEGIN / VERDICT-CORE-END 框出的区段,加 bite/ 目录整个(ADR-64:判定口径、跳过口径、跑床外壳,由运行器的维护者框定,运行器自己的床守着「决定结果的关键符号都在框内」;bite/ 里的空壳对照执行器、预加载桩与写追踪预加载文件改一个字,全部旧记录作废),bed-runner.js 框外的改动不作废任何记录;没有标记或标记不成对时退回整文件(宁严勿漏)。harness.js(只分发)与 test-faces.js 自己不在这组 —— 判定模块改指纹算法时床的指纹自然跟着变,「哪些状态算通过」是读记录时的解释、改了立即生效;三个整文件都算的话,运行器或判定模块随便改一行全部面就一起作废,收尾报文被淹没、每次都要全量重跑。parts 逐份记 8 位短指纹,红的时候能说出是哪一份变了。写者只有唯一运行器(每张床启动之前算指纹、跑完记)与部署门入口;读者是收尾环。跳过不算通过;登记过的「本机缺外部环境」由运行器转成 SKIP-EXEMPT(名单住运行器),它是第三态「豁免」—— 不算通过,收尾只提示不追讨(原因是这台机器缺东西,不是谁改坏了),封版与发布都不认,开发流 VERIFY 把它单独列出、不说「全过」。
床账跨根(造副本带账 · 换入收回):账是本机状态、每个仓根一份,施工区副本里跑出来的结论不会自己出现在真仓的账里;床账跨根让它们按指纹收回真仓,真仓里不必把副本里跑过的床从头再跑一遍。造副本时带账、补环境:真仓的床账 beds.json 与准入册 bed-trace.json 只读拷进副本的 .claude/tmp/ledger(来源不动;都先读得懂才拷,正被写坏的不带并明说;不进指纹清单;.claude/tmp 里别的文件与子目录一个都不带),副本头一轮不再重跑真仓早过了的床,进池的结论也是热的,副本里的 .claude/tmp 不建空。环境(都不进指纹清单):按名字不带的手机端包 miniprogram_npm(各端主包与分包)原样补回;依赖目录 node_modules 把来源仓根上那一层原样拷进副本(联接不带)—— 「副本在仓里面、顺上级目录就找得到」只对 require 成立,检测引擎找 oxlint 是按「仓根/node_modules/.bin」查的、不顺上级目录,副本里没有这一层,增量检测一碰 js / ts 就报「Oxlint 未安装」退出码 1,收尾环的床跟着红;其余各层 node_modules 不补(pnpm 的链接联接不带、拷了是断的,或体量很大),预览与执行都点名是哪几层、会让哪类床在副本里红或自报跳过,留到换入之后在真仓里跑;检测引擎要的 typescript 不在根层,预览与执行打印一句「在副本里跑检测时把环境变量 NODE_PATH 设成 <typescript 所在那层 node_modules>」,不另造一份。换入收回:换入帮手换入全做对了之后,同一个进程里拿运行器那把仓库级跑床锁(别处在跑最长等 45 分钟,与运行器等锁同一个数),让目标仓判定模块的 reclaimLedger 在真仓里重算指纹,副本床账里指纹和真仓此刻逐张相同的条目原样收进真仓(连时刻都不改),对不上的一条不收;真仓里也有同一指纹的记录时,红的算数(严重度 FAIL = ERROR > SKIP > SKIP-EXEMPT > PASS,副本更红的盖掉真仓的,真仓更红或一样的留着,不让一边的绿盖掉另一边的红);只动床账的 beds 一节,封版记录、部署门记录、准入册都不收。拿不到跑床锁、判定模块装不上、收回途中出错,都是换入照常成功、收回跳过并明说、真仓的账一个字不动,之后任何一次从这个副本换入成功时再收一遍;副本里没有床账就不收;换入有一个文件没换对、被拒、restore 都不收;预览只说一句「执行时会收回」。收回只认指纹逐张相同 —— 床、夹具、被测文件、上游任何一份在副本和真仓之间不同,指纹就不同,不收;缺环境的床在副本里本来就红或自报跳过,没有缺环境却收成绿的路。收回的是账里的结论,不是文件。判定模块里账本的读写没有自己的锁:读-改-写靠调用方已持仓库级跑床锁,写用临时文件改名不留半截(改坏栏的两个导出和收回同此)。副本里的床账与准入册、检测射程缓存照真仓写保护(§八「项目自带」②的例外),副本里的账只有运行器等脚本在进程里写得了,收回的结论因此不比真仓自己记的更好改。
盯盘上状态的床(ADR-103):有些床的检查直接针对真仓库盘上的情况 —— 查某个路径在不在、某个目录里有哪些东西(执行体目录下有哪几个文件、各端与母本包源根在不在、几个真函数目录在不在),而这些路径不在床自己的指纹里:路径变了,账本里的旧「通过」照样算数,收尾、补跑、体检、三查、封版都沿用(看板规范那张床盯计划归档目录时,就这样把一条该红的死条目藏过一天)。守卫目录里有一张名单 .claude/hooks/guard/state-watch.json,写明哪些床盯哪些路径:每张床列几项,一项要么是一个路径(path,盯它在不在、是文件还是目录),要么是一层通配(list,只用 *、一个 * 只在一段里匹配,盯它此刻匹配到哪些名字),每项带一句为什么盯它。名单上的床多记一样东西 —— 它盯的路径此刻的样子(不读文件内容),这一样进它自己的指纹(分项里多一份 state)。路径一变,这张床的旧「通过」在收尾、补跑、体检、三查、封版各处同时作废,原因写成「盯的某某变了」(刚登记进名单、刚从名单拿掉的,原因各写一句);名单以外的床,指纹完全不变。「只因盯的路径变了而作废」= 床、夹具、被测文件、上游都与记录相同,只有盯的状态不同;很早的、没记分项的旧记录说不清,不算。名单从被判的那个仓根读:文件不在当空名单,写坏了判定当场报错(收尾记成基础设施异常,不放过)。谁来重跑:收尾环遇到这种床不算到任何会话头上,单凭它不拦、只提示 —— 路径多半是别的会话、别的需求挪的(搬一份计划进归档、加一份执行体文件),拦下的往往不是挪它的人;重跑落在封版那一关,封版命令当场挑出这种床交唯一运行器重跑(见下「封版的测试前置」)。名单收哪些床:检查真仓库盘上的路径、而那条路径不在床指纹里的床;盯的路径本来就在床自己的指纹里(被测文件、夹具、@covers)的不收 —— 发布流水线床就是这样;只拿真文件当样本、看内容的床不收;床里调了持锁函数、自报会临时改真仓的床本来就每次重跑(补跑时不沿用它们),也不收。盯的路径落在记录区(地图属性「记录」是状态或日志)的,只许盯它在不在、是什么类型(path),不许盯一层名字(list)—— 记录区里的名字随签字、归档、提交天天在变,盯名字的床跟着天天作废;卫生检查 ⑦ 核这一条。名单住守卫目录:受脊柱写保护,也是整个框架锁住的内容 —— 改名单属脊柱文件(办理会话在签字放行内写得进)、要升整个框架的版。床本身一行不改,也不要求床头声明什么。名单上新登记一张床、或改了它盯哪些路径,这张床的旧记录作废一次,在下一次相关的封版里补跑。名单里点名的床盘上没有了、名单写坏了,唯一运行器的全量卫生检查报出来、计入失败(见下「卫生检查」⑥)。守不到:① 名单靠人维护 —— 新床盯了盘上的状态却没登记、床改了盯的路径而名单没跟上,都照旧沿用旧结论(卫生检查只核点名的床在不在,不核名单全不全);② 只看路径在不在、有哪些名字,不看文件内容;③ 依赖整个仓库的床(闭环床、站点床这类,见下诚实边界 ③)没法按路径记,不在名单上;④ 两次封版之间没有人主动重跑:路径变了之后床只是不新鲜,要等有人补跑或下一次封版;⑤ 整个框架封版只核守卫、检测引擎、技能三类面的床 —— 名单上的规范床要等那份规范自己封版时才被重跑,业务域的床等那个域封版;⑥ 封版前的需求对账排在测试前置之前:用例点名的床若在名单上、只因盯的路径变了而作废,第二查先按「用例没闭环」拒封,轮不到当场重跑 —— 要先手跑那张床;⑦「封版挑床 → 唯一运行器重跑 → 记进账本」这一整条链,没有一张床从头到尾验过(判定模块床的封版前置那一组只走到收尾判定,封版命令床在进程内调封版、用假运行器核重跑的命令行);⑧ 名单文件被删掉就当空名单,判定与卫生检查都不报 —— 兜着的是版本契约:它是整个框架锁住的文件,删掉当轮在它上面报红。
收尾「测试新鲜度」(规则 + 分级):① 测试记录单独记账,不复用文件的「已复核干净」结论 —— 用本会话【全部】改动;账本还没建立 = 一张床都没跑过,照常判(不然删掉账本就等于关掉了测试这道闸)。② 归属(宪法 §六.6):记录作废的原因全是别的会话的改动 ⇒ 只报归属、不拦本会话;面里混着别的会话的改动而没过,两边都报;原因是无主改动(台账里没有任何会话的写证据,如手工编辑)或已离开工作区的改动(谁的在途改动里都没有,多半已提交)⇒ 只报、不拦本会话,定版与发布会当场核;从没跑过、新建或改过还没咬过的床,看床文件本身在谁的在途改动里 —— 在别的会话名下就不拦本会话,不在任何人名下就归碰了这个面的人去跑。③ 分级:快面每轮拦;重面(上次实测整面超过 5 分钟,池里跑的床按它最近一次独占用时求和,见上「跑床分道并发」;按记录自动判、不手写名单)只提示 —— 守卫、检测引擎、自研技能与规范面四类不因「重」降级(规范面在内:封版可以一直不做,不能让它只提示);只经上游牵动的面只提示,框架面除外:本会话改了检测引擎或运行器而牵动的守卫、技能面照样拦,它们没有别的闭环点。只因盯的路径变了而作废的床不算到任何会话头上:单凭它不拦、只提示,不分哪一类面(见上「盯盘上状态的床」:它们的闭环点在封版,封版当场重跑)。执法模式是 test-faces.js 的常量 MODE,为 block(ADR-67):依据是可复现的证据 —— 切到硬拦之前用硬拦模式对当时全部会话的台账干跑一遍判定,零误拦;判定出错按基础设施异常 fail-closed。MODE 住脊柱、刻意不设环境变量开关 —— 一个变量就能关掉的闸等于没有闸。装配面的旧新鲜度戳仍并存,并入按张记录归回归清单(诚实边界⑫)。
发布绑定上传内容:上传指纹 fnDirFingerprint 只有一份(按名字逐层排序、喂「相对路径 + 原始字节」、只跳顶层 sys/ 与任意层 node_modules/、测试文件不跳 —— 支付模板的测试随函数上线),与出包工具的复制口径一致,仓库函数目录与仓外出包目录算出同一个值。部署门入口跑完记 recordFnFace;写前拦截(床门、内核装配闸之后)、写后复判、脚本发布出口都用 uploadTested 对实际上传目录比。内核那一半:传上去的是函数目录 + 装配进去的内核,recordFnFace 另记跑床之前的内核母本指纹 kernelPrint(x-core/server 全部文件,按路径排序喂「路径 \0 原始字节 \0」,sha256;直接按目录走,不依赖检测引擎在场),uploadTested 对五文件形态的函数核「母本现在 = 测过时那一份」(写前拦截另有一道核「上传包里的内核 = 母本现在」,两道合起来才是「传上去的内核测过」);没有内核指纹的旧记录不算测过;测试期间内核母本被改,这次记为没过。上传档案闸(四种档案同一个要求):静态托管上新内容(assets / cutover)的发布档案 checks 必须写明 —— beds(推导出的每张床与结果,零张写 [],每张都要 PASS,跳过与登记豁免都不算)、faces(推导出的测试面)、inputPrint(发布输入的源码指纹);治理站点另要 verifyDist 为 pass。没有 checks、形态不对或 kind 认不出一律拦;回滚上传传的是备份的线上原样,不要求。源码在准备档案之后又变,由发布库的备份与上新文件两个检查点当场比 inputPrint,守卫要求那两个检查点已过;档案本身受写保护。
写后复判与开闸感知:写前拦截停着(手动开闸)时,云端写操作照样执行。写后钩子对每次 cloudbase 工具调用用写前的同一套判据再判一次,判为本该拦的记一笔、收尾报红一次;Bash 同样复判:命令行直接发布(tcb / cloudbase 的发布子命令 —— fn deploy / create / delete / code update、hosting deploy / delete、run / cloudrun / framework / app deploy 与冒号写法;剥 npx 等包裹词,node 直接跑 CLI 脚本、npx @cloudbase/cli 也算,bash -c / cmd /c / powershell -Command 里包着的向内再判一层)记一笔、收尾报红一次;同一份识别(command-policy.cloudPublishOf)在写前整条拦下(写前拦截在岗时),只读子命令与网关路由不在射程;收尾每轮提示写前拦截是否停着;体检 L4 核对三个钩子键真挂着(开闸时如实显示「停着」;只看配置里有没有 hooks 对象的话会照样报健康)。守卫主自测经薄壳床(原路径 .claude/hooks/tests/verify-harness.test.js 一块、verify-harness-blk1 到 blk5 五块、探针小床 verify-harness-probe.test.js、核对床 verify-harness-groups.test.js;拆法见 §十六「跑床分道并发」)进唯一运行器、归守卫面;判定模块自己的床是 test-faces.test.js。
体检与闭环验证带测试维度:六层体检多一行「测试闭环」(横切,不是第七层):收尾新鲜度的执法模式、账本在不在、无归属的床、各面新鲜度计数、命令行发布拒绝名单挂没挂、封版起算日 —— 判不正常只看确定的两样(账本缺失、有无归属的床),面没闭环是日常状态只报数;有测试面不新鲜时这一行下面多印一行,写明怎么只补跑不新鲜的(运行器的 --stale),没有不新鲜的面就没有这一行。各面新鲜度的计数用判定模块里一个只给体检用的批量函数一次问完:账本整读一次,判定上下文开头重建一次,按文件去重哈希的记忆是批量期间才生效的私有表(平时为空,结果与不批量时一样),挂在取文件指纹的函数上,不碰闸共用的全局缓存;批量函数只给体检用,收尾、封版、三查、接力用的那几个函数不经它(函数体里不出现批量函数的名字,一条静态断言读源码钉着),所以闸看到的仍是当场的内容。三处抛错的语义与逐面问逐字相同:单面或单床抛错只让那一面记不新鲜、不连累别的面;推不出归属的床仍算无归属(它直接决定体检这一行判不判正常);批量整体抛(账本坏等)或批量函数缺席,体检退回逐面问,结果与逐面问一致,不吞、不改判。版本契约的全量审计是判决依据,不在这里去重;体检报告里不打用时(行数有床钉着)。体检是时点快照、不是闸,见诚实边界 ㉗。闭环验证加第 ⑤ 步「收尾 → 封版 测试链」:只读核规范封版前置、业务域封版前置、收尾封版复核三处都接在真仓上(判的是接没接上,不是此刻过没过)。
检测裁判的同一套规矩(ADR-67):测试守的四条规矩,检测这边同样守 —— ① 结论随上游作废:会话台账里的「查过干净」结论带判据组指纹(检测引擎脚本 + 全部判据与同前缀注册表,session-ledger.detectPrint),判据或引擎改一个字,旧的干净结论不再算数,部署门重新挡、下一轮收尾重查;② 跳过不算通过:四个编译检查器在工具没装、缺配置时返回「不算通过」并报 compile-tool-skipped(没有文件要查仍是通过 —— 没东西要查不是跳过);③ 读得懂才算数:oxlint 1.x 的报告是对象形 { diagnostics },读不懂、或退出码非零却一条错误都没解析出来,一律按错误报(只认数组的话全仓会读出零错误);④ 语言层接进增量检测:--changed 对本轮 js/ts 改动跑 oxlint,只有语法解析失败算错(默认规则全是警告级,警告不判失败),于是收尾、VERIFY、部署门都带上它。两个裁判在收尾分栏报、分开记账,见 §八环3。检测的「咬得住」由判据床守着(判据床本身有空壳对照),语言层的检查器由引擎床 tests/engine/compile-checkers.test.js 守着。
诚实边界:① 本机记录可以被故意伪造(改 JSON 即可):这套设计防的是忘记,不是故意绕过;② 按位置推的被测文件会漏掉「床读了别处的代码」,@covers 补、全量跑兜底;③ 在真仓库上跑的床(闭环床、站点床这类)结论依赖全仓内容,指纹只覆盖判据、床与夹具;运行器的 --stale 沿用的就是这同一份记录 —— 其中自报会临时改真仓的床(床里调了持锁函数)照旧重跑,在真仓上跑却没自报的照这条边界被沿用,把关与收尾、封版认账本时一样、没有更松。收窄的一块(ADR-103):只盯几条路径在不在、有哪些名字的床登记在盯状态名单上,那几条路径进它的指纹、变了就作废,封版当场重跑(见上「盯盘上状态的床」);没登记的、依赖整个仓库内容的,照这条边界被沿用;④ 测试全过只证明「对当前内容跑过」,证明不了「测得对」;⑤ 写后复判看 cloudbase 工具与 Bash 的命令行直接发布;它事后拦不回来,只保证不静默。cloudbase 工具这一路,写前拦截不是确定在岗时,部署门两臂(待检范围里没复核的改动、版本没封)连同运行时配置绕过、上传目录缺内核或会被剥掉都补判 —— 与写前走同一份代码(§八 环2;守卫主自测 PU14、PU16、VG2 守着);联调还是正式发布也在补判之列(正式发布被在办需求签过字的落点表盖住的,补判成本该拦)。真不补的是四样:写前拦截确定在岗时那四类(写前已拿同一份输入判过)、资损域回归床(写后只判不跑测试床)、回滚与清理的仓库状态(写前写后都不看,§八 部署门 d)、Bash 的命令行直接发布(只认出「这是一次发布」记一笔,不对它跑部署门那几臂)。拒绝名单(permissions.deny)由 Claude Code 权限系统执行、与写前钩子无关,写进即生效,但按前缀匹配,npx、node <CLI 路径>、cmd //c、全局参数前置都能绕开,只作软兜底 —— 主闸是写前的结构化识别(写前拦截在岗时生效)与写后复判;挂不挂拒绝名单由用户处理,体检如实显示;⑥ 登记豁免(SKIP-EXEMPT)是第三态:收尾只提示不追讨,封版与发布(上传档案闸要每张 PASS)都不认,VERIFY 单独列出;豁免名单是运行器判定区段里的常量,加一条就是改判定口径,没有单独的审批闸;网页版的逼真度床(x-backend/replica-fidelity)登记为豁免,为的是没装微信开发者工具、或没下载过那个版本基础库的机器不恒红(豁免名单里那句原因:「本机没装微信开发者工具,或没下载各端调试用的那个版本的基础库」)。它写了 @covers(注册表、复刻件源码、两端的基础库配置),网页版发布推导得到它、当场对拍,而发布不认豁免 —— 本机缺那个版本的基础库包,网页版就发不出去(用户定的);代价是网页版发布推导多了 spec:x-backend 一整面(它的判据床一起当场跑),两端配置文件里任何一个键改动都会让这张床的旧记录作废。它照各端开发者工具的调试基础库版本拍 —— 线上真实版本由微信后台最低基础库设置与用户客户端决定、不在仓库里,调试版本只是离它最近的代理(x-backend ARCH-C01 刻意不把它写进判据,床只拿它挑跟哪个包对拍);端一换调试版本,就得先对新版本重新对拍、改注册表基准,才发得出去;⑦ 开闸期间云函数代码推送只剩出包门与写后事后报红,发布档案目录没有写保护;⑧ 没登记在部署门的函数按函数目录推导它的床,推导出零张照样记账;后台与官网按被发布物推导测试,推导出零张时档案如实写 beds: [] —— 零床不等于测过,只等于没有测试;零床的面收尾不判;⑨ 网页版与静态站点的产物与测过的源码之间,由档案的输入源码指纹 inputPrint 与发布库两个检查点绑定;产物与源码之间仍是同一进程先测后建,没有逐文件对拍;⑩ 空号:这一项守得到 —— 脚本发布给了 --skip-validate 就拒(x-deploy NS-SERVER-0003)。⑪ 开闸期间写后复判认旧记录:它拿账本里这个函数最近一次「测过」的记录比函数目录指纹与内核母本指纹(内核一起锁);记录之后床改了,这次推送照样判成「测过」;写前拦截在岗时当场重跑,没有这个问题。⑫ 装配面临时双账:装配面的旧新鲜度戳(.claude/tmp/assembly-beds-stamp.json,装配面自己的指纹)与按张记录并存,戳不在台账目录的写保护之内;执法模式是硬拦,并入按张记录归回归清单 —— 宪法「按内容记账」对它成立,「一份口径」对它暂不成立。⑬ 放置规则的机器闸只到「推不出面」:x-test 里有三张移动端床的几段断言以判据原文为判断依据(读判据文件、抽出检测正则再对拍交付物:mobile/core/mobile-auth-ioc、mobile-preload-ioc、mobile-tabbar-ioc),按 ADR-58 的分桶判据它们守的是治理本身,应拆进判据床目录 —— 首例(移动端网页 backend 的三条臂)拆了,这三处没拆。⑭ 收床的候选目录清单写了两份(唯一运行器与判定模块各一份),测试根谓词虽只有一份,新增一种测试根位置时两处要同批改。⑮ 咬得住不等于测得全:空壳对照已是全部面族的机制(见上「改过的测试怎么证明仍咬得住」),但它只证明「被测对象什么都不做时床会红」—— 床查得全不全、断言对不对、边界用例有没有,它看不见;逐闸覆盖也只证明「有床提到这颗闸」。起算基线里的老床不追溯(空壳对照上岗时那次人工突变审计是它们仅有的证据);空壳桩打得到同步读写、require 与同步复制(copyFileSync、cpSync 抄出去的就是空壳),异步读与异步复制、非 node 子进程、起子进程时洗掉 NODE_OPTIONS 的打不到 —— 打不到判 miss、不算过,逼着补适配器或登记不做,不静默放过。⑯ 定版点的空白:内核母本不属于任何业务域(它冻结在业务总览的无主业务代码里),它的测试的闭环点只有发布门(见下方「面族 → 闭环点」);元规范 x-standard 随整个 HARNESS 封版。⑰ 空号:这一项守得到 —— 封版记录只有封版命令写得出,收尾复核逐项对封版记录,手写、手改都拦(见下「封版的测试前置」里的「封版记录」与收尾「封版复核」)。⑱ 归属偏宽:记录因上游组变化而作废时,归属按整组文件判,别的会话改了上游也可能被算成本会话的;无主改动与已离开工作区的改动单独判(守卫床 J10–J12 守着),「整组」这一层仍偏宽 —— 执法模式已是硬拦,拦错人时报文会写出是哪一份上游变了。⑲ 宪法 §七 的测试禁区(测试面划分、收床与记账、测试指纹算法、收尾执法强度及其切换状态、空壳对照的造法与豁免名单)列在 x-governance 条款书 ARCH-A03 的下层内容清单里,其中只有执法强度的切换状态有可抓的词形:「试运行」已进快照词表(NS-COMMON-0002,紧挨「测」「尝」「调」的复合词除外);「只提示」「硬拦」这类说法仍不在词表,其余四项没有形态可抓,靠人审(改词表走 /x-meta-dev)。⑳ 写前拦截停着(开闸)时,两个裁判在写入那一刻都不在岗:剩收尾、定版、发布三处,外加写后事后报红 —— 开闸期间写进去的错,最早在收尾才看见。㉑ 微信小程序包在本体系之外:由用户在微信开发者工具手工编译上传,没有发布门、没有「传上去的就是测过的那一份」核对;它的四件套母本与网页版同源,网页版发布时推导出的床是它仅有的间接覆盖。发布登记里它那一格记「在体系之外发」、不算进该发的格(数据表同此)。㉒ 没有测试的部分只有检测一个裁判(后台、端业务模块、官网与站点页面源码、数据表文档,见面族表最后一行):它们「写得合不合规」有人判,「行为对不对」没人判,设计里如实写着,回归逐域复审时补。㉓ 本机账本与会话台账都能被故意改写(改 JSON 即可):两套记账防的是忘记与手写,不防故意绕过 —— 与①同一条边界,写在这里是因为检测结论从此也进了同样的账。㉔ @covers 点名的文件不存在的床,收尾只拦本会话写错的:别的会话写错的、谁的在途改动里都没有的,只报不拦。机制:反查表与业务域找面用宽松读取,写错的那一条剔掉、其余照样进推导(发布推导推得到这张床);算这张床的指纹仍用严格读取,真跑时当场报错,发布因此被拦而不是漏床;唯一运行器的卫生检查点名写错的床;收尾判定里这种床只判它自己「坏了」,按床文件与缺失路径归属,不把整轮判定抛成「判定不可用」—— 否则别的会话写错一张床,碰到它点名文件的每个会话都会被整轮拦死、还说不出是谁弄的;封版与业务域前置同样给理由而不是抛。㉕ 空号:这一项守得到 —— 规范封版前置另收「床头 @covers 点名本规范面被测文件(判据与同前缀注册表)」的床,它们同样要对当前内容全过(x-surface 封版时,逼真度床就在前置里)。㉖ 空号:这一项守得到 —— 收尾复核认框架变更历史,第一节两行指纹必须等于守卫台账里的封版记录(键 framework:harness@版本),手写、手改、封过版后删掉都拦;守卫床经收尾环的入口验它(K7b),不直接调判定函数(那样会绕过收尾环调用之前的那层过滤)。㉗ 体检是时点快照、不是闸:六层体检里「测试闭环」那一行读账的窗口等于一次审计的时长,审计中途别的会话改了文件,「新鲜」计数会有偏差;偏差翻不了体检的结论(那一行判不判正常只看账本在不在、有没有推不出归属的床)。收尾、封版、三查这些闸用的函数不走批量问法,各自判当场的内容。㉘ 跑床分道并发的守不到(机制见「跑床分道并发」):非 node 的子进程,追踪只按它的工作目录与参数判,它真写了什么看不见:工作目录落在仓里、或参数里有仓根路径的算脏、不进池(宁可少并发,不冒假干净;只读 git 与不带改写开关的 oxlint 除外,见「准入」);工作目录在仓外、参数里又没有仓根路径,却用相对路径往仓里写的,追踪这一道看不见,交第二道快照;追踪钩的是 Node 的 fs 入口,看不见的有:原生扩展、WASI、直接调底层绑定、node:sqlite、堆快照与诊断报告这几处输出、编译缓存目录;经 fd 写而那个 fd 不是在本线程里带写意图打开的(跨线程传来的、继承来的额外 fd)只能记成认不出路径,只会多判脏;路径别名(8.3 短名、subst 盘符、事先存在的目录联接或符号链接,经它们写进仓内)不解析;主线程被同步死循环占死时盯父进程的定时器不触发(由运行器的超时兜);只记调用里给的那个路径(递归建目录时仓内此刻缺的祖先目录除外,那些按解析后的路径找、各记一笔;带 .. 的相对路径里 Node 顺带建出来的中间目录不单独记,但总在已记的最上面一级之下,事后 rm -r 那一级照样还原得了;cp 与 rm -r 里的子文件各自不记);同一个 fd 同一个入口 250 毫秒内的后续写只记第一笔(路径在打开那一笔已记全);只在 Windows 加 Node 22.18 上验过,Node 升级新加的入口由对账床先红;这几样靠第二道快照兜,兜不住的一类见下。追踪器判「NODE_OPTIONS 里已经有追踪器」用路径子串匹配:床自己在选项里带上追踪器路径字样(比如塞进 --title=)就能让追踪器不再往子进程补自己,即床想逃过子进程注入是做得到的 —— 床是自家代码、不是威胁模型,意外撞上的概率很小;围栏一类的预加载排在追踪器之前载入时,追踪器存下的低层入口本身就是围栏版,日志在原理上写不出去,这时不出声(不往床的标准输出和标准错误写字)、运行器照没有载入行判这个进程追踪不可信(对账床 J4 钉着);运行器与追踪器自己起子进程时追踪器总补在最前面,这种次序只会出现在手工拼 NODE_OPTIONS 的场合;嵌套的追踪会话外层看不到内层床的写、只能记脏;worker 注入拿不准时(给了非空的 execArgv、床又清了 NODE_OPTIONS),追踪器保守报没注入上(Node 22.18 里 worker 其实继承了父线程的预加载),所以只钉「报了」、不钉「看不见」。追踪看不见的写(上面几类)若落在被忽略目录里、又是追踪册里从没出现过的新路径,第二道快照也看不见 —— 两道都比不出来,这张床会被学成干净,对账床用例演出来了,是诚实边界、不是目标行为;第二道抓得到的是追踪册里出现过的被忽略路径、git 清单里没有的未入库路径、已脏文件的内容改动,抓到时点名变了的路径,处置见「一轮的次序与两道快照」与「污染窗口与作废重跑」;池里两张床经网络端口或系统临时目录里的固定名互相干扰,只做过抽查(起 HTTP 服务的床都监听随机端口,临时目录基本是 mkdtemp 随机名),不是穷尽;追踪册有条数上限、超了丢最老的,早先记下的被忽略目录路径可能不再被第二道逐个核;准入册与追踪册是本机状态,与账本同一条边界(①)。㉙ 整机预算、床账跨根与改坏对照的守不到(机制见「跑床分道并发」「床账跨根」「改坏对照按点跑」):收回只认指纹逐位相同 —— 指纹证明内容相同、证明不了环境相同,所以副本补不齐环境的床在副本里红或自报跳过,原样收回(红的算数),没有「缺环境却收成绿」的路;反过来副本里缺了某样东西却照样通过的床(悄悄少测又不自报跳过,这本来就违反「跳过不是通过」),它的绿会被收回,只能靠补环境时不造假依赖;node 进程里直接改副本账,和真仓账本一样守不到(①);封版命令、部署门入口写账不一定在跑床锁里,收回把读-合并-写压在最后一小段,仍有极小的丢一笔窗口;收回等锁最长 45 分钟而工具里单条命令最长 10 分钟,运行器占锁超过 10 分钟时换入命令会被工具超时杀掉 —— 换入早已做完、收回没做,下一次换入成功时再收;缺省路数的系数按机器静时量出的拐点取保守值,机器忙时快不到那么多;副本与真仓、几个会话同时跑床时各按整机预算开池,合起来会超,要等待立项目「同时进池」的机器级计数;池越宽,掐着时限的床越容易在忙时超时变红(照旧独占复跑归因、红不改绿);CPU 占用是整机的,分不出是谁占的;全量检测照旧按核数定线程,和宽池同时跑时两边共用一台机器;床的仓内沙箱豁免按字面路径判,床往同名目录里写了别的东西、或床外预置的目录联接把写引到别处,追踪都看不出;清理归档之后读不到施工区里的行,同一张床跑了几次只数经运行器跑的,账本目录里清掉的旧行不计入;直跑这一条只写进说明,数与拦都要等待立项目「同时进池」;改坏对照的桩只拦同步读写、require 与同步复制(copyFileSync、cpSync):异步读与异步复制、非 node 的复制与读取、起子进程时洗掉 NODE_OPTIONS 又按真路径读的、桩自己(bite-stub.js)都打不到,打不到就是「桩没命中」、记出错,逼着换一张床或换一个点。
异常 · harness-P-01 测试文件本身不受检查(待复盘 · 只登记不修):把测试里判断对错的语句删掉,收尾照样放行,重跑全过后还会记成「对当前内容通过」—— 删断言、减用例、把断言改成恒真,没有任何闸看得见;判据床、x-test 的业务床、守卫自己的床都走同一条路。会出什么事:测试被掏空之后仍然全绿,读的人以为有测试守着。动不动钱:间接(资金函数的床同样可以被掏空)。依据:测试根 *.test.js 不在任何判据的适用文件里;唯一运行器与判定模块只看床过没过、不看床里有什么。状态:要修(防掏空:用例数棘轮、删断言检测、基线只减不增)。由什么测试守着:待补测试。
异常 · harness-P-02 删模块工具查「谁还在用它」这一步不可靠(待复盘 · 只登记不修):x-module-del 扫描跨模块引用时,把整行文字而不只是路径当成「是不是本模块自己的文件」的依据 —— 以 @xModules/<模块>/… 形式真引用该模块的 import 一律被当成自家文件剔除(真依赖查不到),同名兄弟模块又制造一批假引用;扫描清单里的路径在 Windows 上是反斜杠。自测是绿的,恰恰是靠同名兄弟模块产生的假引用。会出什么事:删一个模块时漏掉还在用它的地方,删完才炸。动不动钱:间接(删的若是支付或订单相关模块)。依据:.claude/skills/x-module-del/scripts/scan-module.js(跨模块引用过滤;路径拼接没有统一斜杠)。状态:要修。由什么测试守着:删模块工具自己的测试床(现有用例测不出这个洞,需补反例)。
锁步:架构页的测试床点名只接受测试根下的床(x-arch NS-COMMON-0010);改测试根只改地图里的名册「测试根」一处(引擎常量 test-roots.js 读它,运行器、索引器、该闸与 guard 都读它或它算出的常量);新增一种测试根位置时,运行器的候选目录清单要同批加上,否则那里的床算测试根、却没有人去收。删规范时它的判据床目录随判据与条款书一起删(/x-meta-dev delete)。
封版的测试前置(测试指纹 · 封版记录 · 收尾复核;ADR-62)
定版(本节统一用这个词):用统一封版命令封一个单元 —— 整个 HARNESS、系统规范域、业务域、业务总览、项目架构或 agent 架构(§十三 单元表)。改版本号本身不受测试前置拦,封版才受。
一句话:测试跟着单元定版 —— 钉死一版之前,证明这一版的测试必须对当前内容全过;钉死时在那一版写一行「测试指纹」,说明这一版是在哪套测试结果上认的账。
一个命令,按层取测试面(判定只在 guard/test-faces.js,封版命令只调用它):
- 系统规范域:
sealGate—— ① 规范面spec:<规范>的每张床、以及住在别处却写明「规范名:编号」覆盖它某颗闸的床,都对当前内容通过;② 每颗闸都有床提到(与运行器--coverage同一口径);③ 架构页测试床一节零「待补床」。检测前置另跑-t/-v。 - 业务域:
domainGate—— 本域代码(文档头 describes 的目录)被哪些测试面测着(被测文件或@covers落在目录下),这些面全过;本域代码不在任何测试的被测范围里时如实写none,覆盖缺口一眼可见。业务总览没有代码,写none。 - 项目架构、agent 架构:设计页没有代码,测试指纹如实写
none,并在那一行写明谁在守 —— 项目架构:守着六个阶段那几道关口的是框架的床(设计页点名);agent 架构:执行体文件由 x-agent 规范的闸判,守着那些闸的床随 x-agent 规范自己定版时核。 - 整个 HARNESS:守卫、检测引擎、技能三类测试面全过(框架的代码就在这三类面里)。
- 封版前跑什么:系统规范域跑唯一运行器
--guards=<规范>;业务域跑--changed本域代码;整个 HARNESS 跑--face=guard/engine/skill。没过时拒绝报文按每张床自己的面给命令。 - 盯盘上状态的床当场重跑(ADR-103;判定模块
testPrintOf的rerun与preview两个口,重跑器由封版命令注入,守卫不加载运行器):整个 HARNESS、系统规范域、业务域三类封版共用的这一步 —— 先照账本判一遍,挑出只因盯的路径变了才作废的床(名单见上「测试闭环」里「盯盘上状态的床」),执行时逐张交唯一运行器当场重跑(harness.js --action=beds --only=<床> --quiet --lock-wait=45:每张都要拿运行器的仓库级锁,别处在跑床就排队,最多等 45 分钟;床的输出在.claude/tmp/beds-last/),跑完照账本再判一遍。重跑没过就不封,点名是哪张;运行器不在或起不来,按「重跑没做成」拒封。封版报文逐张写重跑了哪几张、各自过没过,测试指纹那一行的说明里写明其中几张是封版前当场重跑的。预览(不带执行开关)不跑:列出封版时会先重跑哪几张,测试指纹那一项写成重跑之后才算得出;体系守护的闭环验证这类只读调用同样不跑。盯的路径没变的床不重跑;床本身、夹具、被测文件或上游改过的照旧不代跑 —— 那是改它的人该先跑的,拒绝报文照旧给命令,跑完再封。重跑是真跑:同一个运行器、记进同一份账本,收尾与三查随后认的就是这一次的结论。路径没变时这一步只多几次查目录;没有选「封版时把整面床一律重跑」—— 什么都没变时整个框架每次封版也要多跑好几分钟,而且封版以外的地方照旧沿用旧结论。 - 钉版只认真跑过:登记豁免的跳过(
SKIP-EXEMPT)在收尾新鲜度里算过,在封版前置里不算 —— 跳过不算通过。 - 测试指纹 = 这些面的每张床「路径 + 记录指纹 + 状态」排序后 sha256 取 16 位;一张床的记录指纹已覆盖床、夹具、被测文件与上游。
封版记录:本机账本同一个文件里的 seals 一节,键 <单元>@<版本>(framework:harness / spec:<规范> / domain:<中心>/<域> / business:overview / project:overview / agent:overview),记三行指纹、测试指纹行、日期、标题与说明的指纹、改动清单、整段历史指纹与床数;另有一栏认领清单 claimed(ADR-103)—— 为了哪条需求、这一次封版自动认领了哪几个删掉的文件、为什么能认(§十三 第 3 关「删除的自动认领」);没有认领就没有这一栏;收尾复核不比这一栏,锁清单也不记它。先记账、再写盘:记不下就一个字都不写。预览不记。
收尾「封版复核」(stop-handler sealRecheck,判定 sealProblems):看本会话改过的变更历史与锁清单,契约生效之后封过的每一版 —— 已封版却没有封版记录(手写的)、三行指纹或标题说明或改动清单与记录不符(手改过)、有记录却把记录行删了(想借机重封)、锁清单不在而台账有记录,都拦;锚单元(整个 HARNESS、业务总览、x-arch)每轮都核,台账封过却从磁盘上消失即拦。契约之后只有封版命令写得出记录行;发布前另把全部单元契约生效之后的每一版逐版对台账(各条发布通道共用),契约之前的旧条目不在复核面。它不分试运行;判定模块坏了按基础设施异常记,台账读不了按判不了处理、不当成「没有记录」,绝不静默放过;本会话没改变更历史就什么都不做。
只对真仓生效的是记账与会话归属:封版命令按脚本自己所在的仓认真仓;测试床在临时仓里验封版编排时,检测、测试、记账与归属都显式注入,不碰真仓台账。
真仓锚点床按收尾口径判:断言「真仓此刻零违规」的床若把「施工中还没封版」也算违规,就与封版前置互相等待(封版要求床先过,床要求先封版)。这类断言带施工中开关跑(versionWip),其它任何违规照报。
诚实边界:① 封版记录是本机状态,账本被清过之后,还没被新一版盖过的那一版会被收尾当成手写的 —— 处置是在变更历史最上面加新的一版、重新封版;② 业务域的测试指纹是 none 不拦 —— 它如实暴露覆盖缺口,补测试归业务开发;③ 与测试新鲜度一样,防的是忘记与手写,防不了故意改账本。
| §一 x-test:业务端与内核母本的长期回归测试、部署门入口 | L5 | 测试根唯一定义:地图名册「测试根」(引擎常量 check/constants/test-roots.js 读它;运行器、引擎索引器、x-arch NS-COMMON-0010、guard 四处读);按被测对象分桶,判定模块 guard/test-faces.js 对不认识的桶抛「推不出面」;部署门入口 x-test/run-deploy-gate.js --verify 按注册表核登记床住址 | 全量运行的卫生检查计失败;--verify 手动 | 后台、端业务模块、官网没有桶也没有面(⑧);放置检查没有自动触发点;⑬ |
| §二 测试是与检测并列的第二个裁判;检测读代码、测试跑代码 | L2 · L4 · L5 | 检测 check.js(语言层 + 规范层);测试 harness.js --action=beds(唯一运行器 bed-runner.js);二者并列接在 VERIFY、收尾、定版、发布四处 | 收尾两个都硬拦、分栏报;封版两个都是前置(三层同一个命令,业务域也有检测前置);发布两个都当场跑 | 没有测试的部分只有检测一个裁判(㉒);⑧ |
| §二 执法在开发中、收尾、定版、发布四处把两个裁判一起叫来 | L2 · L4 · L1 · L5 | 开发中:verify-feature.js --changed;收尾:stop-handler.runStop(两栏、分开记账、总时限);定版:统一封版命令 x-meta-dev core/seal.js(三层同一个;开发流入口 arch/seal.js);发布:部署出口 + 部署门 + 上传档案闸 | 开发中是向导;其余三处硬拦 | 开闸期间写入那一刻两个裁判都不在岗(⑳);小程序包不经发布门(㉑) |
| §二 两个裁判同构:按内容记结论、上游一变作废、说不清不算过 | L4 · L3 | 测试:按张账本(床 + 夹具 + 被测文件 + 上游组);检测:会话台账干净结论带判据组指纹(session-ledger.detectPrint);编译检查器跳过不算通过、报告读不懂按错报 | 确定性 | ①㉓(本机账本可改写) |
| §二 裁判也被裁判:检测器有测试守着,测试要证明咬得住被测对象 | L4 · L3 · L5 | 判据床守检测器(x-arch NS-COMMON-0010 点名、封版逐闸有床);空壳对照守床(test-faces.bitePlan + 运行器 + 部署门入口 --bite);bite.test.js、compile-checkers.test.js 守对照与语言层 | 新建或改过的床没咬住不算通过(收尾、定版、发布) | ⑮(咬得住不等于测得全;老床不追溯) |
| §二 测试跟着被测对象安放 | L3 · L4 | 测试根常量 + 面族按位置推(test-faces.js),@covers 补跨读 | 推不出面的床计入「无归属的床」 | ②(@covers 手写)⑭ |
| §二 跑过没有、对哪份内容跑过按内容记账 | L4 | 按张账本 .claude/tmp/ledger/beds.json(床 + 夹具 + 被测文件 + 上游组的 sha256;盯状态名单上的床另加它盯的路径此刻的样子);部署门入口另记「这份目录测过」;封版记录 seals | 确定性(读账本即生效) | ①(本机可伪造)⑫(装配面旧戳双账) |
| §二 执法测试的机制自己也有测试守着 | L4 | 判定模块与收尾环 test-faces.test.js、stop-ring.test.js、session-ledger.test.js;守卫主自测(原路径 verify-harness.test.js 一块、verify-harness-blk1 到 blk5 五块、探针小床 verify-harness-probe.test.js、核对床 verify-harness-groups.test.js);运行器与体检 harness-dev.test.js;并发池 bed-pool.test.js、写追踪 bed-write-trace.test.js;选床认法对拍 face-parity.test.js、体检批量 audit-batch-parity.test.js;增量检测提前起跑 incremental-parity.test.js;空壳对照与改坏对照 bite.test.js;语言层 compile-checkers.test.js;封版命令 seal-command.test.js、版本契约 version-contract.test.js、框架锁极简比对 framework-lock.test.js;业务域版本锁步 x-arch business-lockstep.test.js;VERIFY feature-dev.test.js;出包门 x-core-tools.test.js | 部件一改,它自己的床记录作废、改过的床要咬得住;框架面在收尾硬拦 | ⑮;盯盘上状态的床那一条「封版挑床 → 运行器重跑 → 记进账本」的链没有一张床从头验到尾(判定模块床那一组只走到收尾判定,封版命令床在进程内调封版、用假运行器) |
| §二 测试不单独设版本号,随单元定版 | L1 · L2 · L4 | 统一封版命令按层取测试前置(sealGate / domainGate / 框架三类面),写「测试指纹」、先记封版记录再写盘;收尾 sealRecheck 复核手写与手改 | 封版时硬前置;收尾复核硬拦、不分试运行 | 内核没有定版点(它是无主业务代码,只减不增);契约之前的旧条目不在复核面 |
| §三 两个裁判的执行点(L2 开发中 · L1 封版 · L2 升版与发布出口 · L4 收尾与部署门含事后复判 · L5 部署门入口 · 守不到之处写进设计) | 各层 | 见本表其余各行;体检「测试闭环」横切行派生各执行点的在岗状态,闭环验证第⑤步核三处前置与复核接在真仓上 | 体检只读、要人调用 | 资金写函数「要么有测试、要么写明不测」无闸(x-arch-P-01 后半) |
| §三 控制哲学:绕过工作流 ≠ 绕过检测与测试 | L4 · L2 | 两个裁判锚在文件(收尾按会话台账)、写入动作(写前拦截)与发布动作(部署出口、部署门、上传档案闸)上,不锚在工作流上 | 收尾与发布无条件;写入时刻随写前拦截挂载 | ⑳ |
| §三 护城河:检测器有测试守着,执法在每个检查点把两个裁判叫来 | L3 · L1 · L4 | x-arch NS-COMMON-0010 要求每颗闸出现在架构页测试床点名里;封版前置要求逐闸有床、零待补床、-t/-v 零红;判据床的空壳对照掏检测器 | 检测层面允许待补床,封版时才拒 | ⑮;元规范 x-standard 的闸没有架构页核点名 |
| §四 VERIFY〈检测 + 测试〉 | L2 | x-feature-dev/scripts/verify-feature.js --changed:增量检测 + 按改动跑床,登记豁免单独列出 | 工作流向导,不是物理闸 | 不走工作流就只剩收尾一道;零覆盖如实放行 |
| §四 ARCH-SYNC〈回看设计 · 升版 · 测试前置〉 | L2 | 编排器五阶段(core/orchestrator.js);arch/seal.js --unit=domain:<域> --execute(统一封版命令) | 封版时硬前置;编排器只出计划;改了域代码没封版收尾当轮红 | 升哪一位靠人判断 |
| §四 /x-harness-dev:六层体检 · 闭环验证 · 全体测试床的运行与记账 | L2(横切) | harness.js 三个动作 audit / verify / beds | 入口存在即成立 | 三个动作都要人调用 |
| §六.7 被测对象增、改、删时,守护它的测试同批增、改、删 | L1 · L2 · L5 | 删:x-module-del 连床删、删后 --verify;新规范:骨架自带测试床一节、封版前置逐闸有床;改:VERIFY 按改动跑床、收尾按改动判 | 删除侧有工具;改变侧只能逼重跑 | 逼不了「同批改写」(⑮);业务新增侧没有「要么有床、要么写明」(x-arch-P-01);删模块工具的引用检查不可靠(harness-P-02) |
| §六.7 改动触及被测对象、测试本身或上游,旧的「跑过」即作废 | L4 | 指纹含上游四组(检测引擎、内核、部署门入口、运行器 —— 运行器只算 VERDICT-CORE 区段与 bite/ 目录,ADR-64);盯盘上状态的床另含它盯的路径此刻的样子(名单 guard/state-watch.json),只因它变了而作废的由封版当场重跑 | 确定性;盯状态的床收尾只提示、封版硬前置 | 区段框错不作废(ADR-64 诚实边界);②;盯状态的名单靠人维护、只看路径不看内容(「盯盘上状态的床」守不到) |
| §六.7 规范封版与业务域升版之前,相应测试必须对改后内容全过 | L1 · L2 | 同「测试不单独设版本号」那一行 | 同上 | 同上 |
| §六.7 收尾是改动当轮的闭环点(框架自身每轮都在这里闭环,另有整个 HARNESS 封版) | L4 | 收尾「测试新鲜度」(stop-handler.js → test-faces.judge);守卫、检测引擎、自研技能面直接碰过或经上游牵动都拦、不因「重」降级 | 硬拦 | 元规则、宪法与本文、agents/、settings.json 自己不成一个面;体系守护技能的自测在床头点名守着其中几份的说法 —— 宪法、本文、项目设置、执行体目录、三份没配对的规则书,另有四份技能说明与业务编排器 —— 这些文件一改,那一张床就不新鲜、要重跑(它们经这张床连到体系守护技能面;守的是各处说法对不对得上,不是这些文件的全部内容);其中总自测 L1 那一组只守点名的那几段 —— 宪法「两把尺子」「按落点分五条流程」两行、本文「先分级、再选路」「受治文件类」两行、项目架构设计页「它是什么」一格与两张定义表 —— 别处写的流程名与层名改坏了它不红;⑯ |
| §六.7 发布不认旧记录、当场真跑,传上去的必须就是测过的那一份 | L2 · L4 · L5 | 脚本出口 deployer.gateFunctions + 暂存目录指纹核对;出包门 shipGate;网页版床阶段 + 上传档案闸;MCP 写前床门 + 上传内容闸;写后复判;线上对账(x-deploy-dev --target=reconcile);各发布入口第一步先只读查部署门的待检清单 | 脚本出口、出包门、四个静态出口的推导测试无条件;MCP 两道随写前拦截挂载(当前值由体检派生);上传档案闸四种档案同一要求、没有跳过口 | ⑦⑧⑨⑪㉑ |
| §六.7 跳过不算通过 | L4 · L1 · L5 · L3 | 运行器:未登记的跳过计失败;登记豁免是第三态(收尾只提示、定版与发布拒、VERIFY 单列);部署门入口与上传档案闸不认任何跳过;检测侧编译检查器工具没装、缺配置不算通过 | 确定性 | ⑥(豁免名单加一条即改判定口径) |
| §六.7 改过的测试必须证明自己仍咬得住被测对象 | L4 · L5 | 空壳对照(见本节「改过的测试怎么证明仍咬得住」):唯一运行器对新建或改过的床自动做,函数床经部署门入口 --bite;结论入账,没咬住的床收尾、定版、发布都不认 | 确定性 | ⑮;harness-P-01(测试文件本身不受检查);空壳碰不到的几条(测试面判定床的封版前置组、接力命令床那一条真引擎的),整张床在空壳下变红也证明不了它们咬得住 —— 这几处咬不咬得住靠改坏对照 |
| §六.7 测试守不到的地方必须在设计里写明 | L3 | 见 §七「测试守不到之处的登记位置」 | 系统一侧有闸(NS-COMMON-0010);业务一侧有测试设计视图,NS-COMMON-0012 判它的形态(节齐不齐),判不了写得对不对 | 资金写函数「要么有测试、要么写明不测」无闸(x-arch-P-01 后半) |
| §六.7 别的会话牵连出的红不算本会话未闭环、不代修;发布不问归属照拦 | L4 | 收尾 judge 按作废原因判归属;发布出口只看测试结果 | 收尾按执法模式;发布无条件 | ⑱ |
| §七 禁止写入测试面划分 / 收床与记账规则 / 测试指纹算法 / 收尾执法强度及其切换状态 / 空壳对照的造法与豁免名单 | L0 | 人审;x-governance 条款书 ARCH-A03 的下层内容清单 | 无机器闸 | ⑲ |
对拍台与有意改动清单(工作区地基 · 补录与读地图的对账;ADR-115、ADR-126)
对拍台住 .claude/skills/x-harness-dev/tests/path-parity/(本身不改任何生产代码):把仓里按路径判断的函数(守卫、检测引擎、运行器、各技能里的)各配一个适配器(zz-tools/adapters.js),把它们对 8004 条真路径加 3068 条怪路径的回答录成金标准(zz-fixtures/golden/golden.json,冻结在一个提交上,头部写明提交号、语料指纹、被测源文件指纹);之后每一步改了判断函数,重放对拍证明回答一字不差。重放分两档:快档(replay.test.js,常驻快床)只问纯函数一类的适配器;全量证明(zz-tools/full-proof.js,阶段门手跑,真仓约一分半)从金标准那个提交释放一棵冻结的树、全部适配器都问(含要读盘的)、另核每份规范的射程。另有普查床(census.test.js)把「至少 N 处」变成逐条确数、每条出处在冻结的提交里找得到,多一组引擎侧处置表(zz-fixtures/census/engine-dispositions.json:普查登记表引擎部分的每一行写明处置、读哪个名册或属性、理由、留给哪一步;真正的改动点逐处写、改坏对照手跑过;对拍台盯不到的 54 处逐处写兜底);地图等价床(map-equivalence.test.js)拿独立求值器与读取模块各把地图展开一遍并对金标准,探针路径床(probe-path.test.js)拿地基目录里的一个路径逐个问引擎侧每个判断函数,期望值写死。
补录语料与读地图的对账(ADR-126):对拍台要对得上守卫与引擎「现在」的判断,不只是金标准那个提交上的。① 补录语料:金标准之后守卫里新增的特殊路径(大小写、反斜杠、..、尾点尾空格、近似名、仓外写法、合成顶层目录这几族写法)补进单独的补录语料(zz-fixtures/corpus/supplement-paths.json 一份平铺的字符串数组,旁挂 supplement-meta.json;原语料与它的指纹一个字不动),只问纯函数档的适配器,补录回放放在快档里;完整性床核每条补录路径落进地图的一个区、无歧义(按守卫入口的归一规则归一之后落进区也算;盘符、仓外、合成顶层目录不要求)。② 补录金标准(golden-supplement.json)分两部分:adapters(原有适配器在补录语料上的答案)与 base(新补的适配器在原语料上的答案);头部写明基线提交、语料指纹与录法;答案取自基线提交的老代码,主金标准 golden.json 一个字不动,原有适配器的任何一个答案都不改。③ 新适配器(带 afterGolden 标记,对着守卫新导出的函数):A58 laneIsJudge(算不算判定代码)、A59 isHardProtected(挪走或删除要不要拦)、A60 isAncestorOfProtected(是不是某个保护样本的上级目录)、A61 inWorkArea 与 A62 workAreaOf(施工区),各做改坏对照。④ 补登记表与两张处置表:补登记表(judge-functions-supp.json)登记金标准之后守卫与引擎里新增、改动、删掉的判断,出处指现行提交;原登记表与老引擎处置表一个字不动。守卫处置表(guard-dispositions.json)与引擎读地图处置表(engine-read-map-dispositions.json)各与登记表(含补登记表)双向对账:每一行恰好一个去向 —— 读地图 / 写死并钉住 / 写死不钉 / 原样不改 / 已删(可叠加:补地图、补地板、早退写死、老支保留、惰性、过渡、导出补适配器);读与钉住的名字在地图里真实存在;补登记表每一行被且只被一条处置行引用;改动点逐处写全,对拍台盯不到的逐处写明由哪张床的哪几条兜;三份可读版由渲染器从数据文件生成、床核逐字相同。⑤ 独立求值器(map-eval.js)补三种路径规则写法(seq、under、nested)与装载拒绝,只凭规则类型说明写、不抄读取模块;改读名册之前各名单的值(旧名单快照)只用来证明改读前后等值(逐张名册往地图里多加、少一个成员各红一次,证明的输出留在那条需求的证据记录里),证明完连同读它们的床与工具一起拆掉 —— 对拍台不读旧名单快照,名册只有地图这一份账。⑥ 全量证明(full-proof.js)一并回放补录语料与新适配器。
有意改动清单(zz-fixtures/golden/intended.json)登记「回答变了、而且是事先说好要变」的差异,回放的差异必须正好等于它,多一条少一条都红。它带组号与档位:清单头 groups 登记每一组的条数、档位与说明;每条 {adapter, path, expected, actual, group, tier, why},group 是登记过的组号、tier 是 pure(纯函数档:快档与全量证明都问)或 state(读盘档:只在全量证明里问)、与适配器自己的档、与组的档都相同,why 以组号开头;每组实有条数等于组号表登记的条数(也就是签字一列过的条数)。对账按档:快档只对账 pure 档的条目(读盘档的条目快档里问不到、不算「登记了却没发生」),快档里的差异若恰好对上一条读盘档的条目说明档位登记错了、红;全量证明对账全部条目。没归组的差异、条数与签字一不符的组、档位放错的条目、多登记了没发生的差异,一律红并点名。现有一组:D3(.claude/bak 下 20 个文件不再进检测引擎的索引,索引适配器 A25 的答案,读盘档,检测结论零变化)。
规矩:组由用户在签字一点头(点头的是「组」,不是逐条);签字之后新发现的差异先报主控,同因同类的由主控核准、验收时逐笔列给用户,不同类的要用户重签 —— 与 §八「需求对账」签字只锁五样的口径一致(清单是过程,组号表是签过字的承诺)。
十七、术语表与五类需求入口表(ADR-99、ADR-101、ADR-102、ADR-105、ADR-111、ADR-112、ADR-113、ADR-116)
各处说到会话、环、收尾这些词时指的是哪一样,五类需求各从哪进、谁办、怎么封、往哪发,只在这一节写一次。宪法、规则书、技能说明、执行体说明用这些词时以这里为准;项目架构设计页讲流水线怎么走,这里只定名、指路,机制在指到的各节。
术语表
| 名词 | 指什么 | 细说在哪 |
|---|---|---|
| Harness架构 | 五类架构之一,框架这一层的设计,即架构详图(本文)。五类架构自上而下:业务架构答「做什么、为什么做」,系统架构答「按什么规范写」,项目架构答「怎么一步步做成」,agent 架构答「谁来做」,Harness架构答「凭什么保证做对」;管它的架构师叫 Harness架构师。「框架三件套」「框架单元」这类指整个 harness 框架的说法不是它,不随它改名 | 宪法 §三 两把尺子;§十四;§十五 角色表 |
| 主控 | 用户平时说话的那个会话,只有一个,主控即 X大脑,首席产品官(管产品):和用户谈需求,拍板做不做、走哪条流程、排第几,统管各专项的产品经理,弹签字题给用户签,代签设置允许的由它代用户验收、代用户授权发布(授权转给运维经理),环收尾之后跑提交命令、把结案报告原样转给用户;不出设计、不记会话号、不盯进度、不办实施,更不写任何需求的机器镜像。谁是主控由用户在窗口里定,机器认的是会话登记册里登记的那一个;它由执行体定义「X大脑」启动(下一行)。开新窗口先做例行三步(登记主控、看四位常驻在不在、不在就预览恢复,见 §十五「主控怎么交接」),再做三件事:① 跑环的十态命令,不带计划名,看每条需求在哪一态、下一步该谁做 —— node .claude/skills/x-harness-dev/scripts/harness.js --action=loop;② 跑排队一览,看每个版本单元上谁占着、谁排着、哪几条此刻开得了工、哪几条卡在收尾、归档与提交 —— node .claude/skills/x-harness-dev/scripts/harness.js --action=queue;③ 读项目架构设计页与本文 §十五 | §十五 角色表、「主控怎么交接」 |
| X大脑 | 主控这个角色的会话名与执行体名(ADR-101;首席产品官)。定义住 .claude/agents/x-brain.md;启动方式只有一种 —— 在仓根运行 claude --agent x-brain --name X大脑 --model <型号> --effort <推理档>(两个值照型号配置里 X大脑 那一行的有效值,整行由型号配置命令的 show 印出,那一行是 gpt 时整行另带代理设置;用户亲手验过这种启动方式:守卫在岗、宪法照常加载、它自报是 X大脑、窗口标题是 X大脑)。它只作会话用,不当执行体派出去;是交互窗口,不在 agent view 里。「主控」仍是角色的叫法,各处讲主控做什么、不做什么的句子不改名;X大脑是这个角色的名字。三层不嵌套:X大脑 → 会话(常驻会话、各专项的产品经理、复盘经理)→ 执行体 —— 它是队伍的顶端,不是又一支队伍,产品经理自己带执行体。守卫不核窗口是不是这样启动的:「每次开工先开 X大脑」是纪律 | §十五 角色表主控一行、「这张表今天靠什么」;agent 架构设计页「X大脑与会话」 |
| 项目经理 | 管项目的常驻后台会话(ADR-102、ADR-116),定义住 .claude/agents/x-project-manager.md,名字固定叫「项目经理」,靠自己二三十分钟一次的定时巡检保持在线。管:立项排期、排开工(排队的需求排到了就跑开工命令)、起关每个专项的会话(用会话命令)、跟进度催超时、环收尾后请主控提交并拿结案报告转 X大脑、管用量与静默时段、记总账与待立项目清单、遗留去向台账;不决策、不签字、不出设计、不写任何需求的机器镜像。这套体系本身管放行的那一面叫「关口」(下一条),不是项目经理 | §十五 角色表、「常驻会话与会话命令」;agent 架构设计页「X大脑与会话」 |
| 关口 | 这套体系本身管放行的那一面:计划、守卫的各道门、三查、封版、验收单。放行只由关口决定,不归任何一个会话或执行体 ——「领队不替关口放行」里的关口就是它。项目架构六个阶段各在结束处有一道关口(讲某一道时写「阶段 N 的关口」,见下「阶段」),是这一面落在流水线上的六处(ADR-75、ADR-102) | §十五 角色表;§八 |
| 主会话、领队 | 同一个意思:一个会话里派执行体的那条主线。主控与产品经理在各自的会话里都是领队;「领队只派活、不替关口放行」对两种会话都成立。守卫只分得出带执行体编号的事件与不带的,不带的就是领队 | §十五「称呼对应与顶层的范围」;§八「组队与执行体」 |
| 产品经理 | 每个专项一位的后台会话(执行体 x-product-manager,只作会话用、不当执行体派出去),从立项到归档端到端负责:请架构师出设计、写计划、带执行体实施(开了工才动受治文件,排队的等项目经理叫醒)、请对抗审查官复盘、申请发布、收尾归档;从写第一笔计划起就是这条需求的办理会话 | §十五 角色表 |
| 产品架构师 | 管业务的常驻会话(执行体 x-architect 的显示名,id 与文件名不变):拥有整个业务架构,业务需求从逻辑链、数据链、功能链出产品设计,审计划合不合设计,实施后回看业务架构有没有同步;做设计的第一条要求是「取舍只问最佳最合适,规模与成本不作为取舍的理由,禁止复杂化」;不是任何需求的办理会话,受治文件由产品经理派执行体写 | §十五 角色表;agent 架构设计页 |
| Harness架构师 | 管框架的常驻会话(执行体 x-framework-architect 的显示名,id 与文件名不变):拥有整个 Harness(宪法、五类架构、L0–L5),Harness 流程与规范流程的需求出设计,各条线报上来的 Harness 毛病由它分析、出方案;第一条要求与不是办理会话同产品架构师 | §十五 角色表、「遇到顶层问题的两种走法」;agent 架构设计页 |
| 复杂化审查官 | 只读的执行体(x-complexity-reviewer),专管「复杂化检验」:待立项目进门前分诊、成条与难事的计划签字前做减法审、待立项目清单更新前瘦身;判断只有四种 —— 立、并、不立、问你;只砍「不必要」的,不拿规模、工作量、成本当理由 | §十五「取舍原则与复杂化审查官」;宪法 §六 第 9 条 |
| 办理会话 | 机器认的那一个:一条需求的账 —— 写前放不放、三查、封版前对账、越界 —— 算在哪个会话名下。签「确认」那一刻按「机器镜像最后是谁写的」记下,之后可以用改派命令换(接手的会话自己 --take,或主控、项目经理 --to= 指名)。机器只分办理会话与非办理会话,不分主控、产品经理、运维经理(签字放行另认会话登记册里登记为这条需求产品经理的会话,说话钩子另认登记册里的主控) | §八「办理会话」「办理会话改派」「写前按办理会话判」 |
| 开工 | 一条需求从「签了字」到「可以动受治文件」的那一步:签字一管做什么,可以提前签、一次签好几份;开工才占版本单元、放行写受治文件、算在办(在办 = 签了字、开了工、没完结)。开得了工的,签字那一刻就是开工;开不了的记成排队,排到由项目经理(或主控)跑开工命令(harness.js --action=start,只有会话登记册里的主控与项目经理跑得了)、叫醒产品经理。开工条件三样,签字那一刻与开工命令判的是同一个:要占的单元上没有开了工没完结的需求、也没有完结了还没提交的;碰判定代码时没有别的开了工没完结的需求也碰着;仓里没有已完结还留在计划目录的需求。「开没开工」只有一个判法:账本里有「开工」那一笔,或有一笔确认不带「排队」标。同一处同一时刻只开工一条,占到上一条提交完 | §八「签字与开工分开」「同一块排队」;§十四 |
| 排队 | 签了字、但开不了工的状态:账本里那一笔确认带「排队」标,不记基线、不占单元、不放行写、不算在办(不挡正式发布、开不了联调、验收完结与代签都拒并说「还没开工」),签字照旧会作废(另带「要重签」)。十态里并进第 2 态「已立项」,不加态。「同一块排队」说的是开工条件里单元占用那一样;「排队一览」(harness.js --action=queue)出五段:占着的、排着的、此刻开得了工的、卡在收尾归档与提交的、判定代码谁在改 | §八「签字与开工分开」「同一块排队」「排队看得见」;§十四 |
| 运维经理 | 管部署的常驻后台会话(执行体 x-ops-deployer 加了常驻一段):一切线上写入都在它的会话里做,开发中途的联调上线也归它;每次上线都要授权 —— 随某条需求验收而做的发布,授权就是那条需求验收完结的那一签;不随验收的发布与生产构建是用户的单次授权,联调另可照代签设置由 X大脑 代授权;认代签记录,只认发件名是 X大脑 的跨会话消息当授权或代签中转;照发布技能自己动手,量大派运维发布专家;不提交(提交只由主控跑提交命令) | §十五 角色表、「跑整面床、发布两个全仓共用的窗口」一段里「谁来发布、怎么授权」 |
| 复盘经理 | 用时起、用完关的后台会话(定义住 .claude/agents/x-retro-manager.md,只作会话用、不当执行体派出去;名字固定叫「复盘经理」;不是常驻会话,也不是任何需求的办理会话):每个专项验收完结时由项目经理起它,和发布同时进行;它跑耗时表那条只读命令,按这条专项的档写结论与发现,只写主控线复盘记录目录里这条专项的复盘记录,报 X大脑,然后由项目经理关它;复盘在归档之后的后台办,不挡归档、提交和下一条开工。不定去向、不派执行体、不碰线上 | §十五 角色表、「常驻会话与会话命令」;§八「过程复盘的耗时表与红旗」「后台收尾」;agent 架构设计页 |
| 过程复盘 | 一条专项验收完结之后,对这一程(时间花在哪、哪里卡、哪里反复)的复盘,补上 PDCA 里的 A:机器先出耗时表与红旗,复盘经理按这条专项的档写结论与发现,发现先过一次减法审、再由 X大脑 逐条定去向、交项目经理记;表收进收尾单第一栏的「过程复盘」一节(归档那一刻定格),结论与发现写在主控线的复盘记录里(归档前写好的结论抄进那一节);复盘与去向在归档之后的后台办,不挡归档、提交和下一条开工,也不挡验收和发布。和独立复盘不是一回事:独立复盘在验收之前、只派对抗审查官、判交付对不对 | §八「过程复盘的耗时表与红旗」「后台收尾」「收尾单与治理站点一格」;§十五「遇到顶层问题的两种走法」 |
| 派发表头 | 派独立复盘时交给对抗审查官的提示词,也是它的全部内容:几行字,由复盘说明命令(harness.js --action=review-brief)按账和说明文件现算,接力命令七步走完后在末尾也印同一段(夹在两条分隔线之间);第一行是说明文件的第一行(任务编号、计划名、结果单编号),后面写明说明文件在仓根下的位置、请审查官用读文件工具从第 1 行读到最后一行(写明共几行)。产品经理把它原样当提示词、不加字不删字、不带名字,说明全文不进提示词、审查官自己读;守卫派发时核提示词逐字等于此刻现算的这一段,复盘者收尾时再核一遍并核它把说明读全了。和任务说明不是一回事:任务说明是写在账本目录里的全文(判法、需求、标准、结论行的格式都在里面),表头只是指着它 | §八「复盘进关口」「接力命令」;ADR-122 |
| 常驻会话 | 项目经理、运维经理、产品架构师、Harness架构师四位各管一摊的官方后台会话,名字固定,由主控起(开新窗口的例行三步里发现不在就恢复,新电脑上用发起子动作);闲着约一小时后进程被官方收掉、agent view 里显示「做完」,叫一声就从原处接着干;只有项目经理靠自己的定时巡检常醒。常驻会话不是任何需求的办理会话,也不写任何需求的机器镜像 | §十五「常驻会话与会话命令」「主控怎么交接」 |
| 会话登记册 | 记着每一位常驻、每个专项产品经理和用时起、用完关的复盘经理的完整小写会话号、名字、角色、哪条需求的那份账(仓里 .claude/tmp/sessions/ 一份、用户目录里镜像一份;状态不存、现查会话列表)。和平台自己的会话名册是两回事(平台那份放在用户目录里、记的是会话文件;这一份是我们自己登记谁是谁):会话命令与代签命令靠它认主控与项目经理,签字放行靠它认某条需求的产品经理 | §十五「会话登记册与恢复」 |
| 会话命名 | 会话名的规矩:四位常驻叫项目经理、运维经理、产品架构师、Harness架构师,复盘经理固定叫「复盘经理」;每个专项的产品经理叫「需求短名-类别-档」—— 类别:业务流程写产品、Harness 流程写 Harness、规范流程写规范,档:小事、成条、难事(成条的事写成条),例:地图立起来-Harness-难事;角色不进名字;会话名必须唯一,发起和改名都按这条规则,对不上规则的拒绝 | §十五「常驻会话与会话命令」 |
| 恢复命令 | 会话命令的恢复子动作(harness.js --action=session --do=recover):死机或重开之后,默认只预览登记册里谁该拉,带执行开关才拉 —— 只拉停了、失败、干着活的,有进程的跳过、已完成的不拉;每个先停再用不带参数的 claude --resume <完整号> --bg <固定句> 续上,会话号不变;停服务本身是用户的动作 | §十五「会话登记册与恢复」 |
| 执行体(agent) | 领队派出去干具体活的执行者,定义住 .claude/agents/;只在自己的写域里写,不和用户说话、不认签字。组队时的队友也是执行体。有哪些执行体、各自的分工与队形写在 agent 架构设计页(名册的真相源是那一页的名册表) | §十五;agent 架构设计页 .claude/arch/agent/ARCH.html |
| 环 | 两种意思,看上下文。① 治理环与开发环:宪法 §五 说的两个环 —— 改规则与流程本身的那一圈(规范流程、Harness 流程)、做业务的那一圈(业务流程);运维与分析不进环;一条需求从开工走到已发布且已归档的那一圈另叫「项目架构环」,有十态、有启动与收尾。② 守卫的几个环:守卫在一次工具调用前后与一轮结束时的几个时刻 —— 环1 写前、环2 写后、环2.5 事后测量、环3 收尾 | ① 宪法 §五、本文 §十四;② §三 全景图、§八 |
| 收尾 | 三种意思,写的时候带上后面那个字。① 收尾环:守卫的环3,会话每说完一轮跑一次,检测与测试没过就逼修 —— 宪法里的「收尾」「收尾逼修」指它。② 收尾单:一条需求的交接清单(计划目录里的 WRAPUP.md,固定五栏),机器起草 —— 接力命令末尾那一回机器自己跑;验收完结之后那一回由接力命令完结之后三步的第一步刷新(办理会话写了去向的照它的),接着预览清理归档,没人在跑床或建站就归档;复盘和去向不挡,在后台办。③ 清理归档:一条命令把已完结的计划搬进归档、清掉过程文件(验收完结之后由接力命令调,也可以手跑)。另有「环收尾」:一条需求已发布且已归档的那一刻,之后由主控跑提交命令(见「提交命令」) | ① §八 环3;② §八「收尾单与治理站点一格」;③ §八「清理归档」;环收尾 §十四 |
| 阶段 | 项目架构把一条需求从提出到归档分成的六段:阶段一需求与设计、阶段二实施与落地、阶段三测试与验证、阶段四复盘与验收、阶段五部署与上线、阶段六收尾与归档。每个阶段结束处一道关口,依次是:签「确认」;只改签过的范围;两个裁判都过;复盘过、签「验收完结」;发布前的核对都过;归档、提交之后下一条才能开工 —— 讲某一道时写「阶段 N 的关口」。阶段六的关口:仓里有已完结、还没清理归档的需求时,新的需求开不了工(签得上、记成排队);同一个版本单元上完结了还没提交的需求,同样让下一条开不了工;它逼的是上一条的清理归档与提交做完,自己不清任何东西、不提交任何东西。阶段是给人分段读的,状态机的八个环节、闭环的九格与十态不随它变 | 项目架构设计页第二节;§八「项目架构与封存履历」「清理归档硬控」 |
| 档 | 一条需求的大小:每条流程各分三档 —— 三条主流程叫小事、成条的事、难事,写在机器镜像里,签「确认」那一刻按档核上限(三条主流程同一张上限表);运维流程叫例行、常规、紧急,分析流程叫快问、分析与体检、需求整理,这两条不立需求、档名不进机器镜像。手续的轻重跟着档走 | 每条车道是什么只写在 §十五「先分级、再选路」那张车道表;判法 §八「定档与上限」;各档的上限数字在项目架构设计页 |
| 流程 | 一条需求走哪一套手续(ADR-105;宪法 §四):按落点分五条 —— Harness 流程(宪法、框架的机制、项目架构、agent 架构、五层怎么写怎么管)、规范流程(一份系统规范)、业务流程(业务需求)三条主流程,每一档都走宪法 §六.8 的闭环;运维流程(不改仓、只动线上的部署与版本)、分析流程(只分析、不改任何东西,所有流程的入口)两条辅助,不立需求。走哪条由落点定、不由人选 —— 三条主流程签「确认」那一刻由守卫按落点认(不归任何版本单元的看目录),主控先认车道、运维与分析两条认流程靠纪律 | §十五「先分级、再选路」车道表与「跨流程的五条规矩」;本节入口表上方那一句;§八「认车道」 |
| 车道 | 流程 × 档:五条流程各分三档,一共十五条。一条车道写明是什么、走哪几步、跑哪些床、复盘几轮、谁来做、今天靠机器还是靠纪律。派工先认车道:先由落点认出流程,再按大小定档 | §十五「先分级、再选路」车道表 |
| 风险标记 | 定一条需求最低走哪一档的七样:落点里有写保护文件(至少成条的事);有判决依据(三查含核准命令与开工命令、复盘说明、封版命令、发布出口含提交命令、版本契约);有母本、内核、云函数骨架模板或端壳模板;版本单元多于两个;动钱;动权限与身份;已发布表改字段类型或删功能(后六样都是难事)。签「确认」那一刻由守卫按签字那一刻落点表里的目录算出最低档,写低了签不上;动钱、动权限与身份、改已发布字段或删功能三样读机器镜像里自报的栏 | §十五 车道表后「七个风险标记定最低档」;§八「认车道」 |
| 操作单 | 运维流程「常规」那一档用的一张单子:做什么、事前备份、怎么核对、出事怎么回滚,加用户一句授权;仓里一个文件都不变时用它,不立需求;要改仓里的文件就回到主流程 | §十五 车道表「运维流程 · 常规」一行 |
| 高保真 | 改界面的需求在签字之前出的、要改的那一屏的真实样子(能直接打开看的页面,不是示意图);用户点过头的那一版放进这条需求自己的 preview 目录(被否的几版留着、名字带第几版,不盖不删),嵌进看板「设计」「签字」两个页签,对着它的标准写明本计划 preview 目录里的文件名与内容指纹 —— 实施照这一版做,复盘和核准有处可对 | §十五 车道表(业务流程的小事、成条的事);开发规则书「业务流程三档」 |
| 场景判定 | 计划「设计」页签最顶上的一块:写明这条需求走哪条流程(落点认出的)、中了哪几个风险标记、为什么定这一档、要不要高保真。写计划的人写,机器不读、也不拿它和自己认的车道比,日后复盘照它对 | §十五「先分级、再选路」 |
| 判决依据、判定代码 | 判决依据只指五样:三查(核对命令、核准命令与开工命令)、复盘说明、两条封版命令、发布出口(云函数与静态站点两条发布出口、x-test 两个部署门入口、守卫一侧的发布前版本比对,与提交命令)、版本契约 —— 落点里有它就是难事。判定代码 = 判决依据加守卫目录整棵(含它的床与回归套件)、检测引擎(check.js 与 check/ 整棵,不含各规范的判据与床)、测试运行器(bed-runner.js 与 bite/)—— 碰到它的需求全仓同一时刻只开工一条。两份名单住工作区地图的名册「裁判五样」「判定代码」(守卫需求零件按名册取),写保护的扣除项写在守卫需求零件里。「裁判」只指宪法 §二 的检测与测试两个裁判 | §十五「七个风险标记」「跨流程的五条规矩」⑤;§八「认车道」 |
| 开闸、关闸 | 手动开闸 = 用户把钩子接线文件里写前拦截那一段摘下,此后写保护、顶层围栏、部署门写前那一道都不在岗;关闸 = 恢复。闸只有用户能开;关闸可以由主控代关。它只留作急救(见「急救开闸」):日常开发里受保护文件的放行跟着签字走(见「签字放行」),不靠开闸 | §二「钥匙石」;§八 环1「签字放行」;§十五「跑整面床、发布两个全仓共用的窗口」 |
| 施工区 | 一条需求自己在项目里的工作文件夹 x-test/zz-work/<需求名>/(ADR-112;需求名就是计划的目录名):办理会话的整仓副本、前后对照、探针、换文件前的备份、过程记录只放这里。git 不管、不受治、不受写保护,只放这条需求的办理会话写;办完的需求留下的区叫死区,谁都不能再写、谁都可以删,包括没签字的会话;清理归档整份删。停滞区 = 对应的需求已完结、计划已归档或已不在、还没签字的施工区,盘点只列不删。要留给复盘和后续步骤看的记录别放这里 | §八「项目自带」「清理归档硬控」;项目架构设计页第十节「施工区放哪」 |
| 工作区地图 | 全仓「这个路径是什么、归谁、能不能动、算不算」唯一的一份写法(ADR-113),住地基目录 .claude/hooks/workspace/ 的两个数据文件:引擎段 map-engine.jsonl(词表、名册、区树骨架、引擎要读的属性存在与检测)、余段 map-rest.jsonl(其余属性、对象认法、视图)。区是按路径划的一棵树,每个路径落在最深的那个声明过的区,区路径一律按整块算;地图没声明的路径答「无区」。读取模块读不到就拦、点名文件与行号;why.js <路径> 问为什么(答出区、每个属性的值与出处文件第几行)。读它的有两路:检测引擎(索引、目录遍历、名册常量、版本契约、判据注入口)与守卫(按路径分类的判断,经唯一入口 guard/map-reader.js) | §十八「引擎读地图」「守卫读地图与读坏了怎么办」;设计稿主控线设计目录 |
| 地板 | 写在读取模块旁 floor.js 里的冻结集合:脊柱、引擎承牙、保护区、装配产物、发布档案、受治根、必跳名和地基目录自身(各有仓根写法与任意深度写法),地图数据坏了或被改宽了它照样答,守卫问地基目录里的路径时保护类视图直接由它答,地图只能在地板之上加严、不能放松(装载时核样本,答案比地板松就拒绝);只许加、不许减,棘轮床守着,退役一项必须走一条框架需求并在签字一里单列请用户点头 | §十八 |
| 落点表、格 | 落点表 = 计划里「这条需求要改到哪些版本单元的哪些部位」那张表,每个部位叫一格,格里列目录;一条需求的设计范围 = 签字时确认的版本单元与流程,加之后主控核准过的目录(ADR-111,见 §八「需求对账」签字只锁五样 —— 落点表此刻列着的目录里,签字之后新加、还没核准的不算在范围里),也是它开发期联调的放行面。发布段里也说「格」,那是另一张表:这条需求的每个发布面一格,分三种 —— 该发的格(云函数、后台、手机网页版、官网、治理站点与「已生效」;全部发了才算已发布,一格都没有的验收完结即已发布)、在体系之外发的格(数据表、微信原生包,不算进该发的格)、联调格(只留痕,不算进该发的格) | §八「需求对账」「落点格认办理会话签字后的写证据」;发布段 §八「收尾单与治理站点一格」;放行面 §八「部署门认联调」 |
| 联调、正式发布 | 一次云端写入(或脚本发布)到了发布门,机器判成两种之一。联调 = 开发期联调上线:验收完结之前把这条需求的云函数或数据表放上线联调 —— 要有口径(运维经理先跑联调开始、带需求名;脚本通道在发布命令上带两个开关)、那条需求在办、要上线的东西都落在它签过字的落点表里;不算正式发布,只记「联调」一格。正式发布 = 其余一律:排在验收完结之后,要发的云函数或站点源码被在办需求签过字的落点表盖住就拦。联调标记 = 联调开始命令写下的那个口径,有效 30 分钟 | §八「部署门认联调」;怎么走见部署技能说明「联调上线与正式发布」与开发规则书「开发期联调上线」 |
| 机器镜像 | 计划的机器读版本(计划目录里的 scope.json):需求、动不动钱、怎样算做完、用例、落点表、档,另有两栏自报 —— 动不动权限与身份(permission)、改不改已发布表的字段类型或删不删功能(breaking),为真时进签字锁住的内容。签字锁的是它里面的五样(见上面「签字锁住的五样」一行),其余是过程;看板(PLAN.html)给人读,两边要对得上 | §八「需求对账」 |
| 签字锁住的五样 | 签「确认」那一刻用户签的内容(ADR-111):需求那一句话;要用户亲手验的清单(哪几条、每条验什么、条数);动钱、动权限与身份、改已发布表字段类型或删功能三个自报;档;流程(业务、Harness、规范认成哪条,机器从落点表算)。五样之外的叫过程 —— 标准的措辞与条数、自动用例的一切、亲手验用例的「在哪看、怎么验」、同一流程之内加或换的版本单元、落点表里的目录与格 —— 签字之后改了不让签字作废;五样改了才请用户重签 | §八「需求对账」签字只锁五样 ①② |
| 待核准、核准、没有核准路 | 签字之后的过程改动叫待核准;由核准者跑核准命令记一笔,叫核准(核准者是会话登记册里此刻登记的主控,登记册读不出或没登记主控时是最近一笔确认所在的会话):机器核它不是当时的办理会话、不是写过这份机器镜像的会话,核准那一刻重判碰到五样就拒,验收时逐条(旧到新)列给用户;核准不是代签。办理会话就是签字会话(或核准者自己写过机器镜像、写者查不到)的需求没有核准路:待核准的过程改动当作实质,签字作废,重签时一并带进新的签字 | §八「需求对账」签字只锁五样 ③④⑤;命令 harness.js --action=approve |
| 代签 | AI 在用户设置允许的范围里替用户签验收、授权发布与联调:设成代签的那一类,验收完结的签字(连带这条需求的发布与提交)、开发中途的联调授权都由 X大脑 代用户点头,走受信的代签命令,签字人写「X大脑 代签」。签字一(需求确认)与改代签设置从不代;用户本人随时能签 | §十五「签字机制:两条路」「代签设置、验收谁签与代签命令」;§八「签字记录只认两条路」 |
| 代签设置 | 两个开关,各有「代签」「亲签」两个值(.claude/sign-settings.json,不归任何版本单元):产品专项是类别写「产品」的需求(业务流程),Harness专项是类别写「Harness」或「规范」的需求(Harness 流程与规范流程);设成代签的那一类,验收完结与线上写入的点头由 X大脑 代用户来,设成亲签的由用户本人来;文件缺了、读不出或写得不对一律按亲签;改设置不立项,用户在 X大脑 窗口说四句固定的话之一,或自己手改 | §十五「代签设置、验收谁签与代签命令」 |
| 型号配置 | 一份文件 .claude/model-settings.json(不归任何版本单元):主控类(X大脑、产品架构师、Harness架构师)与执行类(其余会话角色与全部执行体)各一对「型号 + 推理档」,七个会话角色另可按角色单独设一行(没写的随它所属的类,单独设的仍归原来的类),角色那一行另有快速型号与上下文宽度两列(只设在角色行上;没写的,走代理的拒绝起会话,走官方的由客户端用它自己的缺省),文件顶层另有一个代理地址(全文件一个值、不许带口令),是型号与推理档的唯一出处,别处都不写具体值;改它只有一条路 —— 用户在 X大脑 窗口说固定话「型号配置:<类> <型号写法> <档>」「型号配置:<角色> <型号写法> <档>」(后面可带「快速 <型号写法>」「宽度 <数>」)、「型号配置:<角色> 跟随」或「型号配置:代理 <地址>」(按行认,一条消息里可以连说几行、每类或每个角色一行),X大脑 跑受信命令,不立需求、不升版、不封版;改型号配置的那一刻也核走代理的角色两列与代理地址齐不齐,换族时没说到的两列清空,改代理地址那一句只核地址本身;查看命令印每个角色一行的有效表;型号以 gpt 打头的经本机代理,会话命令发起、叫醒、恢复任何会话之前洗掉继承来的代理六项,代理不通当场拒绝、不退回 Claude;读不出一律拒绝起会话、不退回写死的旧值 | §十五「型号与推理档」;§八 环3「派发的型号与推理档」;体系守护技能说明 model-settings 一节 |
| 验收谁签 | 每条计划的看板与机器镜像里的一栏(亲签或代签,加一句理由),签字一时就定下:主控写设计要点时判断、产品经理写进计划;那一类设成亲签只能亲签,设成代签默认代签、验收清单里有只有用户能判的项就定亲签;用户签「确认」时说「这条我自己验」就改成亲签。随签字一锁住:放宽(亲签改代签)要用户重签,收紧(代签改亲签)走核准、不用重签 | §十五「代签设置、验收谁签与代签命令」;§八「需求对账」签字只锁五样 ① |
| 签字放行 | 签字一就是受保护文件放行的授权:实施时守卫照常在岗,只对这条需求的办理会话放行它签过的那几个受保护文件(四样同时成立:写的是办理会话、路径在签字时的落点表算出来的受保护格里且核准后还在、需求在办、不在永不放行名单),范围写死为脊柱与检测引擎承牙两类;写文件工具与命令行只放行写,受保护文件的删除只经换入帮手标删、问的是同一份放行;验收完结、归档、签字作废当场收回;放行评估出错一律按不放行 | §八 环1「签字放行」 |
| 受保护格 | 落点表里落在受保护文件(守卫、检测引擎、执行体目录、项目设置等,名单照守卫自己的保护名单;通配符先展开成真实文件再逐个问名单)上的格;由计划工具(立项命令、对账命令、签字题命令)自动标「受保护」,不靠人手标、不另存标记,由签字那一刻的落点表和保护名单现算;永不放行名单里的文件虽然受保护但不在放行之内;放行范围也比受保护格窄(只脊柱与检测引擎承牙),落在保护区或项目设置上的受保护格不放行,要改仍得用户手动开闸 | §八 环1「签字放行」;§十五「七个风险标记定最低档」 |
| 急救开闸 | 手动开闸(把项目设置里写前拦截那一行改名)只留作急救:新换上的守卫坏了、连恢复命令都被拦住时,用户照旧可以手动停掉写前拦截来救;救完提醒关。设置会热加载,开闸那一刻全部在跑的会话同时失去守卫,所以第一步先停掉常驻会话与各位产品经理 | §八 环1「签字放行」;§二 |
| 提交命令 | 体系守护命令的提交动作(harness.js --action=commit --plan=<需求名>),真仓里写 git 的唯一一条受信的路:环收尾(已发布、已归档)之后由主控跑,把这条需求验收过的那一份(它的交付、履历、归档与台账,不带别的需求的东西)按项目名提交进版本库、打项目标签、推主干与这个标签(只许正常推,两样一起成或一起不成)。不带 --execute 只预览,带了才做;跑之前核五样,哪一样不过就停、什么都不写;授权就是验收完结那一签,命令不另要一次授权。命令行里的 git 一律只读,提交与推送只经它;钥匙石与代签设置它从不提交;命令末尾另印这一次放开了哪些单元、此刻开得了工的是谁 | §八「提交命令」「命令行里的 git 一律只读」;§十四「环收尾之后的提交与结案报告」 |
| 项目标签 | 每条需求提交之后打的带说明的 git 标签,名字 req/<需求名>(需求名就是计划目录名,全仓唯一)。一条需求一个提交、一个标签:用户随时能按标签回看这条需求改了什么;提交说明以短名打头,写着改了哪几个单元、各升到哪一版,发了哪几格记在随提交进库的需求履历与发布段里。推送只推主干与这一个标签 | §八「提交命令」 |
| 结案报告 | 十态命令带计划名查一条已提交的需求时,末尾印出的五行加一行提交号:交付了什么、发了哪几格、还要用户自己上传的端(在体系之外发的格)、遗留去了哪、代签凭什么,另一行写提交号、标签与推没推到远程;新式专项(见 §八「后台收尾」)最末另多一栏后台收尾(取自复盘记录)。其余全取自履历、发布段、收尾单与账本;项目经理转 X大脑,X大脑 原样转用户 | §八「结案报告」;§十四「环收尾之后的提交与结案报告」 |
五类需求入口表
一条需求改的是哪一类东西,就照哪一行办。前三行(改 agent 架构、改项目架构、改框架)走 Harness 流程,第四行(改系统规范)走规范流程,第五行(业务需求)走业务流程;运维与分析两条辅助流程不立需求、不在这张表里(ADR-105;车道见 §十五「先分级、再选路」)。落点不归任何版本单元的按目录认流程,官网走业务流程的小事那一档(见下「不归任何版本单元的东西」)。三条主流程走的是同一套闭环(计划、签字一、封版、独立复盘、三查、验收完结(签字二)、发布、清理归档),差别只在这张表的六栏。「单元」一栏里带代码记号的就是这一行的单元名,而且只有它们带代码记号(尖括号里的是占位:规范名、中心与域照实填)—— 体系守护技能立项那条命令按落点单元查执行体时读的就是这张表的「单元」与「执行体」两栏,改表头或改这一栏的写法要同批回看它。那条命令按落点单元只印对得上的那几行(命令行给了单元就按它筛;没给而这份计划已经在、机器镜像里有落点表,就照落点表筛;两样都没有才整张打印并写明没给单元),所以每一行的「执行体」一栏要自己写全 —— 各类需求都要派的四位(项目经理、调研员、对抗审查官、复杂化审查官)每一行都列;产品经理 x-product-manager 是办这条需求的会话、不是派出去的执行体(只作会话用),但每一行「执行体」一栏的头一位也写明它(名册里主控之外的每一位都要在这一栏出现,立项命令的床守着);复盘经理 x-retro-manager 同理 —— 只作会话用、验收完结之后由项目经理起,不是派出去的执行体,每一行也写明它;每位先写叫什么、再写执行体定义的名字(派的时候类型就写这个名字,名册外的类型守卫会拦)。那条命令新建骨架时(ADR-104),命令行给的单元里有 project:overview 或 agent:overview 的,在机器镜像与看板的落点表里各自动带一行这个单元的落点 —— 三格「设计页」「变更历史」「锁清单」,对着它目录下的设计页、变更历史与锁清单三个文件,两份逐字相同(计划已经在了再跑不补)—— 锁清单由封版命令写,没列进范围就算范围外的改动,只能补范围、重签一次;agent 架构要改的执行体文件、别的单元的格,由写计划的人填。
| 哪一类 | 单元 | 入口 | 谁写计划 | 执行体 | 封版命令 | 发布面 |
|---|---|---|---|---|---|---|
| 改 agent 架构(执行体这一侧的设计页与执行体文件) | agent:overview,锁设计页与执行体文件;执行体文件的形归 x-agent 规范管,改到它的判据或条款时同一份计划另列「改系统规范」那一行的单元 | 需求流水线,没有专属工作流 | Harness架构师出设计,产品经理写计划(看板与机器镜像);小事产品经理写一页计划 | 产品经理 x-product-manager(办理会话,只作会话用);Harness架构师 x-framework-architect(设计页的字与变更历史的说明);视觉设计师 x-visual-designer(设计页里的图与预览稿);元治理专家 x-meta-governor(执行体文件与注册表,执行体目录受守卫写保护、办理会话在签字放行内写得进);站点工程师 x-site-engineer(治理站点上这一栏的构建器要动时 —— 站点源码不归任何版本单元,落点表里另列一行、单元写 none);项目经理 x-project-manager(接力点:立项排期、起关会话与握手;回报节点;封版之前核同一单元上别的线停没停;遗留去向台账);复盘经理 x-retro-manager(只作会话用:验收完结之后由项目经理起,做过程复盘、写复盘记录、报 X大脑);调研员 x-researcher(要先查清的只读活);复杂化审查官 x-complexity-reviewer(成条与难事签字前的减法审);对抗审查官 x-adversarial-reviewer(独立复盘,只派它) | node .claude/skills/x-meta-dev/scripts/meta.js --action=seal --unit=agent:overview --execute | 落盘即生效,发布段记「已生效」一格;另有「治理站点」一格,由运维经理发 |
| 改项目架构(流水线自己的设计页) | project:overview,只锁设计页;流水线的机制住守卫与体系守护技能,改到机制时同一份计划另列「改框架」那一行的单元 | 需求流水线,没有专属工作流 | Harness架构师出设计,产品经理写计划(看板与机器镜像);小事产品经理写一页计划 | 产品经理 x-product-manager(办理会话,只作会话用);Harness架构师 x-framework-architect(设计页的字与变更历史的说明);视觉设计师 x-visual-designer(设计页里的图);改到机制时加体系工程师 x-harness-engineer 与测试工程师 x-test-engineer;项目经理 x-project-manager(接力点:立项排期、起关会话与握手;回报节点;封版之前核同一单元上别的线停没停;遗留去向台账);复盘经理 x-retro-manager(只作会话用:验收完结之后由项目经理起,做过程复盘、写复盘记录、报 X大脑);调研员 x-researcher(要先查清的只读活);复杂化审查官 x-complexity-reviewer(成条与难事签字前的减法审);对抗审查官 x-adversarial-reviewer(独立复盘,只派它) | node .claude/skills/x-meta-dev/scripts/meta.js --action=seal --unit=project:overview --execute | 落盘即生效,发布段记「已生效」一格;另有「治理站点」一格,由运维经理发 |
| 改框架 | framework:harness | 需求流水线,没有专属工作流 | 同上 | 产品经理 x-product-manager(办理会话,只作会话用);Harness架构师 x-framework-architect(宪法、本文、决策记录、工作流说明与参考文档);体系工程师 x-harness-engineer(守卫、检测引擎、工作流脚本、技能资产 —— 含计划模板与端壳模板);元治理专家 x-meta-governor(元规范、没配对的规则书;执行体文件归上面「改 agent 架构」一行);测试工程师 x-test-engineer(测试床);站点工程师 x-site-engineer(同批回看治理站点入口页与构建器时,落点表里另列 none 一行);体系体检官 x-harness-auditor(改完守卫、检测引擎或工作流之后的体检,只读);项目经理 x-project-manager(接力点:立项排期、起关会话与握手;回报节点;跑整面床与发布两个窗口的排法;遗留去向台账);复盘经理 x-retro-manager(只作会话用:验收完结之后由项目经理起,做过程复盘、写复盘记录、报 X大脑);调研员 x-researcher(要先查清的只读活);复杂化审查官 x-complexity-reviewer(成条与难事签字前的减法审);对抗审查官 x-adversarial-reviewer(独立复盘,只派它) | node .claude/skills/x-meta-dev/scripts/meta.js --action=seal --unit=framework:harness --execute | 同上;守卫与脚本改完在本机立即生效 |
| 改系统规范 | spec:<规范名> | /x-meta-dev —— 走的仍是这条需求流水线,它管改判据、回看条款、刷新派生区这几步 | 同上 | 产品经理 x-product-manager(办理会话,只作会话用);Harness架构师 x-framework-architect(规范流程的设计);元治理专家 x-meta-governor(判据、条款、架构页与系统架构公共部件);测试工程师 x-test-engineer(判据床);动到检测引擎时加体系工程师 x-harness-engineer;项目经理 x-project-manager(接力点:立项排期、起关会话与握手;回报节点;规范收紧带出的业务整改逐条记进去向台账、排成业务需求;遗留去向台账);复盘经理 x-retro-manager(只作会话用:验收完结之后由项目经理起,做过程复盘、写复盘记录、报 X大脑);调研员 x-researcher(要先查清的只读活);复杂化审查官 x-complexity-reviewer(成条与难事签字前的减法审);对抗审查官 x-adversarial-reviewer(独立复盘,只派它) | node .claude/skills/x-meta-dev/scripts/meta.js --action=seal --unit=spec:<规范名> --execute | 同上;规范收紧带出的业务代码整改各归各的业务域单元,要上线的照下一行发 |
| 业务需求 | domain:<中心>/<域>;跨域关系图与注册表是 business:overview | /x-feature-dev | 产品架构师出设计要点,产品经理起草计划,产品架构师审计划合不合设计 | 产品经理 x-product-manager(办理会话,只作会话用);产品架构师 x-architect(域设计:实施之前先在本域变更历史最上面加新的一版,实施之后回看域文档);数据表专家 x-data-engineer、云函数专家 x-server-engineer(含服务端内核母本)、后台前端专家 x-admin-engineer、小程序前端专家 x-client-engineer(含移动端母本与各 backend)、支付专家 x-payment-specialist(按端与域);视觉设计师 x-visual-designer(页面的预览稿与走查);测试工程师 x-test-engineer;模块下线专家 x-module-terminator(删除这个动词时:出残留清单、删仓内文件);运维发布专家 x-ops-deployer(发布量大时由运维经理派);项目经理 x-project-manager(接力点:立项排期、起关会话与握手;回报节点;联调上线的去程与回程 —— 产品经理报主控、主控转运维经理、运维经理回主控、主控转回产品经理;数据表在控制台导入做完的那一句;验收完结之后正式发布的排法、盯到发布登记跑完;遗留去向台账);复盘经理 x-retro-manager(只作会话用:验收完结之后由项目经理起,做过程复盘、写复盘记录、报 X大脑);调研员 x-researcher(要先查清的只读活);复杂化审查官 x-complexity-reviewer(成条与难事签字前的减法审);对抗审查官 x-adversarial-reviewer(独立复盘,只派它) | node .claude/skills/x-feature-dev/scripts/arch/seal.js --unit=domain:<中心>/<域> --execute,或元治理那一条换上同一个单元名 —— 二选一,结果相同 | 云函数、后台、手机网页版由运维经理经 /x-deploy-dev 发(这几样是该发的格;验收完结之前要上线只走联调);数据表在控制台发、小程序包由用户在微信开发者工具上传 —— 两样都在体系之外发,发布段里记「在体系之外发」、不算进该发的格;只有业务域落点、又没有哪一行业务域只改业务设计页的需求(落点表里除了不归任何单元的那几行,单元全是业务域,而且没碰治理站点自己的源码)没有「治理站点」一格;业务域那一行的目录至少写了一条、而且条条都落在业务架构目录下的(只改业务设计页)不按端推格,有一行这样的就带上这一格;另列了别的版本单元、或碰了站点源码的照旧有 |
四栏的通则:① 签字(签字一、签字二)、独立复盘、三查、清理归档五类都一样,同一份代码(§八「需求对账」)。② 执行体都由办这条需求的领队照这张表与立项命令打印的名单派(§十五 执行体按层表);派出去的类型不在名册就被守卫拦下,平台内置的通用类型也拦(名册里有同名的一行也拦)—— 闸认类型只核类型在不在名册,不核派得对不对(型号与推理档另判,§八「派发闸」「派发的型号与推理档」);独立复盘只派对抗审查官。③ 两个封版入口转调同一个核心:元治理入口封全部版本单元,开发流入口只封业务两类(§十三「两个封版入口,同一个核心」)。④ 一切线上写入只在运维经理的会话里做、每一次都要授权。授权在哪说、谁动手(ADR-102、ADR-116):用户的授权只对 X大脑 说,X大脑 逐字转给运维经理;照代签设置由 X大脑 代授权的,凭 X大脑 转来的代签记录;运维经理以转来的原话或代签记录为准、两样都没有不动手,照发布技能自己动手、量大派运维发布专家,机器只核带「代授权」标记的这一条路(用户本人授权的,机器不核)。这一句里 X大脑 就是主控。这条需求该发的格,授权就是它验收完结的那一签(§十五「谁来发布、怎么授权」)。正式发布排在验收完结之后,由机器核;验收之前要上线只走联调(只限云函数与数据表,§八「部署门认联调」)。⑤ 项目经理在每一行都有接力点(「执行体」一栏各行里写着):它管运行面、不写受治文件,所以封版与发布两栏里没有它;产品经理是办理会话、每一行也都在(只作会话用,不是派出去的执行体);复盘经理每一行也都在(只作会话用,验收完结之后由项目经理起,不是派出去的执行体),所以封版与发布两栏里同样没有它。
不归任何版本单元的东西(治理站点的源码与构建器、官网、钩子接线文件、部署门登记表、代签设置文件、型号配置文件,§十三 诚实边界③):改它们同样走这条流水线,落点表里单元写 none、格里写目录;没有封版这一步,也没有版本记录,只有需求履历。谁写:治理站点的源码与构建器、官网归站点工程师 x-site-engineer;钩子接线文件(项目设置)归体系工程师 x-harness-engineer;项目设置在签字放行的永不放行名单里,改它仍要用户自己动手(手动开闸、亲自编辑,或用「!」跑项目设置改法的脚本,§十五「要 BOSS 亲手做的事」);代签设置文件与型号配置文件不由任何会话写(只经用户在 X大脑 窗口说的固定话驱动的受信命令,或用户手改),落点表里它们各单列一行、单元写 none,同样不在放行之内。改框架时要同批回看治理站点入口页的(§十三「同批回看站点入口页」),在同一份计划里加这一行。认流程照目录(签「确认」那一刻守卫照这个认,§八「认车道」①):官网走业务流程的小事那一档(只改展示;不归任何版本单元、没有封版那一步,全量检测在复盘之前跑一次;不走开发规则书的四端流程),部署门登记表在 x-test 里、同样归业务流程;治理站点的源码与构建器、钩子接线文件归 Harness 流程。
守不到:这张表是照现状写的指路,机器不核一条需求「选对了哪一行」—— 机器认的只有落点表里的单元名、办理会话与文件归哪个单元;谁写计划靠纪律(§十五「这张表今天靠什么」)。派哪个执行体有两道机器:立项命令按落点单元把这张表里对得上的那几行印进派工底稿(只打印、不拦);守卫拦名册外的类型与平台内置的类型(只核在不在名册、定义文件在不在、是不是平台内置的那几个名字,不核派得对不对,不经派执行体那个工具起的执行体不过这道闸,§八「派发闸」)。照不照名单派仍是纪律。执行体那一栏与各执行体文件的「写域」一行一不一致,没有机器对拍;那一栏里的名字全不全,立项命令的床里有一条对真仓的断言守着(名册里主控之外的每一位至少出现一次)。
十八、工作区地基(工作区地图 · 读取模块 · 地板 · 引擎与守卫两路读者;ADR-113、ADR-114、ADR-115、ADR-126)
一条原则:全仓「这个路径是什么、归谁、能不能动、算不算」只写一份,住 .claude/hooks/workspace/(叫地基目录),别处读它、不另抄。病根:同一个目录在索引里是一个结论、在检测器自己走目录树时是另一个结论(§七「路径级忽略」),守卫另有一份名单,改一条路径规矩要改很多处、漏一处就静默分叉。两路读者:检测引擎(索引、目录遍历、五份名册常量、版本契约的单元根、判据注入口)与守卫(按路径分类的判断,经唯一入口),下面「引擎读地图」「守卫读地图与读坏了怎么办」「测试面上游」三节写它们怎么读、读坏了怎么办、测试记录怎么跟着作废;两路都只换了读法 —— 答案逐条等于对拍台金标准里的答案,由对拍台守着(§十六「对拍台与有意改动清单」);会改答案的有意改动一律不在读地图这件事里(见本节末「没改的」)。还各抄各名单的读者不在这两路里:技能脚本、治理站点构建器、三份规范判据里暂留的名单抄本;材料侧的抄本(内核母本工具、后台插件、部署门入口)照旧不读 .claude,由对拍床钉住。
地基目录里有什么:
| 文件 | 是什么 | 谁读 |
|---|---|---|
map-engine.jsonl | 引擎段数据:词表、名册(成员可带附加信息)、区树骨架、引擎要读的两个属性(存在、检测)和作用在它们上的路径规则 | 读取模块(引擎的取数口只读它;守卫两段都装) |
map-rest.jsonl | 余段数据:其余属性按区编号挂在骨架上、作用在这些属性上的路径规则、对象认法、视图 | 读取模块(两段都装的取数口:守卫、问为什么命令、床;引擎不读) |
read.js | 读取模块:装载、校验、查询(落在哪个区、属性取什么、名册成员与附加信息、视图)、问为什么、给判据的只读取数口;只用 Node 自带模块和地基目录内的兄弟文件,按自己所在位置找数据文件;engine() 只装引擎段、all() 两段都装,都接 { foldCase }(折小写,只给守卫用) | 检测引擎(索引、目录遍历、名册常量、版本契约、判据注入口)、守卫(经 guard/map-reader.js)、why.js、床 |
floor.js | 地板:写在代码里的冻结集合(脊柱、引擎承牙、保护区、装配产物、发布档案、受治根与「受治里不许有免检写区」、必跳名、地基目录自身),地图数据读坏了、被改宽了它照样答;每一类有仓根写法与任意深度写法(守卫「路径里含这一段就算」的写法照原样搬);另有「记录」一类,把盘点表里每一类记录的代表路径钉成状态或日志(只认仓根写法);只许加、不许减,有棘轮床 | 读取模块(装载时拿每一项的样本路径问地图,答案比地板松就拒绝;「记录」一类是钉死、不是只许加严,答得不一样也拒绝)、守卫的读地图入口(问地基目录里的路径时保护类视图直接由它答) |
glob.js | 地图自己用的路径匹配函数:自写、不依赖 minimatch,以引擎现行 matchFilePattern 的五步为基线,支持字面前缀(整块)、*、**、?、花括号并列;取反和字符集不收,不认得的写法当场抛错。它只服务地图,引擎现行匹配器与各处自写的通配一个不换,由差分床逐位对拍(仓里在用的模式、对拍台的 33 个写法、固定种子的随机写法) | 读取模块 |
fingerprint.js | 指纹口径的骨架:只定接口,调用即抛(指纹算法没定) | 暂无 |
why.js | 命令行:why.js <路径> 问为什么(输出格式固定:路径、区与出处、每个属性的值与出处、地板);why.js --check 核数据文件 | 人、床;地图读坏时照常能跑、点名坏处 |
数据格式:JSON,一条记录一行,t 字段在前,出处就是「文件:行号」(仿 git check-ignore -v);第一行是文件头 head,末行是带条数的结束记录 {"t":"end","n":条数}(截断在行边界的文件读得出来,条数对不上就红);读的一端容忍回车加换行。记录类型:attr(词表)、roster(名册)、zone(区骨架)、zset(区的余段属性,按区编号挂)、seg(路径规则)、kind(对象认法)、view(视图)。不自造键序规范化器:排版只要求「一行一条合法 JSON、t 在前」,why.js --check 守着。
数据模型:区按路径划成一棵树,每个路径落在最深的那个声明过的区(同深度字面多的赢),子区继承父区属性、写了就覆盖;区路径一律按整块算(带通配的区路径命中路径本身或它的任一祖先目录都算落在这个区);无区(地图没声明的路径,如仓外目标、判据床的固件根)既不额外跳过也不抛错。属性是闭集词表,取值也是闭集,每个取值要么有区在用、要么登记成「预留」并写明哪一步第一次用它(没人用也没登记的词表取值是红)。名册是顶层物、端、业务端、框架内核、站点、移动端实例、母本包根与容器(带单包多包与层)、测试根、按名跳过(build、worktrees 标过渡)、路径级跳过、没有配对规范的规则书、单元根、版本契约跳过名、裁判五样、判定代码、覆盖令牌等;成员可以带附加信息(info,如单元根的常量名与管不管顶层版本单元、裁判五样的成员属于哪一样)和过渡说明(trans),读的一端按名取,名册不存在、成员缺附加信息或类型不对一律抛、不给默认值;名册是这些名单唯一的一份账,引擎常量与守卫里的几处从它算出,或由钉住床核它们与它一致(legacy 字段只记它顶替的旧名单名,作说明)。路径规则(seg)按路径里某一段的名字、或连续几段(seq,如 dist/web、.cache/web-src)叠加属性,可以用 under 限定只对哪些路径起作用、用 nested 表示起点不能是仓根那一段(目录名册里的名字、点开头、sys/templates/.umi 保护区、任一层 .gitignore 受治、任意深度的装配产物与账本等写法),都是为了与守卫和引擎今天的答案逐路径一致而原样搬来的;改成从根按前缀算会改答案,不在本节。文件类的区(.mcp.json、settings.json 这类)只管文件本身:区路径按整块算,所以它底下另立一个 <文件>/* 子区把「保护」读回普通(写 /* 不写 /**,尾部 ** 在读取模块里至少要再有一段)。引擎段与余段:引擎要读的属性(存在、检测)和骨架、词表、名册在引擎段,其余在余段 —— 分文件是因为测试面机制只能整个文件挂上游(§十六),改余段不让检测引擎一族的床作废。
属性「记录」:答「这个路径是不是一份记录、哪一类」,取值状态、日志、否(不写就是否:设置、说明书、代码都是否)。状态 = 判定代码按内容判的那一份,只写现在、能小就小 —— 需求账本与会话台账的第一层、原话账、跑床账、变更历史、需求履历里的 releases.json 与 record.json、发布台账与各站点发布档案、总账与待立项目清单;日志 = 只供将来复查,只追加或封死,住日志区 —— 已提交的账本区 requirements/done/、已结束的台账区 ledger/ended/、跑床记一行 ledger/bed-runs/、需求履历里的 RECORD.md、决策记录、复盘记录、计划归档。一个路径只属一类,只由区写、不由路径规则叠加;每一类记录各落一个区,区的说明写清谁按内容判它、或它是日志、什么时点进来(会话台账与需求账本到时点挪进日志区,见 §十五「记录分几类、放哪」);地板把每一类的代表路径钉死;why.js 一问就答出值与出处第几行。按它核的是运行器的卫生检查(床的上游不许盖记录区,§十六「卫生检查」⑦)与日志换空对照(§十六「床不读真仓的记录」);判定代码不按日志的内容判,是写法规矩、机器不另立闸(§十五「记录分几类、放哪」)。三个属性并存、各答各的:「记录」「运行时状态」「入库」。属性「运行时状态」与属性「记录」的取值「状态」不是一回事 —— 前者答它是哪份账、哪把锁、哪份缓存(取值账本、锁、缓存、否),后者答它是判定代码按内容判的那一份记录:锁与缓存是运行时状态、却不是记录,变更历史是状态类记录、却不是运行时的账。属性「入库」答它该不该在 git 里(入库、台账、不入库),与它是不是记录、哪一类无关(挪进日志区的已提交账本区照样答台账,挪账的改名靠它被下一次提交带走)。
读不到就拦:文件缺、空文件、有一行不是 JSON、读到半截(先重读一次,仍坏才报)、未知键、取值不在闭集、越过地板(把脊柱区标成普通)、被改宽(把受治区标成不适用),各抛一次 WorkspaceMapError,报文点名文件和行号,绝不退回内置的旧值。装载在用到时才发生,加载读取模块本身不读任何数据;读的一端按名取名册时发现名册不存在、附加信息缺或类型不对,同样抛。
引擎读地图(ADR-114、ADR-126)
索引与目录遍历共用一个跳过判断(scanners/walk-skip.js):检测引擎的索引(scanners/indexer.js)与检测器自己走目录树的遍历(scanners/file.js 的几个遍历函数)问同一个判断。一个目录要跳过,满足任一条:名字在目录名册里、点开头(.claude 除外)、落在测试根里、落在路径前缀表里(前三张表就是地图的名册「按名跳过」「测试根」「路径级跳过」),或地图里目录所在的区「检测」是「不扫」(第五条,目前只有 .claude/bak,有意改动 D3)。合并时只许多跳、不许少跳;第五条只问扫描根(顶层物加 .claude)之下的目录,扫描根之外(docs、x-temp 这类)索引从不进、地图的「检测」答案对它们没有意义,遍历从仓根往下走时也不因此多跳。不变量:顶层物之下凡「检测=不扫」的区,必须已被目录名册、点开头、测试根、路径前缀四者之一蕴含,.claude/bak 是唯一例外(它不在业务树里),否则覆盖闸会与索引分家。
名册常量从地图算出:检测引擎里有地图对应物的名单不写字面量,加载时读一次地图引擎段的名册,算成与字面量写法一模一样的普通数组或对象(导出名、形状、值、顺序都相同):constants/defaults.js(按名跳过、路径级跳过、目录标记排除)、terminals.js(顶层物、端、业务端、框架内核、站点、移动端实例、母本包根与容器、非母本目录)、test-roots.js(测试根转成正则)、rule-books.js(没有配对规范的规则书)、version-contract.js(九个单元根;版本契约跳过名的全部成员,与其中「业务代码判断也跳」为真的成员)、utils/module-detector.js 的三个冻结常量(端内部结构、端入口文件、端内叶子目录,仍是冻结的)。展示用的几项(端的显示名与次序)与各文件里的函数没有地图对应物,留在原处。名册不存在、成员的附加信息缺或类型不对、单成员名册被改空,一律抛 WorkspaceMapError 并点名名册所在行,不给默认值;缺地基目录时这些文件加载当场抛、点名读取模块的位置,不读名册的文件照常装得上。
六张名册(地图为引擎与守卫立的名单):「单元根」(版本契约的九个单元根路径,附加信息写常量名与管不管顶层版本单元)、「版本契约跳过名」(附加信息:业务代码判断是否也跳它)、「没有配对规范的规则书」,引擎读;「裁判五样」(判决依据五样展平成文件,附加信息:属于哪一样)、「判定代码」(守卫整棵、检测引擎、测试运行器三块展平,附加信息:属于哪一块、文件还是目录),守卫读;「覆盖令牌」,元规范读。「裁判五样」「判定代码」与属性「判决依据」(它的值「判官」)是两回事:后者恰好等于脊柱加引擎承牙(地板强制),比五样大得多,直接读它会让守卫对执行体定义、项目设置、锁清单这些多拦,所以五样与判定代码另住名册,「判官」属性不动、仍给地板用。
判据注入键 workspaceMap(buildDetectorTools):只读取数口(zoneOf 查区、attrOf 查属性、roster 查名册、rosterInfo 查名册的说明与附加信息〔只读、冻结〕、why 问为什么),只看引擎段(问余段属性抛错),进程级只建一次、连造多少次 tools 都是同一个冻结对象;读取模块装不上(沙箱缺地基目录)时造 tools 不抛、给一个五个口全抛的占位,判据真用到才抛;缺注入(手搭 tools)判据自己抛或推红,不退回旧名单。判据只经这个键取名册,读它的判据取的是名册成员(例如元规范的覆盖令牌、标记规范的源根、发布规范的发布目标),其余判据照旧不读;规范判据里暂留的几份名单抄本另行改读。射程缓存键多一样(第五样):地图引擎段加读取模块、地板、匹配函数三件代码的原样字节。
check.js 里不读名册的几处:按语言层筛选读「计划区」「来源」两个余段属性的几处与单元前缀的几处留字面量,由引擎常量床(workspace-engine-constants.test.js)逐处核它们与地图一致 —— 引擎读口只装引擎段,挪属性进引擎段或让引擎装余段都会牵动射程缓存键与四族床记录。读不到就拦:引擎里读名册的文件加载当场抛、要建索引的检测(含收尾与部署门起的 check.js 与覆盖闸)被拦,这是预期;守卫懒加载这些文件时怎么办,见下一节。引擎整树被抄进沙箱的床要把地基目录一并带上,见下一节的「沙箱带地基目录」。
守卫读地图与读坏了怎么办(ADR-126)
一句话:守卫里按路径分类的判断(这个路径受不受治、保护到哪一级、算不算判决依据、归哪个版本单元、属哪个测试面上游……)问同一张工作区地图,不各抄一份名单;答案逐条等于对拍台金标准里的答案;读不到地图时,要用地图的动作一律按拦、报文点名坏在哪个文件第几行并写明修法,哪一处都不把「读不到」当成「不受治」「不保护」放行。
一个入口,两段都装:守卫只经 guard/map-reader.js 这一个入口问地图;各零件一律在用到的那一行才 require 它,不许自己去装读取模块 —— 装哪个读取模块、读哪个目录、折不折小写、读不到怎么办,只在这一处定。入口三条规矩:① 顶层只 require Node 自带的东西,读取模块与地板在函数体里第一次问才装;② 折小写开关只给守卫:入口恒以 { foldCase: true } 取两段都装的读者(守卫要读余段属性),读取模块把输入、区路径、路径规则里的名字与地板的正则一律折成小写再比,脚本与检测引擎照旧直接用读取模块、区分大小写,读取模块进程内缓存的键含这个标志,同一个进程里两种读者答案互不串;③ 读不到就把读取模块的错原样抛:不改写、不包一层、不退回旧值,也不叠重试(「读到半截先重读一次」只在读取模块里做)。调用方交进来的是它按自己入口的老办法归一好的仓根相对路径(折小写、折叠 .. 与 //、去尾点与尾空格),入口不再归一;读的是守卫自己所在那棵树的地基目录,沙箱里守卫在哪读的就是哪棵树的地图。入口导出 view(视图真假)、attr、zoneOf、roster、rosterInfo、zonePaths(直接写了某个「属性 = 值」的区的区路径)、generationOf(地图代数:数据文件变了、读者换了才加一,调用方据此记住按地图算出来的东西)、explain(把错说成一句话)、isMapError(调用方的 catch 用它认「这是地图读不到」);同一个进程里连着问时读者拿住约五十毫秒再去核数据文件的修改时刻。
哪些判断问地图,哪些不问:问地图的 —— 命令判定零件的五个写保护谓词(脊柱、检测引擎承牙、保护区、装配产物、发布档案)与判业务目录(视图 spine、engine、protected-area、generated、release-archive、biz-dir);需求零件的受治根、判决依据五样与判定代码(名册「受治根」「裁判五样」「判定代码」);测试面零件的上游组与测试根(属性「测试面上游」、名册「测试根」);收尾处理的规则书分类(名册「没有配对规范的规则书」);守卫懒加载的引擎文件(端名册、测试根、规则书名册、版本契约)加载时读它们自己的名册。今天直接对原始写法做字符串比较的判断(受治、顶层围栏的路径预筛)不问会先规整路径的视图:受治用名册「受治根」的成员做同样的字符串比较,预筛用写死的前缀表(钉住床核它不比地图窄),所以对不规整写法的答案不变。不问地图、按老写法判的(老支,保留原来的判法,答案与金标准一致):换不成仓根相对的写法(仓外绝对写法、盘符、UNC)、带 $ ~ % 的写法(展开后落在哪守卫不知道)、无锚怪癖(名字以 .claude 结尾的段前面还有别的字符)、目录自身节点(老写法要求目录名后面还有内容;挪走与删除目录由 mv 那一支用「目录 + /_」代入,不接受地图对目录本身的答案)、判业务目录时带非字面字符的怪名字;保护样本表、「目录 + /_」代入与保护上级目录的判断写在守卫里,不从区树派生。
用到才装,三条路不碰地图:不需要按路径判断的事件与工具调用,不装入口、不读数据文件。原话入账(说话那一步记原话,以及它之前的一切)、会话开始(含它读计划状态那一步)、收尾记写证据(写后记账、收尾里的量仓与归属)三条路连间接经过的零件也不碰地图,改配置同样;各零件加载时一个都不装入口,命令判定零件里老支用的「任一段」正则、端名册与测试根在第一次被问到时才由名册现造并缓存,收尾处理里的规则书判据只有这一轮真改了规则书、要分类时才装。要用地图的步骤才读:说话时记完原话之后认签字、算排队计划开不开得了工;写前对路径的判断;写后记完写证据之后的「写后提醒」(读名册「受治根」,问这个文件在不在在办需求的范围里);收尾真走一轮时算测试新鲜度(问上游组与测试根)与分类改过的规则书。认流程那一条链上一律不读地图:planStates → flowCheck → flowStamp → flowOf(以及 sessionGate、workAreaStateOf)在会话开始、每条命令、施工区状态里都要走,链上用到的名单与字面量全部写死在需求零件里(认流程用的端名、无单元落点行的路径表、计划目录与需求账本目录名、会话登记册位置),由钉住床核它们与地图一致;链外只在明确要用的步骤(开工判断与排队占用、判决依据冲突判断、签字核对、判决依据五样与判定代码的判断)才读,读的时候也不从链上间接触发。惰性床(workspace-guard-lazy.test.js)在沙箱里起真守卫,逐事件记装了哪些模块、读了哪些数据文件,不需要地图的一个都不读。
读不到地图怎么办:读不到 = 数据文件的毛病(缺、空、格式错、读到半截重读仍坏、越过地板、被改宽),或读取模块的代码本身装不上、运行出错。处置只有一条:要用地图的动作一律按拦(退出码 2),报文点名「文件:行」、原因、按拦的交代和修法 —— explain 一处出话:有在办需求时在它的施工区副本里把点名的文件修好、经换入帮手换进真仓;没有在办需求时只剩急救开闸;核数据文件的格式用 why.js --check,问一个路径落在哪个区、出自数据文件第几行用 why.js <路径>。读取模块的代码本身有毛病时报文多带出错的文件与行;入口自己装不上就退回只带出错位置的说法,不让出话的代码再抛一次。哪一处都不把「读不到」当成「不受治」「不保护」「放行」:凡有 catch 把错吞成「不是」或「判不了」的几处(判脚本在不在受治树里、认排队计划开不开得了工、认签字、量站点原料目录用的端名册),遇到地图的错一律原样往上抛,别的错才按各自的走法处理;每个 catch 之后还要往下走的,先问入口的 isMapError,是就继续抛;回归套件的失败矩阵(§八「零件用到才装」)把入口算一列,另有一行「地图读到半截 + 非字面的业务目录写法 ⇒ 抛地图的错、不放行」守着。各事件在读不到地图时:
| 事件 | 地图读不到时 |
|---|---|
| 说话(原话入账) | 退出码 0、原话已进账本;记完原话之后要用地图的步骤(认签字、算排队计划开不开得了工)没做 —— 这一句签字不生效,说话照常,回一句点名文件行与修法的话;读取模块有语法错、有排队计划、说了签字句也一样 |
| 会话开始、改配置 | 照常(读计划状态那一步用写死的名单,不碰地图) |
| 写后记账 | 写证据照记,退出码 0;写后提醒这一次没做,回一句点名文件行的话 |
| 写前:编辑工具与命令行直写 | 除下一行不问地图的几种之外一律拦(受治文件、不受治的文档、计划目录都一样),退出码 2,GUARD-ERR 点名「文件:行」并带修法;零件装载期问到地图走 GUARD-BOOT |
| 写前:不问地图的 | 只读命令照放;施工区副本里的写照写(办理会话写自己的施工区);办理会话的换入帮手与 why.js 照跑 |
| 收尾 | 第一次照记写证据基线;真要算测试新鲜度或分类规则书的那一次点名地图并拦,被拦过之后放行并说明 |
读坏之后怎么修:守卫自己的修复路径不能依赖要修的那样东西。所以三处写死在守卫里、不问地图:施工区判断(x-test/zz-work/<需求名>/ 里的副本)、免检写区(计划目录、需求账本目录、需求履历目录)、判业务目录时的施工区早退;准跑脚本树的四个根(.claude、x-harness、x-core、x-test;没签字的会话只许 node 跑这四个根里已有的受治脚本)也写死在守卫里,只是预筛 —— 脚本在不在受治树里那一问仍读名册「受治根」(免检写区排在它前面、不问地图),读不到就原样往上抛 —— 并由钉住床核四个根仍在名册「受治根」里。地基目录自己的保护由地板(代码)判、不问地图数据:入口的 view 对地基目录里的路径(目录自己也算),脊柱、引擎承牙、保护区、装配产物、发布档案五个视图一律直接由地板答 —— 地图读得好时两边答案本来逐条相同(床逐条核,五个视图的选择式在数据里必须仍是「保护 含 某个值」,数据里改了选择式钉住床红并点名),读不到时它照答,所以换入帮手与放行询问问「这个目标是不是守卫脊柱」不依赖地图,修好的地图换进真仓时守卫照签字放行。整条修复路径于是是:地图读坏 → 要写真仓的东西被拦 → 在这条需求的施工区副本里写(施工区判断写死,别的会话写别人的施工区仍被拦)→ 副本里修好地图数据、why.js --check 核格式 → 换入帮手预览并执行,把修好的文件逐字节换进真仓(目标是地基目录里的受保护文件,地板答「脊柱」,凭签字放行)→ 守卫恢复。没有在办需求时新需求签不了字,这条路走不通,只剩急救开闸。
认签字读不到时:说话那一道永远不拦。guard.js 在需求零件外面加最后一层,只放过地图的错 —— 退出码 0、原话已进账本、回一句「这句话里要用工作区地图的步骤(认签字、算排队计划开不开得了工…)没做,签字不生效,说话照常」加点名文件行与修法;不是地图的错仍走顶层兜底的退出码 2。认签字要用地图(车道、单元、判决依据冲突的判断)而读不到时,这一句签字不生效,不会因此记成签上了或排队;地图修好之后用户再说一遍即可。记原话那一步排在所有要地图的步骤前面、一次不碰地图,所以原话不丢。
车道按改地图的值办:地图的属性「车道」只有两个取值 —— 业务流程(业务各端、官网、内核母本、代码测试与业务架构目录)和 Harness 流程(部署门两个入口与其余一切;没写值的区也读作 Harness 流程);规范流程不从区的值来,只经单元 spec:* 认出,分析流程不改任何文件、没有路径走它。守卫认车道时单元先于区的值:落点是有配对规范的规则书,单元是 spec:x-*,答规范流程;没有配对规范的规则书,单元是整个框架,答 Harness 流程;只有落点里没有单元的那几行才按路径认,那张路径表写死在守卫里、由钉住床核它与属性「车道」逐项一致(无区路径按 Harness)。
刻意写死的字面量,由钉住床核:守卫里有几处刻意不问地图的字面量 —— 它们不能因为地图读不到就答不出(地图坏了施工区副本里要能照写、换入帮手与 why.js 要能照跑)。不问地图的代价是两处各写一份会漂,所以钉住床 workspace-guard-literals.test.js 逐项核每一份字面量与地图对应的区、名册、属性或视图一致;往地图里改一项、或改守卫里的一个字,对应那一条必须红并点名:
| 零件 | 写死的 | 对着地图的 |
|---|---|---|
| 台账零件(每个事件都装) | 台账目录、检测目录与检测文件四件(引擎段数据与读取模块、地板、匹配函数)、版本根 | 区 tmp-ledger、spec-scripts、workspace-engine、harness 与 arch |
| 测试面零件 | 床账位置、起算基线与盯盘清单的位置 | 区 tmp-ledger、hooks |
| 装配面零件、联调零件与守卫主文件 | 装配标记位置、联调标记位置、治理站点名与业务架构目录 | 区 tmp-stamp、tmp-requirements、arch-business,名册「站点」 |
| 写后记账零件 | 写证据与收尾量仓跳过的路径正则、施工区正则 | 视图「量仓时跳过」(守卫跳的地图必跳,地图跳而守卫不跳的只许是登记的过渡)、区 work-area |
| 需求零件 | 计划目录与它的归档目录名、需求账本目录(原话账本、各需求账本、复盘说明与它的账的后缀都由它派生)、会话登记册位置、认流程用的端名、无单元落点行的路径表、施工区判断、免检写区、永不放行名单(每一项地图都判受保护)、顶层围栏的路径预筛(不比地图的「可能归顶层版本单元的文件」窄) | 区 plan、tmp-requirements、tmp-sessions、work-area,名册「端」,属性「车道」,视图「免检写区」 |
| 命令判定零件 | 准跑脚本树的四个根、床账与射程缓存两条正则(排在施工区早退与地图之前)、施工区早退 | 名册「受治根」、区 tmp-ledger、tmp-scope-cache、work-area |
另有一批写死而不钉的:单元名前缀与单元显示名(单元名不是路径,地图没有对应物)、风险标记里母本与内核一项、写保护的扣除项(四条正则,不是路径名单)、认命令词的几处(与路径无关)。
沙箱带地基目录:凡把守卫树、五份名册文件、版本契约或引擎整树抄进沙箱或假仓的点,都把地基目录一并带上,不需要带的写明理由 —— 没有共用的复制帮手,每个点补一行。登记在 .claude/hooks/tests/zz-fixtures/workspace-copy-points.json:引擎一侧在 points 与 intentionallyWithout,守卫一侧另立数组 guardPoints(带的写 carries、不带的写 reason),不并进 points(运行器把 points 里的床当作「不做按点替换」的名单读,守卫一侧几十张床放进去会被静默排除出改坏对照)。覆盖床 workspace-sandbox.test.js 现场重扫引擎树与守卫树里的复制点,与登记逐个核对:多一个(新床抄了没登记)、少一个(登记的点已不在)、登记为「带」的那一摞之后几行里没有拷地基目录的那一行,都红并点名;缺地图时期待被拦的用例核拦因必须是读不到地图,不许因守卫起不来而假绿。沙箱缺地基目录时:守卫的零件装得上,引擎里读名册的文件装不上并点名读取模块的位置,要用地图的判断被拦(脱钩床 workspace-decouple.test.js 守着)。
换入后自检:守卫是裁判,改了它一落盘就对所有会话生效,所以改守卫读法的需求在换入真仓之后还要当场自检:用一次性会话号对真守卫各事件(放一条、拦一条、写后、收尾、说话、会话开始、改配置)冒烟,事后账本只多这几行;再对每个入库文件问守卫的写保护、受治、判决依据、落点范围四样,与换入之前的答案逐个相同(落点范围用一份固定的样本计划问,两份答案各带样本的指纹,指纹不同拒绝比对);在办需求的状态与放行询问不变。这是落地那一刻的一次核对,工具与样本放在需求的施工区,不是常驻的床。
守卫读地图的守不到(照实写):① 地图读坏期间,真仓里除施工区副本之外要问路径的写(编辑工具与命令行直写)都被拦,包括计划目录、账本目录这类免检写区与不受治的文档:免检写区的早退只管需求对账那一道,过不了判脊柱与判业务目录那一问;被签字放行的地基目录文件也一样 —— 放行询问由地板答,随后判业务目录那一问要读地图数据,所以编辑工具直写真仓的地基目录在地图读坏时被拦,修复只走「施工区副本里修好、经换入帮手换入」;没有在办需求时新需求签不了字,只剩急救开闸。抢修态(地图读坏时守卫只放读与地图校验命令)这一条没做,去向「新增拦截」。② 只是显示、不是闸的几处读不到地图时静默丢:需求履历的放行栏、排队行、待提交清单、站点发布行 —— 少一行显示,闸照拦。③ 读取模块自己有语法错时,引擎一侧常量与版本契约的装载口报「沙箱里缺 .claude/hooks/workspace/?」并点名 read.js 第 1 行,实际是第 N 行的语法错、目录不缺 —— 仍拦、仍点名 read.js,说法偏弱;守卫一侧的装载口点名对出错的行。④ 老支按老写法判,地图里改了对应的区,这几类写法不跟着变;写死的字面量里钉住的几样由钉住床核「与地图一致」,不核「地图写得对」;不钉住的几样(单元名前缀与显示名、风险标记里母本与内核一项、写保护的扣除项、认命令词)地图里改了对应的区守卫也不跟着变,靠签字与封版。⑤ 折小写只给守卫:同一张地图对只差大小写的路径,守卫与检测引擎可能答不同(今天就是这样)。⑥ 惰性床的追踪器看的是模块装载与对地基目录的 fs.readFileSync,用别的方式读(fs.readFile、createReadStream)看不见;守卫里没有这样的读。⑦ 覆盖床只核源码里有拷地基目录的那一行,不核运行时真拷到;运行时的表现由缺地图沙箱里的真守卫床核。⑧ 延迟只量不设门槛:改读前与落地时各量一次写进需求的证据,没有延迟预算床;新进程第一次问地图要装读取模块、读两个数据文件,同进程之后每问很快。⑨ 守卫判 mv 的来源与 rm 的目标只比受保护样本表与「目录 + /_」,样本表里没有的上级目录可以被整份挪走或删掉;签字会话用 curl -o 等不在守卫写命令清单里的程序可以往受保护文件落盘 —— 两个已知漏洞,不在读地图这件事里修,去向「新增拦截」。
测试面上游(ADR-115、ADR-126)
上游组取自地图:测试面机制里的上游组(它们变了,下游床的旧记录就作废)各对应词表属性「测试面上游」的一个取值 —— 检测引擎、内核、部署门入口、运行器 —— 组里的目录与文件就是直接写了这个取值的那些区的区路径,按区在数据文件里的顺序,经守卫读地图入口的 zonePaths 取;guard/test-faces.js 里只留地图没有的三样:组的显示名、挂哪些面族、哪份文件只取标记区段。测试根目录取自名册「测试根」。加载判定模块不读地图,每组第一次被读到才问,按地图代数记;读不到地图就在读到某一组的那一刻原样抛,调用方记成基础设施异常(收尾记成算不出指纹、上传内容闸按拦),不当成「没有上游」。区路径最后一段带不带扩展名认目录还是文件(地图里目录名不带点),钉住床核:目录必是真目录、文件必是真文件、取标记区段的文件必在该组的区路径里。
检测引擎组登记哪几份:引擎段数据文件与读取模块、地板、匹配函数三件代码(区 workspace-engine)加检测引擎脚本目录(区 spec-scripts)属于「检测引擎」上游组,这个组挂规范、技能、守卫、引擎四个面族(引擎面的新床因此不用逐张写 @covers):改引擎段或这三件代码,引擎、规范、技能、守卫四族的床记录作废;改余段,守卫族(地基目录本来就在它的被测范围里)作废,引擎、规范、技能三族不作废(只有 map-equivalence.test.js 一张因床头 @covers 点名了余段而作废)。会话台账的判据组指纹(session-ledger.js 的 detectPrint)多登记同样四个文件(DETECT_FILES),登记的文件缺了不抛(把「缺」记进指纹):改引擎段,检测干净结论作废;改余段,不作废。台账零件的这几个位置与检测目录写死在零件里(每个事件都装它,地图读坏了它也得走),钉住床核它们与地图一致。一张咬合床(workspace-segments.test.js)在小固件仓里逐族断言。
工作区地基的完整性闸、没改的与守不到
完整性闸:每个入库路径、每个盘上路径(含被 git 忽略的 .env、.mcp.json、x-demo 及其中的嵌套仓、x-mock、端目录里被忽略的条目、.claude 下的锁与备份、施工区 x-test/zz-work)都必须落进一个声明过的非兜底的区;私人区、嵌套仓按「整块」声明,里面新出的文件自动归它;35 个灰区(今天各判断函数没认领或认领得前后不一的入库路径)逐一归区,登记在对拍台的灰区登记表里。闸分入库、盘上未追踪、盘上被忽略的顶层三道,每道故意漏一个区就红并点名,并登记进 guard/state-watch.json(盯仓根一层与 .claude 一层有哪些名字)。
没改的(会改答案的有意改动,不在读地图这件事里;地图里用「过渡」或「预留」标着,等各自另立的需求):D1 build、worktrees 从「按名字」改成「按路径」;D4 docs/ 与 .claude/bak 加「会话不许直接写」;D5 .claude/docs 整个归框架受治;D6 x-temp 里两份 .gitignore 不再受治;D7 技能自带的模板目录不再被误当保护区、保护区判法(sys/templates/.umi,今天是「路径里含这一段就算」)改成从根按前缀算;D8 x-vpn、x-proxy 量仓时跳过;D9 业务端目录里的非代码文件保留今天的口径(「业务源」的扩展名判断留在守卫);还有抢修态(地图读坏时守卫只放读与地图校验命令)、注入的完整性核对、按名跳过的目录落在业务源码区时当场报出、把「过渡」那几组翻过来、各处自写通配收成一种方言 —— 它们都会让守卫比今天多拦或少拦,归待立项目「新增拦截」。床里按现状钉着、动这些有意改动要同批改的断言:读取模块床(workspace-map.test.js)的 R1-11(.claude/docs 其余文件不受治,等 D5)、R2-04 与 R2-13(x-temp 里的 .gitignore 受治,等 D6)、R5-2 的按名跳过过渡成员 build、worktrees(等 D1)、R5-4 的指纹骨架「调用即抛」(指纹算法没定);改引擎名册或地图时同批改的登记:index-walk-unify 的登记例外、glob-differential 的登记与随机表摘要、手搭 tools 清单夹具。
守不到(照实写,工作区地基整体;守卫一侧的细目在上面「守卫读地图与读坏了怎么办」末尾):① 对拍「一字不差」只对语料里的路径成立 —— 真路径、怪路径(大小写、反斜杠、.. 折叠、盘符写法)、补录的特殊路径;语料之外靠地图的区与地板、完整性闸和别的床。② 地图被改宽:地板挡底线(脊柱、引擎承牙、保护区、装配产物、发布档案、受治根、必跳名、地基目录自身),地板之外靠写保护(地基目录在脊柱里)、签字与封版;名册改读之后没有常驻的等值床 —— 往地图里改一个名册成员,引擎常量与守卫会跟着变,改得对不对靠区的说明、签字与封版(逐张名册多加、少一个成员的等值证明只在改读那一次做过、留在那条需求的证据记录里,旧名单快照连同读它们的床与工具已拆,对拍台不读它)。③ 地图写错了一个区的路径,若恰好落在别的区的整块里,完整性闸看不出「落错了区」,只看得出「没落进任何区」和「歧义」 —— 属性对不对靠视图与金标准的对拍(只对有金标准适配器的那些属性),其余属性靠独立复盘抽查;区的说明文字写得对不对,机器判不了。④ 目录遍历收成一种视图,遍历看不见点开头目录与测试根里的东西:这一类变化不在对拍台回放里,靠全量检测前后对比逐条比结论与每份规范的射程兜,比的是此刻的盘,盘上以后新出现的、恰好落在这一类里的目录不在其内。⑤ 引擎的匹配器(matchFilePattern,以及 file.js 里两处直接用 minimatch 的写法)与各处自写的通配没换,两种写法收成一种会改变 -m 的射程,另行决定。⑥ 读取模块不折叠路径中段的 . 与 ..(通配吞不了这两种段,与 minimatch 一致),调用方(守卫一侧本来就先折叠)先折叠再问;怪路径语料里没有触发。⑦ 独立求值器与读取模块有两处口径不同:under 点名的名册写在规则后面(读取模块不拒绝,独立求值器按规则类型说明拒绝)与区路径末尾的 X/**(读取模块要求 X 之后至少再有一段、X 自己不中,独立求值器吞零段、X 自己也中)—— 只对非法数据与真数据里没有的写法有分别,两边各自的答案在地图等价床里钉着,不修;文件类的区底下写 /*、不写 /**,就是为了绕开它。⑧ 地图里标「过渡」的几处(被 git 忽略的路径地图也答入库或跳过、运行时状态、build 与 worktrees 按名跳过)保住今天的答案,零行为差,翻过来是会改答案的有意改动。⑨ 覆盖床只在被跑到时才发现新的复制点:有人新增一张把引擎整树、守卫树或名册文件抄进沙箱的床,覆盖床不会因为那张床是新的而被选中,要等全量跑或体检才红并点名那一处(同批登记就不会红)。
变更历史
全表已外迁 →harness/CHANGELOG.md。
本文件版本号见文首;每次架构性变更在那份变更历史最上面加新的一版(宪法 §六·4),禁止写回本文件。