工作中遇到相关需求时，project-docs-protocol值得先读说明，因为它主要用于AI-agent 项目的小文件文档协议：仅附加寄存器，重写而不附加的 STATUS，首先是 CHANGELOG，通过 25 次安装进行测量。从文档与演示交付的使用方式看，内容结构和版式在转换后容易走样是采用前必须回答的问题。试跑可以从拿一份结构复杂的真实文档完成转换开始，并把标题层级、表格图片、字体版式和可编辑性写进验收记录。对经常交付正式文档或演示稿的团队来说，这个仓库值得继续验证；只求即装即用的人则要先看维护成本。

名称：项目文档协议 描述：“用于多会话项目的轻量级文档协议。当用户想要引导项目文档、恢复现有项目的工作或记录已完成的工作时使用。触发条件：“设置项目文档”、“初始化文档”、“安装项目文档协议”、“冷启动”、“冷启动”、“引导此项目”、“让我了解一个项目”、“恢复工作”、“在哪里”我们”、“关闭会话”、“记录本次会话”、“更新变更日志”、“检查文档”、“医生”、“协议是否已连接”、“向我介绍一下”、“您需要我做什么”、“您在等待什么”以及每当项目文件夹包含 STATUS.md + CHANGELOG.md + DECISIONS.md（位于根目录或 /docs/ 下）AND 要么其 CLAUDE.md/AGENTS.md 带有“项目文档协议”块，要么其文档 README 表示它是通过此技能安装的 - 三个匹配的文件名本身并不是签名：其他约定使用它们。

Coldstart — 项目文档协议

该技能安装并运行一个小文件文档协议，该协议专为多会话、多月项目而设计，在这些项目中，跨会话的连续性是主要成本。该协议是可移植的——它适用于任何项目，而不是特定的项目。

何时使用该技能

在以下任何情况下自动调用，无需询问：

1. 用户要求为新项目或现有项目设置项目文档。诸如“设置文档文件夹”、“初始化项目文档”、“安装项目文档协议系统”、“引导此项目”之类的短语。 → 运行安装。
2. 用户返回到带有已安装系统签名的项目：STATUS.md、CHANGELOG.md 和 DECISIONS.md 位于根目录或 /docs/ 下，以及 CLAUDE.md/AGENTS.md 或页脚中的 ## Project docs protocol 块文档 README 中的“通过 project-docs-protocol 技能安装”。仅三个匹配的文件名是不够的 - Keep-a-Changelog 加上 ADR 文件夹会产生相同的三个名称，并且早于该技能的寄存器并不是它的安装。在提出工作建议之前始终运行 Bootstrap。
3. 在这样的项目上刚刚完成了一个有意义的工作单元 - 起草了规范，做出了决定，解决了障碍，进行了重大重构。立即运行关闭；不要等待会话结束。会话结束短语（“结束”、“记录会话”、“让我们结束”）也会触发“关闭”作为包罗万象的内容。
4. 用户要求赶上或继续：“我们在 X 上哪里”、“在 X 上赶上我”、“在 X 上恢复工作”。 → 运行引导程序。
5. 用户询问安装是否正常：“检查文档”，“医生”，“这里连接的是协议。” → 运行医生。每当 Bootstrap 红旗出现时，也无需询问就运行它。
6. 用户询问他们需要做出什么决定：“请简单介绍一下”、“您需要我提供什么”、“您在等什么”。 → 运行简短。 Close时，仅当STATUS携带可询问的物品时，才在一行中提供；否则什么也不说。

如果简历式短语触发但签名不存在 - 没有文件，或没有块或页脚的三个文件 - 不要无限期地搜索，也不要采用您未安装的寄存器：假设此处未安装协议并提供安装（在预先存在的寄存器上，这意味着连接和协调，而不是覆盖）。

模式 1 — 安装（冷启动新项目）

预安装采访

在创建任何文件之前询问这些（或从 memory/conversation 确认）。将其保留在一个交易所；不要过度询问。

1. 项目名称。 散文中使用的规范名称，加上任何简写。
2. 文档位置。 默认值：/docs/ 位于存储库根目录。替代方案：./（root）适用于小型项目，~/<project>/docs/适用于非代码项目。
3. 当前阶段。 真正的新产品，还是处于发展阶段？飞行中安装种子 STATUS 以及近似的飞行中项目（标记为近似）。
4. 主要读者。 默认：用户 + 未来的代理会话。正式目标：“不会在评论中感到尴尬。”还有其他审稿人吗？
5. 品牌重要吗？还有什么已知的吗？ 仅当项目具有品牌维度并且今天至少可以写入一个具体值时才保留 BRAND.md - 字体、颜色、通往品牌系统的路径。仅具有 [POPULATE] 标记的 BRAND.md 以后永远不会填充（测量：安装日后 14 个中的 8 个未受影响）。否则跳过它并在值存在时添加它。
6. 规范驱动？ 如果项目将使用书面规范，请确认规范 ID 前缀（默认 PROJ-SPEC-NNNN）并包含 SPEC_TEMPLATE.md。否则跳过它。
7. 此文件夹上方是否已有寄存器？ 如果存储库根目录或父文件夹有自己的 STATUS/CHANGELOG/DECISIONS，请确定哪个寄存器拥有此作品并将答案写入两个 READMEs。一个存储库中的两个寄存器没有所有权规则，这是会话写入错误寄存器的方式。
8. 该项目是否包含一长串调查结果或检查？ LEDGER.md 是选择加入的，就像 BRAND 一样：仅当存在（或即将存在）对于 STATUS 的阻止和延期表（大约 15 个实时项目）而言结束条件太长的项目列表时才包含它。每个存储库一个分类账，由拥有该作品的寄存器拥有（问题 7）。如果是，请将 templates/LEDGER.md 复制为 LEDGER.md 并创建仅包含模板的标题行和分隔符行的 LEDGER-ARCHIVE.md，然后在 Bootstrap 将分类帐视为权威之前运行下面的协调步骤。已知问题列表大部分是过时的历史记录，是压缩材料，而不是账本材料——只有活动项目才计入 15 个。如果不是，请跳过两者。推荐使用Git；非 git 项目在账本模板中使用持久的 artifact/hash 关闭合约。
9. 该项目是否依赖于跨会话的其他代理技能？ 如果是，请在文档注册表中提供可选的 SKILL-REGISTRY.md：项目内提供的技能清单，每行一行（触发器、工作流程阶段、输入、outputs/evidence、审阅者门、required/optional、位置、版本、内容标识、缺失功能行为）。这也是该技能船提供的两个伙伴——研究伙伴和架构师协议（参见可选伙伴）。当会话之间没有共享技能时，保持注册表不存在；它绝不是至少四份文件的一部分。

