From eeacdd4790ff71e7c65844dcc435bd6243d0fa3d Mon Sep 17 00:00:00 2001 From: Tianyi Cui <53024+tianyicui@users.noreply.github.com> Date: Sun, 9 Aug 2026 21:01:51 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20fix=20round-3=20review=20findings=20?= =?UTF-8?q?=E2=80=94=20=C2=A7/used-to/v1=20residuals,=20zh=20stamp=20examp?= =?UTF-8?q?le,=20budget=20freeze=20honored?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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-committed-artifact-citations.i18n.yaml | 4 ++-- .../2026-08-09-committed-artifact-citations.md | 2 +- .../2026-08-09-committed-artifact-citations.zh.md | 4 ++-- docs/AGENTS.md | 12 ++++++------ packages/bundle/web-app/cordis.patch.yml | 4 ++-- packages/client/hmr/src/client/index.ts | 8 ++++---- packages/client/runtime/tests/slots-service.spec.ts | 2 +- .../src/client/skeleton/InputBar.module.css | 6 +++--- .../ui-models/src/client/ModelsSection.module.css | 8 ++++---- packages/client/ui-slots/tests/type-chain.spec.tsx | 2 +- scripts/doc-budgets.manifest.json | 2 +- 11 files changed, 27 insertions(+), 27 deletions(-) diff --git a/.agents/notes/implemented/process/2026-08-09-committed-artifact-citations.i18n.yaml b/.agents/notes/implemented/process/2026-08-09-committed-artifact-citations.i18n.yaml index f3a910d338..9c9cb9b476 100644 --- a/.agents/notes/implemented/process/2026-08-09-committed-artifact-citations.i18n.yaml +++ b/.agents/notes/implemented/process/2026-08-09-committed-artifact-citations.i18n.yaml @@ -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 diff --git a/.agents/notes/implemented/process/2026-08-09-committed-artifact-citations.md b/.agents/notes/implemented/process/2026-08-09-committed-artifact-citations.md index 890555df29..31b2d52b42 100644 --- a/.agents/notes/implemented/process/2026-08-09-committed-artifact-citations.md +++ b/.agents/notes/implemented/process/2026-08-09-committed-artifact-citations.md @@ -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 diff --git a/.agents/notes/implemented/process/2026-08-09-committed-artifact-citations.zh.md b/.agents/notes/implemented/process/2026-08-09-committed-artifact-citations.zh.md index 7eb446cca8..b69bb8743d 100644 --- a/.agents/notes/implemented/process/2026-08-09-committed-artifact-citations.zh.md +++ b/.agents/notes/implemented/process/2026-08-09-committed-artifact-citations.zh.md @@ -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）；对本次清扫自身的评审恰好在这些电池之外的形态中发现残留，因此它们位居候选清单之首。 - **删除引用了失效产物的设计理由。**不予采纳：事实性语句都得到保留或改写；依行文标准的完整命题规则，删掉的只有引用、评审编排与推导过程记录。 ## 验证 diff --git a/docs/AGENTS.md b/docs/AGENTS.md index aa9db3dcff..04cd0f22f0 100644 --- a/docs/AGENTS.md +++ b/docs/AGENTS.md @@ -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). diff --git a/packages/bundle/web-app/cordis.patch.yml b/packages/bundle/web-app/cordis.patch.yml index d4fb2e8511..c3a66ebbf4 100644 --- a/packages/bundle/web-app/cordis.patch.yml +++ b/packages/bundle/web-app/cordis.patch.yml @@ -105,8 +105,8 @@ # Dual-face: node half scans this very tree for dshClient rows, composes # window.__DSH_BOOT__, serves /plugins//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' diff --git a/packages/client/hmr/src/client/index.ts b/packages/client/hmr/src/client/index.ts index 99f0938555..d0558bcecc 100644 --- a/packages/client/hmr/src/client/index.ts +++ b/packages/client/hmr/src/client/index.ts @@ -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. diff --git a/packages/client/runtime/tests/slots-service.spec.ts b/packages/client/runtime/tests/slots-service.spec.ts index 0b8ce8a301..a796d324ee 100644 --- a/packages/client/runtime/tests/slots-service.spec.ts +++ b/packages/client/runtime/tests/slots-service.spec.ts @@ -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 diff --git a/packages/client/ui-conversation/src/client/skeleton/InputBar.module.css b/packages/client/ui-conversation/src/client/skeleton/InputBar.module.css index fdbf28c74b..26f3532426 100644 --- a/packages/client/ui-conversation/src/client/skeleton/InputBar.module.css +++ b/packages/client/ui-conversation/src/client/skeleton/InputBar.module.css @@ -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. */ } diff --git a/packages/client/ui-models/src/client/ModelsSection.module.css b/packages/client/ui-models/src/client/ModelsSection.module.css index 8facc3a110..5203524517 100644 --- a/packages/client/ui-models/src/client/ModelsSection.module.css +++ b/packages/client/ui-models/src/client/ModelsSection.module.css @@ -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; diff --git a/packages/client/ui-slots/tests/type-chain.spec.tsx b/packages/client/ui-slots/tests/type-chain.spec.tsx index 64277edccc..a65f56a508 100644 --- a/packages/client/ui-slots/tests/type-chain.spec.tsx +++ b/packages/client/ui-slots/tests/type-chain.spec.tsx @@ -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. diff --git a/scripts/doc-budgets.manifest.json b/scripts/doc-budgets.manifest.json index 575f25b61b..2626cec2da 100644 --- a/scripts/doc-budgets.manifest.json +++ b/scripts/doc-budgets.manifest.json @@ -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,