docs(ffx): Phase 3.12 信息架构重构 —— 四层拆分 + 目录迁移 + canonical 文档

[Thy985]

改动说明（what + why）

Phase 3.12 信息架构重构（2026-08-27，按 Owner 批准的 INFO-ARCHITECTURE-DESIGN + MIGRATION-MAP 执行）。
目标：把 docs/ 从"文件名罗列"升级为四层信息架构——人类入口 / 工程真相 / 历史档案 / 机器资产；
新人类贡献者与新 Agent 不读历史 RUN/AUDIT 即可获得正确当前状态，追溯时沿引用回到原始证据。

一、目录迁移（L3 历史归档，git mv 保留历史）

• ADR 29 篇：docs/ADR/ → docs/decisions/ADR/（内容不动）
• RUN 报告 35 篇：docs/runs/ → docs/archive/runs/（phase3.11×16 + adl×12 + dogfood×7）
• 顶层重复副本 16 个删除（D2 决策：PR feat(ffx): Phase 3.11 Capability Hardening Loop 收口 + PHASE_3_11_EXIT 判定通过（E6/E8 视觉语义验证 + 真机证据） #164 顶层副本与 archive/runs 内容一致，已验证 100% 相同）
• audits×8 → archive/audits/；spikes×4 → archive/spikes/；investigations → archive/investigations/
• old-designs×2 → archive/old-designs/；governance×4 → archive/governance/
• backlog → decisions/REVIEW-BACKLOG.md

二、工程真相分流（L2）

• product/：PRODUCT / UX-GUIDE / TYPORA-GAP-ANALYSIS / CAPABILITY-STATUS-source-*
• architecture/：ARCHITECTURE / EDITOR-MODEL / EXPORT-MODEL / AGENT-ENGINEERING / UI-COMPONENT-MODEL / UI-INTERACTION-MODEL / UI-ARCHITECTURE
• engineering/：ENGINEERING-BASELINE / GATE-REPORT / DEVELOPMENT-RULES / GIT-WORKFLOW / WORKFLOW / QA-PIPELINES / CLI-VERIFICATION-STATUS / FUNCTION-AUDIT-STATUS
• decisions/：INDEX（ADR 状态表）+ ADR/

三、canonical 文档（新增，L2/L4）

• product/CAPABILITY-STATUS.md：能力完成度（人类视图，机器视图在 contracts/）
• architecture/EDITOR-MODEL.md / EXPORT-MODEL.md：架构真相拆分（ARCHITECTURE 瘦身）
• engineering/VERIFICATION-POLICY.md：验证纪律（source-e2e/gap/skip 聚合）
• .agent/CURRENT-STATE.md：Agent 当前状态入口（Current State Truth）
• regression/：BUG-001~003 case 包（case.json + input.md + expected.json + README）
• evidence/：capability / visual / consumer 索引（vlm_corpus 因 ffx 硬编码引用保留原位）

四、门户重写（L1 人类入口）

• README.md：253 → 126 行（人类首页：产品/能力/状态/架构图/入口；导航与 ADR 索引拆出）
• docs/README.md：按阅读目的导航（新人 / 改代码 / 决策 / 验证 / 历史 五类读者）
• docs/INDEX.md / ROADMAP.md 路径同步

五、链接修复

• 511 个链接扫描；迁移断裂全部修复（旧名→新路径映射 + 层级修正，含 ADR 移入 decisions/ 后深度 +1）
• 剩余 5 个为既有/预期悬空：REPO_AUDIT_2026-08-25.md（AGENTS.md §14.1 已注明"未入库，引用暂悬空，待 Owner 补录"）+ phase3.1-verification-report.md（task-contract 未勾选交付物）

测试方式