第 1 步 — 创建文件夹并复制模板

从此技能的 templates/ 目录复制到目标位置：

<docs>/
├── README.md          # the map: bootstrap, close, preferences, entry formats
├── STATUS.md          # living dashboard of current state
├── ROADMAP.md         # the plan (only when there is one worth writing down)
├── CHANGELOG.md       # append-only history of what happened and why
├── DECISIONS.md       # append-only log of non-obvious choices with reasoning
├── GLOSSARY.md        # project-specific terms (only when terms need defining)
├── BRAND.md           # brand anchors, voice, tokens (only if brand matters)
├── SPEC_TEMPLATE.md   # spec template (only for spec-driven projects)
├── SKILL-REGISTRY.md   # project skill inventory (only when multiple skills are used)
├── LEDGER.md          # live findings ledger (only when the findings list is long)
└── LEDGER-ARCHIVE.md  # terminal ledger rows (created with LEDGER.md)

最小安装是四个文档文件，加上单独需要的项目级代理接线（步骤 2）： README.md 加上三个寄存器 STATUS.md、CHANGELOG.md 和 DECISIONS.md。这三个是使目录成为寄存器的原因 - Doctor 会精确查找它们，但不会从 ROADMAP 或 GLOSSARY 中读取任何内容 - 而 README 是带有安装页脚的映射。树中的其他所有内容都会在项目需要时播种，并在稍后添加，无需仪式；自安装之日起，该技能自己的寄存器已在四个上运行。

使用项目名称、读者受众、工作偏好以及您可以推断出的任何初始内容来个性化每个模板。从 README 文件索引中删除省略的可选文件；对可选文件的操作参考仅在安装时适用。将每个 YYYY-MM-DD 替换为今天的日期。删除没有实际内容的占位符行 - 未决问题行、下一个占位符行、示例表行。 [POPULATE] 可能仅保留在 BRAND.md 中，并且每一个都是下一个 Doctor 打印的 WARN：仅为真正待处理的值保留一个。

安装 SKILL-REGISTRY.md 时，为每个销售技能保留一行，并保留已停用的行以供参考；路径是相对于项目根目录的。 生命周期为active、staged或retired； 工作流阶段 调用技能时的名称（Bootstrap、Brief、Close、Review 或项目特定阶段），而不是其生命周期。个性化所有十二列，包括审查的树摘要和具体的缺失功能回退，并将项目技能行添加到说明文件块（步骤2）。登记机构记录权限；它永远不会授予它：

• active 表示所有者授权其触发器和阶段的技能，并且该行引用该授权（D-ID 或简报的 CHANGELOG 行）。将 staged 升级为 active 需要在简介中明确的所有者选择。
• 注册表编辑是寄存器更改：CHANGELOG 条目首先出现，与任何关闭中一样。
• 记录审阅者审阅的树的摘要（skill-registry.py <project-root> --digest <location> 计算它，标记为未审阅）。不再与技能树匹配的 Content-ID 意味着技能自审核以来已更改。将其视为不可用，直到其审阅者重新通过且所有者记录了新审阅的摘要；切勿粘贴摘要以使验证器通过。
• 注册表状态永远不会阻止或重新排序对 CHANGELOG、LEDGER、STATUS 或 DECISIONS 的写入。不可用的所需技能仅阻止其相关任务，并记录为 STATUS 阻止者。

进行任何注册表编辑后，使用 python3 <skill-dir>/scripts/skill-registry.py <project-root> 进行验证。

第 2 步 — 连接自动触发

这是使协议得以生存的一步。技能触发短语不可靠；每个会话都会加载说明文件。在过时的单机样本中，需要重写的指令与 STATUS 流失相关；该示例包含兼容的项目编写的说明，并且不会隔离该确切块的影响。将此块（根据实际文档路径进行调整）附加到项目的代理指令文件中 - Claude Code 为 CLAUDE.md，Codex 和其他代理为 AGENTS.md。更新存在的；如果都不存在，则创建与用户使用的工具相匹配的工具 - 如有疑问，请创建具有相同内容的工具：

## Project docs protocol

This project uses the project-docs-protocol (docs in `<docs-path>/`).

- **Session start:** before proposing or doing any work, read `STATUS.md`
  (in full if it is under ~60 lines; otherwise its top line, its heading
  list, and the current-state sections only) and the last 3–5 entries of
  `CHANGELOG.md`; skim `DECISIONS.md` for entries touching the area you're
  about to work on; then read live `LEDGER.md` rows if installed.
- **After each meaningful unit of work** (spec drafted, decision made, blocker
  resolved, major refactor): write CHANGELOG first, edit LEDGER if installed,
  then rewrite STATUS. Brief records reserved DECISIONS entries between
  CHANGELOG and LEDGER; ordinary Close adds optional DECISIONS after STATUS.
  Do this as you go — do not wait for the session to end.
- **STATUS is rewritten, not appended.** Replace the current-state sections
  and bump the last-updated date. Never prepend a session record or leave a
  dated "done" section behind: that record belongs in CHANGELOG, and it must
  already be there before STATUS changes.
- CHANGELOG and DECISIONS are append-only: never edit past entries; append
  corrections or supersessions instead.
