ACDL研发流程附录B：登记表、状态和常用命令

ACDL研发流程系列第14篇，共15篇。

上一篇：ACDL研发流程附录A：术语和对象关系

下一篇：ACDL研发流程附录C：设计要求与验证追踪

先找到唯一登记入口

ACDL中的同一状态只在一个地方维护。开始实际工作时，先从docs/README.md进入，再找到负责当前对象的登记表，不从聊天、提交标题或其它摘要反推状态。

要查的对象	当前状态由哪里维护	主要内容
REQ和路线图	`docs/01-需求/README.md`	REQ编号、需求状态、优先级、目标版本和路线图入口
当前设计	`docs/02-设计/README.md`及系统、能力、横切设计目录	Accepted产品与架构结论、ADR、索引和稳定设计要求正文
ISSUE	`docs/03-实施/ISSUE/README.md`	问题编号、状态、严重程度、来源和处理去向
ACL	`docs/03-实施/ACL/README.md`	ACL编号、整体状态、版本关系、启动方案和记录入口
DFL	`docs/03-实施/DFL/README.md`	DFL编号、整体状态、实际环境、执行基线（实际使用的提交、制品和配置）及记录入口
ERL	`docs/03-实施/ERL/README.md`	ERL编号、整体状态、评审基线（实际检查的提交或Git标签）、计划和记录入口
目标版本与正式版本	`docs/04-版本/产品版本总览.md`	实际纳入范围、验收结论、发布说明和Git标签
环境	`docs/05-环境/README.md`	当前部署状态、环境变更记录和恢复入口
设计要求追踪	`tests/traceability/design-requirements.json`	稳定要求的来源、产生原因、主题和验证关系

索引负责编号和当前状态，单项正文负责详细内容。不要在实施根索引复制每轮Loop状态，也不要在追踪账本复制REQ、ISSUE、Loop或版本状态。

编号和状态

常用编号和文件名

对象	形式	编号范围
规范	`STD-三位编号-标题.md`	全局连续，不复用
REQ	`REQ-六位编号-需求简称.md`	全局连续，不复用
路线图	`RM-三位编号-标题.md`	全局连续，不复用
系统设计	`SYS-三位编号-标题.md`	全局连续，不复用
能力设计	`CAP-三位编号-标题.md`；专项设计可用`CAP-三位编号-两位子编号`	全局连续，不复用
横切设计	`CRS-三位编号-标题.md`	全局连续，不复用
ADR	`ADR-四位编号-决定名称.md`	全局连续，不复用
设计索引	`IDX-三位编号-标题.md`	全局连续，不复用
ISSUE	`ISSUE-六位编号-问题简称.md`	全局连续；详情文件按需建立
ACL	`ACL-六位编号-主题实施记录.md`	全局连续；计划版本与身份分开
DFL	`DFL-六位编号-主题实施记录.md`；独立计划按需建立	全局连续
ERL	`ERL-六位编号-主题评审记录.md`；独立计划按需建立	全局连续
发布说明	`V0.X-发布说明.md`	与真实正式版本对应

编号一经使用不回收。文件标题变化时保留原编号；工作停止时保留编号并更新状态，不用删除文件来制造连续编号。

Markdown文档状态

状态	含义	常见去向
`Draft`	内容仍在整理	继续编写，或者进入评审
`Proposed`	已经可以评审，等待决定	进入`Accepted`，或者退回修改
`Review`	正在评审或等待确认	进入`Accepted`或`Completed`，也可以继续修改
`Accepted`	负责人确认，可以在注明范围内采用	规范、产品、设计、ADR、当前手册的常见最终状态
`Completed`	计划、记录、版本或材料已经执行结束	Loop计划与记录、正式版本和发布说明的常见最终状态
`Withdrawn`	尚未确认的方案或计划已经停止	保留原因和已发生事实
`Superseded`	已经被新文档或决定替代	与替代入口建立双向关系
`Rejected`	ADR经过评审后明确不采用	只用于ADR

