test(docs): split docs-drift.test.ts along its describe seams (#1196)

[huangyiirene]

Fixes #1196

test/docs-drift.test.ts was 99,746 bytes against the 102,400-byte
MAX_FILE_BYTES in scripts/check-source-hygiene.mjs — 2,654 bytes of
headroom, 97.4% full. #1135 is queued to add assertions to that very file
(it reuses the capCel machinery there) and would have hit the ceiling
mid-implementation, which is the detour #814 and #635 each paid for once
already.

This splits the file along the describe seams it already had. It is a move,
not a rewrite — each describe travels whole with its header comment, and
no assertion, name or test was added, removed or edited.

⛔ MAX_FILE_BYTES is untouched. ⛔ #1135's assertions are not implemented here.

Same suite, either side

Same command, same tree, local both times.

	before (origin/main @ 6ed7b8dd)	after (43daabcf)
pnpm test (whole suite)	Test Files 124 passed (124) Tests 2900 passed | 1 skipped (2901)	Test Files 131 passed (131) Tests 2900 passed | 1 skipped (2901)
just this family	Test Files 1 passed (1) Tests 76 passed (76)	Test Files 8 passed (8) Tests 76 passed (76)

Test files +7 (the seven new siblings); test count identical. The name sets were
diffed too, not just counted — vitest run --reporter=verbose over the family
before and after, describe > it paths sorted and compared: 76 names, sets
identical.

The move itself is mechanically provable rather than eyeballed: the eleven line
ranges lifted out of the original tile [11, 2018] exactly once each, and their
concatenation is byte-for-byte identical to the original file's body (lines
11–2018, i.e. everything below the copyright header and the import block, which
is the only thing rewritten per file).

Resulting sizes — the durability half

file	bytes	headroom	% of cap
test/docs-drift.test.ts	10,778	91,622	10.5%
test/docs-src-tree-paths.test.ts	10,035	92,365	9.8%
test/docs-runnable-samples.test.ts	10,641	91,759	10.4%
test/docs-dashboard-tiles.test.ts	11,760	90,640	11.5%
test/docs-locale-callouts.test.ts	6,366	96,034	6.2%
test/docs-retired-personas.test.ts	10,764	91,636	10.5%
test/docs-metadata-counts.test.ts	14,724	87,676	14.4%
test/docs-declared-versions.test.ts	31,963	70,437	31.2%

Before: one file at 99,746 B / 2,654 B headroom / 97.4% full. After: the fullest
file is at 31.2%, and docs-drift.test.ts — where #1135 lands, because that is
where capCel stayed — is at 10.5% with 91,622 bytes of room. Sum is 107,031 B
against 99,746 B before; the 7.3KB is eight copyright/import blocks, the pointer
table below, and the per-file family notes.

How the thirteen families were grouped, and why

