From 1e13091f559d91fd0502e4e32a03471ece23c5a5 Mon Sep 17 00:00:00 2001 From: Tianyi Cui <53024+tianyicui@users.noreply.github.com> Date: Mon, 5 Oct 2026 18:18:42 +0800 Subject: [PATCH] docs: preserve instruction meaning and clarify reuse policy --- .../2026-10-05-reuse-ecosystem-declarations.i18n.yaml | 4 ++-- .../process/2026-10-05-reuse-ecosystem-declarations.md | 4 ++-- .../2026-10-05-reuse-ecosystem-declarations.zh.md | 4 ++-- AGENTS.md | 10 +++++----- docs/AGENTS.md | 2 +- scripts/doc-budgets.manifest.json | 2 +- 6 files changed, 13 insertions(+), 13 deletions(-) diff --git a/.agents/notes/implemented/process/2026-10-05-reuse-ecosystem-declarations.i18n.yaml b/.agents/notes/implemented/process/2026-10-05-reuse-ecosystem-declarations.i18n.yaml index 300c47e026..deb5b655f2 100644 --- a/.agents/notes/implemented/process/2026-10-05-reuse-ecosystem-declarations.i18n.yaml +++ b/.agents/notes/implemented/process/2026-10-05-reuse-ecosystem-declarations.i18n.yaml @@ -9,8 +9,8 @@ en: 549330d38e58af03 zh: be91a1cc6d5d5004 /agent-note-reuse-ecosystem-declarations/decision: - en: f9d931cab44e8cc2 - zh: 1560a1b50717f00b + en: b86e80cdb73058b8 + zh: 8a1143246b38a1d5 /agent-note-reuse-ecosystem-declarations/alternatives-considered: en: e323031a81d83039 zh: c5bce4f4257b01da diff --git a/.agents/notes/implemented/process/2026-10-05-reuse-ecosystem-declarations.md b/.agents/notes/implemented/process/2026-10-05-reuse-ecosystem-declarations.md index 04a7cb6c6b..dd28b72e31 100644 --- a/.agents/notes/implemented/process/2026-10-05-reuse-ecosystem-declarations.md +++ b/.agents/notes/implemented/process/2026-10-05-reuse-ecosystem-declarations.md @@ -10,9 +10,9 @@ Custom declarations can duplicate information that package ecosystems already de ## Decision -DSH reuses established ecosystem declarations, formats, and meanings when they satisfy its requirements. Readers use maintained parsers and validators. Catalogs and user interfaces derive their data from the original declarations. A generated projection may omit unused fields or normalize display data, but it preserves the source meaning and documents the projection. +DSH reuses established ecosystem declarations, formats, and meanings when they satisfy its requirements. Readers use maintained parsers and validators. Catalogs and user interfaces derive their data from the original declarations. A generated projection may omit unused fields or normalize display data, but it preserves the source meaning. The owning package README or generator JSDoc documents the projection rules. -A new field or changed meaning requires a specific unmet requirement and a documented difference from the ecosystem rule. For npm package metadata, reuse package identity, version and range syntax, and person fields. DSH-specific composition, localized display data, and host enforcement still require explicit DSH rules. +A new field or changed meaning requires a specific unmet requirement and a documented difference from the ecosystem rule. When authors define npm package metadata, they reuse npm's package identity, version and range syntax, and person fields. DSH-specific composition, localized display data, and host enforcement still require explicit DSH rules. The [dependency policy](2026-07-26-dependencies-over-hand-rolling.md) governs dependency selection. The [public manifest decision](../architecture/2026-09-10-public-package-manifest.md) governs the selected npm fields and DSH declarations. These decisions retain their ownership; this policy governs reuse of declarations and their interpretation. diff --git a/.agents/notes/implemented/process/2026-10-05-reuse-ecosystem-declarations.zh.md b/.agents/notes/implemented/process/2026-10-05-reuse-ecosystem-declarations.zh.md index c20d38e2e7..5657df18f9 100644 --- a/.agents/notes/implemented/process/2026-10-05-reuse-ecosystem-declarations.zh.md +++ b/.agents/notes/implemented/process/2026-10-05-reuse-ecosystem-declarations.zh.md @@ -10,9 +10,9 @@ Status: implemented ## 决策 -既有生态声明、格式和含义满足需求时，DSH 复用它们。读取方使用持续维护的解析器和校验器。目录与用户界面从原始声明派生数据。生成的投影可以省略未使用的字段，或归一化显示数据，但须保留原始含义并记录投影规则。 +既有生态声明、格式和含义满足需求时，DSH 复用它们。读取方使用持续维护的解析器和校验器。目录与用户界面从原始声明派生数据。生成的投影可以省略未使用的字段，或归一化显示数据，但须保留原始含义。所属包的 README 或生成器的 JSDoc 记录投影规则。 -新增字段或改变含义时，必须说明尚未满足的具体需求，并记录与生态规则的差异。对于 npm 包元数据，复用包身份、版本与范围语法，以及人员字段。DSH 特有的组合、本地化显示数据和宿主检查仍须明确的 DSH 规则。 +新增字段或改变含义时，必须说明尚未满足的具体需求，并记录与生态规则的差异。作者定义 npm 包元数据时，复用 npm 的包身份、版本与范围语法，以及人员字段。DSH 特有的组合、本地化显示数据和宿主约束的强制执行仍须明确的 DSH 规则。 [依赖政策](2026-07-26-dependencies-over-hand-rolling.zh.md)负责依赖选择。[公共 manifest 决策](../architecture/2026-09-10-public-package-manifest.zh.md)负责选取的 npm 字段与 DSH 声明。这些决策继续负责各自的范围；本政策负责声明及其解释的复用。 diff --git a/AGENTS.md b/AGENTS.md index 36a0325ab3..864102877b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -137,7 +137,7 @@ Real-API tests/demos read `DEEPSEEK_API_KEY`, optional `DEEPSEEK_BASE_URL`, and - **Plugins, not loop changes**: new behavior goes on documented extension points; changing `agent-loop` requires updating docs/architecture.md. - **A capability seam comprises Service Definition / Service Provider / Consumer roles.** It is complete, never one role; split only when roles evolve independently ([glossary](docs/glossary.md#capability-seam)). - **Prefer maintained dependencies over hand-rolling** when they genuinely delete owned code and tests ([policy](.agents/notes/implemented/process/2026-07-26-dependencies-over-hand-rolling.md)). -- **Reuse ecosystem declarations, formats, and meanings when suitable.** Use maintained parsers and validators; derive catalog and UI data from original declarations. New fields or changed meanings require a documented unmet requirement ([policy](.agents/notes/implemented/process/2026-10-05-reuse-ecosystem-declarations.md)). +- **Reuse ecosystem declarations, formats, and meanings when they meet DSH requirements.** Use maintained parsers and validators; derive catalog and UI data from original declarations. New fields or changed meanings require a documented unmet requirement and difference from ecosystem rules ([policy](.agents/notes/implemented/process/2026-10-05-reuse-ecosystem-declarations.md)). - **Explicit > implicit at package boundaries**: defaulting is an explicit `resolve(request): Spec` step in the owning implementation, never a hidden `?? default` inside `run()` (the `dsh-shell` request/spec split is the template). - **No hardcoded tunables in plugins**: deployment-varying choices are validated `Config` fields changeable from cordis.yml; a `DEFAULT_*` constant or test hook is not configurability. Protocol constants, external specs, and security invariants stay fixed. - **Misconfiguration fails loud** at load when self-contained, otherwise at the earliest resolvable point; never silently skip a missing referent. @@ -168,15 +168,15 @@ Read [docs/defensive-patterns.md](docs/defensive-patterns.md) before lifecycle, ## Type safety and documentation -Compile under `strict: true` and `noImplicitAny`; every remaining `any` explains why narrowing is infeasible. Every module/export has concise JSDoc for non-obvious contracts; function-like exports include `@param`/`@returns` (`verify-export-jsdoc`). Heritage-declared members, plugin-protocol slots, and constructors keep docs at the declaring Service Definition, protocol, or class. +Everything compiles under `strict: true` with `noImplicitAny`; every remaining `any` explains why narrowing is infeasible. Every module and export has concise JSDoc for its non-obvious contract; function-like exports include `@param`/`@returns`, as enforced by `verify-export-jsdoc`. Heritage-declared members, plugin-protocol slots, and constructors keep their docs at the declaring Service Definition, protocol, or class. -Comments/docs state complete contracts/context directly and concretely, without metaphors, reasoning transcripts, control-flow/test narration, review history, or code restatement. Prefer exact subjects to `contract`, `boundary`, or `shape`. `contract` names preconditions, postconditions, invariants, compatibility promises, or other obligations that callers/callees, implementers/providers, and producers/consumers rely on; `boundary` names a literal process, wire, security, transaction, or lifecycle boundary. Preserve behavior, failure, timing, ownership, safe-use facts, and rationale links; follow [dsh-prose-standard](.agents/skills/dsh-prose-standard/SKILL.md). Executed top-level gates check mechanically checkable invariants; demonstrate each changed acceptance path rejects an invalid case. Use narrow, justified exceptions; never disable rules globally. +Comments and docs state complete contracts and context, not reasoning transcripts. Use direct, concrete terms. Do not use metaphors. Before writing `contract`, `boundary`, or `shape`, ask whether a more exact term names the subject: write `response fields`, `JSON validation`, or `ESM exports` instead of `response shape`, `validation boundary`, or `module shape`. Keep `contract` for preconditions, postconditions, invariants, compatibility promises, and other obligations that callers, callees, implementers, providers, producers, or consumers rely on. Keep a literal process, wire, security, transaction, or lifecycle boundary. Do not narrate control flow or tests, preserve review history, or restate code. Keep behavior, failure, timing, ownership, and safe-use facts; link the rationale. Use [dsh-prose-standard](.agents/skills/dsh-prose-standard/SKILL.md) for decisions. Wire mechanically checkable invariants into an executed top-level gate and prove each changed acceptance path rejects an invalid case. Use narrow, justified exceptions instead of disabling a rule globally. -Every code change updates affected README/JSDoc contracts together. [docs/AGENTS.md](docs/AGENTS.md) governs routine bilingual work, current-state prose, one physical line/paragraph, one home/fact, and word budgets; `dsh-translate-docs` requires explicit user invocation. +Docs accompany every code change: update affected README and JSDoc contracts together. Routine bilingual work follows [docs/AGENTS.md](docs/AGENTS.md); only explicit user invocation may run `dsh-translate-docs`. Current-state prose, one physical line per paragraph, one home per fact, and word budgets live there. ## Editing these instructions -Root and `packages/` `CLAUDE.md` symlink `AGENTS.md`; edit targets. Keep rules self-contained, linking high-level docs. Condense without losing clarity; raise `verify-doc-budgets` ceilings only when required content needs more space. +`CLAUDE.md` symlinks `AGENTS.md` at root and `packages/`; edit the real file. Keep each rule self-contained while linking high-level docs. Condense when clarity survives; raise a `verify-doc-budgets` ceiling when the required content genuinely needs more space. ## Vendoring policy diff --git a/docs/AGENTS.md b/docs/AGENTS.md index b524a84b3e..6e2c5527b4 100644 --- a/docs/AGENTS.md +++ b/docs/AGENTS.md @@ -55,7 +55,7 @@ When the gate goes red: 2. **Condense** content that belongs here but can be shorter. 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 document still has room. Targets: root `AGENTS.md` ≤ 1,960; `architecture.md` ≤ 2,400; subtree `AGENTS.md` ≤ 600, except `packages/AGENTS.md` ≤ 750 and this file ≤ 1,320; `packages/README.md` ≤ 994; plus `cordis-primer.md` 600, `defensive-patterns.md` 550, `testing.md` 1,300, `examples/AGENTS.md` 310. 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 document still has room. Targets: root `AGENTS.md` ≤ 2,060; `architecture.md` ≤ 2,400; subtree `AGENTS.md` ≤ 600, except `packages/AGENTS.md` ≤ 750 and this file ≤ 1,320; `packages/README.md` ≤ 994; plus `cordis-primer.md` 600, `defensive-patterns.md` 550, `testing.md` 1,300, `examples/AGENTS.md` 310. Review governs unbudgeted tiers. ## The slop checklist diff --git a/scripts/doc-budgets.manifest.json b/scripts/doc-budgets.manifest.json index 2eba3f4c17..670ff02765 100644 --- a/scripts/doc-budgets.manifest.json +++ b/scripts/doc-budgets.manifest.json @@ -1,5 +1,5 @@ { - "AGENTS.md": 1960, + "AGENTS.md": 2060, "docs/AGENTS.md": 1320, "docs/architecture.md": 2410, "docs/cordis-primer.md": 600,