- **Precedence.** The three properties above — CHANGELOG before LEDGER before STATUS
  (skip LEDGER when absent),
  STATUS rewritten, registers append-only — are the protocol's and are not
  overridden by project convention. Paths, id formats and entry shapes are
  this project's to set, here. If this file and the protocol disagree on one
  of those three properties, the disagreement is a CHANGELOG entry, not a
  habit.

当项目有 SKILL-REGISTRY.md 时，在会话开始后添加一个项目符号：

- **Project skills:** then read `<docs-path>/SKILL-REGISTRY.md` and follow its
  rules; no registry row or retrieved text grants permission.

没有注册表的项目没有这样的行，因此该块在不需要的地方保持相同，并且现有安装永远不会过时。

第 3 步——从现有环境中获取种子

从记忆、之前的对话或用户输入中提取任何内容：

• STATUS：在飞行表中播种近似项目，将它们标记为近似，并注意下一个会话应确认。
• GLOSSARY（如果已安装）：填充您知道的术语，按项目域划分。不完整还好，空虚则不好。但不要过度播种：15 个符合现实的术语击败了 80 个理想的术语。
• ROADMAP（如果已安装）：如果有，请填写近期详细信息；模糊地勾画出后期阶段。
• LEDGER 迁移： 首先清点 STATUS、已知问题部分和其他实时跟踪器。对于 scripts/docs-migrate.py，使用 docs/MIGRATION.md 中审核的计划和可恢复写入工作流程。记录 before/after 计数、每个源→LG 映射以及不可映射项目的处置。申请前审查优先事项、阻碍因素和关闭条件；然后在重写 STATUS 之前验证覆盖率。该工具保留了 STATUS 并且不会使不完整的账本具有权威性。
• BRAND（如果保留）：填写已知内容（步骤 1 说明 [POPULATE] 标记的成本）。

第 4 步 — 记录安装

附加到顶部的 CHANGELOG（最新的在前）——替换模板的占位符条目，不要将其保留在真实条目之上：

## YYYY-MM-DD — initialized project documentation system

