plan-cards

plan-cards — 自包含的卡，不是设计文档

产物是 cards/CARD-xx.yaml（形状：assets/card_template.yaml）。合格标准只有一条：单独丢给一个没有任何 上下文的 agent，它能干完。本文件写：卡在流水线里是什么、什么算拆对了、原语与出口、进实现前的门。 先拆哪块、拆几张是你的份额。

缺口（Judgment + Capability + Control）

deletion 测试：撤掉本 skill，引擎会写一份平铺的 tasks.md——没有文件归属、没有 AC 子集、两张卡都改 package.json、一张卡要 80k 上下文。并行实现时合并冲突，卡级验收没有对象，白名单执行器无从执行。 缺的是判据（自包含长什么样）、原语（三项 lint）、门（lint 不过不进 implement——aidlc_state.py advance implement 对 cards.dir 自己跑 lint_cards.py；cards.lint_passed 不可 set）。

世界（Σ）

• 卡 = 子 agent 的 prompt 载荷（SKILL.state：只给卡 + 状态摘要，不给整段历史）。卡里没写的，实现者 不知道；所以 notes 要自包含，不引用对话。
• REQ 一卡一主：每个 REQ 只能归一张卡（重复归属 = 两个实现者改同一行为）。AC 子集从 done_when.acceptance 按 req 取。
• 文件级存在性在卡里，不在契约里（C2）：allowed_files 是白名单执行器（verify_commit.py --card）的输入； forbidden_files 默认继承 done_when.constraints.forbidden_paths + tests/** + 锁文件。
• 共享文件（lockfile / 配置 / 路由表 / schema）要么归一张卡，要么全部禁改——"卡间无写冲突"必须覆盖它们。
• 卡级验收 ≠ 需求级验收：每张卡只跑 AC 子集；所有卡完成后必须整体跑一次（/acceptance-fleet）。
• depends_on 只表示依赖顺序（Σ 第 1 格），不是执行脚本；无依赖的卡可并行。
• 投影与其数据源同卡：渲染 / 报告脚本与它读的数据在一张卡里，否则没人能原子地同时改数据的形状与它的 标签。跨卡是例外，例外要 reads_from + depends_on + notes 里的接缝风险三样齐全（lint 项 6）。
• 上下文预估：卡 + 相关源码 + AC 子集 + 测试 > 40k → 必拆（lint，不是备注）。
• 这条 40k 会反压契约：一个 REQ 的实现读集若超 40k，"REQ 一卡一主"与"≤ 40k"同时成立就无解。 G2 冻结前就要按分区把这类 REQ 拆开；G2 之后再拆要走变更提案 + 重新签锁。
• 关于用户的 Σ："拆细一点"= 上下文预算更小，不是更多卡；"一张卡做完"= 合法，但仍要过 lint。

判据（φ）

• lint_cards.py 三项 + 上下文 + ac_ids 存在性 + allowed_files 非空 + 投影/数据源同卡 → 全过。
• 残差（人 / judge）：卡是否真的自包含；allowed_files 是否最小；上下文预估是否诚实。

原语（Π）

• scripts/lint_cards.py <cards_dir> [--spec spec.md] [--done-when done_when.yaml] [--dos dos.yaml] [--require-dos] [--max-context N] [--repo-root DIR] [--projection-pattern RE] —— --require-dos 把"dos_slice 闭包未检"从一条 info 升成 reject，并在没给 --dos 时自动发现 项目里的 dos.yaml（../ai-dlc/scripts/repo_assets.py）。M / L 档带上它：卡里出现一个本体 解析不了的名词是整条流水线上代价最高的一次漂移，而"没算过"和"算过且通过"在旧输出里长得一样。 —— exit 0 / 1 / 2。进 implement 前必须跑；aidlc_state.py set cards.dir=cards 后 advance implement 会再跑一遍并记 cards.lint_passed（它不可 set：一个引擎 set 的布尔是执行者的说法）。 给 --repo-root 时会读渲染脚本本身核验 reads_from，声明因此可核验而非自述。
• ../dos-extract/scripts/verify_vocabulary.py --dos dos.yaml cards/CARD-*.yaml —— B 档术语传感器。 lint_cards.py 的第 3 项只闭包 dos_slice.objects / dos_slice.invariants（结构化字段，作者主动列出来的）； 卡的 title 与 notes 是散文，从来没人检——而实现者拿到的全部输入就是这张卡， 卡里出现一个本体解析不了的名词，是整条流水线上代价最高的一次漂移：实现者会自己给它挑一个意思， 而这个意思要到验收才对得上。两者不重叠：结构化归 lint_cards.py（拒），散文归传感器（告警）。 exit 0 / 1（超阈值）/ 2（IO）/ 3（没有 dos.yaml = 未检，不是通过；--require-ontology 变 1）。
• assets/card_template.yaml —— 卡的具名字段。
• references/splitting.md —— 拆分启发式（按观察边界 / 按 DOS 对象 / 先契约后 UI / 投影与数据源同卡）、 共享文件处置、上下文估算法、以及 L4 对契约层 REQ 粒度的反压。