four-state-ratchet plugins

by XRenSiu

AI-DLC — 一条产研自闭环的软件开发流水线，做成 Claude Code 插件：世界 → 本体 → 契约 → 标准 → 计划 → 实现 → 验收 → 交付 → 学习，每一步的产物要么能被脚本检，要么被一道只能人签的门挡住，没有第三种。30 个 skill 组织成九环 + 一根脊柱（docs/ARCHITECTURE.md）。 三条主线。**上半段建世界**：/psl 把体验性需求写成六层 Product Specification Language，/psl-derive 推出 DOS 提案 / workflow / 形态草案（每条决策引用一个 PSL-ID）并用 N 次隔离推导的分歧集当 G1 议程。**下半段收敛交付**：/issue → /donewhen-extract（或 /acceptance-spec）→ G2 哈希冻结判据 → /plan-cards 切成自包含任务卡 → /implement 隔离实现 + /commit 三道闸 → /acceptance-fleet 并行派发六个审查 skill → /meta-judge 合成四态棘轮 → /pr → /review-loop（评论当待验证主张）→ /release → 归档。**横切**：/dos-extract 与 /invariant-extract 管本体与不变量，routing.yaml 管失败按层回流与分层预算，/retro 与 /tune 管度量与环参数。 设计上不肯让步的几条。**路由确定化，质量交给模型**：状态机、路由表、执行图、六个环契约全是数据，由脚本强制，引擎只提议——`aidlc_state.py advance` 对着状态检前置条件，不对着模型的说法检。**判据先于代码且冻结**：done_when.yaml v2 是唯一契约 schema，G2 签它、L5 再签一次测试，之后改锁内文件必须附变更提案。**评估者与被评估者分离**：实现者只见卡 + AC 子集 + 红基线，看不到评审判据与隐藏集。**声明了但没求值 ≠ 通过**：分析器跑不了退出 3，审查没跑完记为 unevaluated，两者都不许报绿。**失败归层不原地重试**：同指纹两次、震荡、平台期分别路由到方案层或任务层，预算耗尽写失败报告交人。**账本只增不删**：产物可回滚，判据与失败记录不回滚。**三道门只能人签**：G1 世界裁决 / G2 判据冻结 / G3 例外复核，`--autopilot` 与自治阶梯都不代签。 v1.0.0 起流程按三个正交旋钮伸缩（借鉴 AWS AI-DLC 2.0 的 scope grid，见 docs/reports/aidlc-gap-2026-09-07.md）：**广度**是 sizing.yaml 的阶段网格，由 next_allowed / prereqs 强制、verify_sizing.py 九条 lint 核验，never_skippable 把三道门挡在旋钮之外，跳过要用可数的证据换、每次写一条带理由的账本行；**测试量**是下界，derive_counts.py --strategy 检，低于地板退出 4；**深度**只是声明，因为没有脚本能判「这份文档够不够细」——文档如实标注，不假装它是闸。同版新增解释日记（notes.md 四格：Interpretations / Deviations / Tradeoffs / Open questions，门禁前逐字呈现不筛选，Open questions 不晋升，晋升的规则下一次 init 才编译进去）、审查完成度闸 verify_review_complete.py、跨制品术语传感器 verify_vocabulary.py（B 档）、自治阶梯 autonomy、启动前算有效规模的 plan、装置健康度 doctor。 证据等级诚实登记：全部 skill 为 static_only —— 结构过审 + 脚本在 fixture 上冒烟（条数以 `eval/smoke.sh` 结尾行为准，不手抄；关键行为配变异证明），**带 / 不带这套纪律的行为层对照只跑过一轮十题**，且出题人与被测者同源。能说什么、不能说什么写在 docs/evaluation.md。 v1.6.0（2026-09-12）按「它是不是一条闭环」重读一遍，修了七处声明与代码不一致：逃逸缺陷有了登记入口（`aidlc_state.py escape`：计到归因层、追加 escape-defects.md、镜像进归档——此前没有任何命令写 escape 事件，复盘的逃逸率结构上永远是 0）；`meets_done_when` 由 `meets_done_when.py` 比对阈值得出且不可 set（R010 从 not_enforced 变 system）；`advance` 对着文件检不对着 flag 检（implement 自己跑 lint_cards.py、pr 读 final-state.json、archive 读 post-deploy 行、四个阶段重验锁）；`card_retries` 按卡计不按层计；`--evidence` 先归一化再取指纹；M 档的两人审查子集只认推导来的档位；红→绿证据有了另一半（`verify_red_green.py`：消失的红测试算不绿）。同版第二遍按「没有断点」再走一次每个阶段的前置：G2 的裁决在 implement 再查（S 档跳过 cards 不跳签字）、l5 锁与红基线是 implement 的前置、红→绿证据与锁历史回放是 pr 的前置、校准报告按档编译进 acceptance、评审出口读 pr-poll 写的裁决文件、merge.sha 与 release.tag 问 git、契约有 human AC 时 G3 关不掉。冒烟主链跑在一个真的 git 仓库里。 v1.7.0（2026-09-15）把插件放进一个真实团队仓库（Electron 桌面端，自带 harness）用了一遍，修了九处「默认假设和人家的仓库对不上」：`verify_pr.py --sections` 把 PR 语义槽映射到团队自己的模板（槽键封闭集、豁免要理由且逐条 flag、issue 链接 / 验证 / AC 映射只能挪不能免）；同步检查的远端与 base 由跟踪分支和 `<remote>/HEAD` 解析，多远端无跟踪时记跳过而不是去比 origin；契约新增 `constraints.test_globs`，`advance g2` 带 `--repo` 检 forbidden_paths 是否真盖住了仓库里的测试文件（就近放 `*.spec.ts` 的仓库里 `tests/**` 一条都盖不住）；`verify_release.py --scheme semver|calver|external`，SemVer 不再接受前导零；`doctor` 报会话里装的插件版本是否落后、宿主里与子 skill 同名 / 近名的 skill；scope 目录不存在时说出来；`verify_agent_map.py` 核对 `file:` 来路（文件在、行号不越界、`#"原文"` 仍逐字在源文件里）。每条都有正反两面的冒烟期望和变异证明。 v1.10.0（2026-09-15，随 1.9.x 一起发）在 vana-builder 上真跑 /dos-extract 时，`inventory.py` 把 478 个 Vue 单文件组件扫成了零、把 spec 文件里的 mock 与全大写常量当成名词，而报告对此一声不吭：现在读 SFC 的 `<script>` 块，测试文件默认跳过并计数（`--include-tests`），常量进剪枝组，没有提取规则的语言按扩展名报「not scanned」。同一轮起草 agent-map 时发现 `verify_agent_map.py --probe` 会照跑一条清空本机应用数据的 E2E 命令：期望列 `no-probe: <理由>` 的行跳过并记 flag，理由必填，全套测试不许。probe 前比对 `.nvmrc` / `.node-version` 与当前 Node，不一致时出 flag 并在失败条目里提示先排除环境（vana 的 `npm test` 在 Node 25 上全挂，22.23.2 上 3147 条全过）。v1.11.0（2026-09-20）堵上「直接说冻结」这个口子：一张带未裁冲突的不变量卡，`lock_done_when.py sign` 原本照签不误、退出码 0——草稿该有的未决项被当成已定的法冻上了。现在 `verify_card.py --ready-to-sign` 把未裁的冲突 / 没人裁过的低置信条目 / 未过存活测试的条目从「草稿的未决项」升成拒并点名；`sign` 按形状认出不变量卡（有 `territory_id` + `hard_invariants`）自己去跑它，不过就拒签，`--force-unresolved --reason` 强签时把理由与未决项清单写进锁——一个没写下来的例外，和一次疏忽长得一模一样。 v1.12.0（2026-09-20）加第 30 个 skill `/ratify`：V-15 让 `sign` 拒签带未决项的卡之后，缺的是把人**带过**这段仪式的东西——用户原话「还是需要 skill 的吧？不然我怎么同意呢？我不想手打命令」。纪律：未决项由 `agenda.py` 从**文件**里逐条读出呈现（不做有趣度筛选，同 notes --for-gate）、一条一条当场裁、裁决盖姓名与日期写回、再跑一次判据、最后才签；拖延（待定 / TBD）被脚本拒——它不是坏答案而是另一个去处（进 open_questions 带负责人）。签字只有两种身份：人自己签，或**受委托签署**且把人的授权原话写进锁文件；模型以 human 身份签字是伪造签名，不是省事。 前身叫 sdlc，2026-09-08 改名；归档目录与历史报告保持原样未改写。

