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.
This commit is contained in:
Tianyi Cui
2026-08-09 21:01:51 +08:00
parent 8053dc38fa
commit eeacdd4790
11 changed files with 27 additions and 27 deletions

View File

@@ -2,5 +2,5 @@
# side as of the last confirmed-consistent state. Both languages carry equal authority; # 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: # 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 # 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.md: 31b2d52b423a080579b3ca95cf077859d0bf4c91
2026-08-09-committed-artifact-citations.zh.md: 7eb446cca8fc0109814a8b2669a9a7031db9647b 2026-08-09-committed-artifact-citations.zh.md: b69bb8743d10e2d1e194905d6d0de2d3d3667b1d

View File

@@ -23,7 +23,7 @@ One repo-wide purge applied these rules across the prose surfaces, including the
## Alternatives considered ## 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. - **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. - **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 ## Verification

View File

@@ -16,14 +16,14 @@ Status: implemented
- 决策有已提交归属文档的设计会话序号替换为该决策的名称——曾以「决策 21」记录的序号如今是「纯文本引用决策」归属于 [web 输入状态机 note](../architecture/2026-07-25-web-input-machine-and-slash-pipeline.md);该序号本身在仓库内无从解析,已全部移除。没有归属文档的序号予以删除,其事实性语句改写为可独立成立的表述。 - 决策有已提交归属文档的设计会话序号替换为该决策的名称——曾以「决策 21」记录的序号如今是「纯文本引用决策」归属于 [web 输入状态机 note](../architecture/2026-07-25-web-input-machine-and-slash-pipeline.md);该序号本身在仓库内无从解析,已全部移除。没有归属文档的序号予以删除,其事实性语句改写为可独立成立的表述。
- 已修复的回归以现在时反事实句固定下来(「没有 X 就会发生 Y」、「朴素的 X 会……」),绝不写成仓库历史(「过去曾 Y」 - 已修复的回归以现在时反事实句固定下来(「没有 X 就会发生 Y」、「朴素的 X 会……」),绝不写成仓库历史(「过去曾 Y」
- 已实现的 Agent Note 陈述已交付的现实:「推迟到后续 PR」的说法若其目标已经交付就改为点名那篇已交付的 note。 - 已实现的 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改后把文档页重新粘贴以及双语对侧文件改后重新记录配对 一次全仓库清理把这些规则应用到了各个行文表面,包括生成器持有的模板(`scripts/gen-doc-graphs.ts``scripts/gen-tool-catalog.ts`、typert 生成器的页面提示语改后重新生成、type-equiv 源码 JSDoc改后把文档页重新粘贴以及双语对侧文件改后重新记录配对
## 曾考虑的替代方案 ## 曾考虑的替代方案
- **把设计台账与审计文档提交入库,让序号得以解析。**不予采纳:会话 transcript 是工作产物,不是持续维护的参考资料;提交它们会在 Agent Note 之外形成一套平行且不受门禁约束的决策语料,其内部编号也仍会漂移。 - **把设计台账与审计文档提交入库,让序号得以解析。**不予采纳:会话 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);对本次清扫自身的评审恰好在这些电池之外的形态中发现残留,因此它们位居候选清单之首。
- **删除引用了失效产物的设计理由。**不予采纳:事实性语句都得到保留或改写;依行文标准的完整命题规则,删掉的只有引用、评审编排与推导过程记录。 - **删除引用了失效产物的设计理由。**不予采纳:事实性语句都得到保留或改写;依行文标准的完整命题规则,删掉的只有引用、评审编排与推导过程记录。
## 验证 ## 验证

View File

@@ -4,7 +4,7 @@ This file defines document structure, Markdown tiers, writing rules, and `verify
## Document structure ## 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. 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 ## 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 | | 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. 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. 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. 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 ## 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. - 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. - 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. - 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. - 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. - 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. - 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). - 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).

View File

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

View File

@@ -30,7 +30,7 @@
* Failure window: if prefetch rejects after invalidate, the module is left * Failure window: if prefetch rejects after invalidate, the module is left
* unregistered while the OLD fiber keeps running untouched (teardown never * unregistered while the OLD fiber keeps running untouched (teardown never
* started) — degraded but recoverable, the next rebuilt frame retries from * 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 * 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 * that arrival's task and may materialize the pre-rebuild bytes; the next
* rebuilt frame self-heals. * rebuilt frame self-heals.
@@ -57,7 +57,7 @@
* apply opens a fresh channel. Frames arriving during the gap are lost — * apply opens a fresh channel. Frames arriving during the gap are lost —
* acceptable for the dev channel, the next rebuild renotifies. * 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 * fiberless (the next rebuilt frame retries from scratch); an apply failure
* leaves a FAILED fiber for the shell's status projection. Both log loudly. * 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 // re-plugins under the entry context. Import failures are logged by
// Entry._init and leave the entry fiberless (retryable). // Entry._init and leave the entry fiberless (retryable).
await entry.refresh() 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() await entry.fiber?.await()
} }
@@ -151,7 +151,7 @@ export function apply(ctx: Context): void {
}) })
break break
case 'graph': 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 // goes stale after rebuilds — harmless, since prefetch hits the
// network anyway (host serves bundles no-cache); graph rev refresh // network anyway (host serves bundles no-cache); graph rev refresh
// lands with the reconnect-handshake mechanism. // lands with the reconnect-handshake mechanism.

View File

@@ -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 / * built-in 'root', the three load-time throws (duplicate declaration /
* undeclared contribution / cross-scope store handle), the renderer installation * undeclared contribution / cross-scope store handle), the renderer installation
* contract (double install / not installed / non-root key), store instance * contract (double install / not installed / non-root key), store instance

View File

@@ -225,9 +225,9 @@
so by construction now that all three sit INSIDE .scroll — a scrollbar so by construction now that all three sit INSIDE .scroll — a scrollbar
that consumes layout space narrows the scrollport, which is their shared that consumes layout space narrows the scrollport, which is their shared
containing block, so it costs all three the same width on every engine. 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 A textarea that scrolls itself would break this, and no property fixes
fixed it: WebKit reserved gutter space for the overflow-y:auto textarea it: WebKit reserves gutter space for an overflow-y:auto textarea and not
and not for the overflow:hidden layers beside it, leaving them 8px apart for the overflow:hidden layers beside it, leaving them 8px apart
(768 against 776) — worth 2 to 5 wrapped lines on a long draft. */ (768 against 776) — worth 2 to 5 wrapped lines on a long draft. */
} }

View File

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

View File

@@ -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 // composed register constraint — children spec x SlotMap alignment, renderSlot
// key-set containment, store share matching, inject face completeness — plus // key-set containment, store share matching, inject face completeness — plus
// the full positive chain. Bodies with @ts-expect-error sites never run. // the full positive chain. Bodies with @ts-expect-error sites never run.

View File

@@ -1,6 +1,6 @@
{ {
"AGENTS.md": 1782, "AGENTS.md": 1782,
"docs/AGENTS.md": 1335, "docs/AGENTS.md": 1320,
"docs/architecture.md": 2174, "docs/architecture.md": 2174,
"docs/cordis-primer.md": 600, "docs/cordis-primer.md": 600,
"docs/defensive-patterns.md": 550, "docs/defensive-patterns.md": 550,