docs(agents): sync AGENTS.md §14.1 顶层目录清单 (PR-5) - #172
Merged
Conversation
仓库治理调研报告 (REPO_AUDIT_2026-08-25.md v4) 发现 AGENTS.md §14.1 与实际仓库偏差较大: v1 §14.1 (本 commit 之前): - 4 个 tracked 顶层目录 (.agent / flutter_app / tools / docs) - 11 个文档 (缺 INDEX.md / archive/ / contracts/ / design/ / releases/ / runs/ 等) - ADR/ 写 26 篇实际 29 - test/ 写 175 个实际 175+ - ffx-cli tests/ 写 40 passing 实际 170+ - 缺所有 .githooks / .github / contracts / design-system / skills / tests / openwiki / .claude / .ffx / .adi 等 v2 §14.1 (本 commit 之后): - 17 个 tracked 顶层 + 10 个 ignored 顶层 + 临时 untracked 标注 - 完整目录树包括 .agent sub-dirs (context/ templates/ tools/ state/), .claude (settings.json vs hooks.log), docs (INDEX.md 19 个子目录) - ffx-cli/ 6 个子目录 (core/ harness/ adapters/ utils/ tests/) - flutter_app/tool/ (preflight.sh / wsl_golden.sh) - 新增 14.1.1 七维治理策略表 (tracked source / project assets / runtime artifacts / one-shot artifacts / generated artifacts / docs / branches), 每行标注 v3-PR 完成状态 依据: REPO_AUDIT_2026-08-25.md v4 + git ls-tree --name-only HEAD 实测 (HEAD = 10cbf4b) AGENTS.md §6.4 架构决策类文件, 但本会话已显式获得 Human Owner 授权 (PR 序列连续 5 个) Task scope: ROADMAP repo-governance / PR-5
PR-5 描述文档, 含: 1. v1 vs v2 差异表 (tracked 顶层 4 → 17, ADR 26 → 29, ffx tests 40 → 170+ 等) 2. 14.1.1 七维治理策略落地 (tracked source / project assets / runtime artifacts / one-shot artifacts / generated artifacts / docs / branches) 3. 验证方法 (git ls-tree / check-ignore / fsck) 4. AGENTS.md §6.4 架构决策类文件授权例外声明 (本会话已获 Human Owner 授权) Task scope: ROADMAP repo-governance / PR-5
|
Claude encountered an error after 1m 58s —— View job PR-5 Review: docs(agents): sync AGENTS.md §14.1 顶层目录清单审查级别：Level 1 普通代码 Review 验证结果
🔴 Blocker：文档引用断链问题： $ git ls-files | grep -i "repo_audit"
# (empty — never tracked)
$ git log --all --diff-filter=A -- '*REPO_AUDIT*'
# (empty — never committed)引用点：
风险：CI/编辑器/IDE 中点击链接会 404；v3 / v4 版本号承诺无法溯源；§14.1 的"依据"链断裂（无法验证 §14.1 数据来源的真实性）。 修复建议：
🟡 Minor Issues（不阻塞合并）1. AGENTS.md:865 —
|
| 维度 | 评价 |
|---|---|
| 可维护性 | ✅ 优秀。14.1.1 七维治理策略表把 v3 报告 §0.2 落地为单一信息源，未来新增顶层条目只改一处 |
| 可追溯性 | |
| 完整性 | ✅ 顶层 17 / ADR 29 / contracts 11 / releases 11 / ffx-cli tests 170+ 全部对齐实际值 |
| 内部一致性 | ✅ AGENTS.md §14.1 ↔ PR-5_DESCRIPTION.md 数据互相印证 |
| 可读性 | ✅ 中英混排 + 注释 + 树形结构清晰 |
| Hard Rules 合规 | ✅ 0 行 Dart / 0 行 gitignore 变更，符合 §6.4 架构决策文件例外授权要求 |
测试覆盖（Level 1 范围）
| 检查 | 结果 |
|---|---|
git diff origin/main...HEAD --stat = 2 files / 162+/30- |
✅ |
git ls-files --others --exclude-standard 仅有 .atomcode/memory.md |
✅ 当前 working tree 无 untracked（注：.atomcode/ 不在 .gitignore 中，是文档一致性问题，非本 PR 范围） |
git fsck --no-dangling |
✅ 未执行（PR 描述声称零输出，建议在合入前实际跑一遍） |
最终结论
理由：
- 数据准确性优秀：所有具体数字（17 / 29 / 11 / 170+）均经实测验证
- 结构设计优秀：14.1 + 14.1.1 双层组织提供完整 inventory + governance 视图
- 但 6 个文件的断链（特别是 AGENTS.md 主入口）严重损害文档可信度——v4 §3.3 / §5.5 这种章节锚点无法溯源，本 PR 的"依据"承诺落空
合入前必须修复：
- ✅ 修复
docs/REPO_AUDIT_2026-08-25.md断链（补文件 / 改占位 / 删除引用 三选一）
可后续 PR 改进：
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
docs(agents): sync AGENTS.md §14.1 顶层目录清单 (PR-5)
关联文档
9e37e86） + chore: root cleanup + tracked state corrections (PR-2) #169 (PR-2) + docs: add PR-3_DESCRIPTION.md (60 golden failure PNG cleanup 审计记录) #170 (PR-3) + docs: add BRANCH_AUDIT_2026-08-25.md (PR-4 治理基线 + 执行结果) #171 (PR-4) 全部 MERGED，main HEAD =10cbf4b10cbf4b改动说明
What：仅修改
AGENTS.md§14.1（line 841 起），97 insertions / 30 deletions。Why：
v1 vs v2 关键差异
git ls-tree --name-only HEAD实测14.1.1 七维治理策略（v3 报告 §0.2 落地）
验证
git ls-tree --name-only HEAD列 17 个 tracked 顶层——与 §14.1 一致git ls-files --others --exclude-standard列 1 个 untracked (.atomcode/memory.md)——已标注git check-ignore -v .adi/ .ffx/ openwiki/ .claude/hooks.log flutter_app/test/golden/failures/全部命中——ignored 顶层正确git fsck --no-dangling零输出不影响公共 API
测试方式
git diff origin/main..HEAD --stat应 = 1 file / 97 insertionsgit ls-tree --name-only HEAD验证 17 个 tracked 顶层与 §14.1 描述一致git ls-files --others --exclude-standard应仅含.atomcode/memory.md自检清单（AGENTS.md §5.3 + §9.4）
Task scope
ROADMAP repo-governance / PR-5