aep-validate

验证

对 AEP 工作流生成的任何产物运行生成器／评估器模式。生成器尝试使用该产物（试运行），评估器根据实际情况（代码库、约束、下游协议）检查它，随后将结果汇总为针对该产物本身的修复。

**核心原则：**生成产物的 Agent 无法诚实地评估它——Agent 会称赞自己的工作，而生成器／评估器分离正是为了解决这个问题。角色分离契约、评分框架、Agent 提示词模板、评估协议和发现项格式的规范定义均位于 /aep-gen-eval 参考资料中——请阅读这些资料以了解其底层机制；此技能将该模式应用于产品产物。

适用场景：

/aep-envision → /aep-map → /aep-model (UI-facing) → /aep-validate → /aep-dispatch → /aep-design → /aep-launch → /aep-build → /aep-wrap
                    ▲ you are here

Also usable after any phase:
  /aep-envision → /aep-validate   (validate product context)
  /aep-map      → /aep-validate   (validate architecture + stories)
  /aep-design   → /aep-validate   (validate specs before launch)
  /aep-build    → /aep-validate   (already built into Phase 5 — use that instead)

**会话：**主会话，可自主运行，也可交互运行
**输入：**任何 AEP 产物（拆分模式下为 product/index.yaml + product-context.yaml，或 v1 模式下仅为 product-context.yaml，也可以是 OpenSpec 变更、设计文档、代码）
**输出：**修复问题后的同一产物。验证报告追加到变更日志中。

---

开始之前

确定要验证的内容：

ls product-context.yaml 2>/dev/null   # product context
ls openspec/changes/ 2>/dev/null      # OpenSpec changes
ls .dev-workflow/ 2>/dev/null          # design artifacts

用户指定目标时，验证该目标。如果用户未指定：若上述探测项中恰好有一项命中，则验证该产物；如果有多项命中，应询问用户要验证哪一项，而不是自行猜测。**后置条件：**启动 Agent 前，必须确定产物（具体路径）及其模式（A/B/C/D）。

对于产品上下文，请使用 references/file-resolution.md 中的探测方法判断拆分模式或 v1 模式（该文件是模式语义的规范来源）。拆分模式：验证两个文件，并检查跨文件一致性。V1 模式：仅验证 product-context.yaml。

---

步骤 0：一致性预检（机械式，阻塞）

启动任何 Agent 前，运行确定性检查。该检查成本低、无需判断，并且能够发现控制文件与工作记录不再一致的这类缺陷：

node scripts/coherence.mjs --context product-context.yaml

若发现阻塞性问题，检查会以非零状态退出，并为每项问题打印修复建议：

发现项	阻塞原因
not_started 门控下存在已完成的故事	门控已无法反映工作状态；所有下游使用方都会错误解读它
门控状态不在定义集合中	控制文件中的措辞会先于其内容发生偏移
汇总与记录不一致	非零记录旁的零值总计，是对总计的一种陈述
故事使用了但从未声明的模块	所有架构使用方都无法看到这项工作
架构未定义的字段	这些字段承载着框架使用方无法读取的实际含义

继续之前必须修复阻塞性问题——Agent 无法评估自相矛盾的产物。

派生规则详见 references/drift-facts.md；scripts/coherence.mjs 是其可执行部分，与 /aep-human-alignment 共享，以确保两者不会发生偏移。表格第 2 行中的“定义集合”指 references/aep-vocabulary.schema.json，检查器会在运行时加载此文件——整个语料库的门控状态仅定义一次，而 scripts/json-schema.mjs 是其背后的共享验证器。

---

步骤 1：确定验证模式

此技能根据产物类型在四种模式之一运行。每种模式都会配置要启动的 Agent 及其检查内容。**模式 A（产品上下文）详见下文。**对于模式 B（设计）、模式 C（代码）或模式 D（文档），请阅读 references/modes.md，了解 Agent 角色、Phase-5 代码分支及 Agent 数量自定义方法。

模式 A：产品上下文验证

时机： 在 /aep-envision 或 /aep-map 之后——验证 product-context.yaml（拆分模式下还包括 product/index.yaml）

拆分模式下的跨文件检查：