The card names four families and the dispatch listed twelve describes; the
file actually carried thirteen (the listing omitted
docs/STATUS.md states the current repository (#1011) at line 1810). All
thirteen are accounted for below.

Grouped by subject first, and by shared derivation where the two agree:

• docs-drift.test.ts (kept) — package docs do not drift from the flows they document. The family the file is named for and was written for, and the
  home of cap / capCel / CRON_LABEL / RULES, so the pointers in
  src/objects/_thresholds.ts, src/docs/crm_*.md, deal-threshold-parity and
  automation-docs-coverage still resolve without being touched. It carries the
  SPLIT BY FAMILY table.
• docs-src-tree-paths.test.ts — the three tree rules (maintainer inline,
  product inline, drawn diagrams). One subject on two axes, and they share
  inlineSrcDirs, treeSrcDirs and the three doc lists.
• docs-runnable-samples.test.ts — documented agent names (Wow #1 demo docs + script still POST the retired sales_copilot agent #606) and the
  action example (两处仍读/仍教 input.selectedIds（无下划线）—— 平台永远不会投递这个键，docs 示例会把下一个作者带进 #508 同一个坑 #813). Both guard a snippet a reader is invited to run, and
  both exist because a fenced block is prose to every other gate in the repo.
• docs-dashboard-tiles.test.ts — the dashboards page rules. Sole consumer
  of headingLabel() among these families.
• docs-locale-callouts.test.ts — translation callout parity (forecasting.zh-Hans/zh-Hant 相对英文页存在早于 #627 的整页漂移 —— 桶语义、承诺定义、缺失的汇总提示框需要整页重译 #736).
• docs-retired-personas.test.ts — the prose half of the retired-persona
  vocabulary (Docs drift (round 2 leftovers): ~39 product pages still name "Sales/Service Copilot" as a persona; config comment and RELEASE_STRATEGY.md still stale #612); the src/ half is test/persona-copy.test.ts and both
  read test/helpers/persona-vocabulary.ts.
• docs-metadata-counts.test.ts — the [17.0-rc2验收] README 与 marketplace 文档的对象/flow 数量仍是旧值(15 objects / 23 flows),rc.2 实际为 17 / 24 #729 count rule.
• docs-declared-versions.test.ts — app version (Docs drift (round 2 leftovers): ~39 product pages still name "Sales/Service Copilot" as a persona; config comment and RELEASE_STRATEGY.md still stale #612), protocol ([17.0-rc2验收] objectstack.config.ts 的 engines.protocol 仍是 ^17.0.0-rc.1,与 objectstack.manifest.json(rc.2)及 build 产物不一致 #728) and
  the docs/STATUS.md transcript (docs/STATUS.md 的「当前状态」全表过期：对象/流程/仪表盘/动作计数、平台版本、测试规模无一与 main 相符 #1011). These three are the one grouping where
  the mechanical seam decided it as much as the subject: PACKAGE_JSON,
  PLATFORM_VERSIONS and h2Sections are read by the Docs drift (round 2 leftovers): ~39 product pages still name "Sales/Service Copilot" as a persona; config comment and RELEASE_STRATEGY.md still stale #612 rules and the
  docs/STATUS.md 的「当前状态」全表过期：对象/流程/仪表盘/动作计数、平台版本、测试规模无一与 main 相符 #1011 rules, so separating them would mean either a duplicated derivation (the
  drift risk this whole file exists to prevent) or a new helper module — more
  moved surface than the split needs. It is the largest resulting file at 31.2%
  of cap, which is the price and it is a cheap one.

Pointer sweep — the #931 half

#814 split test/metadata-references.test.ts and left four comments pointing at
families that had moved; one of those is stale to this day. Every in-repo
reference was re-derived (grep -rn docs-drift, plus a grep for each moved
describe title and each moved identifier) and triaged one at a time.

Repointed (21 edits, each asserted to match exactly once before rewriting):

now names	was	in
docs-dashboard-tiles.test.ts	tile-guard / locale-convention pointers	heading-label.test.ts ×3, docs-service-index-analytics.test.ts ×2, docs-quick-tour-navigation.test.ts, content/docs/analytics/dashboards{,.zh-Hans,.zh-Hant}.mdx
docs-locale-callouts.test.ts	"compares callout counts"	sharing-coverage.test.ts ×2
docs-retired-personas.test.ts	the prose-side persona guard	persona-copy.test.ts ×2, test/helpers/persona-vocabulary.ts
docs-metadata-counts.test.ts	the #729 count rule	docs-readme-token-figures.test.ts, docs-view-rosters.test.ts, docs-role-hierarchy.test.ts, docs/STATUS.md
docs-declared-versions.test.ts	the protocol pairing / STATUS pins	objectstack.config.ts, docs/STATUS.md ×2, docs-view-rosters.test.ts

Plus the seven cross-references that were internal to the old file and became
cross-file the moment it was split ("the check above", "its own rule below",
"the flow rules at the top of this file", …) — each now names the file it means.
And two comments quoting the old size as the reason a rule shipped elsewhere
(docs-readme-token-figures.test.ts: "is 100,190 bytes"; docs-view-rosters.test.ts:
"that file is 97KB") were rewritten: the subject argument stands on its own and
the arithmetic one no longer holds.

Deliberately not edited, with the reason:

• src/objects/_thresholds.ts, src/docs/crm_{sales,admin,service,overview}.md,
  test/helpers/repo-root.ts, test/sharing-coverage.test.ts:622,
  test/automation-docs-coverage.test.ts ×2, test/deal-threshold-parity.test.ts,
  test/docs-revenue-approvals-navigation.test.ts — every one names something
  that stayed in docs-drift.test.ts (the thresholds, CRON_LABEL, the
  REPO_ROOT example) or makes no file-level claim at all.
• CHANGELOG.md and the three existing .changeset/*.md — dated records of what
  a past change did, true when written; none names a path that has moved.
• content/docs/whats-new{,.zh-Hans,.zh-Hant}.mdx — says "the repository's
  docs-drift guard" with no path. Left as prose; a reader who follows the name
  lands on the SPLIT BY FAMILY table.
• The four fenced trees — src/pages/, src/actions/, src/flows/,
  src/translations/ — belong to A lead flagged duplicate_status: suspected looks clean on its record page, and Convert Lead never mentions it — the duplicate converts into a second account, contact and opportunity #1207 in this batch and were not touched.
  Measured: they contain zero docs-drift references, so the fence cost this
  sweep nothing and nothing is left behind there.

Gates

pnpm verify — validate → typecheck → lint → lint:i18n-gate → hygiene
→ hygiene:tokens → build → test — green on 43daabcf, run under the
container's shared verify lock, exit code read from the wrapper's verdict line
rather than through a pipe:

os-verify-lock: VERDICT command-exit 0 · held the lock 118s (1m58s) · waited 0s

The gate that was red at 107KB, printing its own verdict:

  ✓ no source file over 100KB
  ✓ copyright header at the top of every .ts file
✓ source hygiene clean

typecheck covers the new files rather than merely passing beside them —
tsc --noEmit --listFiles puts all eight in the program (tsconfig.json
includes test/**/* with no *.test.ts exclusion), so its silence is a
measurement.

Changeset: .changeset/docs-drift-split-by-family.md, empty frontmatter — the
sanctioned "this PR releases nothing" declaration changeset-check.yml
documents. No skip-changeset label was applied.

Reported, not ridden along

• The card's option 2 (a 90%-of-cap hygiene advisory) is not in this PR. It
  is still worth its own card: this split fixes the instance, not the class —
  the cap is silent at 99% and red at 101%, and this is the third time
  (test/metadata-references.test.ts 距 100KB hygiene 上限只剩 817 字节 —— 下一个往里加测试的 PR 会被 gate 拦住 #814 · src/data/index.ts sits ~1.5KB under the 100KB hygiene cap, so the next seed edit fails pnpm hygiene #635 · this one) the condition was found at the moment it bit.
• With docs-drift.test.ts down to 10,778 B, the repo's largest source file is
  now test/flow-scheduled.test.ts at 71,456 B — 69.8% of the cap. Not urgent,
  but it is the next one an advisory would name.

---

Generated by Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
hotcrm	Ignored		Aug 25, 2026 2:09pm