Dverity 5.0 Truth-to-Main transformation spec

[Dimon94]

Source map #56: #56

Post-discovery route: needs-spec

Next gate: tickets

Canonical resolutions:

• Topology and workflow authority: Define Dverity public routes and internal gates #60 (comment)
• Brand inventory and migration risks: Inventory Dverity brand migration surfaces #61 (comment)
• Final compatibility and release policy: Choose the cc-devflow compatibility and release policy #62 (comment)
• Canonical 55-ID acceptance contract: Define transformation acceptance evidence #63 (comment)
• Supporting disposition, overlap, and handoff evidence: Audit the Dverity skill disposition #57 (comment), Map remote-review contract overlap #58 (comment), Choose the Wayfinder to Dverity handoff #59 (comment)

R62 is final and supersedes earlier intermediate compatibility and physical-Skill-count judgments. The target is exactly nine Skills and only .agents / .claude projections.

Problem Statement

cc-devflow 的现有产品边界、Skill 拓扑、remote-review ownership、安装投影、机器身份和发布流程分散在旧实现与多份 discovery resolution 中。虽然 #57–#63 已消除产品和架构未知项，但 implementation tickets 仍缺少一份共同的 scope truth source，容易重新引入以下问题：旧 feature-control-plane 职责混入 Dverity、重复的 diagnosis/review/landing 状态机、多个 Skill 或 host inventory 真相源、缺乏 ownership 的迁移与删除、以及在 provider 或 registry truth 未确认时产生 false-green。

用户需要把该产品线一次性转型为 Dverity 5.0：Display brand 为 Dverity，promise 为 Truth before main.，唯一产品链为 Truth-to-Main。这次 transformation 必须保持 frozen decisions，不以兼容层、隐藏 alias、第二 acceptance matrix 或猜测 live provider 状态来换取表面上的平滑迁移。

Solution

发布一次 breaking Dverity 5.0 transformation：GitHub identity 目标为 Dimon94/dverity，npm identity 为 dverity@5.0.0，CLI 为 dverity。产品只保留三个 workflow entries：dverity-repair、submit-remote-review、merge-remote-review；再加六个 reusable dependency Skills：do-not-repeat-yourself、postmortem、dverity-research、dverity-simplify、git-commit、resolving-merge-conflicts。

根目录 skills/ 是唯一 Skill source。安装只产生 .agents/skills 与 .claude/skills 两个 exact-set/hash projection；其他 host adapters、outputs、flags 和 current documentation 全部移除。根目录 DVERITY.md 是唯一完整 Truth-to-Main chain contract，其他文档和 Skills 只能引用它或描述局部责任。

用户 CLI 仅提供显式 scope 的 install、migrate、verify、uninstall，以及 help/version。Breaking migration 使用 journaled transaction；每个 install root 由唯一 .dverity/managed-skills.json 证明双 host projection 的 package/source provenance、exact set、per-file hashes 与 transaction state。Runtime 只读写 .dverity 与 DVERITY_*，没有 legacy alias window。

Truth-to-Main 固定为 Repair → Verified Local → Submit → Review Ready → Merge → Verified Remote Main。Repair 默认本地终止；远程 mutation 需要明确 scope authority；Independent Review 是 Merge 内部的 fresh、read-only、head-bound mode/reference，不是第四个 Skill。GitHub/GitLab 通过 provider-neutral record 归一化，任一 required truth 为 pending、unknown 或 stale 都 fail closed。

Release 只从一个 frozen commit/artifact 推进：repo-first rename、authenticated npm publish/readback、fresh install/host discovery、current docs、approved downstream allowlist，最后才对旧 cc-devflow 做 metadata-only deprecation。Authenticated registry readback 是 point of no return；之后只允许 immutable fix-forward。

User Stories