产品、设计、ADR和规范持续表达当前结论，不使用Completed。环境状态随部署持续变化，使用Review记录环境当前状态，不用Accepted表示环境已经获得批准。

REQ状态

需求状态	含义	目标版本
`待评估`	刚登记，尚未判断是否值得保留	不需要
`候选`	值得继续考虑，但当前不一定投入	不需要
`已选中`	Director确认可以进入产品与架构设计	不需要
`已排期`	设计已经确认，并确定交付顺序和目标版本	必须填写
`已完成`	随实际正式版本通过验收	填写实际版本
`不采纳`	拒绝、撤回、重复或由其它事项覆盖	不需要，但保存原因和去向

“设计中”“开发中”和“测试中”不是REQ状态。设计进度从设计文档读取，开发和验证进度从Loop读取。

ISSUE状态和严重程度

ISSUE可以按实际情况在调查、处理和验证之间变化，不把它强行简化成一条只能向前的流水线。

状态	什么时候使用
`待确认`	来源和现象还需要复核
`待分流`	问题已经保留，但还不知道进入REQ、ACL、环境还是其它处理
`待处理`	去向已经确定，尚未开始
`处理中`	已经有正在进行的调查或处理
`待验证`	修复或处理已发生，尚未取得要求的验证结果
`已关闭`	结果已经验证并有明确结论
`不处理`	Director决定不继续处理，并保存理由
`重复`	已有其它ISSUE处理同一个问题

严重程度	含义
`S0`	会造成Secret泄露、越权、跨员工访问、数据损坏、无法恢复或未批准业务写入等必须立即阻止交付的问题
`S1`	核心流程不可用或高概率造成严重业务影响
`S2`	存在明确缺陷，但仍有可用替代路径
`S3`	低影响交互、表达、文档或维护问题

严重程度表达影响，不等于处理顺序的全部答案。是否阻止某个版本，还要结合版本范围和ERL计划中事先确定的标准判断。

Loop整体状态

Loop在启动内容已经准备好、但还没有第一次真实执行时可以处于Ready；开始执行后进入In Progress。现行主要变化是：

Ready →In Progress →Review →Completed
Ready →Withdrawn
In Progress →Withdrawn
Review →In Progress
Review →Withdrawn
历史Accepted →Completed

Review表示执行结束，证据和剩余问题已经整理，等待结论确认或合入；它也可以因为发现缺口回到In Progress。Completed和Withdrawn是最终状态。ACL进入Completed还要求已经合入目标分支，并记录实际合入提交。结果另行记录，不能从Completed推断“没有遗留问题”。

Loop整体状态只在相应ACL、DFL或ERL登记表维护。计划和记录的Markdown状态需要与整体状态一致，但不能替代整体状态。

常用命令

运行命令前先检查工具版本、分支和已有修改

项目命令使用仓库固定的Node.js和pnpm。开始验证前先运行：

nvm use
git status --short
git branch --show-current
git rev-parse HEAD

这四条命令分别确认工具版本、已有差异、当前分支和当前提交。发现不属于本任务的改动时保留它们，不为了得到干净工作树删除或覆盖。

文档和追踪命令

命令	是否修改文件	用途
`pnpm docs:check`	否	检查文档结构、编号、状态、路径、链接、ISSUE与ACL关系及设计要求追踪
`pnpm trace:check`	否	单独检查稳定设计要求账本、正文、验证入口和生成视图
`pnpm trace:render`	是	根据设计正文和追踪账本重建人类可读视图的生成区
`git diff --check`	否	检查空白错误和冲突标记

修改普通Markdown后运行：

pnpm docs:check
git diff --check

稳定设计要求或追踪关系变化时，先生成视图再检查：

pnpm trace:render
pnpm docs:check
git diff --check

ISSUE命令

本地发现的问题先预览编号和准备写入的文件：