by XRenSiu

Done_When Pipeline v1.0 — turn fuzzy natural-language requirements into machine-verifiable completion contracts, then run a multi-agent acceptance loop against an implementation. Nine skills in a two-layer topology (per HTML v2 architecture). Layer 1: TWO contract producers + SIX independently-invocable review skills — `/acceptance-spec` (NL → EARS spec + done_when.yaml with existence/behavior/rules schema + spec-robustness.md anti-gaming companion), `/test-suite-generator` (EARS → 5-layer test pyramid: existence/unit/integration/e2e/mutation; the v0.x fitness rubric layer was retired per HTML v2 §3.5 fitness-check dissolution), and six review skills each user-invocable on their own: `/code-reviewer` (diff → findings, focus-driven: security/logic/perf/style/all; Detective Loop not flowchart; 5-finding cap; cross-vendor adversarial mode), `/qa-reviewer` (actually runs tests, classifies maintenance-vs-genuine failures, emits go/no-go), `/pm-reviewer` (Agent-as-Judge: LOCATE/READ/RETRIEVE atoms; requirements normalized from EARS/Jira/Linear/PRD/issue; 4-state TicketCompliance verdict where requires_human_verification is the formal home for genuinely-unautomatable evaluation), `/spec-drift-detector` (code archaeologist: detects spec/code factual divergence without judging which is correct; git_blame traces commit_introducing_drift; 3 divergence types: timing/behavior/contract), `/spec-gaming-detector` (assumes author is gaming; 6 RHD patterns absolute + diff mode; outputs spec_robustness_gaps for contract hardening), `/meta-judge` (synthesizes findings via 4 actions: dedupe/weight/arbitrate/classify; HARD WALL — does NOT re-review code; pluggable rules source). Layer 2: `/acceptance-fleet` is pure orchestrator — dispatches the 6 review skills in parallel against an impl, hands findings to /meta-judge, decodes verdict into four-state ratchet (DONE/FIX/SPEC_DRIFT/GAMING_RISK), persists every iteration to ratchet-log/iteration-NNN/. Anti-gaming structural guarantee: implementation agents MUST NOT see evaluator prompts; minimum medium isolation (mixed Claude sizes) enforced; cross-vendor (Codex/Gemini) preferred for adversarial-reviewer and spec-gaming-detector to break the Claude-reviewing-Claude sycophancy loop per Milvus benchmark. Borrows: PR-Agent diff schema + TicketCompliance 4-state; Greptile v3 Detective Loop; Anthropic Code Review verification step + fleet-by-focus; DevAI Agent-as-Judge (LOCATE/READ/RETRIEVE); Playwright Healer maintenance-vs-genuine; Dartmouth/Yale Meta-Judge (replaces multi-agent debate); 4-Eyes Principle from finance; Weaver framework for weighted weak-verifier ensemble; Komorebi AI Specification Self-Correction. Design philosophy: verifiable beats judgeable (even for things that feel subjective); debate amplifies bias (use meta-judge synthesis, not debate); independence-by-default (each review skill works standalone — done_when.yaml is just one of its consumers).