• stories[].layer 的值必须存在于 product/index.yaml 的 product.layers[] 中
• stories[].activity 的值必须存在于 product/index.yaml 的 product.activities[] 中
• calibration.plan[].dimensions[] 必须引用 product/index.yaml 的 product.quality_dimensions[]
• 启用拆分模式时，product-context.yaml 中不得包含 opportunity 或 product 部分
• product/index.yaml 必须包含 personas、capabilities 和 product 部分
• 如果 object-model 是已声明的质量维度：每个面向 UI 的能力都必须有一个 product/maps/<capability>/object-map.yaml；每个 stories[].object_model_refs 条目都必须指向一个现有的对象映射路径和对象 ID；对象名称必须与 architecture.domain_model 和 docs/glossary.md 保持一致

模式 A 分为 两轮检查——先检查产品设计质量，再检查技术正确性。

第 1 轮：产品设计评估（“我们做的东西对吗？”）

**Agent：**产品设计评估器 + 愿景一致性检查器

Agent	职责	检查内容
产品设计评估器	根据用户故事地图原则进行评审	行走骨架的有效性、分层顺序、INVEST 合规性、依赖关系图质量、活动覆盖度、叙事连贯性
愿景一致性检查器	追溯故事与机会简报的关联	每个故事都对应已陈述的用户需求、没有范围蔓延、JTBD 覆盖度

使用 /aep-gen-eval 的 agent-contracts.md 中的产品设计评估器提示词，以及 scoring-framework.md 中的故事地图评分维度（行走骨架有效性、分层顺序、愿景一致性、INVEST 合规性）。

第 1 轮硬性失败条件：

• 行走骨架有效性 < 3 — 第 0 层不够精简
• 愿景一致性 < 3 — 故事已偏离产品愿景
• INVEST 合规性 < 3 — 故事无法由自主 Agent 执行

第 1 轮活动检查（如果存在 product.activities）：

• 活动覆盖度： 每个 layer_introduced: 0 的活动至少有一个第 0 层故事。没有故事的活动意味着行走骨架存在缺口。
• 活动一致性： 每个 activity 非空的故事都引用 product.activities 中有效的活动 ID。
• 叙事连贯性： 按 order 从左到右阅读活动时，应形成连贯的用户叙事：“用户先[活动 1]，然后[活动 2]，接着……”。如果流程不连贯，则需要重构主干。
• 基础设施占比： 如果第 0 层故事中 activity 为空的占比超过 60%，则分解可能过于偏重技术；可考虑围绕用户能力重新组织故事。

