docs: freshness stamps say what actually backs them

[claude]

Closes #1570

What was wrong

Two documents asserted their own freshness with a hand-written date that nothing produced and nothing checked:

docs/README.md:3             > Last reviewed: June 4, 2026
docs/feature-inventory.md:5  > 最后清点日期:2026-08-07。

⛔ Neither date is bumped. Bumping is the one move that must not happen: a stamp nothing produces is a claim about a review no review backs, and moving it converts an obviously stale assertion into a plausibly fresh false one.

⭐ The card's "only such stamp in the repo" claim is false — and the two did not resolve the same way

The seat note on the card measured the second stamp. This PR confirms both, and the measurement is what separates them.

	docs/README.md	docs/feature-inventory.md
Does the date name a real event?	No — introduced by a09ea91b "docs: reorganize HotCRM documentation", a reorganisation, not a review	Yes — 891aaa18 (#1052 / #1055), the full count-from-src/ compile that created the file
Ever updated after it was typed?	Never, on any ref	Never — correctly, no second full count has happened
Commits maintaining the file since	6 (a09ea91b..HEAD)	11 (891aaa18..HEAD)
Anything in-file depends on it?	No	Yes — ## 总览统计(清点时点) is scoped to it
Disposition	freshness claim removed, replaced by the real mechanism	date kept, reframed as an event date

docs/README.md — the pickaxe finds exactly one commit that ever wrote that string, and six commits have maintained the file since without touching it. So the file is maintained; its stamp never was. There is no cadence, no reviewer, no producer. The header now states the mechanism that actually keeps the index true — a PR that adds, moves, retires or renames a document under docs/ updates the tables in the same PR — and points at git log for the freshness record that cannot go stale. Reworded in place rather than deleted, following PR #1569 on this same file: "A negative instruction is enforceable by a reader; an absent one is not." All 12 links in the index resolve, so the per-change claim is measured, not aspirational.

docs/feature-inventory.md — ⚠️ deleting this stamp would have broken the file. 总览统计(清点时点) is scoped to that date, and those figures have drifted hard since:

metric          stamped(2026-08-07)   today(0f478744)
业务对象文件            17                18
流程文件                21                22
仪表板                   5                 7
报表                    10                 6
数据集                   9                10
profile                  6                 8
视图文件 / 页面 / AI技能  14 / 8 / 6        14 / 8 / 6   (unchanged)

Six of nine no longer match. The date is the only thing making that block true — remove it and a frozen reading starts reading as a claim about today's tree. So the stamp is kept and reframed, the shape PR #1705 (#1698) landed for the module-split inventory: it now says it is an event date rather than a freshness claim, that rows are maintained incrementally under the file's own 「锚点即真相」 rule, that incremental maintenance does not move the date, and — the do_not_hand_patch half — that hand-editing the overview figures to match today's tree is not a count, it swaps an honest old reading for an unsourced new one.

⭐ No deadlock is recreated. The #1698 lesson is that the only permitted action did not exist and the only available action was forbidden, so nothing happened. Every instruction either header now gives is one a maintainer can perform by hand today.

The sweep — re-derived by meaning, not by phrase

The two stamps share a semantics and share nothing lexically, so the English probe could never reach the Chinese one. The population was re-derived across docs/ (30 files) and content/docs/ (240 files) on three independent axes:

1. Every date-bearing line — 20[4-9] and YYYY-MM-DD shapes: 162 lines in 43 files. This is the net that does not depend on vocabulary at all.
2. Freshness vocabulary, both languages — last reviewed / reviewed / as of / valid as of / up-to-date / freshness / generated / regenerate / measured / maintained and 清点 / 复核 / 审阅 / 最后更新 / 最近更新 / 截至 / 时点 / 盘点 / 核对 / 快照 / 重新实测: 284 lines in 93 files.
3. Header-region scan — lines 1-14 of every .md / .mdx / .json in both trees, the structural signature both known stamps share.
4. Frontmatter keys (date:, updated:, reviewed:, last_updated:) across both trees: zero.

Difference set: empty. No third instance of this defect exists. The two known stamps are the whole population.

⭐ Found and classified as NOT this defect

A sweep that reports only its hits cannot be judged for what it missed, so:

Location	Why it is not this defect
docs/STATUS.md:3-9	The model answer, already landed: "This page states the CURRENT state of main — it is not a dated snapshot", with its figures pinned by test/docs-declared-versions.test.ts. A freshness statement with a real producer.
content/docs/whats-new.mdx:74	Declines to hand-maintain a release table and names the real producer (CHANGELOG.md compiled from .changeset/). The fixed form.
docs/architecture/module-split-inventory.json	The $maintenance / measured_at / $hand_edits blocks — this is the precedent's output (PR #1705), not an instance.
docs/architecture/module-split-plan.md:4	"Measured against" anchors to the inventory's measured_at.commit — names its referent.
docs/archive/** (7 files, 40+ dated lines)	docs/archive/README.md carries a blanket, accurate disclaimer: "preserved for context only… may contain old object counts, old protocol versions". A frozen tree that says it is frozen.
content/docs/administration/sandbox-and-releases.mdx:12 (×3 locales)	"The page was checked claim by claim against … (spec 17.0.0-rc.6)" — a past-tense measurement record naming its referent version. Asserts no currency.
docs/developers/api_reference.md:12, docs/MAINTENANCE.md:33,44, docs/ARCHITECTURE.md ×5, docs/DEPLOYMENT.md:95, docs/README.md:66	*Supersedes … — 2026-08-31 ruling, item 5.* notes. Historical records of a past removal, not freshness claims.
docs/requirements/0001-…md:8 (**Raised**: 2026-06-21)	An event date on a requirement — when it was raised, not how fresh the file is.
content/docs/sales/forecasting.* (28 hits), service/knowledge-base.mdx:8, administration/state-machines.*	快照 / snapshot / "well-maintained" describing the product's data model. Not about the document.
content/docs/revenue/approvals.*, billing-handoff.*, customization/testing-and-ci.*, guides/files-and-comments.*	Dates inside sample payloads, audit-trail examples and file-naming advice.

⚠️ One near-miss that is a real defect of a different class — filed, not fixed here

content/docs/reference/security-and-compliance.mdx:13-14 (and its .zh-Hans / .zh-Hant twins) reads:

"re-measured against 17.2.0 on 2026-09-03, the version package.json has pinned since 2026-09-01"

package.json now pins 17.3.0 — 71a34523, "chore(deps): upgrade the ObjectStack platform to 17.3.0 (#1577)", landed 2026-09-04. The measurement stamp itself is a true historical statement; the appended present-tense clause about the current pin has drifted.

⛔ Deliberately not fixed here. Editing 17.2.0 → 17.3.0 would assert a re-measurement against 17.3.0 that nobody performed — the identical forbidden move this card rules against, one file over. An honest fix requires actually re-auditing the page's claims against 17.3.0, which is a different card with a different surface (3 locale files). This is drift in a transcribed machine fact (AGENTS.md documentation-discipline rule 5, the #610 / #965 / #977 / #1228 / #1536 lineage), not a producerless freshness stamp.

Measurements the card and dispatch flagged as UNVERIFIED

1. ⚠️ "three commits since" — stale, and low. Re-taken on 0f478744 with exact range syntax: 6 commits touch docs/README.md after the stamp commit (b64c2048, 36dc36c0, 891aaa18, 23dacc9b, 72d56d23, 7ba260b0). The card's 1812a9bd / e2fddae8 are pre-squash shas not on main. And the premise re-read holds: the file is maintained; only its stamp is not — which is precisely why the replacement describes maintenance rather than deleting the line.
2. ⚠️ PR refactor(views): retire the duplicate SIMPLE layout example from the lead showcase #1718 — branched from merged main at 0f478744, which contains 1a21aee2 (refactor(views): retire the duplicate SIMPLE layout example from the lead showcase #1718, the LEA-015 row). Every reading of docs/feature-inventory.md above is taken on that ref.
3. ⚠️ docs/feature-inventory.md QUO-010/QUO-012 credit crm_product with three capabilities that were removed #1536 is CLOSED as completed (2026-09-06T00:37:57Z, PR docs(inventory): drop the crm_product capabilities the catalog no longer has #1619). Its ruling covers rows QUO-010 (:119) and QUO-012 (:121) and its declared file surface was those rows plus a changeset. This PR touches line 5 only, in the header block. No overlap. ⭐ Its 「锚点即真相」 maintenance rule is exactly what the new header now cites as the mechanism that maintains rows between counts.
4. ⚠️ Not assumed to be two — see the sweep above; the difference set is empty.

Changeset — derived from precedent

'hotcrm': patch. Derived by checking what every recent commit touching these two exact files used, not by category:

• docs/README.md: b64c2048 (docs(readme): stop ordering the field transcript back into the tree (#1494) #1569) → patch
• docs/feature-inventory.md: 16705571 (docs(inventory): drop the crm_product capabilities the catalog no longer has #1619) → patch; e5de6974 (docs: three transcribed machine facts in docs/ become pointers (#1478) #1486, the closest shape — MAINTENANCE.md + feature-inventory.md) → patch
• Empty frontmatter ("releases nothing") is used for docs/architecture/** design artifacts: 36dc36c0 (docs(architecture): module-boundary inventory and split plan for the ADR-0130 multi-package artifact (#1448) #1449) and inventory-header-says-what-can-be-done.md (docs(architecture): make the module-split inventory's header true #1705).

Both files here sit in the patch lineage, so this is not one of the 88 empty-frontmatter declarations. No src/ changes; the built artifact is identical.

No new gate, no new test

2026-08-31 ruling item 3 keeps gate-type mechanisms on the platform. Neither stamp is load-bearing to any guard — measured: zero references to Last reviewed, 最后清点, 清点日期 or feature-inventory anywhere in test/, scripts/, .github/, src/ or e2e/. docs/README.md is read by test/docs-src-tree-paths.test.ts (TREE_DOCS, TREE_DIAGRAM_DOCS) and test/docs-role-hierarchy.test.ts; all three read src/DIR/ paths and a forbidden-term list, none pins the header, and the new text introduces no forbidden spelling. Green either side.

content/docs/releases/ untouched. CHANGELOG.md and existing .changeset/*.md read only.

Verification — pnpm verify fully green, every stage read from the log

VERIFY_EXIT=0. All eight stages ran:

validate        ✓ Validation passed (1201ms)
typecheck       tsc --noEmit — no diagnostics
lint            objectstack lint — clean
i18n gate       ✓ 0 `i18n/missing-*` issues
hygiene         ✓ source hygiene clean (incl. "no raw control bytes in first-party files")
hygiene:tokens  ✓ source token ratchet clean — authored total ~136,683 (ceiling ~140,000)
build           ✓ Build complete (1444ms)
test            Test Files 161 passed (161) · Tests 3410 passed | 1 skipped (3411)

The token ratchet reads src/**/*.ts only, so a docs-only diff cannot move it — and it did not.

---

Generated by Claude Code

[vercel]

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

1 Skipped Deployment

Project	Deployment	Actions	Updated
hotcrm	Ignored		Sep 6, 2026 2:09pm UTC