1. 作为 Dverity 用户，我希望所有当前产品表面都显示 Dverity 和 Truth before main.，从而清楚理解产品身份与承诺。
2. 作为工程师，我希望只看到一条 Truth-to-Main 产品链，从而无需在多个相互竞争的流程图中判断当前阶段。
3. 作为 Bug 修复者，我希望从 dverity-repair 进入 tight red loop、最小化、kill probe、Injection 与回归证明，从而得到证据驱动的修复结果。
4. 作为 Bug 修复者，我希望 Repair 默认终止于 Verified Local，从而修 Bug 的请求不会暗中获得 push 或 PR/MR 权限。
5. 作为明确要求远程交付的用户，我希望一次授权即可把 verified repair 提升到 Submit，从而不被重复询问同一 authority。
6. 作为 Wayfinder 编排者，我希望把 named、clean、verified、ahead 的 integration branch 交给 Submit，从而在清晰边界停止 discovery 和 implementation orchestration。
7. 作为提交者，我希望 clean-but-ahead branch 被识别为待交付工作，从而 clean worktree 不会被误判为没有变化。
8. 作为提交者，我希望每次 Submit 只创建或更新一个明确的 review item，从而避免重复 PR/MR 和隐式批量 mutation。
9. 作为恢复现有远程工作的用户，我希望 Submit 复用同一 source 的既有 review item，从而恢复路径不会制造 duplicate。
10. 作为仅要求发现远程状态的用户，我希望未指定 item 时保持只读，从而 discovery 不会扩大为 mutation authority。
11. 作为合并者，我希望 Merge 只接受 authenticated provider-native review item，从而 bare branch 或模糊 task 不会绕过 review gate。
12. 作为 reviewer，我希望 Independent Review 绑定 provider、repo、item、head 和 fresh task/session，从而 verdict 只对精确代码头有效。
13. 作为合并者，我希望 material head change 自动使旧 verdict stale，从而旧批准不会被静默复用。
14. 作为合并者，我希望只有完整证明 semantic no-op 的 rebase 才生成新的 carry-forward record，从而 freshness 例外可审计。
15. 作为冲突处理者，我希望只在产品意图可证时调用 conflict resolution，从而 Merge 不会为了完成 rebase 发明行为。
16. 作为 GitHub 或 GitLab 用户，我希望 provider 差异只存在于 adapter evidence/mutation 层，从而两种 provider 共享同一产品生命周期。
17. 作为交付负责人，我希望 Verified Remote Main 分别证明 provider merged state、target、tracking ref、local target、active worktree 和 post-merge checks，从而 merged 不会冒充完整 parity。
18. 作为 issue 维护者，我希望 closeout 只作用于直接完成的 issue，并在 merge 后读回，从而 parent、sibling 或 blocker 不会被递归误关。
19. 作为 Skill 用户，我希望物理 Skill exact set 始终恰为九个，从而旧 control-plane shell 或隐藏入口不会复活。
20. 作为 Skill 维护者，我希望 workflow entries 与 reusable dependencies 的职责唯一，从而内部 gate 名称不会膨胀成额外 Skills。
21. 作为构建维护者，我希望 Skill inventory 只从根 source 枚举一次，从而 package、registry、installer 和 projections 不会维护平行 allowlist。
22. 作为安装者，我希望 .agents 与 .claude 都来自同一 frozen artifact，从而任一 projection 都不会成为 source 或反向污染另一 host。
23. 作为 release owner，我希望真实 Agent-Skills host 与 Claude Code 都能发现并读取 artifact-matching Skill，从而 filesystem copy 不会冒充 host success。
24. 作为 CLI 用户，我希望只看到 install、migrate、verify、uninstall 与 help/version，从而旧 control-plane 命令不会形成兼容后门。
25. 作为 CLI 用户，我希望 global/project scope 必须显式且互斥，从而工具不会猜 cwd 或扫描整台机器。
26. 作为首次安装用户，我希望 install 只在 fresh root 建立 exact set，从而 legacy-owned 或 unknown state 不会被覆盖。
27. 作为旧版本用户，我希望 migrate 通过一个 journaled breaking transaction 完成切换，从而旧/新状态不会混杂。
28. 作为迁移用户，我希望每个 mutation edge 都可 fault-inject 并逆序补偿，从而失败后只剩完整旧状态或完整 Dverity 状态。
29. 作为迁移用户，我希望成功后重跑 deterministic no-op，从而重复命令不会产生 timestamp 或内容 churn。
30. 作为验证者，我希望 verify 严格只读并能定位 missing、drift 与 unknown，从而检查不会通过偷偷修复制造假绿。
31. 作为卸载用户，我希望 uninstall 只删除 manifest+hash-proven projections，从而 config、human evidence 与 unknown files 被保留。
32. 作为安装根所有者，我希望一个 manifest 同时证明两个 host projections，从而 per-host marker 不会产生 ownership drift。
33. 作为同时使用 global/project 安装的用户，我希望命令只影响明确 root，从而 cross-root、outside sentinel 与 unrelated Skills 保持 byte-identical。
34. 作为运行时用户，我希望新 runtime 只读取 .dverity 与 DVERITY_*，从而 zero alias window 是真实行为而非文档声明。
35. 作为历史数据所有者，我希望已知 postmortem/research 数据可事务迁移，而 devflow/changes 与 unknown data 原地保留，从而迁移不会破坏不可判定的历史。
36. 作为文档读者，我希望 DVERITY.md 是唯一完整 chain contract，从而 README、Skills 与 migration docs 不会演化出第二状态机。
37. 作为验收维护者，我希望 55 个 acceptance IDs 只存在于一个 machine-owned catalog，从而 Jest、validator、CI 与 release runbook 不会各自维护 required-check truth。
38. 作为 release owner，我希望一个 generated acceptance packet 汇总 freshness、authority、evidence refs 与 mutation readback，从而发布结论可审计且不可手工美化。
39. 作为安全审阅者，我希望 acceptance outcome 没有 skipped，并让 unknown/pending 阻止 roll-up，从而 live gate 不会被降级为不适用。
40. 作为发布者，我希望一个 commit 只对应一个 frozen tarball/provenance，从而源码验证与实际发布字节不会分叉。
41. 作为仓库管理员，我希望 repo rename 在 npm publish 前完成并完成 authenticated readback，从而新包指向已验证的 canonical repository。
42. 作为 npm 用户，我希望 registry authenticated readback 定义 point of no return，从而 rollback 与 fix-forward 边界明确。
43. 作为故障响应者，我希望 PONR 后只通过新版本 fix-forward，从而不会 unpublish、重写 tag 或回滚已公开身份。
44. 作为 downstream 维护者，我希望只有显式 allowlist、authenticated target 和本地 ownership proof 都成立时才同步，从而 search result 或 README 文本不授予 mutation authority。
45. 作为批量同步观察者，我希望每个 downstream 独立报告 success/fail/blocked/unknown，从而一个成功项不会掩盖其他失败。
46. 作为历史审计者，我希望旧 CHANGELOG、ADR、tags、tasks 与 evidence 保持原文，从而 transformation 不会改写过去。
47. 作为法律与社区维护者，我希望 current license notice 为 Copyright (c) 2025 Dimon，并删除无 replacement 的聊天群 surface，从而当前品牌表面符合冻结决策。
48. 作为旧 npm 用户，我希望 cc-devflow tarballs 继续可用于历史 lockfile，同时 deprecation 只在 Dverity end-to-end 可用后发生，从而升级指引不会提前断路。
49. 作为 implementation agent，我希望 live provider/name/host/downstream facts 都是 fail-closed gates，从而实现不会通过猜测改变 namespace、scope 或 authority。

