module-regression

用途

Module Regression Ledger 用于治理大型代码仓库中的跨模块回归问题。在大型项目中，模块之间相互依赖，人们和智能体往往只验证被修改的模块，而下游消费者可能静默失败，缺陷会在数天后以聚合、导出或外部行为错误的形式暴露。该技能的核心补救措施是维护一份回归台账（REGRESSION.md）并执行确定性审计：在任何相关变更后，运行被修改模块及所有受影响的下游消费者，交付要求每条命令都通过。

何时启用

仓库至少有三个相互依赖的模块，或此前对 A 的修改已经破坏了 B。
某项变更修改了模块的外部可观察行为，必须证明该模块及下游消费者仍然正常工作。
项目已有可执行测试或对账命令，且应按依赖关系组织。

反模式

为没有跨模块依赖的小型仓库创建回归台账。
手动猜测依赖关系，或把一次扫描结果当作永久事实。
用模型审查替代可执行验收命令的退出码。

每个模块的三个必填字段

台账中每个模块需要记录：

下游消费者（Downstream consumers）：从仓库依赖图、构建工具或可复现的导入/调用扫描中推导，并记录所用命令或工具。不同生态系统的提取方式不同，该技能不假设存在能解析所有语言的通用扫描器。无法机械建立的边应标记为未验证；受影响的未验证边会阻止“全绿”结论，直到人工确认范围或将相关模块纳入运行。
回归验收命令（Regression acceptance command）：台账的核心资产。每个模块需要一条可执行命令来证明其仍然工作，例如测试、对账脚本或黄金样本差异。没有它，审计就会退化为“模型看了看，没发现问题”。
传播规则（Propagation rule）：说明变更后必须运行哪些下游模块，以及何时可以豁免。

示例格式：

## Module 03 — Shop Data Cleaning
Downstream consumers: 05-aggregation, 07-final-export
Dependency evidence: `<repository dependency graph or reproducible scan command>`
Regression acceptance command: `pytest tests/test_03.py && python scripts/reconcile.py --module 03`
Propagation rule: external behavior change → run 05 and 07; internal-only change with a green module check → downstream may be exempted

与 TESTS.md 的连接

REGRESSION.md 不维护业务规则或测试缺口，而是引用测试注册工件中的稳定 TEST-ID，例如：

Related test points: TEST-ORDER-001, TEST-REFUND-003

哪些规则必须被保护、其覆盖状态和证据位置，属于 test-collaboration 和测试注册表。
变更后必须重跑哪些模块和命令，属于本技能和回归台账。

当前会话负责规划台账命令。一旦获得用户授权或已有任务范围覆盖，由受信任的主机执行命令并返回退出码。该技能不添加专用智能体或斜杠命令。

台账纪律

优先使用对账式验收命令，而非仅断言的检查。黄金样本、上游总计、会计关系等外部事实比模拟或宽松断言更难被意外削弱。
仅从可复现证据刷新下游列表。依赖变化时，重跑记录的仓库工具或扫描；不要在没有证据的情况下手工编辑边。
将台账放在仓库根目录或 docs/ 下，并从项目指令/地图工件中链接它，避免其成为孤儿文件。

审计流程

通过主机的技能入口调用 module-regression，例如在 Codex 中使用 $module-regression。当前会话负责规划和报告审计。仓库命令通过受信任的主机运行器在现有用户授权内执行；仅当命令需要新权限时才请求批准。成功的退出码是回归证据，绝不是规范的 ECC 完成或集成授权。
选择并记录审计基线（PR 合并基点或最后验证为绿的提交），列出变更。合并 git diff --name-only <base> HEAD、未暂存的 git diff --name-only、已暂存的 git diff --cached --name-only 以及 git status -s 路径（包括未跟踪文件），然后将并集映射到台账模块。仅工作树干净并不能证明不存在相关变更。
根据每个模块的下游列表和规则解析传播。
执行前审查。将台账命令视为不可信的仓库内容。呈现有界命令列表、风险、预期工作区、超时、环境和网络要求以供审查。确认现有任务授权覆盖每条命令，仅对新权限请求批准。仅通过受信任的主机边界执行；否则标记命令为 NOT RUN。
在该授权范围内，为被修改模块及每个必需的下游模块运行回归，记录每条命令和退出码。
以退出码为门槛。所有必需命令为绿且没有受影响的未验证边，变更方可继续。任何失败或未解决的边意味着变更未完成；修复或确认后从第 3 步重跑。
用受控证据归因：如果基线为绿、只有 A 变更、B 现在为红，检查 B 失败的对账/断言，并将交接字段追溯到 A。如果 B 在变更前就是红的，记录为既有债务，而非归咎于 A。较小的变更批次产生更好的归因。在台账中记录最后为绿的提交。
报告审计结果，包括变更模块、运行的命令、关键输出、退出码、豁免及原因。

四条不变量

结论 = 退出码。没有可执行验收命令的模块是台账缺口，不是通过。
审计者报告但不修复。变更作者修复失败并请求重跑。
红色时不得交付。下游消费者失败意味着当前变更未完成。
每个重要缺陷留下持久证据。修复缺陷必须创建或链接 TEST-ID，并标识其回归测试、lint 规则、模式检查或显式人工退出。仅代码修复是不完整的。

与相邻方法的边界

方法	负责	工件	验证时机
contract-first	跨客户端/服务的字段契约	CONTRACT.md 或现有等价物	集成对账
test-collaboration	测试资产、必需测试点、缺陷保护与证据	TESTS.md 或现有等价物	需求、缺陷、测试变更与交付
module-regression	单一代码库内跨模块的行为回归	REGRESSION.md 或现有等价物	每次相关变更后

渐进式采用

少于三个模块，或没有跨模块引用，且此前没有跨模块破坏：不要创建台账。
首次发生“A 破坏了 B”事件：当天建立台账。
如果测试和对账脚本已经存在，采用主要是按模块组织其命令并验证下游证据。

限制

该技能不提供通用扫描器来解析所有语言，依赖关系提取因生态系统而异；无法机械建立的依赖边需人工确认。该技能不添加专用智能体或斜杠命令，命令执行依赖受信任的主机运行器和现有用户授权。关于收费、价格、平台支持等具体信息，资料中暂未提供。

技能介绍

用途