ratchet

Ratchet — 为项目引导或强化防护措施

开始时宣布：“正在使用 ratchet 技能，为此项目设置防护措施。”

前置条件

• 用户调用了 /ratchet，或要求为项目设置、补充或更新防护措施。当前目录就是该项目。
• 对于现有项目，逐步强化执行力度。绝不放宽门禁，也绝不覆盖人工编写的内容。

步骤

步骤 0：定位防护措施源文件

防护措施源文件是与此 SKILL.md 同级、名为 .guardrails-source 的目录（install.sh --copy），否则就是它上两级的仓库；其中包含 templates/ 和 scripts/。读取之前，运行 git clone -q <checkout> <guardrails>，将其克隆到 <tmp>/guardrails；<tmp> 是项目外的临时目录。所有复制操作和测试套件均从该克隆读取；ratchet 完成后删除克隆（references/rationale.md）。

步骤 1：判断模式

Greenfield = 除脚手架外没有其他提交，且没有源文件和现有 AGENTS.md/文档。其他情况均为 retrofit。如果项目已有 .guardrails/scripts/，且需要更新版本，则属于 upgrade：按下方专用流程操作，不做差距分析（references/rationale.md）。

git rev-list --count HEAD 2>/dev/null   # none or few → likely greenfield
ls src lib app AGENTS.md docs 2>/dev/null

除非显然是一个程序的仓库，否则要提问（一次只问一个问题，并推荐一个答案）：是一个系统包含多个包，还是一个仓库包含多个系统？ 一起进行版本管理、发布并承担风险的包属于同一系统：单一单元项目不需要清单，其余步骤照常执行。需要分别满足合规要求的系统，应先进行单元访谈（步骤 1b），再复制任何文件。

步骤 1b：单元访谈（仅适用于多单元仓库）

/ratchet 用于声明事实；规则不可配置。一次只问一个问题，推荐一个答案，并按照表格指示记录每项事实：

询问内容	写入位置
单元有哪些？（每个单元都是相对目录）	.guardrails/units.yaml 中的 units:
哪些内容不纳入合规范围，原因是什么？	清单中的 not_a_unit:；原因作为 # 注释放在对应条目旁
每个单元的安全等级是什么？	该单元配置中的 safety_class: — 步骤 4 的访谈，每个单元重复一次
每个单元依赖什么？	消费方单元配置中的 depends_on: — 每条边都会触发依赖评估（grill-requirements，“声明依赖”）
是否有依赖被隔离？依据哪项控制措施？	消费方配置中的 segregated_from:，并注明 (RC-…)、(adr: <path>) 或 (ADR-<token>)（文件位于根目录或消费方的 docs/adr/）；check-units.sh：未注明来源的条目会被标记为 INCOMPLETE-SEGREGATION

不要询问是否适用等级下限、某个单元是否可以查看其他单元的内部内容，或哪些单元会在合并时运行。

按顺序逐步采用，每次只进行一步。强制的第一步是创建清单、各单元配置和免责声明；depends_on: 为空的单元，是一个与其他项目共用仓库、独立运行的防护措施项目。清单中只列出一个单元、其他所有内容均声明为不纳入范围，是有效且可通过检查的第一步。只有在耦合确实存在时，才声明依赖边（depends_on:、导出项和预期）。

然后运行 .guardrails/scripts/check-units.sh。其发现项（尤其是 UNCLAIMED-PATH）就是免责声明问题的待办清单。

步骤 2（从零搭建）：脚手架

1. 如果还不是 Git 仓库，运行 git init（默认分支名不限）；如果尚无提交，创建一次初始提交（工作树需要一个基底）。

2. 为脚手架创建工作树（worktree-discipline）。