Implementation Decisions

1. 产品身份采用 immediate breaking Dverity 5.0 transformation；没有 legacy Skill、CLI、config、env 或 path runtime compatibility window。
2. 物理 topology 固定为三个 workflow entries 与六个 reusable dependency Skills；内部 gate、mode、reference、script 或 runbook 不得提升为第十个 Skill。
3. Workflow Chain owner 只有一个；三个 entries 是 phase owner/selector，不能各自拥有平行 Visible State Machine。
4. Repair 独占 diagnosis/repair/regression loop，默认终态为 Verified Local；remote promotion 和 local-target integration 都需要各自明确 authority。
5. Submit 独占 source scope、clean-ahead proof、push、单一 review item create/update 与 Review Ready readback；不得 approve 或 land。
6. Merge 独占 authenticated review item、fresh Independent Review、live-target integration、landing、closeout result 与 remote-main parity；不得从 bare branch 直接 land，也不得在原 authority 下修产品代码。
7. Independent Review 是 Merge 所消费的 fresh、read-only、head-bound record；head material change 默认使其 stale，semantic no-op carry-forward 必须生成新的 auditable record。
8. Provider-neutral remote model 统一 identity、auth、capability、review blockers、CI、mergeability、queue/protection、closeout intent 与 mutation scope；provider adapter 只负责字段映射、readback 和受权 mutation。
9. Reroute 规则固定：confirmed defect 到 Repair；feature、requirement 或 product-intent gap 到外部 Wayfinder/executor；ambiguous conflict 或 required truth 缺失直接 blocked。
10. Source/Inventory seam 只允许一次 canonical enumeration，并向 package、registry、installer plan 和两 host projections传递同一 provenance；任何二级 allowlist 都是错误设计。
11. CLI/Migration seam 采用四个 user lifecycle commands、严格显式 scope、safe path boundary 与 journaled transaction；错误输入和 failed preflight 必须 zero mutation。
12. Host/Ownership seam 由每个 install root 的唯一 ownership manifest 管理两个 projections、exact set、per-file hashes、artifact/source provenance 与 transaction state；目录名本身从不证明 ownership。
13. Runtime namespace 只采用 Dverity config/env/schema；legacy surface 仅能被 one-time migrator 作为 bounded input 读取，不能进入运行时 precedence。
14. Durable human evidence 只在真实 trigger 下进入 postmortem/research records；未知历史数据、外部 shell/CI/env references 与 manifest 外文件保持 Unknown 并原地保留。
15. Acceptance architecture 只有一个 machine-owned catalog、每 ID 一个 owner/executor，以及一个 generated roll-up packet；它们不取代 Skill source、provider truth 或 install ownership truth。
16. Release seam 从一个 frozen commit/artifact 单调推进：repo identity verified、exact artifact published/read back、fresh installs/hosts、current docs、approved downstreams、legacy npm deprecation last。
17. Authenticated registry readback 是 identity PONR；此前允许停止并按 runbook 回滚 repo identity，此后只允许 immutable fix-forward。
18. Cross-repository mutation 只接受显式 managed-downstream allowlist 和每个目标 root 的独立 ownership proof；默认计划为空且零 network/file mutation。
19. Historical records保持原文；current brand/legal/community surfaces按 Dverity 决策更新，且不创建新的聊天群替代物。

