docs(v2): §0.5 文体硬约束 + C01 最小 diff 重做 + C-1~C-4 CI 脚本 - #17
Merged
Conversation
- spec: §0 four-rules → five-rules; insert §0.5.1–§0.5.7 (style baseline, iteration rules for v1 chapters, new-chapter rules, PR #15 reverse-examples, CI/human review acceptance, and the narrowed migration-matrix semantics) - spec §1 intro: add the 'v2 是更准确，不是更新颖' clause - spec §3 / §7.2: bump CI count and list four new scripts - 01-项目全景.md: minimum-diff redo of PR #15. Restore v1 narrative, add a single 250-word paragraph in §3.2 noting the 12 first-class dirs that v2 will cover (bridge/remote/coordinator/server/upstreamproxy/ migrations/buddy/screens/outputStyles/keybindings,vim,voice/native-ts/ schemas), no other section reshuffles. - scripts/check-prose-diff-ratio.ts (C-1): 8-CJK-char window retention check - scripts/check-heading-preservation.ts (C-2): v1 H1/H2 set ⊆ v2 set - scripts/check-code-ratio.ts (C-3): source-lang fenced ratio, applies to v2 new chapters only (per §0.5.4 #3) - scripts/lint-section-titles.ts (C-4): 5 forbidden patterns - .github/workflows/v2-style-guard.yml: wire C-1..C-4 to PR checks Co-authored-by: multica-agent <github@multica.ai>
Co-authored-by: multica-agent <github@multica.ai>
- C-1/C-2: when a protected v1 doc exists in base but is missing in worktree (delete or rename), fail loudly instead of warn/skip — prior branches let `docs/01-...` be removed silently. - C-3: drop the stale `C04|C13|...` filename whitelist (actual files use `NN-标题.md` and never carry book-spine IDs in the filename); the frontmatter `新增章节: yes` declaration is now the sole gate, and V2-REVISION-SPEC §0.5.4 + §9.3 mandate it for the 8 new chapters. Co-authored-by: multica-agent <github@multica.ai>
OC-R flagged that new chapters could skip C-3 by simply omitting `新增章节: yes`. Now any docs/*.md file not in the v1 published manifest is treated as a planned-new-chapter path and must declare the frontmatter, otherwise C-3 fails (no longer skip+exit 0). V1 published files keep the prior skip behavior (C-3 doesn't apply to v1 chapters by spec §0.5.4 / §9.3). Co-authored-by: multica-agent <github@multica.ai>
按 issue YAO-60 范围确认，C01 正文修订留作后续子 issue 处理。 Co-authored-by: multica-agent <github@multica.ai>
OC-R reported that the prior C-3 candidate filter (docs/*.md minus
V2-REVISION-SPEC.md) treated planned docs/appendix/{A..F}.md auto-
generated appendices as new-chapter candidates and would FAIL them
for missing '新增章节: yes' frontmatter.
Restrict candidates to top-level chapter files matching
^docs/\d{2}-[^/]+\.md$, aligned with V2-REVISION-SPEC.md §9.3
(NN-标题.md naming). Appendices, the spec itself, and any other
non-chapter pages are now skipped.
Co-authored-by: multica-agent <github@multica.ai>
OC-R PR #17 二次反馈：旧实现把"不在 V1_DOC_FILES 内"等价为"新增章节"， 会误伤 v2 改名后的非新增章节（例如 v1-04 → docs/06-System-Prompt-与- Output-Style-注入.md 对应 C06，仍是非新增）。 改为基于 V2-REVISION-SPEC §5/§9.3 维护 NEW_CHAPTER_NN 集合 {04,13,17,24,25,28,29,30}，按 NN 前缀显式判定 v2 新章。V1_DOC_FILES 保留并优先匹配，使 v1 文件被重命名/移除前不被新 NN 槽位误判为新章。 Co-authored-by: multica-agent <github@multica.ai>
Co-authored-by: multica-agent <github@multica.ai>
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.
落地动作（对应 issue YAO-60 §0.5.8）
按 OC-PM 的 §0.5 文体硬约束补丁与 PR #15 翻车点清单一次性落地：
docs/V2-REVISION-SPEC.md— §0 四公约 → 五公约；引言补一句 "v2 是用更强模型重新解析同一套源码以校正准确性，不是用更新颖的写法重写既有文章"；§3CI 校验单元由 3 项扩为 7 项；§7.2 仓库布局补 4 个新脚本路径docs/01-项目全景.md：仅在 §3.2 目录结构后加一段 250 字散文，提示 v1 未入图的 12 个一级目录及它们对应的 v2 新增章节；v1 标题 / 段落 / 表格全部保留；无章节骨架重排scripts/check-prose-diff-ratio.ts/check-heading-preservation.ts/check-code-ratio.ts/lint-section-titles.ts，由.github/workflows/v2-style-guard.yml在 PR 触发风格双亲（§0.5.1）
本 PR 修订对象是
docs/01-项目全景.md（即 C01 v1 原稿）。最小修改原则下不需要"模仿"风格——保留 v1-01 自身的全部叙事；新增的一段散文以 v1-01 §3.2 既有文风（"目录结构与职责"散文 + 缩进 ASCII 树）为基线，并参照 v1-25（架构模式总结）的"罗列式但保持口语化"写法。风格双亲：v1-01（项目全景）+ v1-25（架构模式总结）
本次修改量化对照（§0.5 R-2）
docs/01-项目全景.md：CI 自检（base = origin/main）：
C-3 范围说明
§0.5.4 #3 把"代码块占比 ≤ 25%"写在新章规则下；为了不阻塞 v1 老章节的 minimal-diff 修订（v1-01 自身因 mermaid 图与 ts 片段而天然偏高），脚本仅对 C04/C13/C17/C24/C25/C28/C29/C30 这 8 个 v2 新增章节文件名生效，或对 frontmatter 含
新增章节: yes的文件生效。其他章节走 C-1/C-2/C-4。反例对照（§0.5.5）
PR #15 的六条翻车点已全部规避：
# C01 · ...# 第 1 篇：项目全景 — 一个 AI CLI 产品的技术蓝图## 源码锚点列表验证
Refs: YAO-60 (
mention://issue/7ca361f1-1a45-474a-92f4-f58bb1dd559c)