Superval 是一个计划驱动的验证引擎，其目标是为已构建的项目提供证明，确认其与原始计划一致。
一、用途与定位 Superval 用于验证由 superbuild 或 autobuild 构建的项目，确认计划中的每个功能都被正确实现、正确接线并且真正可用。它属于验证环节，典型流水线为：/superplan（计划）-> /superbuild 或 /autobuild（构建）-> /superval（验证）。适用场景包括：superbuild 或 autobuild 完成所有阶段之后；需要证明每个计划功能存在且可用时；构建中途失败需要评估缺失内容时；上下文压缩后恢复并需要验证状态时；创建 PR 之前证明实现正确时。不适用场景：计划尚不存在（应先使用 /superplan）；正在构建过程中（应使用 /superbuild 或 /autobuild）；没有计划文档的项目（缺少验证依据）。
二、核心原则 计划是规格说明，构建出的代码是实现，Superval 是证明。验收测试将应用视为黑盒，通过其公共接口从外部驱动，就像真实用户一样，绝不导入源代码。
三、执行流程 完整流程共 10 个阶段：1. INGEST PLAN（查找并读取计划文档）；2. READ STATE（加载 .autobuild/ 与计划复选框状态）；3. DETECT STACK（检测测试框架与工具）；4. EXTRACT FEATURES（从计划构建功能映射）；5. STRUCTURAL VERIFICATION（结构验证：预期文件是否存在）；6. WIRING VERIFICATION（接线验证：模块是否连接）；7. BEHAVIORAL VERIFICATION（行为验证：功能是否真正可用）；8. TRACEABILITY REPORT（可追溯性报告：将每个功能映射到结果）；9. GENERATE FEEDBACK（生成结构化失败诊断）；10. FIX FAILURES（修复每个失败项）。之后回到结构验证重新验证，循环不息，直到全部通过，最终报告 PASS。
四、各阶段要点 阶段 1 按顺序查找计划文档：用户提供的路径、docs/-plan.md 或 docs/-plan-*.md、根目录 -plan.md、.autobuild/config.json 的 plan_path 字段。找不到计划则立即中止。多文件计划需读取全部部分。阶段 2 读取 .autobuild/ 目录下的 config.json、各 phases/phase-.json、logs/execution.log，以及计划文档中的阶段总览表和各阶段目标、完成定义的复选框状态，输出状态摘要，并声明所有声明都将被独立验证。阶段 3 运行检测脚本 ./scripts/detect-test-framework.sh <project-dir>，或手工检测 package.json、tsconfig.json、pyproject.toml、requirements.txt、go.mod、Cargo.toml 等，再检测测试框架（如 vitest.config.ts、jest.config.ts、pytest.ini 等），找不到测试框架则硬性中止。阶段 4 从计划中提取阶段总览、各阶段目标、代码变更（创建/修改/删除）、测试文件、验收标准和完成定义，构建功能映射。阶段 5 检查每个源文件和测试文件是否存在，并验证声明的依赖是否已安装，结构失败会阻断后续验证。阶段 6 检查入口点是否可达功能代码、桶文件是否导出预期符号、服务是否可无错误导入（可捕获循环依赖）。阶段 7 先做冒烟测试（项目必须能构建并启动），再运行质量门（lint、format、typecheck、test），最后生成由外而内的黑盒验收测试。
五、验收测试模式 验收测试通过面向用户的接口自动化被测应用，接口决定自动化工具。CLI 工具用 bash 脚本测试构建产物；TUI 应用用 expect（TCL）或 pexpect（Python）驱动交互式终端；Web 应用（React、Vue、Angular 等）用 Playwright 或 Cypress 驱动真实浏览器访问运行中的应用。验收测试可用任意脚本语言编写，其语言无需与项目语言一致。
六、版本与限制 当前版本为 1.0.0，作者 skulto。使用前需先有可对照的计划文档，且项目必须有可检测到的测试框架，否则 Superval 会直接中止。其行为验证循环设计为持续进行，直到全部通过。