第 1 轮对象映射检查（如果存在任何 product/maps/*/object-map.yaml）：

• CTA 覆盖度： 每个 UI 故事中的动词都应对应其能力对象映射 coverage 中某个对象上的 CTA。未覆盖的 UI 故事意味着缺少对象或存在未显露的任务流。
• 对象归属： primary_objects 中的每个对象都至少有一个 screens[] 条目（collection 或 detail）。没有主界面的主对象将无法访问。
• 锚点存在： 每个能力对象映射都声明了 navigation.anchor_object。
• 任务流依据： 每个 mode: task_oriented 的 interaction_modes 条目都有非空的 reason（默认采用对象优先；如有偏离，必须说明理由）。
• 审批状态： 当能力对象映射的 status 为 draft 或 stale 时，不得将面向 UI 的故事标记为可分派；必须先将其状态设为 approved（运行 /aep-model）。
• 引用解析： 每个 stories[].object_model_refs 条目（<path>#<object-id>）都能解析——路径存在，并且 <object-id> 同时出现在该映射的 primary_objects/supporting_objects 以及 object-model.yaml 的 objects[] 中。
• 名词覆盖度： 从 product.activities 中收集的每个名词都对应一个对象，或被说明为仅用于实现。

第 2 轮：技术验证（“我们能正确地构建它吗？”）

**Agent：**Generator + Evaluator + Protocol Checker

Agent	角色	检查内容
Generator	对每个故事／层进行试运行	每个故事是否可实现？是否缺少细节、验收标准是否含糊、是否存在依赖缺口
Evaluator	对照设计与代码库	软件包版本、导入路径、现有模式、文件是否存在、API 兼容性
Protocol Checker	验证下游兼容性	调度所需字段、DAG 有效性、评分兼容性、文件冲突检测

**为什么分两轮：**第 1 轮发现产品设计问题（故事不当、分层不佳、偏离愿景）；第 2 轮发现技术问题（字段缺失、引用失效、与代码库不匹配）。两轮都在将任务分派给自主 Agent 之前运行；这些 Agent 会按照收到的内容进行构建。

---

第 2 步：组装验证上下文

为每个 Agent 准备一个聚焦的上下文包——其范围决定了评估质量。通用的 Generator 和 Evaluator 上下文配置方案（包含哪些内容、排除哪些内容）以 /aep-gen-eval agent-contracts.md（“上下文组装规则”）为准。

**Protocol Checker 上下文（仅限模式 A）：**向其提供产物中的故事部分、必须满足的下游协议规范，以及拓扑和层级门控定义。下游协议要求（调度故事字段、评分公式、DAG 规则、设计／构建交接契约）在 references/protocol-specs.md 中有说明。

---

第 3 步：启动 Agent

并行启动所有 Agent。每个 Agent 独立工作——彼此看不到对方的输出。使用 /aep-gen-eval agent-contracts.md 中的提示词模板：Generator（产物验证）、Evaluator（代码库验证）、Protocol Checker，以及——对于模式 A 第 1 轮——Product Design Evaluator。**后置条件：**每个已启动的 Agent 都返回一份发现报告。

---

第 4 步：汇总发现

所有 Agent 返回后，将发现汇总为一份操作清单，把多个 Agent 从不同角度发现的同一问题合并为一项，并附上综合证据。

按严重程度分类

类别	描述	操作
阻塞	会导致下游使用方无法正常工作	立即修复
重要	会造成阻碍、困惑或返工	继续之前修复
次要	外观问题、可选字段缺失、文档缺口	记录；若修复简单则予以修复

呈现给用户

在应用任何修复之前，向用户展示汇总后的发现及数量——用户可能会重新排序优先级或否决某些发现：

Validation complete: {N} blocking, {M} important, {K} minor issues found.

Blocking:
  1. [issue] — found by Generator + Evaluator
  2. [issue] — found by Protocol Checker

Important:
  3. [issue] — found by Generator
  ...

**后置条件：**已向用户展示去重并计数后的发现列表。

---

步骤 5：应用修复

读取磁盘上当前的工件状态（而非缓存副本），然后修复所有阻塞和重要问题；将轻微问题记录在变更日志中，并在修复简单时一并修复。只要仍存在阻塞问题，工件就不能通过验证。

修复规则：

• 仅修改正在验证的工件——不得创建新文件、编辑其他工件或实现代码。
• 保留工件现有的结构和约定。
• 如果修复需要 Agent 无法做出的决定（架构选择、业务优先级），请将其标记为 open_question，并注明默认假设，而不是默默猜测。
• 根据产品上下文架构，为每次修复追加一条变更日志条目（date、author: aep-validate、summary），记录验证内容以及已修复的阻塞、重要和轻微问题数量。

如果工件是 product-context.yaml，请在提交前确认其仍能解析——运行 references/yaml-guardrails.md 中的验证命令。后置条件：npx js-yaml product-context.yaml 以状态码 0 退出。

---

步骤 6：提交

# Resolve $BASE (integration branch) per /aep-git-ref "Integration Branch".
git pull --ff-only origin "$BASE"
git add <validated-files>
git commit -m "fix: validate {artifact-name} — {N} issues found and fixed"
git push origin "$BASE"

**后置条件：**修复已提交并推送到 $BASE。

---

验证维度

评估时，Agent 会根据特定模式的维度进行权衡（完整性、一致性、安全性、可行性、准确性等）。各模式的维度表，以及完整的 5 维代码评分框架的链接，位于 references/validation-dimensions.md。

---

何时不应使用此技能

• 在 /aep-build 第 5 阶段期间——改用内置评估器循环（其中包含 executor.spawn_evaluator、验证 JSON 和评分框架）。
• 用于主观质量评估——此技能验证事实正确性和完整性，不评判审美。若要评审可用性／设计质量，请使用 /aep-design-lens（以 HCI 理论为基础的启发式健康检查）；其设计质量检查可补充 validate 的事实检查。
• 用于微小改动——单文件编辑或拼写错误修正无需进行 3 Agent 验证。

---

下一步

验证后，继续执行相应的下游技能：

Product context validated → /aep-dispatch
Design validated          → /aep-launch
Code validated            → create PR (or /aep-build Phase 9)
Document validated        → publish/share