3. 从 <guardrails> 复制以下内容：

   • 单单元：templates/config.yaml → .guardrails/config.yaml
   • 多单元：将访谈结果填入 templates/units.yaml，复制到 .guardrails/units.yaml；并将 templates/config.yaml → <unit>/.guardrails/config.yaml，为每个单元调整其 doc_* 路径和 verify_commands。清单仓库中不得存在根目录下的 .guardrails/config.yaml：在每个关卡中，一个目录树由两个权威配置管理会导致退出代码为 2。references/multi-unit.md 说明了哪些文件应放在各单元中。
   • scripts/*.sh → .guardrails/scripts/（保留可执行权限）
   • templates/srs.md → docs/requirements/README.md
   • templates/rmf.md → docs/risk/README.md
   • templates/sad.md → docs/architecture/README.md
   • templates/soup.md → docs/architecture/soup.md
   • templates/problems.md → docs/problems/README.md
   • templates/CONTEXT.md → docs/CONTEXT.md
   • templates/*_GUIDELINES.md → .guardrails/templates/
   • templates/CLAUDE.md → CLAUDE.md（如果已存在则跳过）
   • templates/AGENTS-block.md → 新建 AGENTS.md 的正文

   requirements、risk、architecture 和 problems 目录是按变更记录的日志：每次变更新增一个文件，命名为 YYYY-MM-DD-<slug>.md，日期为创建该变更的当天。每个 README 都包含条目格式说明。

4. 创建 docs/adr/、docs/plans/ 和 docs/verification/，并将 templates/verification.md 复制到 .guardrails/templates/verification.md。切勿将模板放入 docs/verification/：其中的每个 *.md 都会被视为记录。如果记录保存在其他位置，请设置 doc_verification。将以下缺失项添加到 .gitignore：

   .worktrees/
   .claude/worktrees/
   *.bak
   

   即使项目此前只使用过一个工作树，也要添加两条工作树排除项：.claude/worktrees/ 用于 harness 的变更工作树，.worktrees/ 用于手动回退方案和每个任务工作树；任务工作树嵌套在变更工作树中（worktree-discipline 步骤 1）。

5. 确保提交中存在每个已配置路径；否则 check-trace.sh 会以退出代码 2 结束，而 Git 不会跟踪空目录。

   • strict_paths / test_paths 条目是 Git 路径规范，必须至少匹配一个已提交文件；在空的 src/ 中放置 .gitkeep 即可。
   • doc_* 值必须是文件，或其中直接包含 *.md 文件的目录。目录中必须有实际的 *.md 文件，不能只有 .gitkeep：保留子步骤 3 中的 README。
   • 目录尚无内容时，切勿省略某个键。若要关闭某个关卡，请从 id_prefixes 中移除其前缀，并记录原因。

6. 进行安全等级访谈（步骤 4），将答案写入 safety_class:，替换 TBD 占位值，并将 verify_commands 设置为项目实际使用的测试命令。对 TEST、CODE 和 ARCHITECTURE 运行 tailor-guidelines（对于需要单独文件的每个单元，再运行一次）。

7. 在工作树中提交，然后使用 merge-change 集成。检查脚本必须在集成结果上通过。

升级现有项目中的脚本

在工作树中进行，并作为单独的变更处理。

1. 按照 references/upgrade-notes.md 中的工作顺序执行；其中前三项必须在步骤 2 之前完成。
2. 复制前，为每个指南文件在升级模式下运行 tailor-guidelines。然后从 <guardrails> 复制 scripts/*.sh → .guardrails/scripts/，保留可执行位；并复制 templates/*_GUIDELINES.md → .guardrails/templates/。如果存在，请删除 .guardrails/scripts/finalize-ids.sh、finalize-docs.sh 和 prune-plans.sh。
3. 更新说明语法规则的文件，使其与脚本保持一致。 从同一 guardrails 版本重新复制四个账本 README 和验证模板，并重新替换 AGENTS.md 中的受管区块。如果项目修改过某个 README，请先比较差异，再重新应用其新增内容。
4. 运行 check-trace.sh；修复每项失败，并在步骤 5 写入验证记录时，逐项列出新增警告。现有账本会报告存在问题的 status:/opened:、互为对应的取代关系以及 DANGLING-FILE。 现在会声明派生评估：如果 RMF 中没有 assesses: 行，派生的 REQ/LLR 将标记为红色。
5. 重新记录工具鉴定（步骤 5），然后通过 merge-change 集成。

步骤 3（改造）：先分析差距，再逐步收紧

1. 盘点（只读）：AGENTS.md/CLAUDE.md 的内容，以及与 guardrails 冲突的规则（“直接提交到基准分支”）；现有需求、风险和架构文档；错误跟踪器或问题日志；值得归档到 docs/verification/ 下的验证证据；测试布局和命令；CI 配置；近期提交的签名情况（git log -20 --format='%h %G? %s'）。
2. 将差距分析写入 docs/plans/<YYYY-MM-DD>-ratchet-gap-analysis.md：说明现有内容、缺失内容、冲突内容以及建议的采用顺序。这是本次变更的计划，在通过门禁前将其移除：步骤 5 写入验证记录后，将采用顺序复制到该记录中。
3. 第一齿：安装 .guardrails/（配置、脚本和模板，或来自步骤 1b 的清单和单元级配置），将受管区块合并到 AGENTS.md，添加缺失的文档骨架，并按步骤 2.4 所列扩展 .gitignore。本次变更中不要迁移现有文档。 对于多单元仓库，请先阅读 references/multi-unit.md。
   • 如果 `` 存在，只替换标记之间的区块。否则，将 templates/AGENTS-block.md 全文追加。向用户说明冲突规则；不要删除这些规则。
   • 将 strict_paths 设为较小的路径列表，其中仅包含已符合要求或新建的路径。现有未追踪的代码视为既有内容，不受此要求约束。
4. 后续齿（单独的变更，列入改造的验证记录）：通过 grill-requirements / analyze-risks 迁移旧版需求和风险文档；为每个指南文件运行 tailor-guidelines；逐个区域扩展 strict_paths。 每个 doc_* 键都接受文件或目录，因此 srs.md 仍可继续使用；对于多开发者仓库，建议先将每个整体式 doc_* 文件移入目录，作为该目录中带日期的首个文件，并附上 README，以避免变更相互冲突。
5. 通过 merge-change 集成。

步骤 4：安全等级访谈（IEC 62304 4.3）

每次只问一个问题，并建议一个答案：

1. 此软件发生故障是否可能导致危险情况？ 如果否 → A 类。
2. 如果是：考虑软件之外的外部风险控制后，可能造成的伤害是否会是严重伤害或死亡？如果是 → C 类；如果是非严重伤害 → B 类。
3. 将理由记录为 ADR（grill-requirements，“ADRs”）。

如果用户不确定，请先梳理预期用途、可预见的误用和硬件防护措施。若介于两个类别之间，在有充分理由支持其他结论前，按较高类别处理。

对于多单元仓库，请为每个单元重复此访谈，并在该单元的配置中记录其类别。

步骤 5：人工设置检查清单

现在编写本次变更的验证记录：将 .guardrails/templates/verification.md 复制到 docs/verification/<date>-<branch>.md；将填写并打印好的 references/setup-checklist.md 放在 ## Tool qualification 下。

签名事项是逐步收紧的门槛。 只有 .guardrails/scripts/check-signing.sh --setup 以状态码 0 退出，才算完成： 请在步骤 2.7 / 步骤 3.5 前满足这些要求。对于改造， 请尽早说明：现有项目必须先配置提交签名， 才能完成采用 guardrails 的过程。如果缺少某位提交者的公钥， 请停止并指出缺少的公钥。

工具资格认定。 在配置和该记录中记录 guardrails_version 和 guardrails_commit（git -C <guardrails> rev-parse HEAD）， 并记录测试套件结果。切勿 修改目标项目中的脚本。

测试套件在克隆目录中运行，绝不在目标项目中运行，且绝不安装 bats。 切勿将 bats 添加到目标项目。每次更新记录一次符合要求的运行，或记录 suite not run at install time: <reason>。

直接从运行命令本身获取退出状态，绝不要通过管道获取，否则 记录的通过/失败状态对应的命令就会出错：运行 <guardrails>/tests/run-tests.sh > <tmp>/ratchet.log 2>&1; rc=$?，并先读取 $rc。将日志保存在克隆目录之外；日志必须包含 run-tests: testing commit <guardrails_commit>；任何其他以 run-tests: 开头的行都表示日志描述的不是某个提交：请重新运行 （references/rationale.md）。

危险信号

想法	实际情况
“我直接覆盖他们的 AGENTS.md 就行了”	改造绝不覆盖。只使用托管区块。
“现在就在所有地方启用严格检查”	这会阻止所有针对旧代码的工作。一次只收紧一个齿位。
“签名可以以后再加”	第一次合并就会强制执行：没有经过验证的签名，就不能清理。
“脚手架不用 worktree”	与任何变更一样，使用 worktree 和签名 squash 合并。
“safety_class 可以先留空”	在设置它之前，其他事项都无法正确扩展。
“脚本都复制好了，所以升级完成了”	README、模板和托管区块也必须刷新。

完成条件

• 已设置 safety_class（如果有多个单元，则逐单元设置），并附有其 ADR。
• 改造的验证记录包含差距分析中的采用顺序。
• 升级时，从同一个 guardrails 版本复制了脚本和语法文件，修复了每一项失败，并在验证记录中列出了每一条新警告。
• 已保存设置检查清单及资格认定依据。
• check-signing.sh --setup 以状态码 0 退出。
• 变更已通过 merge-change 合并，且检查脚本通过。

参考资料

• references/upgrade-notes.md — 更新已有 .guardrails/scripts/ 的项目时，在复制新脚本前阅读。
• references/multi-unit.md — 如果步骤 1b 发现多个单元，在步骤 2.3 或步骤 3.3 安装任何文件前阅读。
• references/setup-checklist.md — 到达步骤 5 时阅读。
• references/rationale.md — 认为此处某条规则有误时，或准备提议修改某条规则前阅读。