• 自动：链接完整性脚本——511 链接仅 5 个既有/预期悬空
• 自动：ffx contract_sync.py 依赖的 root/contracts/*.json 路径未移动（验证保留）
• 手动：目录结构核对（ADR 29 / RUN 35 / 顶层仅 5 门户文件）

是否影响公共 API

• 否（纯文档 + 目录迁移，零代码改动）

是否更新文档

• 是（本次即文档重构本身；新增 INFO-ARCHITECTURE-DESIGN.md + MIGRATION-MAP.md 作为设计与迁移记录）

自测清单

• 关联 issue：无（Phase 3.12 立项，见 INFO-ARCHITECTURE-DESIGN.md）
• 改动说明（what + why）
• 测试方式（自动 + 手动）
• 是否影响公共 API：否
• 是否更新文档：是
• 链接完整性：511 链接仅 5 个既有/预期悬空
• 机器资产路径未破坏（root/contracts/*.json 保留原位）
• 重复副本清理（顶层 16 个 RUN 与 archive 内容一致后删除）

备注

• push 按 AGENTS.md §11.3 既定做法 SKIP_PREFLIGHT=1（纯文档改动；analyze 无需跑）
• 迁移中一个事实一个 canonical source：历史完整矩阵/报告全部保留在 archive/ 可追溯，不删除任何工程事实
• 遗留待 Owner：REPO_AUDIT_2026-08-25.md 补录或改链（AGENTS.md §14.1 已有注明）；phase3.1-verification-report.md 交付后链接自然闭合

[github-actions]

Claude finished @Thy985's task in 2m 38s —— View job

---

架构评审报告（Level 3 Architecture Review）

PR: #174 — Phase 3.12 信息架构重构
审查级别: L3 架构评审
范围: 四层拆分 / 目录迁移 / canonical 文档 / 链接修复
变更: +1190 / −2798, 162 files

---

一、架构合理性 ✅

四层信息架构——L1 人类入口 / L2 工程真相 / L3 历史档案 / L4 机器资产——是一个清晰、合理、可扩展的纵切分层。

• 关注点分离：决策（decisions/）/ 真相（product/ + architecture/ + engineering/）/ 历史（archive/）/ 资产（contracts/ + regression/ + evidence/）互不污染。
• 三种 Truth 模型（Decision / Evidence / Current State）映射了文档生命周期，避免新人被 RUN/AUDIT 历史淹没。
• README → docs/README → product/architecture/engineering/decisions 的双入口与五类读者导航（首次了解 / 改代码 / 查决策 / 验证 / 追溯），与 AGENTS.md §0 的"阶段间空档期"约束一致。
• 双入口模型（人类 README vs Agent .agent/CURRENT-STATE.md）正确承接了 AGENTS.md §9 的协作流程。
• docs/README §"目录地图"用 ASCII 树形图可视化分层，对新人是低摩擦入口。

---

二、可扩展性 ✅

• 新增 L2 文档：直接落入 product/ / architecture/ / engineering/ / decisions/ 对应子目录，INDEX 自动同步。
• 新增 ADR：N+1 编号（保留 0026/0027 跳号 + 0025b 异常——皆历史继承，非本 PR 引入，已确认 main 上同样存在），INDEX 追加一行即可。
• 新增回归资产：regression/<capability>/BUG-NNN-<short>/（case.json + input.md + expected.json + README.md），格式契约已在 regression/README.md §原则定义。
• 新证据：vlm_corpus 因 ffx 硬编码引用保留原位（tools/ffx-cli/.../test_e8_structure.py:26）——evidence/README.md §"视觉证据"建立索引但不复制，机器资产路径不变（设计正确）。
• ADR-0029 ListElement 嵌套 AST（解决 BUG-5）等决策可继续冻结到 decisions/INDEX.md 状态表。

---

三、可观测性 / 证据等级 ✅

VERIFICATION-POLICY.md §"证据等级"显式列出 synthetic < test_runtime < production_runtime < virtual_device_runtime < physical_device_runtime < visual < human_confirmed——明确反对"Emulator PASS ≠ release gate PASS"。这是高水平的验证纪律文档化。

---

四、安全 / 容灾 / 性能 N/A

本次为纯文档 + 目录重构——零代码改动，零接口变更，零数据迁移（仅 git mv），无运行时影响。

• ✅ flutter_app/lib/ 未触碰
• ✅ contracts/*.json 11 个全部在 root/contracts/ 原位保留（contract_sync.py:133 / contract.py:36 / test_harness.py:22 / test_e8_vision.py:32 多处硬编码 repo_root() / "contracts"，无任何破坏）
• ✅ 无新引入敏感文件 / 凭据 / 全局状态

---

五、运维成本 ✅

• git rename 验证：ADR / RUN / 顶层文件 87–100% similarity 全部被 git 识别为 rename（而非 delete+create），历史 blame / bisect 不会断。
• 链接修复：511 链接扫描；剩余 5 个为既有/预期悬空（已正确归类）：
  • REPO_AUDIT_2026-08-25.md：6 处引用（AGENTS.md §14.1 / BRANCH_AUDIT_2026-08-25.md / PR-2/3/5_DESCRIPTION.md / 2026-08-12-git-governance-snapshot.md），文件未入库——AGENTS.md §14.1 已显式标注"⚠️ 该报告文件未入库，引用暂悬空，待 Owner 补录或改链"。这是 Owner 遗留事项，不是本 PR 的 regress。
  • phase3.1-verification-report.md：docs/contracts/phase3.1-task-contract.md:420 的待交付 checkbox（[ ] 完成 [docs/releases/phase3.1-verification-report.md]），交付后链接自然闭合——属于"任务未完成"的预期悬空。

---

六、风险矩阵

#	风险	等级	缓解	状态
R1	evidence/ 仅有 README.md（无 capability/ / visual/ / consumer/ 子目录或资产）	🟡 低	evidence/README.md §"视觉证据"显式说明 vlm_corpus 因 ffx 硬编码引用保留原位、不复制——设计正确；但目录承诺 vs 实物不一致，需在 README 顶部补一句"索引而非容器"	⚠️ 建议改进
R2	regression/ 仅 3 个 BUG（承诺 5 个 BUG-001/002/003/005/006）	🟢 信息	regression/README.md §"提取来源"显式说明"本轮提取前 3 个作范式，其余按需补充"——是刻意节制而非缺失	✅ 可接受
R3	decisions/INDEX.md 状态表中 ADR-0009 / ADR-0012 / ADR-0025 等标注"需治理" / "待签字"，但 OWNER 关注表未给出明确 ETA	🟡 中	README 中"需要 Owner 关注"已分类列出；本 PR 不应承担 ADR 状态变更责任（AGENTS.md §6.4 ADR 决策类文件属 Owner 专属权限）	✅ 边界正确
R4	engineering/VERIFICATION-POLICY-source-*.md 3 个原始文档与合并后的 VERIFICATION-POLICY.md 共存——可能在 6 个月后让人困惑"该信哪个"	🟡 中	合并文档 §"数据源"清晰指向 source-* 作为完整原始档案；但缺乏自动化"以合并版为准"的强制（如 README 顶部"supersedes"声明）	⚠️ 建议改进
R5	product/CAPABILITY-STATUS-source-*.md 同样与 CAPABILITY-STATUS.md 共存	🟡 中	同 R4——CAPABILITY-STATUS.md §"数据源"已声明；同样建议加 supersedes 标记	⚠️ 建议改进
R6	PR 描述承诺 16 个顶层 RUN 副本删除（PR #164 vs PR #166 内容重复），但 diff 中未看到显式 git rm 行	🟢 信息	git diff --stat 显示 docs/{ => archive}/runs/... 全部为 rename（含 phase3.11/RUN-001~016），重复清理通过"目标统一到 archive/runs/"+ 顶层删除实现；与设计意图一致	✅ 已验证
R7	INFO-ARCHITECTURE-DESIGN.md 与 MIGRATION-MAP.md 仍留在 docs/ 顶层，是否应按设计 D 节"迁移完成后可移 archive"执行？	🟢 信息	当前作为本次重构的设计/迁移记录保留有归档价值——但应在下一阶段标记"Historical, see archive/"或挪入 archive/	⚠️ 建议改进
R8	decisions/REVIEW-BACKLOG.md（来自原 phase3.1-review-backlog.md）位于 decisions/ 而非 decisions/ADR/——是否会被误读为 ADR？	🟢 信息	文件命名清晰，位置合理（决策待办与决策本身分离）	✅ 合理

---

七、可改进项（建议改动后合并）

1. evidence/README.md 顶部加一句"索引而非容器"——明确说明 capability/visual/consumer 子目录是规划占位，实际资产保留在 tools/ffx-cli/.../vlm_corpus{,_physical}/ 原位（ffx 硬编码）。当前只在 §"视觉证据"小节才说明，新人会困惑。

2. VERIFICATION-POLICY.md 与 CAPABILITY-STATUS.md 顶部加 supersedes 声明——例如：

   > **Canonical**: 本文档为合并视图（VERIFICATION-POLICY.md）。
   > 原始完整档案：[VERIFICATION-POLICY-source-e2e.md](VERIFICATION-POLICY-source-e2e.md)（历史）...

   防止 6 个月后新增 Agent 不知道哪个是真相源。

3. INFO-ARCHITECTURE-DESIGN.md + MIGRATION-MAP.md 标记 Historical——本次重构成功后，这两份设计文档的历史使命完成。建议在下一阶段（Phase 3.12 收尾 PR）将其移入 docs/archive/ 或顶部加 > Historical: Phase 3.12 已完成迁移，此文档仅供追溯。

4. AGENTS.md §14.1 顶部补充一句：将"REPO_AUDIT_2026-08-25.md 未入库"状态从"⚠️ 暂悬空"升级为正式 TODO——例如加入 AGENTS.md §10 当前阻塞项表，标注 Owner 与 ETA。这能防止悬空引用被无限期遗忘。

---

八、不属于本次审查范围但值得记录

• decisions/INDEX.md 中 ADR-0009 / 0012 / 0025 等"需治理"条目：属于 Owner 专属权限（AGENTS.md §6.4），AI Agent 不应在 PR 中擅自修改 ADR 状态——边界正确。
• DEBT-014（Live/Committed 张力）/ DEBT-006（IME Coalescing）：CURRENT-STATE.md §3 标注"待 Owner 决策：是否单独立项"——同样属于 Owner 决策范围。
• 测试通过 / analyze 通过：本 PR 零代码改动，未触发 flutter analyze / flutter test，按 AGENTS.md §11.3 SKIP_PREFLIGHT=1 处理——与纯文档改动一致。

---

最终结论

✅ 可以合并

理由：

• 架构分层（L1/L2/L3/L4 + Decision/Evidence/Current State 三种 Truth）设计合理、与 AGENTS.md §0-9 既有约束自洽
• 162 文件 / 1190+/2798- 的大规模迁移通过 git mv 正确保留历史（rename similarity 87-100%）
• 关键边界（机器资产路径 root/contracts/*.json 不动）经多处硬编码验证保持兼容
• 链接修复 511 → 5 既有/预期悬空，正确归类
• 8 项风险中 6 项为可接受或需后续微改进，0 项阻塞合并
• 改进项均为可选 polish，不影响本次重构目标的达成

建议合并后立即：开一个 Phase 3.12 收尾 PR 处理"七、可改进项 §1-4"（都是小改动，合并后再做更稳）。

---

_{Review by Claude · · Branch: feat/phase3.12-info-architecture}