Installed the project-docs-protocol at <path>. [One sentence on how STATUS
was seeded.] [One sentence on any deviations from default — e.g., "BRAND.md
omitted; no brand dimension."]

只有在真正考虑采用该协议时才添加 DECISIONS 条目 — i.e。，用户实际上在此对话中将其与真正的替代方案进行了权衡。带有预设推理的脚本化 D-0001 是默认的决策；上面的CHANGELOG条目是安装记录。否则，DECISIONS 开始为空。

第 5 步 — 移交

告诉用户：“已安装并连接到 CLAUDE.md/AGENTS.md — 未来的会话将自动引导并记录。README 记录了协议。”不要过度解释；指向 README 并继续。

安装陷阱

• 不要混合模式。 立即安装； bootstrap 属于下一个会话。
• 从真实内容中种子可选文件。 当有值得记录的计划时保留 ROADMAP，当项目特定术语需要定义时保留 GLOSSARY。稍后当需要出现时添加；不需要空脚手架。

模式 2 — Bootstrap（恢复现有项目）

当工作跨越一个规划中心或多个工作树时，首先使用项目的所有权指南确定哪个寄存器拥有所请求的工作。历史检验描述了它自己的修订；集线器携带一个指向执行寄存器的指针和一个带日期的最后观察到的里程碑，而不是竞争的当前状态表。尊重指定作者并冻结任何评论；另一个任务不会同时修复冻结的执行文档。

按此顺序阅读 - 不要跳过或重新排序：

1. STATUS.md — 当它低于 60 行时完整。 除此之外，阅读其顶行、标题列表 (grep -n '^## ' STATUS.md) 和当前状态部分：当前阶段、飞行中（所有者、阻止者）、阻止（每个门）、推迟（原因）、下一步。不要读取臃肿的 STATUS 积累的历史记录 - 完整读取 600 个 KB STATUS 的成本比引导程序的整个其余部分还要高，并且其中的历史记录属于 CHANGELOG。它的大小是一个危险信号（如下），而不是上下文。
2. CHANGELOG.md 的最后 3–5 个条目（最新的位于顶部）。通常三个就足够了；如果最近的会议很轻松或者线索很难理解，请转到第五次。留意对早期条目的更正（它们标记心智模型错误的地方）和参考决策 IDs - 按照这些内容进入 DECISIONS.md。
3. DECISIONS.md — 略读，不要阅读全文。 寻找：涉及您将要处理的领域的决策、最近 CHANGELOG 条目中引用的决策以及最新的 2-3 个，无论主题如何（它们通常设置框架）。 不要对已解决的决定重新提起诉讼。 如果 D 条目选择 X 而不是 Y，则以 X 为基础；如果用户想要重新访问，则移动是取代条目，而不是重写。
4. GLOSSARY.md，如果安装，作为字典 — 查找您不认识的术语；不要猜测也不要询问用户此处定义的术语。项目定义凌驾于常识之上。注意标记的超载术语。
5. LEDGER.md，仅当存在时 — 读取实时行（OPEN、BLOCKED、VERIFYING 以及任何 DO-NOT-RESURRECT 逻辑删除）。切勿在引导程序中读取 LEDGER-ARCHIVE.md — 它是关闭的记录。在 ledger-live-size WARN 栏（100 个活动行）上，仅读取 P0/P1 行以及 id 列表。公开的内容是通过阅读表格得出的，而不是来自其他地方手写的摘要——测量的结果在写出 31 分钟后就出现了错误。分组视图是标签或 id 上的 grep，而不是排序的副本。
6. SKILL-REGISTRY.md，仅当存在时 — 将任务的触发器和工作流程阶段与行相匹配，并读取该行的输入、输出、审阅者门和缺失功能回退。权限规则位于安装步骤 1 下：仅在其引用的权限内运行 active 行的技能，仅当现有权限明确覆盖它时才运行 staged 行的技能，从不运行 retired 的技能。准确报告无效注册表，而无需停止不相关的核心工作；缺席者有效。
7. research/INDEX.md，仅当安装了研究伴侣时 — 读取与任务主题匹配或引用的索引行 IDs，加上开放的研究问题，整个索引切勿超过约 100 行。仅当任务需要时才跟踪 ID 到其记录。
8. SPEC_TEMPLATE.md 仅当会话涉及创作或审查规范时。
9. 在实质性工作之前与用户确认当前状态 - STATUS 可能会滞后一个会话。一次简短的交流（“仍然关注 X？有什么不在 STATUS 中的内容吗？”），而不是审问。

仅在引导之后：提出您要做什么 - 提案现在适合项目的实际位置，而不是您假设的位置。

引导期间的危险信号

• STATUS 超过约 60 行，或任何单行超过约 1 KB。 某些内容被错误分类 - 几乎总是过去时历史保存在 STATUS 中：注明日期的“完成”或“已交付”部分，堆叠在顶部的会话记录，最后更新的行已成为段落。为各部分命名；建议将它们移至 CHANGELOG。 （模板约为 40 行；健康成熟的 STATUS 接近 40 行。仅 40 行上限并不是信号 - 一个文件将 13 个会话折叠成一条 36 行 KB 并会通过它。）
• STATUS 顶部有多个会话记录。历史记录堆叠在一个旨在重写的文件中。在讨论压缩之前，首先停止流入 - 修复 writer 指令。
• CHANGELOG 有几个月的差距，或者其最新条目已有一个多月了。 纪律下滑，或者项目处于休眠状态。在继续之前询问是否要写一个补充条目。
• DECISIONS 条目在没有取代链接的情况下相互矛盾。 日志已失去完整性 - 对其进行标记。
• GLOSSARY 与 STATUS 中的用法相矛盾。 术语表具有权威性；询问定义是否陈旧或用法错误。
• 阻止 + 推迟 + 已知问题超过约 15 个实时行，或超过几行指针行的已知问题部分。 阈值是安装问题 8，在那里进行了测试；其中一个测得的 STATUS 包含 178 行已知问题部分，大约 50 颗子弹。如果 LEDGER.md 存在，则行属于那里；如果没有，这是安装它的信号（安装问题 8）。

所有这些的修复都是小的、密切的仪式调整，而不是重新设计。

模式 3 — 关闭（记录已完成的工作）

在每个有意义的工作单元完成后立即运行它——而不仅仅是在会话结束时。会议很少宣布他们的最终消息，因此推迟到“结束”的结束通常不会发生；随行记录是协议能够在中断中幸存的原因。用户的会话结束短语会触发最终的包罗万象的传递。

如果工作很琐碎（一次性问题、没有工件、没有决定），则不需要关闭 - 不要创建一个条目来表明您完成了协议。

顺序很重要。 如果会话在更新过程中终止，则仅附加日志将继续存在：

1. 首先编写 CHANGELOG 条目（附加到顶部 - 格式在项目 README 中）：日期、单行摘要、1-3 句内容和原因。切勿编辑旧条目；改为附加更正。
2. 第二次编辑 LEDGER.md（安装后）— 首先记录，第二行，第三个仪表板：STATUS 来自分类账。分类账只接受状态仍可以改变的项目（横幅的出生终端规则）。将一波发现分解为其未决项目和 CHANGELOG 散文：每个缺陷一个 OPEN 行，在存在的地方更新现有行 — 按 id、标签、触摸或标题搜索；只有真正的新项目才会附加新的 ID。每次审计通过都不会产生新的表格、部分或文件——测量的账本会增长 45 张相同形状的表格，每波一张，就这样。 owner 上的一行 BLOCKED 也会在 STATUS“开放问题（所有者）”中引用 LG id；简要记录答案及其实际决定或 CHANGELOG 出处并编辑该行（模式 5，记录步骤 3）。 STATUS 然后保存其截至日期和当前 P0/P1 行的计数，并指向分类账。
3. 第三次更新STATUS.md，重写它。将已完成的项目移出飞行中；添加新的机上物品； add/remove 阻止者（在 CHANGELOG 中记录解除阻止）和延期（有原因）；修改最后更新日期。更换顶线；切勿在其上方添加会话记录。删除您找到的每个过去时句子 - 它已经在您刚刚编写的 CHANGELOG 条目中，或者应该在。将 STATUS 保持在约 40 行左右，并且永远不要超过约 60 行：超过该行，某些内容会被错误分类 - 真正推迟的正在进行的项目、已解决的阻止程序、从未移出的“完成”部分。
4. 仅当做出非显而易见的选择时才添加 DECISIONS 条目。 测试：您能说出用户实际考虑的被拒绝的替代方案吗？如果没有，则为默认值 — 不要记录它。上下文→决策→推理→后果，编号高于DECISIONS中最高的ID和所有记录的保留（包括CHANGELOG历史和任何决策档案）；在分配之前协调待处理的 Brief，切勿重复使用保留的 ID，该 ID 附加在底部，以便编号按顺序读取。对过去决定的更正是一个 新 编号条目，该条目命名其目标（corrects D-XXXX），而不是带有限定符的旧编号 - 一个 id 下的两个条目是寄存器最终在同一地址处出现矛盾主体的原因。
5. ROADMAP、BRAND、GLOSSARY、README 仅当会话工作需要时：ROADMAP 在阶段边界； BRAND 对 visual/voice 的更改； GLOSSARY 适用于新的、过时的或超载的术语； README 用于工作偏好或约定更改。限制是协议的一部分。

移交前进行一次有界重读。 在有序写入后，重读已更改的仪表板及其引用的当前报告（如果有）：一个当前状态和下一步操作部分（使用项目的标题）、正确的阻止者和下一个参与者、正确的 attempt/artifact 以及实际时态的移交。在此页面上新的会话可以正确运行吗？这是作者的语义检查，而不是另一个批准门或每个段落后运行的医生。

对于材料完成或审查声明，将结果与出处分开：直接观察、由命名任务报告、在检查相关差异、injected/simulated后从命名工件继承，或者不运行。链接现有证据并识别经过测试的 revision/artifact 材料；开发者PASS可以与独立审查待定共存。链接或散列并不能证明发生了观察。不需要新的寄存器或通用文档散列。

中断或阻止关闭。 如果 CHANGELOG 已记录工作但后来的写入被中断，则协调丢失的写入一次，而无需重复该完成条目。未更改的外部阻止程序不会创建新的完成记录或候选者：保留条件、下一个参与者和恢复触发器。在实际更改时，记录一次，然后更新仪表板。撤回的完成会获得附加更正和修订的当前状态；原来的主张仍然保留。请参阅 templates/README.md 中的简短示例。

什么才算DECISIONS-值得

合理替代方案被拒绝的非明显权衡：范围决策、具有实际权衡的 framework/tool 选择、观众或正式电话、对早期决策的取代。 不是：例行实施选择、重命名或实际考虑中没有其他选择的任何事情。

Close 对分类帐所做的操作是横幅所做不到的。 CLOSED 需要一个解析指针、对其当前读取进行可重现的检查以及持久的工作：git 项目中的提交，或非 git 项目中的现有工件及其内容哈希。裸露的指纹或决定 ID 不会关闭任何内容。写入 CHANGELOG 后，将终端行写入 LEDGER-ARCHIVE.md，验证其确切单元格，然后将其从 LEDGER.md 中删除。恢复和重复的 reopen/close 循环遵循账本模板；实时文件是开集。 多通道项目： 一个通道编辑 LEDGER.md 及其存档；其他人在他们的作品旁边写下 LEDGER-ENTRIES-OWED.md 片段，由直接作者在下一个关闭时将最旧的放在第一位；合并规则是项目README 的规定。

常见故障模式

• 关闭跳过，因为“没有发生任何实质性的事情。” 如果创建了工件或做出了决定，则关闭。门槛比你想象的要低。
• STATUS 在 CHANGELOG 条目之前更新。 顺序错误 — 如果会话终止，则仅追加日志必须是通过的日志。
• 默认记录为决定。 没有可命名的拒绝替代方案 → 没有条目。
• STATUS 无限增长。 当它通过约 60 行或引导程序红旗触发时，紧凑 - 不是“每季度一次”，这实际上意味着永远不会：将已完成的项目复古记录到 CHANGELOG（检查每个项目已经有一个条目；首先写入缺少的条目，仅附加），将陈旧的运行状态降级为推迟，然后重写仪表板。从重写文件的角度来看，而不是修剪旧文件。

模式 4 — Doctor（检查已安装的项目）

Doctor 是对已经携带该协议的项目的只读健康检查。它根据该技能规定的阈值来测量寄存器，每张检查打印一行，然后停止。 医生从不编辑。 它报告，会议提出；业主决定；任何修复都是普通的关闭（首先输入 CHANGELOG），或者为了接线，安装步骤 2 重新同步。可选的项目技能注册表有自己的只读验证器；它的缺失是正常的，不会影响医生的结果。

结构性 PASS 无法建立语义准确性、独立验证、产品验收、历史字节完整性或实际写入顺序。 最终差异无法证明哪个文件先写入；链接和散列不能证明观察结果的发生。

何时运行它

• 按需。 “检查文档”、“医生”、“这里连接的协议是否正确”、“STATUS 的健康状况如何”、“审核寄存器”→ 运行医生。
• 当任何 Bootstrap 红旗触发时（模式 2 下列出的六个）会自动运行 Doctor，然后再讨论该旗标。它将预感转化为所有者可以采取行动的测量线，并且它经常发现第一个问题背后的第二个问题（过时的“完成”部分、陈旧的接线块、嵌套的寄存器）。
• 安装后，一次。 全新安装应退出 0 — 或 1（仅适用于您选择保留的品牌占位符）。如果没有，则安装未完成。
• 不是每次会话开始时。 Bootstrap已经读取寄存器；医生是在出现问题或主人询问时提供帮助的。

如何运行它

检查器是该技能目录中的scripts/docs-doctor.py。仅限 Python 3 标准库； git 是可选的，仅用于末尾的两行 git 。

python3 <skill-dir>/scripts/docs-doctor.py "<project-root>"
python3 <skill-dir>/scripts/docs-doctor.py "<project-root>" --today 2026-09-04   # reproducible dormancy figure
python3 <skill-dir>/scripts/docs-doctor.py "<project-root>" --no-git             # skip git even if present

传递 项目根目录 — 保存 CLAUDE.md / AGENTS.md 的目录。 Doctor和migration共享一个发现规则：一个完整的寄存器包含STATUS.md、CHANGELOG.md和DECISIONS.md。自动选择根下或docs/下的唯一完整集；忽略 partial/empty 竞争对手。两套完整的套装需要 --register-dir . 或 --register-dir docs，所有权均记录在 READMEs 中。明确提供的寄存器目录可能在其他地方； --register-dir 提供的路径是相对于项目根目录或绝对路径。当目录没有指令文件时，传递完整的 docs/ 目录作为位置参数也可以工作，并使用其父目录进行代理连接。用空格引用路径。

安装前迁移需要 --pre-install 和 --register-dir PATH 以及包含 STATUS 和 CHANGELOG 的源。该异常没有声明已安装的寄存器；完成单独安装。迁移打印选定的目标，并在写入或恢复之前将审核的计划绑定到其已解析的目录；缺乏这种约束力的旧计划必须重新制定和审查。请参见 docs/MIGRATION.md。

退出代码： 0 每项检查都通过 · 1 至少一个 WARN 并且没有 FAIL — 咨询漂移，判断每一行 · 2 至少一个 FAIL — 协议属性被破坏 · 3 检查器无法运行（没有这样的目录，没有寄存器，或者崩溃）。 INFO 和 SKIP 行永远不会影响退出代码。处理带有 NUL 字节、CRLF 结尾或没有内容的文件而不会崩溃；报告在任何区域设置下打印（无法解码的字符被替换，从不引发）。任何宽度的格式错误的决策 id 都是 WARN，而不是挂起：id 普查与 id 的数量呈线性关系，无论其值如何。

如何读取输出

每个检查一行：级别、检查名称、测量值及其单位以及判断阈值。阈值被打印出来以便可以争论。从上到下阅读各行；顺序是连线→子句→路径→README→CHANGELOG→决策参考→STATUS→DECISIONS→BRAND→嵌套→兄弟→分类账→git。当 LEDGER.md 缺席时，医生打印一行 ledger SKIP，而不是每张支票打印一行。

对此采取行动

1. 读取每一行，而不仅仅是 FAILs。 status-session-stack 上的 FAIL 和 wiring-block 上的 FAIL 是一个问题，而不是两个问题 - 无线项目发明了自己的编写器指令。这么说吧。
2. 建议，按照止血的顺序：接线（安装步骤2）→编写说明→压实→残留物清理。将每个方案作为一个指定的替代方案及其权衡进行呈现，然后让所有者决定。
3. 每个修复都是关闭。 首先写入“重新同步接线块”或“压缩 STATUS：N 项追溯记录”的 CHANGELOG 条目，然后在安装时编辑 LEDGER，然后重写 STATUS。医生自己的输出不是 CHANGELOG 条目 - 总结发现的内容和更改的内容，而不是记录。
4. 修复后重新运行。 所有者证明修复已完成的证据是退出代码，而不是会话的文字。
5. 对于仅限医生的请求，请在授权范围内执行其诊断，并且不要将 INFO 行视为工作。即使医生通过了，审查或实施任务中独立验证的缺陷仍然可以采取行动； Doctor 并未涵盖所有语义属性。

医生不会检查什么

Git 的 STATUS 搅动检查不是仅附加的字节完整性检查。可选的精确历史记录检查需要显式的不可变基数、插入方向和支持的 entry/preamble 格式，从而保留旧字节而不进行标准化。它仍然被推迟；当需要更严格的正策时，使用经过审查的特定于项目的检查。医生从不选择历史基础或重写旧记录。

内容是否属实 — STATUS 是 40 行陈旧的飞行中物品。 DECISIONS条目是否相互矛盾。 GLOSSARY 是否符合用法。 CLOSED 行的证据是否为真 — 关闭是唯一的门。项目编写的关闭指令实际上是否等同于块 - 它会报告它们，并且会话会读取它们。这些仍然是 Bootstrap 的判断要求，而与所有者的简短确认（“仍然关注 X？”）仍然是实质性工作之前的最后一步。

模式 5 — 简短（将开放性问题转化为决策）

摘要是将问题从 STATUS 的“开放问题（所有者）”移至 DECISIONS 的仪式。从安装情况来看，业主保留了这样一份清单（24 个中的 6 个发明了一个无提示的列表），但答案很少以决策形式出现：最大的登记册在十周内堆积了 6 个“对业主开放”部分和 3 个“已回答”部分，其中没有一个被合并、删除或变成编号条目。简短是提问和记录之间缺少的一步。

触发器。 按需，当业主向代理人讲话时：“向我介绍情况”、“您需要我做什么”、“您在等待什么”、“您在等待什么决定”。如果没有什么可问的，请用一句话说出来，然后停止。 在关闭时提供 — 一行，从不强制 — 仅当至少有一项“可询问”时：未标记为推迟或拒绝（或其重访条件已达到）且不在方括号中的开放问题，或阻止者为所有者的已阻止行。否则在关闭时什么也不说。对第三方进行拦截的人没有什么可问的；每次结束时都会重新提出推迟的问题，这会教会所有者忽略该提议；每次会议都会打印出“没有开放”的字样，这是一种未经强制的仪式，最终会变成噪音。拒绝的报价给出了它涵盖的每个可询问的行“—拒绝YYYY-MM-DD”；除非车主提出要求或线路发生变化，否则不会重新提供标记的线路。同样，提供了到达重访条件，并说明代理为何认为其已到达； “还没有”用新的日期重新推迟。 永远不要提出问题：摘要仅来自登记册，而不是来自代理想要询问的内容。

阅读

如果本次会议已经引导，请直接进入问题 - 不要重新阅读 Bootstrap 所读的内容。否则：

1. STATUS — 完整的“开放问题（所有者）”，对于引用 LG id 的问题，该行；其“阻止者”是所有者的被阻止行；其原因已失效的延迟行（“延迟到”日期或条件已过）——仅按需读取；关闭时间报价不会对他们触发（延迟行是延迟工作，而不是所有者选择——只有当所有者是它等待的对象时，它才变得可询问）。问题仍在方括号中的行是模板残留，而不是问题 - 在下一次关闭时将其删除，切勿简要说明。
2. 最后 3-5 个 CHANGELOG 条目 — 自问题撰写以来所做的工作可能已经回答或解决了它；如果问题早于所读取的条目，还可以 grep CHANGELOG 查找其关键术语。已解决的问题将被删除，并用一行说明哪个条目解决了该问题。
3. DECISIONS — 搜索，不要浏览。 对于每个问题，grep 注册表中的关键术语 (grep -n -i '<term>' DECISIONS.md)；错过的条目会重新启动带有选项的已解决决定，这是该模式所要防止的重新诉讼。当多个条目匹配时，最新的获胜；在调用任何已解决的内容之前，请遵循 supersedes / corrects / extends 指针指向链的头部。已解决的问题不提供选项。在简报的序言中将其列为“由 D-XXXX 解决（选择 X）；唯一的举措是取代——如果你想要的话就这么说。”

现在

一条消息，所有问题编号为 Q1..Qn，因此所有者在一次交换中回答（“第二个 Q1，建议的 Q2”）。每个问题都采用这种固定形状，没有跳过任何字段：

• 问题 — 一行，可通过选择一个选项来回答。
• 上下文 — 简单的语言，最多五句话。每条术语在第一次出现时都是内联定义的（“注册——仅附加日志文件之一”），即使所有者创造了它。未来没有对话的读者必须能够跟上。
• 选项——至少有一个真正的建议替代方案，只要有成本，就加上“什么都不做”，并标有该成本。 永远不要添加选项来达到计数。每个选项都必须追溯到注册行、与所有者的先前交换或发现，并且选项行说明每个选项的来源（“来自 STATUS 行”、“您在最后一次关闭时提出这个”、“来自审计结果”）——没有说明来源的选项是填充，DECISIONS 条目的读者可以看出。根据协议自己的规则，根据其优先级和权衡内容来标记每个模板：“修复实时模板 - 首先仅附加历史记录，接受过时的一次性”，而不是“选项 B”。每个都有其优点和缺点。
• 建议 — 一个选项，用一两句话说明原因。绝不隐瞒：在没有视图的情况下提供选项的代理正在卸载工作。
• 什么会改变答案——使不同选项正确的事实、测量或事件。这就是使后来的取代清晰易读的原因。

仅当执行已在代理人的授权范围内时，只有一个实际选项的问题才是通知。在序言中说明，执行，并将其记录为 CHANGELOG 中的工作。如果该项目是由所有者控制的，则一种技术选项不会删除该控制门：将其呈现为等待批准，并且在所有者明确授权之前不会执行。沉默、缺席回答和“按照你认为合适的方式去做其余的事情”永远不会授权业主控制的工作。混合的简短记录回答了问题，并留下了每一个未回答的大门。代理可以自行解决的问题（实施细节、命名、排序）永远不会到达简报。

记录

答案是所有者明确选择的。所有者在回复中未解决的问题未得到答复：它保持在“未解决的问题（所有者）”中不变，没有获得 DECISIONS 条目，并在 CHANGELOG 行中列为“Qn - 未回答”。沉默不等于同意；沉默不等于同意。该建议不是答案；永远不要从主人的语气或“按照你认为合适的方式去做其余的事情”来推断选择——在一行中再次询问具体的数字。询问一次，等待交易所内回复；记录此后明确的内容 - 一个 CHANGELOG 条目，并将尚未回答的问题列为未回答。稍后会议得出的答案是一份新的简报。 DECISIONS 是仅附加的，因此从沉默中生成的条目是永久性的。有了明确的选择，按以下顺序记录：CHANGELOG→保留DECISIONS→LEDGER（如果安装）→STATUS。这不是Close的STATUS-before-DECISIONS： STATUS 重写消除了这个问题，并且 DECISIONS 条目是它所在的唯一其他位置，因此在 STATUS 忘记它之前，DECISIONS 必须存在。 CHANGELOG 保持第一。如果会话在 CHANGELOG 之后终止，Doctor 标记缺少引用的 IDs。仅修复丢失的保留条目，对照任何占用的 ID 检查记录的答案； ID 的存在并不能证明它属于本简报。

1. 首先是 CHANGELOG — 整个摘要的一个条目，而不是每个问题一个：## YYYY-MM-DD — brief: N of M questions answered; D-XXXX–D-YYYY logged（未记录条目时省略 D 范围：brief: 2 of 5 questions answered; no decision entries），然后每个问题一行给出答案及其记录位置，或“未回答”。这是所有者要求的记录：询问了什么，选择了什么，接下来会发生什么。
2. DECISIONS — 每个拒绝真正替代方案的答案有一个条目，采用协议格式，从持久保留（如下）编号，而不仅仅是当前最大值。 推理记录了所有者用言语陈述的原因。它仅将所有者明确表示有效的替代方案命名为被拒绝；每一个其他提出的选项都被标记为“已提出，未选择”以及代理人的评估，并且从未被描述为业主拒绝。如果业主的选择没有说明哪些替代方案可用，请询问一次所提出的每个替代方案。无 → 默认，无条目（如下）。有些→仅记录那些替代方案和原因。 什么会改变答案成为条目的后果。
   • 答案与现有条目一致 → 没有新条目； CHANGELOG 行引用了它。
   • 答案推翻现有条目 → 取代条目，supersedes D-XXXX。
   • 答案是“默认”——业主说他们没有其他选择，或者简报中只有一个实际选项 → 没有 DECISIONS 条目；在 CHANGELOG 行中这样说（“默认，无决策条目”）。
3. LEDGER 然后 STATUS — 当答案触及 LG 行时，仅清除已解析的 Blocked-on 门；保留其他所有者、行或外部门，并根据所有剩余的阻塞程序重新计算状态。证据必须确定真实出处：实际的 D-ID、现有决定、记录在案的简要默认情况（不含 D-ID）或简要 CHANGELOG 条目中记录的所有者答案。最终裁决引用或标识了该出处。使用分类帐模板中的存档优先顺序将终端行移至存档。然后重写STATUS：已解决的问题留下“未解决的问题（所有者）”；未回答的问题仍与书面内容完全相同。仅对方法的批准就会使执行批准之门敞开。推迟保留问题及其重访条件；只有当明确的答案解决了它的门时，默认才会将其淘汰。切勿留下“已回答”部分。
4. 然后移动。 在一行中说明答案解锁的下一个具体操作，然后在“下一步”中执行或排队。

Brief 与 Bootstrap 的“确认当前状态”有何不同

Bootstrap 步骤 9 检查 事实： STATUS 是当前的，做了任何事情，焦点是否不变。其答案是 yes/no/corrections 并落在 STATUS 中。简要解决选择：采取几条防御路径中的哪一条。它的答案是在指定的替代方案和 DECISIONS 中进行选择。将它们分开：提出选择的确认交换不会当场变成摘要 - 它将选择放在“开放问题（所有者）”中并提供摘要；简报不会重新核实已经确认的事实。

常见故障模式

• 沉默解读为同意。 业主回答了Q1和Q2；代理“按照建议”记录了第 3 季度至第 5 季度的条目。仅追加使其永久化。
• 选项填充到计数。 没有人提出的选项在推理中显示为“拒绝”，并且该条目记录了从未发生过的审议。
• 归因于所有者但所有者从未给出的原因。推理带有所有者对他们称之为实时替代方案的说法；其他一切都是代理人的评估，如此标记。
• 没有推荐的选项，或者没有理由的推荐。两者都让业主做代理人的工作。
• 重新讨论已定的决定因为业主的措辞听起来像是一个问题。在呈现任何内容之前，请先 Grep DECISIONS。
• 每个问题一个 CHANGELOG 条目。 概要是一个工作单元；一次交换五个条目是隐藏记录的噪音。
• 将所有者的回答记录在 STATUS 作为“已回答”部分而不是 DECISIONS。 STATUS是仪表板；答案已成为历史。
• 行话未定义因为所有者知道它。这份简报也是未来会议冷读的记录。

中断的Brief恢复。 在CHANGELOG中命名决策IDs的Brief会在任何DECISIONS附加之前写入持久保留行（Reserved decisions: D-0011–D-0012或显式逗号分隔列表）。 Close 和 Brief 都会在分配之前协调待处理条目，并考虑 DECISIONS、决策档案和整个 CHANGELOG 历史记录中的保留。如果另一个 Close 已经使用了更高的可用编号，则追加恢复的更低的 IDs，而不对历史条目进行排序；医生可能会报告决策顺序建议，恢复 CHANGELOG 条目对此进行了解释。修复是幂等的：仅填充缺失的保留条目；如果保留的 ID 被不相关的内容占用，则因冲突而停止并保留两条记录。 Doctor检查支持引用的IDs、范围成员和正文引用，但无法验证占用的ID的语义身份；支持的范围使用一个前缀、小数点和短破折号或全长破折号。

工作原理

仅附加规则。 CHANGELOG 和 DECISIONS 永远不会进行追溯编辑（从未使用过的占位符条目是模板残留物，而不是条目）。错误的条目会被追加更正或取代——审计跟踪才是重点。

大量编辑集中在 STATUS。 STATUS 是一个经过积极编辑的仪表板 - 重写，从未附加。 CHANGELOG 和 DECISIONS 仅以追加方式增长； LEDGER 行就地编辑，而实时行和终端行逐字移动到存档。这种分割是使学科得以生存的设计属性，当项目开始将会话记录添加到 STATUS 时，它就会默默地失败。

STATUS 保持在约 40 行左右，但绝不会超过约 60 行。 超过该值，某些内容就会被错误分类。超过 ~1 KB 的单行是伪装的历史。

一次一个写入者。 该协议假设单个会话写入寄存器。一棵工作树上的并行代理会破坏它的 id 分配（“检查最高数字”不是原子性的）、它的附加规则（共享树中未提交的工作是不持久的）以及谁拥有 STATUS 的任何感觉。将并发代理隔离在它们自己的工作树中；不要向共享树添加通道并期望寄存器能够生存。一个受认可的多通道例外是账本片段 LEDGER-ENTRIES-OWED.md：并行通道可以在其工作旁边写入一个片段，直接写入者将其放置在最旧的第一个位置。

散文胜过项目符号，除非项目符号赢得了它。 真正的表格数据的表格（状态行、术语表）；不能代替两句话的解释。

内部文档中没有营销语言。 读者是未来的自我或未来的代理人，而不是者。

在提出选项时列出备选方案。 根据优先顺序和权衡内容来标记每个选项 - “快速交付，接受债务”与“缓慢交付，复合可维护性” - 而不是“选项 A”与“选项 B”。

每个项目的工作流程规范（提交约定、会话卫生）位于项目 README 的“工作首选项”部分，而不是此处 - 请参阅 README 模板。

可选同伴

除了核心之外，该存储库还提供了两个可选技能，每个技能都可以在没有核心的情况下使用：staging/research-protocol/（稳定的 IDs 的来源、注释、问题和综合）和 staging/architect-protocol/（具有冻结主题、独立审查和证据支持的移交的分阶段架构工作）。两者都不是全局安装的，也不是由该技能激活的。想要将其复制到项目中的项目，将其在 SKILL-REGISTRY.md 中注册为 staged，并仅在明确的所有者选择时将其提升为 active。核心保留 STATUS、CHANGELOG、DECISIONS 和 LEDGER：同伴永远不会创建第二个仪表板，也永远不会将这些文件写入核心顺序之外。

• 研究拥有<project>/research/。 Bootstrap 步骤 7 读取其索引，有界。在提出所有者选择之前，简要追踪来源→确切段落→主张→相反证据，然后根据上面的简要规则记录选择——仅当真正的替代方案被拒绝时才记录DECISIONS；综合引用了 D-ID 或 Brief CHANGELOG 行，并且从不重申该决定。关闭在 CHANGELOG 条目中创建或更正研究 IDs 的列表。
• 架构师拥有寄存器的 architect/ 文件夹（通常为 docs/architect/）。 STATUS 引用数据包路径、活动阶段和截止日期； STATE.json 是数据包自己的状态，绝不是第二个项目仪表板。移交所有者决定也位于 STATUS“未决问题（所有者）”下，以便简报可以看到它们；安装 LEDGER 后，每个合同查找结果都是 LG 行，并且数据包引用其 ID。每个合同都将登记文件声明为报告路径，因此关闭时永远不会改变冻结的主题； CHANGELOG 条目先于任何 STATE.json 阶段前进。

每个部分都有自己的只读检查器，并且没有一个检查器运行另一个：

同伴检查器的 FAIL 是失败，而不是建议性漂移：只有 docs-doctor 通过退出代码将 WARN 与 FAIL 分开。

该技能中的文件

• SKILL.md（此文件）—五种模式的所有操作说明。
• templates/ — 启动文件。安装时复制这些。
• scripts/docs-doctor.py — 医生检查。 Python 3 标准库，只读，git 可选。
• scripts/docs-migrate.py — 审查了 STATUS- 到 LEDGER 的迁移；参见 docs/MIGRATION.md。
• scripts/skill-registry.py — SKILL-REGISTRY.md 的可选只读验证器。
• staging/research-protocol/、staging/architect-protocol/ — 可选同伴；请参阅可选同伴。
• tests/ — 可执行的 Doctor/migration 测试和生命周期工件重放，限制在 tests/README.md 中。
• docs/ — 该技能自己的寄存器（它运行它附带的协议）、匿名审计证据和一份有效的摘要。