specsfy-04-validate

验证规范

必备准备工作

执行此技能前，必须先在项目根目录加载 $specsfy-setup。自动交接时，也必须在此步骤前重新加载它。 复用对话中已确认的根目录；如果 setup 指出有待处理事项，则不要继续。

交互模式

交互模式：perguntas。 提出任何问题前，请先阅读并应用 .specsfy/Spec.md 中的 Contrato de perguntas numeradas。

将 spec.md 视为唯一事实来源，并将其视为自然语言编写的代码：先检查严格格式，再从语义上检查清晰度、完整性、一致性和可测试性。

协调对话

完成此步骤或发现属于其他步骤的工作时，请宣布 Pendência detectada: <descrição> — ação: resolvendo nesta etapa，并在事项属于当前步骤范围时解决它。需要转移职责时，请宣布 Transição automática: $specsfy-04-validate → $<destino> — motivo: <motivo> — resultado esperado: <resultado>，并立即加载目标技能，无需请求确认或重复命令。在同一对话中继续。完成当前步骤所需的修正后，请宣布 Retomada automática: $<destino> → $specsfy-04-validate — pendência resolvida: <resultado>，并立即恢复当前步骤。每次交接后都要重新评估状态，以避免循环。交接无需请求确认；敏感操作仍须获得特定授权。

执行验证

1. 根据提供的路径解析 specs/<estado>/<NNNN>-<slug>/spec.md；如果有多个 spec 且未提供 slug，请询问要验证哪一个。
2. 确认 Formato: Specsfy/2.0、三个阶段的顺序、slug 与目录名称一致，以及软件包仅包含 spec.md 和可选的 research/ 目录。
3. 对于查阅过的所有外部 API 或文档，确认 research/ 中有本地证据，并且在 Artefatos de pesquisa armazenados 中有相应索引；这些材料仅供参考，绝不能作为第二事实来源。
4. 当 Status 或 Definition Gate 仍有待处理事项时，执行：

node .agents/skills/specsfy-04-validate/scripts/validate_spec.mjs specs/<estado>/<NNNN>-<slug>/spec.md --allow-draft

1. 阅读 references/quality-gates.md 并进行语义审查。
2. 检查 Interface para pessoas 字段。如果为 Sim，则要求第 10 节包含已观察到的技术栈和约定、屏幕及其职责、信息流和导航、菜单和主导航、表单和操作、组合与布局、状态和无障碍功能。确认拟议技术遵循技术栈来源，或者已记录该缺口并告知相关人员。没有屏幕和表单的 CRUD 属于 BLOCKER；应自动返回 $specsfy-02-backlog 以澄清该缺口。
3. 比较 research、需求、BDD、技术计划、数据模型、契约、TDD、矩阵和任务。确认整个 feature 以及每个 US、FR 和 NFR 至少有三个不同的 AC；不要把“文件格式正确”与“规范正确”混为一谈。
4. 当产品、架构或安全方面的内容具有实质影响时，阅读 references/review-lenses.md，在第 13 节记录 findings，并执行 scripts/review_findings.mjs。存在 P1 Open 时，gate 仍须保持待处理状态。
5. 如果定义会更改技术栈或持久化方式，则要求 Definition of Done 分别引用 .specsfy/STACK.md 或 .specsfy/DATABASE.md。如果用途或能力发生重大变化，则要求审查 PROJECT.md；如果确认新增规则，则要求 .specsfy/RULES.md。
6. 最终验收时，查找 [MIGRATION] 任务，并对每个任务执行 verify_evidence.mjs --delivery。如果任务仍未完成，或者缺少文件、应用命令或状态查询，则保持 Delivery Gate 为待处理状态。

对发现项分类

• BLOCKER：阻碍正确完成任务或测试；需求相互矛盾、没有可观察行为、缺少高影响决策，或未覆盖主要场景。
• WARNING：增加返工或风险，但仍可安全实现。
• NOTE：不产生实质影响的编辑性改进。

对于每项发现，请注明章节或 ID，解释其影响，并提出具体修正方案。

Gate

恰好返回以下一种结果：

• READY：没有格式错误，也没有未解决的 BLOCKER。
• NOT READY：存在任何结构性错误或 BLOCKER。

请包含计数、最低覆盖范围 US/FR/NFR ↔ 3 ACs、最重要的三项发现，以及自动转换规则：

• READY → $specsfy-05-tasks，规划第 14 节；
• NOT READY → 缺少决策时返回 $specsfy-02-backlog；backlog 细化会执行完整周期，只有在补齐缺漏或记录明确输出 avançar 后，才恢复此验证；输出后，记录 NOT READY，并且在本次恢复时不要重新开启同一周期；如果修正方案已确定，则对先前已批准的 spec 使用 $specsfy-update-spec，对初始定义使用 $specsfy-03-specify。

宣布原因并立即加载选定的 skill。

记录到唯一文件

不得自动更改需求：

1. 在第 13 节更新 Gate do Ato I — Definição，填写结果、日期和发现项；
2. 若为 READY，设置 Definition Gate: Passed 和 Status: Defined；
3. 若为 NOT READY，设置 Definition Gate: Failed、Plan Gate: Pending、Delivery Gate: Pending，并保持 Status: Draft；
4. gate 通过后，不使用 --allow-draft，重新运行 validate_spec.mjs specs/<estado>/<NNNN>-<slug>/spec.md；
5. 在聊天中报告结果。

Definition Gate 通过后，运行 specsfy transition <id> defined。 在 review 阶段，使用相同分析进行最终验收。Delivery Gate 通过、Status 为 Complete 且 DoD 已验证后，运行 specsfy transition <id> completed。 在此之前，如果某个回答可能改变交付内容或 Effort，请调用 $specsfy-interviewer。

如果用户要求修正，请编辑源章节，保留 ID 并重新验证。切勿创建其他 spec 或验证文件。

仓库强制执行

本地和 CI 使用相同的 runner：

node .agents/skills/specsfy-04-validate/scripts/verify_repo.mjs . \
  --boundary local --timeout-seconds 300 --max-output-bytes 65536

local、git 和 ci 边界不会改变策略。--attestation PATH 是持久化 attestation 的唯一方式；--self-test 会在临时目录中运行 canary，绝不会生成证明性 binding。schema 2 attestation 会关联 commit、可执行文件摘要、通过的检查、任务和文件哈希。摘要涵盖命令、限制和策略文件。不要接受仅在一个边界通过、超出限制，或截断诊断信息却未标记 truncated 的 gate。

目录契约要求具备十四项基础 skills、specsfy-setup、specsfy-documentator 和 三项 specsfy-aux-*；同时验证每个已安装的 specsfy-specialist-*，不设 specialist 数量上限。 Gherkin BDD 是 spec.md 的唯一参考；强制执行流程绝不运行 .feature。它会在 PHP 项目中运行派生测试，包含 PHP + Node 项目。对于没有 PHP 的 Node 项目，要求提供 test:tdd 脚本；如果缺少该脚本，则报错并指导 skill 询问用户并建议使用 Vitest。

按需调用 Specialist

当 gate 需要特定技术审查时，请阅读 references/specialists.md。安装是明确建议，绝不是验证的副作用。