Testing Decisions

Canonical test truth 是 #63 的 55 个稳定 acceptance IDs：https://github.com/Dimon94/cc-devflow/issues/63#issuecomment-4936916586。本 spec 只批准并分组 seams，不复制 acceptance matrix、predicate 或命令清单。

好测试只验证可观察合同：terminal state、exit code、provider readback、filesystem before/after digest、artifact/provenance、host discovery、authority call audit 与 freshness。不得以 Markdown 关键字、目录存在、mock 的单一 mergeable 字段或命令 exit 0 代替行为证据。

用户已批准以下五个 implementation/testing seams：

1. Source/Inventory seam：root Skill source → package exact 9 → registry/projection provenance。以 DV-SRC-001 为入口并由 DV-SRC-*、相关 DV-DOC-*、DV-LEG-* 与 DV-SIM-* 验证唯一 source、dependency closure、active/history 分类和无 legacy reachability。
2. CLI/Migration seam：install/migrate/verify/uninstall explicit scope → journaled transaction → zero-mutation/fault-injection。由 DV-CLI-* 与 DV-MIG-* 覆盖 happy、invalid scope、idempotence、every-edge failure compensation、new-only runtime namespace 与 durable-data preservation。
3. Host/Ownership seam：单一 install-root manifest → .agents/.claude real discovery → exact-set/hash/cross-root safety。由 DV-INS-* 与 DV-OWN-* 验证 artifact parity、真实 host readback、drift、unknown ownership 和 root isolation。
4. Truth-to-Main seam：Repair/Verified Local/Submit/Review Ready/Merge/Verified Remote Main。由 DV-REP-*、DV-SUB-*、DV-REV-*、DV-MRG-*、DV-REM-* 覆盖 authority、clean-ahead、head freshness、provider-neutral scenarios、reroutes、closeout 与 parity。
5. Release seam：one frozen commit/artifact → repo-first rename → npm authenticated readback PONR → downstream/deprecation last → fix-forward。由 release/current-doc/downstream ID families 验证单调顺序、immutable bytes、live readback、failure frontier 与 final roll-up。

