docs: fix round-3 review findings — §/used-to/v1 residuals, zh stamp example, budget freeze honored

Delete the three §-citation residuals (web-app cordis.patch.yml, two client design.md §-headers); recast the two CSS used-to narrations and hmr's four v1 labels as current-state prose; narrow the zh exemption example to 'this cut' (「本版本」 legitimately renders 'This version'); extend the candidate gate list with the post-battery shapes (§\d with a committed-owner carve-out, 'used to', bare v1) on both sides and re-record; honor the over-target ceiling freeze — docs/AGENTS.md condensed to 1320 and the ceiling restored to 1320.
2026-08-09 21:11:59 +08:00
parent 8053dc38fa
commit eeacdd4790
11 changed files with 27 additions and 27 deletions
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-08-09-committed-artifact-citations.md
-2026-08-09-committed-artifact-citations.md: 890555df2968d706ba732aa8a3507bf81d187e3f
-2026-08-09-committed-artifact-citations.zh.md: 7eb446cca8fc0109814a8b2669a9a7031db9647b
+2026-08-09-committed-artifact-citations.md: 31b2d52b423a080579b3ca95cf077859d0bf4c91
+2026-08-09-committed-artifact-citations.zh.md: b69bb8743d10e2d1e194905d6d0de2d3d3667b1d
@@ -23,7 +23,7 @@ One repo-wide purge applied these rules across the prose surfaces, including the
 ## Alternatives considered

 - **Commit the design ledgers and audit documents so the ordinals resolve.** Rejected: session transcripts are working artifacts, not maintained references; committing them would create a parallel, ungated decision corpus beside Agent Notes, and their internal numbering would still drift.
- **A mechanical gate for the banned vocabulary.** Deferred: the vocabulary is unbounded natural language, and the audit's recall batteries need judgment to separate leakage from legitimate prose ("wait" the noun, contrastive "actually", runtime old/new states). A narrow high-precision gate (for example `\(decision \d`, `\(audit [A-Z]\d`, `\bcut \d`, `this cut`, a bare `\bT\d\b`, and `P-I`) is the candidate if the pattern recurs; review of the purge itself caught residuals in exactly those last four shapes, so they lead the candidate list.
+- **A mechanical gate for the banned vocabulary.** Deferred: the vocabulary is unbounded natural language, and the audit's recall batteries need judgment to separate leakage from legitimate prose ("wait" the noun, contrastive "actually", runtime old/new states). A narrow high-precision gate (for example `\(decision \d`, `\(audit [A-Z]\d`, `\bcut \d`, `this cut`, a bare `\bT\d\b`, `P-I`, `used to `, a bare `\bv1\b`, and `§\d` — the last excluding citations whose section numbering has a committed owner, such as web-styling.md's own §N) is the candidate if the pattern recurs; review of the purge itself caught residuals in exactly these post-battery shapes, so they lead the candidate list.
 - **Delete the rationale that cited dead artifacts.** Rejected: the factual clauses were preserved or restated; only citations, review choreography, and derivation transcripts were removed, per the prose standard's complete-proposition rule.

 ## Verification
@@ -16,14 +16,14 @@ Status: implemented
 - 决策有已提交归属文档的设计会话序号替换为该决策的名称——曾以「决策 21」记录的序号如今是「纯文本引用决策」，归属于 [web 输入状态机 note](../architecture/2026-07-25-web-input-machine-and-slash-pipeline.md)；该序号本身在仓库内无从解析，已全部移除。没有归属文档的序号予以删除，其事实性语句改写为可独立成立的表述。
 - 已修复的回归以现在时反事实句固定下来（「没有 X 就会发生 Y」、「朴素的 X 会……」），绝不写成仓库历史（「过去曾 Y」）。
 - 已实现的 Agent Note 陈述已交付的现实：「推迟到后续 PR」的说法若其目标已经交付，就改为点名那篇已交付的 note。
