用途:plain-healthcheck 是 ***plain 项目的验证关卡(verification gate)。当项目定稿、即将交给用户或其他技能渲染时运行,例如 forge-plain 第 4 阶段结束、add-feature 第 3 阶段最终评审、debug-specs 修复后,以及任何改变可渲染表面的编辑(add-concept、add-functional-spec、add-template、resolve-spec-conflict、refactor-module 等)之后,或用户询问项目是否处于可渲染状态时。
主要能力:采用“检测→修复→重跑”循环,不因首个失败而停止。步骤一盘点仓库根目录及子目录中的 .plain 文件,依据 YAML frontmatter 的 requires、import 构建模块图,识别未被其他模块 requires 的顶层模块,列出所有 config.yaml 与 test_scripts/ 脚本,并按“同目录 config 优先、否则仓库根 config”的规则为每个顶层模块配对配置。步骤二校验每个 config.yaml:能否解析为 YAML、是否至少含 unittests-script、各 *-script 字段路径是否以 .sh 或 .ps1 结尾且文件存在、Unix 下是否可执行、单个 config 是否混用技术栈、是否存在悬空字段、声明 prepare-environment-script 却未声明 conformance-tests-script、以及 test_scripts/ 下是否有未被引用的孤儿脚本(警告)。步骤三对每个顶层模块执行 codeplain <top_module>.plain --dry-run,并按真实渲染方式传入 --config-name、--template-dir、--full-plain、--verbose 等标志;失败时读取错误、用 --verbose 重跑、仅修改 .plain 或相关 config/template,绝不改动 plain_modules/ 或 conformance_tests/ 下的生成代码,然后重跑直至成功。步骤四输出结论,首行为 PASS 或 FAIL,FAIL 时附编号问题清单。
自动修复:仅限为脚本补可执行位(chmod +x <path>),以及在唯一明显候选时修正指向重命名脚本的过期路径;其余问题须向用户报告,重新调用 implement-*-testing-script 需用户明确批准。
限制:不从头编写新规格,不执行真实渲染(仅 --dry-run),不运行测试脚本本身,不静默重新生成 config 或脚本。若 codeplain 不在 PATH 或未设置 CODEPLAIN_API_KEY,须明确报告环境失败并停止,不得假装通过。使用前若尚未加载 load-plain-reference,应先加载以获取 ***plain 语法规则。