这些 seams 不是五个新 Skills、五个状态机或五份真相源；它们只是 implementation slice 与 test ownership 的最高层边界。

实施时只建立一个 acceptance/catalog.json 作为 ID/predicate catalog，以及 runner 生成、不可手工编辑的 dverity-acceptance-packet.json。Catalog 不得被 installer、registry 或 package 用作 Skill inventory source。Jest、publish validator、CI 和 release runbook 只能注册/消费 catalog result，不得维护第二份 required checks。

Packet 没有 skipped outcome；所有 required rows 必须 pass，且 fail/blocked/unknown/pending 都为零。Source/build evidence 绑定 source commit 与 artifact hash，root operation 绑定 before/after root snapshot，remote review 绑定 provider/repo/item/head/session，live release 绑定 actor/token scope/timestamp/current readback。

测试层级沿用 #63：CI predicates、disposable temp roots/repos、recorded provider fixtures，以及 named disposable GitHub/GitLab and real-host live gates。Live smoke 不在用户生产 item 上试错。

可复用 prior art 仅限现有 publish validator、Skill inventory parser、hash/drift primitives、temp-root CLI fixtures、remote-review contract vocabulary、postmortem/simplify invariants。它们必须迁到新 contract；旧 cc-devflow allowlist、ownership 语义或 Markdown-presence assertions 不能直接算通过。

Out of Scope

• 在本 spec gate 中实现代码、创建分支、提交、push、PR/MR、repo rename 或 npm publish。
• 在本 spec gate 中拆 implementation tickets；ticket slicing 是下一门禁。
• 把 discovery、spec、ticket splitting 或 feature implementation orchestration 纳入 Dverity；这些仍属于外部 Wayfinder/executor。
• 把 Independent Review 暴露为第四个 workflow entry，或新增平行 diagnosis/review/landing 状态机。
• 保留任何 cc-* Skill ID、legacy CLI handler、router、alias、warning stub、hidden trigger 或 cc-devflow@5 bridge。
• 支持 .codex、.cursor、.qwen、旧 .agent 或其他 host adapters/projections。
• 安装 pre-commit hook infrastructure，或恢复 quality-gate-contract、setup-pre-commit 作为产品 Skills。
• 自动修改 manifest 外 shell profile、CI secret/env reference、unknown same-name Skill、search-only downstream 或未获授权 provider item。
• 重写历史 CHANGELOG、ADR、tags、tasks、postmortems、research 或其他 durable evidence。
• 与 Dverity transformation 无关的功能增强、清理或代码现代化。

Further Notes

• R62 是 compatibility/release final owner；任何早期 15/23-Skill、兼容窗口或 host 判断均被其 supersede。
• Exact Skill set 是：dverity-repair、submit-remote-review、merge-remote-review、do-not-repeat-yourself、postmortem、dverity-research、dverity-simplify、git-commit、resolving-merge-conflicts。
• Root skills/ 是唯一 source；.agents/skills 与 .claude/skills 是唯一 supported projections；.dverity/managed-skills.json 是每 install root 的 ownership truth。
• DVERITY.md 是唯一完整 Truth-to-Main contract；migration docs、README 与 Skills 必须只引用它或表达局部责任。
• Repo target 是 Dimon94/dverity；package target 是 dverity@5.0.0；release order 是 repo-first；authenticated registry readback 是 PONR；PONR 后采用 fix-forward。
• Copyright 冻结为 Copyright (c) 2025 Dimon；current chat group/QR surface 删除，不提供 Dverity replacement。
• 产品/架构未知项为零。Repo slug、npm ownership/auth/provenance、真实 host discovery、downstream approvals 与当时 provider behavior 是 implementation-time live gates；失败时 blocked/HITL，不得静默改 scope。
• 用户已在 spec gate 真实回答 A，批准 Source/Inventory、CLI/Migration、Host/Ownership、Truth-to-Main、Release 五个 seams 原样进入本 spec。
• 本 issue 是 implementation tickets 的唯一共同 scope truth source；resolution comments 保留调查证据，Define transformation acceptance evidence #63 保留 canonical acceptance predicates。
• Post-discovery route 是 needs-spec；本 issue ready 后下一门禁是 tickets。