- 已录制的 fixture（测试前置数据）、快照与已归档的 Agent Note 不受此约束：已录制的模型输出与封存的历史保持原有行文。在 note 的变更故事段落内，历史阶段名称（「首版交付了 X」）属于安全的现状表述；指示性版本戳（「本版」「this cut」）在任何地方都仍被禁止。
+- 已录制的 fixture（测试前置数据）、快照与已归档的 Agent Note 不受此约束：已录制的模型输出与封存的历史保持原有行文。在 note 的变更故事段落内，历史阶段名称（「首版交付了 X」）属于安全的现状表述；指示性切次戳（"this cut"）在任何地方都仍被禁止。

 一次全仓库清理把这些规则应用到了各个行文表面，包括生成器持有的模板（`scripts/gen-doc-graphs.ts`、`scripts/gen-tool-catalog.ts`、typert 生成器的页面提示语，改后重新生成）、type-equiv 源码 JSDoc（改后把文档页重新粘贴）以及双语对侧文件（改后重新记录配对）。

 ## 曾考虑的替代方案

 - **把设计台账与审计文档提交入库，让序号得以解析。**不予采纳：会话 transcript 是工作产物，不是持续维护的参考资料；提交它们会在 Agent Note 之外形成一套平行且不受门禁约束的决策语料，其内部编号也仍会漂移。
- **为被禁词汇建一道机械门禁。**暂缓：这类词汇是无界的自然语言，审计中以查全为目标的成批检索需要人工判断，才能把泄漏与正当行文区分开（作名词的「wait」、表转折的「actually」、运行时的新旧状态）。若该模式再次出现，候选方案是一道窄而高查准的门禁（例如 `\(decision \d`、`\(audit [A-Z]\d`、`\bcut \d`、`this cut`、裸 `\bT\d\b` 与 `P-I`）；对本次清扫自身的评审恰好在后四种形态中发现残留，因此它们位居候选清单之首。
+- **为被禁词汇建一道机械门禁。**暂缓：这类词汇是无界的自然语言，审计中以查全为目标的成批检索需要人工判断，才能把泄漏与正当行文区分开（作名词的「wait」、表转折的「actually」、运行时的新旧状态）。若该模式再次出现，候选方案是一道窄而高查准的门禁（例如 `\(decision \d`、`\(audit [A-Z]\d`、`\bcut \d`、`this cut`、裸 `\bT\d\b`、`P-I`、`used to `、裸 `\bv1\b` 与 `§\d`——最后一种需排除章节编号有已提交归属的引用，如 web-styling.md 自身的 §N）；对本次清扫自身的评审恰好在这些电池之外的形态中发现残留，因此它们位居候选清单之首。
 - **删除引用了失效产物的设计理由。**不予采纳：事实性语句都得到保留或改写；依行文标准的完整命题规则，删掉的只有引用、评审编排与推导过程记录。

 ## 验证