pnpm issue:new -- --title=问题摘要 --source=反馈来源 --category=实现缺陷 --severity=S2 --dry-run
pnpm issue:new -- --title=问题摘要 --source=反馈来源 --category=实现缺陷 --severity=S2

来源记录已经完整保存事实时，可以使用--registry-only只登记台账。GitHub新反馈经复核后导入，两边都已有编号时只建立关联：

pnpm issue:import -- --github=42 --repository=example-org/acdl-project --category=实现缺陷 --severity=S2 --dry-run
pnpm issue:link -- --id=ISSUE-000036 --github=42 --repository=example-org/acdl-project --dry-run

GitHub同步只从本地ISSUE台账流向GitHub。不带--apply只报告差异，带--apply才修改GitHub：

pnpm issue:sync -- --repository=example-org/acdl-project
pnpm issue:sync -- --repository=example-org/acdl-project --apply

issue:new、issue:import和issue:link会修改本地登记表和文档，正式执行前优先使用--dry-run。同步不会根据GitHub手工状态反向修改本地台账。

Loop命令

当前loop:new只创建ACL。ACL身份与版本分开，计划版本尚未确定时填写未确定：

pnpm loop:new -- --version=未确定 --title=主题 --source=工作来源 --goal=本轮目标 --dry-run
pnpm loop:new -- --version=未确定 --title=主题 --source=工作来源 --goal=本轮目标

默认创建为In Progress。启动内容已经准备好、尚未发生第一次真实执行时，增加--ready创建为Ready。命令会在单一主记录开头生成启动方案；--mainline和--with-plan已经移除。来源精确填写一个ISSUE-六位编号时，工具还会把新ACL写回ISSUE台账的处理关系。

DFL和ERL当前不能自动创建文件，需要在各自登记表取得下一编号，并按相应模板建立主记录。是否另建独立计划，取决于执行前是否需要单独批准高风险、恢复或评审边界。

ACL进入Review使用专门入口，DFL和ERL使用通用状态命令。状态修改都先预览，再正式执行：

pnpm loop:review -- --id=ACL-000039 --dry-run
pnpm loop:status -- --id=DFL-000002 --status=Review --dry-run
pnpm loop:status -- --id=DFL-000002 --status=Completed --confirm="确认本轮结论和未解决问题去向" --dry-run

loop:review会检查ACL候选和最近一次成功的pnpm verify证据是否匹配。进入Completed前需要Director已经确认；ACL还必须已经合入目标分支，并在主记录填写真实主线合入提交。--confirm只记录确认了什么，不能代替确认本身。

验证和发布前检查命令

命令	用途和边界
`pnpm verify -- --dry-run`	读取当前差异并预览将选择的验证范围
`pnpm verify`	根据当前差异执行不低于要求的验证，并保存能够精确对应被测内容的提交或Git树标识
`pnpm check`	执行工具链、CI契约、输入、Lint、依赖、许可证、类型、构建和非数据库测试组合
`pnpm release:preflight`	检查完整发布验证需要的工具链、Docker、Buildx和`linux/amd64`条件
`pnpm validate:release`	执行完整平台验证，构建并检查全部产品镜像
`pnpm process:metrics -- --since=2026-08-01 --until=2026-08-31`	只读统计Loop积压、已完成周期和ACL首次统一验证结果

涉及真实PostgreSQL测试时，PROJECT_TEST_DATABASE_URL必须指向名称以project_test_开头的全新PostgreSQL18专用测试库。正式发布验证、镜像和环境操作的当前输入条件从《开发与验证》和目标环境记录读取，不把本附录当作环境操作手册。

没有辅助命令的状态怎样维护

REQ排期、设计确认、目标版本形成和版本验收目前没有自动代替Director判断的状态命令。Agent根据已确认事实更新对应台账和正文，再运行文档检查。

脚本能够分配编号、检查结构和同步多个文件，但不能判断需求是否值得做、设计是否合理、证据是否充分或版本是否应该通过。为了让命令成功而修改历史结论，比一次检查失败更危险。