docs: harden pairing gate per review — structural signature, not counts

Review findings addressed: - The gate compared only heading and code-block COUNTS, understating the contract it claims to enforce. It now compares ordered structural signatures: heading depths, fenced code blocks verbatim (info string + content), table column counts, list kinds, and every link target except the language switcher. Proven red on a heading demotion, a reworded code-block comment, and a retargeted link; green on all existing pairs. - Stated the gate's limit explicitly (header comment + docs/i18n/README.md both languages): green means fresh and structurally sound, NOT verified — translation quality is the reviewer's half of the contract. - first-line extraction no longer silently drops the last character of a newline-less file (split with limit instead of indexOf slice). - isExcluded documents the trailing-slash-is-the-boundary invariant. - Rollout guidance: grow the required frontier at the pace translation review is resourced. - dsh-code-review's doc-sync sublist is now the exhaustive chain. docs/i18n/README.zh.md updated via the minimal-diff workflow and re-fingerprinted.
2026-07-03 02:06:57 -07:00
parent cd9d559805
commit a899226397
4 changed files with 103 additions and 30 deletions
@@ -34,7 +34,7 @@ These come straight from the source docs above. They are not discretionary; abse
 1. **Docs in sync.** If the PR changes a config key, default, error code, wire field, or event name, it must update the package README + module/JSDoc in the same diff. The `doc-sync` gate (check #4) does not catch prose drift in config keys, defaults, error codes, or wire fields — that is on the reviewer, but it is still required, not optional.
 2. **Core-data-structures catalog in sync.** If the PR adds, removes, or reshapes a type the [core-data-structures catalog](../../../docs/core-data-structures/core.md) documents — a new `…Map` variant, a new content-block/session-event type, a field on `GenerateOptions`/`Agent`/`ToolDefinition`/a bash type, or a whole new core/seam type — it must update that catalog in the same diff (prose + any verbatim ` ```ts type-equiv ` block + the 1:1 `scripts/type-equiv.manifest.json`). The `verify-type-equiv` gate (part of `doc-sync`) catches a *drifted paste* of an already-documented type, but it cannot tell you a brand-new core type went undocumented — that judgment is yours. Confirm a genuinely spine-level type landed in core.md and a new capability's vocabulary on a sub-page, per the spine-vs-seam line in [core.md § What counts as "core"](../../../docs/core-data-structures/core.md#what-counts-as-core). A pure internal type with no cross-package reach needs no catalog entry — say so if it's a judgment call.
 3. **HMR-safety test.** Any new registry/registration needs a test that disposes the contributing fiber and asserts cleanup (packages/AGENTS.md). Its absence blocks merge.
-4. **Quality gates pass.** typecheck, lint, test, test:coverage (100% per-file on `packages/*/src`), knip, build, publint, constraints, `doc-sync` (doc-typecheck + verify-cordis-catalog + verify-md-wrap + verify-md-links + verify-type-equiv + verify-translation-pairing), module-graph freshness (the quality-gates RFC). Don't re-review what a gate already enforces — trust the gate and spend attention on what it can't check. Note that the `doc-sync` gate only covers compilable `ts` blocks, the generated cordis events/services catalog, markdown wrapping/links, verbatim type-equiv blocks, and the bilingual pairing contract ([docs/i18n/README.md](../../../docs/i18n/README.md)); prose drift (checks #1 and #2) and translation *quality* (the [dsh-translate-docs](../dsh-translate-docs/SKILL.md) rules) are *additional* manual review on top of it, not covered by it.
+4. **Quality gates pass.** typecheck, lint, test, test:coverage (100% per-file on `packages/*/src`), knip, build, publint, constraints, `doc-sync` (doc-typecheck + verify-cordis-catalog + verify-tool-catalog + verify-md-wrap + verify-md-links + verify-doc-refs + verify-package-paths + verify-rfc-classification + verify-type-equiv + verify-translation-pairing), module-graph freshness (the quality-gates RFC). Don't re-review what a gate already enforces — trust the gate and spend attention on what it can't check. Note that the `doc-sync` gate only covers compilable `ts` blocks, the generated cordis events/services catalog, markdown wrapping/links, verbatim type-equiv blocks, and the bilingual pairing contract ([docs/i18n/README.md](../../../docs/i18n/README.md)); prose drift (checks #1 and #2) and translation *quality* (the [dsh-translate-docs](../dsh-translate-docs/SKILL.md) rules) are *additional* manual review on top of it, not covered by it.

 ## Reviewer-only checks (gates can't catch these — judgment required)

@@ -16,20 +16,22 @@ This repo's documentation is read by people and agents both inside and outside t

  A blob hash, not a commit hash, so the fingerprint is computable for an English file edited in the same PR (`git hash-object docs/foo.md`), and so staleness is a pure content comparison. The fingerprint is also the update tool: `git cat-file -p <hash>` recovers the exact source text a stale translation was based on, and `git diff <hash> <current-blob>` isolates what changed so the translation can be updated minimally instead of re-translated.
 - **Language switcher.** Both files link to each other immediately after their H1 heading: the English file carries `English | [中文](foo.zh.md)` and the Chinese file carries `[English](foo.md) | 中文`.
- **Structure mirrors the source.** Heading hierarchy, list shape, table columns, and code blocks match the English file one to one — see [translation-rules.md](translation-rules.md) for the full preservation rules. Existing Markdown gates apply to `.zh.md` files unchanged (`verify-md-wrap`, `verify-md-links`).
+- **Structure mirrors the source.** Heading depths and order, list kinds, table columns, link targets, and verbatim code blocks match the English file one to one — see [translation-rules.md](translation-rules.md) for the full preservation rules. Existing Markdown gates apply to `.zh.md` files unchanged (`verify-md-wrap`, `verify-md-links`).

 ## The gate: verify-translation-pairing

 `pnpm run verify-translation-pairing` (part of `doc-sync`, so CI and the pre-push hook run it) enforces the contract mechanically:

 1. Every English file listed as `required` in [scripts/translation-pairing.manifest.json](../../scripts/translation-pairing.manifest.json) has a `.zh.md` sibling.
-2. Every existing `.zh.md` file — required or not — passes all of: its English source exists (no orphans), its fingerprint matches the source's current blob hash (no stale translations), both sides carry the language switcher, and its fenced-code-block and heading counts equal the source's.
+2. Every existing `.zh.md` file — required or not — passes all of: its English source exists (no orphans), its fingerprint matches the source's current blob hash (no stale translations), both sides carry the language switcher, and its structural signature matches the source in order — heading depths, verbatim code blocks (info string and content), table column counts, list kinds, and every link target apart from the switcher.
 3. Files listed as `excluded` have no `.zh.md` sibling at all.

 `pnpm run verify-translation-pairing --list` prints the current translation state of every document in scope — missing, stale, or ok — and is the work list for translation batches. It never fails; it reports.

 The practical rule this gate creates: **when a PR edits an English document that has a `.zh.md` sibling, the same PR updates the translation** (run the [dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md) skill), exactly like the repo's existing doc-sync rule for code and READMEs. A PR that leaves a translation stale goes red in CI.

+The gate's limit, stated plainly: **a green gate means fresh and structurally sound, not verified.** It checks the fingerprint and the shape; it cannot judge whether the Chinese is accurate, well-termed, or natural — that is the reviewer's half of the contract, per [translation-rules.md](translation-rules.md). A re-fingerprinted `.zh.md` with a sloppy translation passes the gate; it must not pass review.
+
 ## Scope, exclusions, and rollout

 **Scope**: the root `README.md` and everything under `docs/**`. Package READMEs (`packages/**`) join the scope in a later batch.
@@ -40,7 +42,7 @@ The practical rule this gate creates: **when a PR edits an English document that
 - `docs/AGENTS.md` — agent instructions, maintained in English only like the root `AGENTS.md`.
 - `docs/i18n/terminology.md` — the terminology table is itself bilingual by construction.

-**Rollout**: the `required` list in the manifest is the enforcement frontier, not the goal. The goal is full bilingual coverage of the scope. Translation lands in reviewable batches (core entry docs, cookbook, RFCs, postmortems, …); each merged batch adds its files to `required`, so the gate ratchets forward and never regresses. Documents not yet in `required` are backlog — visible in `--list` — but any translation that already exists is held to the full contract regardless of the list.
+**Rollout**: the `required` list in the manifest is the enforcement frontier, not the goal. The goal is full bilingual coverage of the scope. Translation lands in reviewable batches (core entry docs, cookbook, RFCs, postmortems, …); each merged batch adds its files to `required`, so the gate ratchets forward and never regresses. Documents not yet in `required` are backlog — visible in `--list` — but any translation that already exists is held to the full contract regardless of the list. Pairing a document is a commitment: every later English edit to it must carry the translation along, so grow the frontier at the pace translation review is actually resourced, not ahead of it.

 ## Division of labor

@@ -1,4 +1,4 @@
-<!-- i18n-source: docs/i18n/README.md@e70a1fed0d0e -->
+<!-- i18n-source: docs/i18n/README.md@fb0e17390e02 -->

 # 双语文档

@@ -18,20 +18,22 @@

  用 blob hash 而不是 commit hash，这样同一个 PR 里改动的英文文件也能算出指纹（`git hash-object docs/foo.md`），过期检测则是纯内容比较。指纹同时也是更新工具：`git cat-file -p <hash>` 能还原过期译文当初依据的确切源文本，`git diff <hash> <当前 blob>` 能隔离出变化的部分，让译文做最小更新而不是整篇重译。
 - **语言切换行。**两个文件在各自 H1 标题之后立即互链：英文文件带 `English | [中文](foo.zh.md)`，中文文件带 `[English](foo.md) | 中文`。
- **结构与源一一对应。**标题层级、列表形态、表格列与代码块和英文文件一一对应——完整保持规则见 [translation-rules.md](translation-rules.md)。既有 Markdown 门禁对 `.zh.md` 文件原样生效（`verify-md-wrap`、`verify-md-links`）。
+- **结构与源一一对应。**标题深度与顺序、列表类型、表格列、链接目标与逐字节一致的代码块和英文文件一一对应——完整保持规则见 [translation-rules.md](translation-rules.md)。既有 Markdown 门禁对 `.zh.md` 文件原样生效（`verify-md-wrap`、`verify-md-links`）。

 ## 门禁：verify-translation-pairing

 `pnpm run verify-translation-pairing`（`doc-sync` 的一环，因此 CI 和 pre-push 钩子都会运行）机械地强制这份契约：

 1. [scripts/translation-pairing.manifest.json](../../scripts/translation-pairing.manifest.json) 中 `required` 列出的每个英文文件都有 `.zh.md` 配对文件。
-2. 每个已存在的 `.zh.md` 文件——无论是否 required——都通过全部检查：其英文源存在（无孤儿）、指纹等于源的当前 blob hash（无过期译文）、双方都带语言切换行、其代码块与标题数量等于源文件。
+2. 每个已存在的 `.zh.md` 文件——无论是否 required——都通过全部检查：其英文源存在（无孤儿）、指纹等于源的当前 blob hash（无过期译文）、双方都带语言切换行、其结构签名与源按序一致——标题深度、逐字节一致的代码块（信息串与内容）、表格列数、列表类型、以及除切换行之外的每个链接目标。
 3. 列为 `excluded` 的文件完全没有 `.zh.md` 配对。

 `pnpm run verify-translation-pairing --list` 打印范围内每篇文档的当前翻译状态——missing、stale 或 ok——是翻译批次的工作清单。它从不失败；它只报告。

 这个门禁带来的实际规则是：**当一个 PR 修改了已有 `.zh.md` 配对的英文文档时，同一个 PR 更新译文**（运行 [dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md) skill），与本仓库既有的代码/README doc-sync 规则完全一致。留下过期译文的 PR 会在 CI 变红。

+把门禁的边界说白：**门禁绿意味着新鲜且结构健全，不意味着已核验。**它检查指纹和形状；它无法判断中文是否准确、术语是否得当、行文是否自然——那是契约中评审者的那一半，见 [translation-rules.md](translation-rules.md)。一个重打了指纹但翻得潦草的 `.zh.md` 能通过门禁；它不应通过评审。
+
 ## 范围、排除与推进

 **范围**：根 `README.md` 与 `docs/**` 下的全部内容。package README（`packages/**`）在后续批次加入范围。
@@ -42,7 +44,7 @@
 - `docs/AGENTS.md` —— agent 指令，与根 `AGENTS.md` 一样只以英文维护。
 - `docs/i18n/terminology.md` —— 术语表本身即是双语构造。

-**推进**：manifest 中的 `required` 列表是强制边界，不是目标。目标是范围内的全量双语覆盖。翻译按可评审的批次落地（核心入口文档、cookbook、RFC、postmortem……）；每个批次合入后把其文件加进 `required`，门禁只进不退。尚未进入 `required` 的文档是 backlog——在 `--list` 中可见——但任何已存在的译文无论在不在清单里都按完整契约检查。
+**推进**：manifest 中的 `required` 列表是强制边界，不是目标。目标是范围内的全量双语覆盖。翻译按可评审的批次落地（核心入口文档、cookbook、RFC、postmortem……）；每个批次合入后把其文件加进 `required`，门禁只进不退。尚未进入 `required` 的文档是 backlog——在 `--list` 中可见——但任何已存在的译文无论在不在清单里都按完整契约检查。给一篇文档配对是一份承诺：此后对它的每次英文修改都必须带上译文，所以边界的扩张要跟上翻译评审的实际投入节奏，不要抢在前面。

 ## 分工

@@ -5,17 +5,25 @@
 *
 *   <!-- i18n-source: docs/foo.md@<first 12 hex of git blob hash> -->
 *
- * The gate checks, mechanically, everything the contract promises:
+ * The gate checks, mechanically, the checkable half of the contract:
 *
 *   1. Every English file in the manifest's `required` list has a `.zh.md`
 *      sibling (the enforcement frontier — grows batch by batch).
 *   2. Every EXISTING `.zh.md`, required or not, is sound: its source exists
 *      (no orphans), its fingerprint equals the source's current blob hash
 *      (no stale translations), both sides carry the language-switcher link,
- *      and its fenced-code-block and heading counts match the source.
+ *      and its structural signature matches the source one to one — heading
+ *      depths in order, fenced code blocks VERBATIM (info string + content),
+ *      table column counts, list kinds, and every link target except the
+ *      switcher itself.
 *   3. `excluded` files (generated docs, agent instructions, the bilingual
 *      terminology table) have no `.zh.md` at all.
 *
+ * What it deliberately does NOT check is translation quality: a green gate
+ * means the pair is fresh and structurally sound, not that the Chinese is
+ * faithful — accuracy, terminology, and tone are the human reviewer's half
+ * of the contract (docs/i18n/translation-rules.md).
+ *
 * The fingerprint is a git BLOB hash, not a commit hash, so a translation
 * updated in the same PR as its English source verifies without any history
 * lookup: staleness is a pure content comparison, computed here directly
@@ -51,7 +59,12 @@ const manifest = JSON.parse(readFileSync(join(root, 'scripts/translation-pairing
 /** First line of a translation: fingerprint of the English source it renders. */
 const FINGERPRINT = /^<!-- i18n-source: (?<path>\S+)@(?<hash>[0-9a-f]{12}) -->$/

-/** An excluded entry ending in `/` excludes the whole directory. */
+/**
+ * An excluded entry ending in `/` excludes the whole directory. The trailing
+ * slash IS the path boundary — `docs/tool-catalog/` cannot prefix-match a
+ * sibling like `docs/tool-catalog-notes/x.md` — so directory entries in the
+ * manifest must keep their trailing slash.
+ */
 function isExcluded(file: string): boolean {
  return manifest.excluded.some(entry => (entry.endsWith('/') ? file.startsWith(entry) : file === entry))
 }
@@ -64,13 +77,25 @@ function blobHash(content: Buffer): string {
  return hash.digest('hex').slice(0, 12)
 }

-/** Counts that must match between a source and its translation. */
-interface Shape {
-  codeBlocks: number
-  headings: number
+/**
+ * The structural signature a translation must reproduce from its source, as
+ * ordered sequences so a swap or a level change is caught, not just a count
+ * change. Prose is deliberately absent: the gate checks shape, never wording.
+ */
+interface Signature {
+  /** Heading depths in document order (h2 → 2). */
+  headings: number[]
+  /** Fenced code blocks verbatim: info string + content, in order. */
+  code: string[]
+  /** Column count of each table, in order. */
+  tables: number[]
+  /** Each list's kind (ordered vs bullet), in order. */
+  lists: string[]
+  /** Every link target in order, the language switcher's excluded. */
+  links: string[]
 }

-/** Whether `text` contains a relative markdown link to exactly `target`. */
+/** Whether the tree contains a link to exactly `target` (the switcher check). */
 function linksTo(tree: Nodes, target: string): boolean {
  let found = false
  const visit = (node: Nodes): void => {
@@ -81,16 +106,63 @@ function linksTo(tree: Nodes, target: string): boolean {
  return found
 }

-function shapeOf(tree: Nodes): Shape {
-  let codeBlocks = 0
-  let headings = 0
+/** Collect the structural signature, skipping links to `switcherTarget`. */
+function signatureOf(tree: Nodes, switcherTarget: string): Signature {
+  const sig: Signature = { headings: [], code: [], tables: [], lists: [], links: [] }
  const visit = (node: Nodes): void => {
-    if (node.type === 'code') codeBlocks++
-    if (node.type === 'heading') headings++
+    switch (node.type) {
+      case 'heading':
+        sig.headings.push(node.depth)
+        break
+      case 'code':
+        sig.code.push(`\`\`\`${node.lang ?? ''}${node.meta ? ` ${node.meta}` : ''}\n${node.value}`)
+        break
+      case 'table':
+        sig.tables.push(node.children[0]?.children.length ?? 0)
+        break
+      case 'list':
+        sig.lists.push(node.ordered ? 'ordered' : 'bullet')
+        break
+      case 'link':
+        if (node.url !== switcherTarget) sig.links.push(node.url)
+        break
+      default:
+        // Every other node kind is prose or container — not part of the signature.
+        break
+    }
    if ('children' in node) for (const child of node.children) visit(child)
  }
  visit(tree)
-  return { codeBlocks, headings }
+  return sig
+}
+
+/** Render a signature element for an error message, truncated for readability. */
+function show(value: string | number | undefined): string {
+  if (value === undefined) return 'nothing'
+  const text = JSON.stringify(value)
+  return text.length > 72 ? `${text.slice(0, 72)}…` : text
+}
+
+/** First divergence between two signatures, as messages; empty when identical. */
+function signatureDiff(source: Signature, zh: Signature): string[] {
+  const out: string[] = []
+  const fields: [string, (string | number)[], (string | number)[]][] = [
+    ['heading (depth)', source.headings, zh.headings],
+    ['code block', source.code, zh.code],
+    ['table (column count)', source.tables, zh.tables],
+    ['list (kind)', source.lists, zh.lists],
+    ['link target', source.links, zh.links],
+  ]
+  for (const [field, s, z] of fields) {
+    const length = Math.max(s.length, z.length)
+    for (let i = 0; i < length; i++) {
+      if (s[i] !== z[i]) {
+        out.push(`${field} #${i + 1} diverges from the source: source has ${show(s[i])}, translation has ${show(z[i])}`)
+        break
+      }
+    }
+  }
+  return out
 }

 function parse(content: string): Nodes {
@@ -135,7 +207,7 @@ for (const zh of translations) {
  }

  const zhContent = readFileSync(join(root, zh), 'utf8')
-  const firstLine = zhContent.slice(0, zhContent.indexOf('\n'))
+  const firstLine = zhContent.split('\n', 1)[0] ?? ''
  const match = FINGERPRINT.exec(firstLine)
  if (!match?.groups) {
    errors.push(`${zh}: first line is not an i18n-source fingerprint (expected \`<!-- i18n-source: ${source}@<12-hex> -->\`, got \`${firstLine.slice(0, 60)}\`)`)
@@ -162,13 +234,10 @@ for (const zh of translations) {
  if (!linksTo(sourceTree, basename(zh))) {
    errors.push(`${source}: missing language switcher — no link back to ${basename(zh)}`)
  }
-  const zhShape = shapeOf(zhTree)
-  const sourceShape = shapeOf(sourceTree)
-  if (zhShape.codeBlocks !== sourceShape.codeBlocks) {
-    errors.push(`${zh}: ${zhShape.codeBlocks} fenced code block(s) vs ${sourceShape.codeBlocks} in ${source} — code blocks must mirror the source`)
-  }
-  if (zhShape.headings !== sourceShape.headings) {
-    errors.push(`${zh}: ${zhShape.headings} heading(s) vs ${sourceShape.headings} in ${source} — heading structure must mirror the source`)
+  const sourceSig = signatureOf(sourceTree, basename(zh))
+  const zhSig = signatureOf(zhTree, basename(source))
+  for (const divergence of signatureDiff(sourceSig, zhSig)) {
+    errors.push(`${zh}: ${divergence}`)
  }
  if (!state.has(source)) state.set(source, 'ok')
 }