@@ -4,7 +4,7 @@ This file defines document structure, Markdown tiers, writing rules, and `verify

 ## Document structure

-These rules apply to human-facing documentation; [Agent Notes](../.agents/notes/README.md) remain outside their scope. A [postmortem](postmortem/README.md) is an incident-scoped reference; chronology records evidence, not a teaching sequence. A document's subject and tree position fix its scope: describe its own subject at appropriate detail, describe direct children only by purpose, responsibility, and high-level behavior, and link to the owning descendant for lower-level detail. Document type does not widen that scope. A reference may be exhaustive only about its own subject. Testing mechanisms, fixtures, and harnesses belong at the lowest owning level; higher documents link there.
+These rules apply to human-facing documentation; [Agent Notes](../.agents/notes/README.md) remain outside their scope. A [postmortem](postmortem/README.md) is an incident-scoped reference; chronology records evidence, not a teaching sequence. A document's subject and tree position fix its scope: describe its own subject at appropriate detail and direct children only by purpose, responsibility, and high-level behavior; link to the owning descendant for lower-level detail. Document type does not widen that scope. A reference may be exhaustive only about its own subject. Testing mechanisms, fixtures, and harnesses belong at the lowest owning level; higher documents link there.

 Classify every in-scope document as a tutorial or reference. A tutorial follows an ordered path to an outcome and introduces only what each step needs. A reference defines a lookup scope and describes current behavior without depending on a teaching sequence. Separate substantial tutorial and reference content; use a clear structural boundary when either part is small.

@@ -14,7 +14,7 @@ Author in this order: locate the document in the tree; set its permitted detail;

 ## The tier taxonomy: one home per fact

-Each fact has one home: the tier whose job it is. Elsewhere, link to that home.
+Each fact has one home: the tier whose job it is; elsewhere, link there.

 | Tier | Job | Does NOT belong there |
 |---|---|---|
@@ -52,21 +52,21 @@ When the gate goes red:

 1. **Relocate** content that belongs in another tier; leave a one-line link if needed.
 2. **Condense** content that belongs here but can be shorter.
-3. **Raise** the ceiling only when the words truly need the space; justify the manifest diff in the PR. A too-low ceiling is a budget bug.
+3. **Raise** the ceiling only when the words need the space; justify the manifest diff in the PR. A too-low ceiling is a budget bug.

 Ceilings are guardrails, not reduction targets. At or below target, retain at least 5% headroom; above target, freeze the ceiling until relocation or condensation brings the document under target. Lower a ceiling only when the contract still has room, and raise it when content would otherwise be deleted. Targets: root `AGENTS.md` ≤ 1,600 words; `architecture.md` ≤ 1,800; subtree `AGENTS.md` ≤ 600, except `packages/AGENTS.md` ≤ 650 and this file ≤ 1,250; `packages/README.md` ≤ 600. Review governs unbudgeted tiers.

 ## The slop checklist

-Hunt these in any doc; the [dsh-doc-standards](../.agents/skills/dsh-doc-standards/SKILL.md) skill runs this list as an audit:
+Hunt these in any doc; [dsh-doc-standards](../.agents/skills/dsh-doc-standards/SKILL.md) runs this list as an audit:

- The same rule stated in more than one home. Grep a distinctive phrase; keep one home, convert the rest to links.
+- The same rule stated in more than one home. Grep a distinctive phrase; keep one home and link the rest.
 - Narrated history or war stories: "previously", "now", "no longer", "used to", "renamed", "was moved", PRs, or commits. State the current fact; link an Agent Note or postmortem when needed.
 - Implementation-status annotations in prose or diagrams ("implemented!", "future: …"). Status rots; the repo layout and package manifests carry it.
 - Hand-restated catalogs, JSDoc, or inventories of tests, packages, and status when source or a generator is authoritative.
 - Reasoning transcripts: step-by-step implementation narration, proof of obvious branches, test walkthroughs, or rejected local alternatives. Keep the resulting contract or durable rationale; delete the path used to derive it.
 - Rationale repeated beside sibling methods instead of once at the owning capability or helper.
- Paragraph walls: one paragraph carrying several rules and parenthetical asides. Split it, or demote the detail to the linked home.
+- Paragraph walls: one paragraph carrying several rules and parenthetical asides. Split it or demote the detail to its home.
 - Emphasis inflation: bold, CAPS, or "critically" everywhere means nothing stands out. Reserve emphasis for the clause that changes behavior.
 - Spec-speak in `implemented/` Agent Notes: "should", migration plans, acceptance checklists. An implemented Agent Note describes what is, per the [implemented-note instructions](../.agents/notes/implemented/AGENTS.md).

@@ -105,8 +105,8 @@

    # Dual-face: node half scans this very tree for dshClient rows, composes
    # window.__DSH_BOOT__, serves /plugins/<id>/client.js; browser half is the
-    # module table the shell kernel constructs before cordis exists (§4.7 —
-    # adopted as a plugin entry by the kernel, never fetched).
+    # module table the shell kernel constructs before cordis exists (adopted
+    # as a plugin entry by the kernel, never fetched).
    - id: modules
      name: '@deepseek-ai/dsh-client-modules'

@@ -30,7 +30,7 @@
 * Failure window: if prefetch rejects after invalidate, the module is left
 * unregistered while the OLD fiber keeps running untouched (teardown never
 * started) — degraded but recoverable, the next rebuilt frame retries from
- * scratch. Consistent with the v1 no-rollback policy below. Known dev-only
+ * scratch. Consistent with the no-rollback policy below. Known dev-only
 * race: a rebuilt frame overlapping a still-in-flight boot arrival shares
 * that arrival's task and may materialize the pre-rebuild bytes; the next
 * rebuilt frame self-heals.
@@ -57,7 +57,7 @@
 * apply opens a fresh channel. Frames arriving during the gap are lost —
 * acceptable for the dev channel, the next rebuild renotifies.
 *
- * Failure policy (v1): no rollback. An import failure leaves the entry
+ * Failure policy: no rollback. An import failure leaves the entry
 * fiberless (the next rebuilt frame retries from scratch); an apply failure
 * leaves a FAILED fiber for the shell's status projection. Both log loudly.
 */
@@ -135,7 +135,7 @@ export function apply(ctx: Context): void {
    // re-plugins under the entry context. Import failures are logged by
    // Entry._init and leave the entry fiberless (retryable).
    await entry.refresh()
-    // Surface apply failures loudly (v1: no rollback, FAILED state stays).
+    // Surface apply failures loudly (no rollback, FAILED state stays).
    await entry.fiber?.await()
  }

@@ -151,7 +151,7 @@ export function apply(ctx: Context): void {
        })
        break
      case 'graph':
-        // Connect-time snapshot, unused in v1. The loader's cached graph rev
+        // Connect-time snapshot, unused. The loader's cached graph rev
        // goes stale after rebuilds — harmless, since prefetch hits the
        // network anyway (host serves bundles no-cache); graph rev refresh
        // lands with the reconnect-handshake mechanism.
@@ -1,5 +1,5 @@
 /**
- * SlotsService terminal-design account (design.md §11-3 main landing):
+ * SlotsService terminal-design account:
 * built-in 'root', the three load-time throws (duplicate declaration /
 * undeclared contribution / cross-scope store handle), the renderer installation
 * contract (double install / not installed / non-root key), store instance
@@ -225,9 +225,9 @@
     so by construction now that all three sit INSIDE .scroll — a scrollbar
     that consumes layout space narrows the scrollport, which is their shared
     containing block, so it costs all three the same width on every engine.
-     Scrolling the textarea itself is what used to break this, and no property
-     fixed it: WebKit reserved gutter space for the overflow-y:auto textarea
-     and not for the overflow:hidden layers beside it, leaving them 8px apart
+     A textarea that scrolls itself would break this, and no property fixes
+     it: WebKit reserves gutter space for an overflow-y:auto textarea and not
+     for the overflow:hidden layers beside it, leaving them 8px apart
     (768 against 776) — worth 2 to 5 wrapped lines on a long draft. */
 }

@@ -3,10 +3,10 @@
 * 32px fields, and `border-l2` hairlines — the vocabulary GeneralSection and
 * the Button/Input primitives already use.
 *
- * Every color resolves through a `--dsw-alias-*` token. The section used to
- * name `--border` / `--surface` / `--text-*`, which nothing in this app
- * defines, so it always rendered the light-mode literals written as their
- * fallbacks and stayed light under the dark theme. */
+ * Every color resolves through a `--dsw-alias-*` token. Bare `--border` /
+ * `--surface` / `--text-*` names, which nothing in this app defines, would
+ * render the light-mode literals written as their fallbacks and stay light
+ * under the dark theme. */

 .section {
  display: flex;
@@ -1,4 +1,4 @@
-// Terminal-design compile-time samples (design.md §11 item 2): the four-share
+// Terminal-design compile-time samples: the four-share
 // composed register constraint — children spec x SlotMap alignment, renderSlot
 // key-set containment, store share matching, inject face completeness — plus
 // the full positive chain. Bodies with @ts-expect-error sites never run.
@@ -1,6 +1,6 @@
 {
  "AGENTS.md": 1782,
-  "docs/AGENTS.md": 1335,
+  "docs/AGENTS.md": 1320,
  "docs/architecture.md": 2174,
  "docs/cordis-primer.md": 600,
  "docs/defensive-patterns.md": 550,