Merge pull request #844 from deepseek-harness/codex/experimental-plugin-group-note

docs: add experimental and internal package group

.agents/notes/implemented/architecture/2026-07-28-experimental-plugin-package-group.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# 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/architecture/2026-07-28-experimental-plugin-package-group.md
+2026-07-28-experimental-plugin-package-group.md: 1ebae5dbb16d4c966f94ffde69fb0cb9bc163d80
+2026-07-28-experimental-plugin-package-group.zh.md: f204ecd052de03d0cf347e2c770feb0ea33966c7

.agents/notes/implemented/architecture/2026-07-28-experimental-plugin-package-group.md

@@ -0,0 +1,33 @@
+# Agent Note: Experimental and internal package group
+
+Status: implemented
+
+English | [中文](2026-07-28-experimental-plugin-package-group.zh.md)
+
+## Problem
+
+The [package hierarchy](../../../../packages/README.md) groups plugins by product role, but it cannot distinguish release packages from prototypes or internal-only packages. The team needs an obvious shared place for useful work that is not part of the official release.
+
+## Decision
+
+The subtree rules in [`packages/experimental/AGENTS.md`](../../../../packages/experimental/AGENTS.md) make `packages/experimental/<pkg>/` the required home for Cordis plugin packages whose whole public contract is experimental or internal-only. Package names remain `@deepseek-ai/dsh-<pkg>`.
+
+The group is the team's in-repository place to share engineering and product-manager prototypes: members can discover, run, review, and extend one another's work against the real plugin graph without implying product support.
+
+Official releases exclude this directory. A package enters a release only after moving to its product-role group; release packages cannot take runtime dependencies on packages here. Examples may use them, while any other runtime dependent also belongs here. Tests may use them as development dependencies.
+
+Experimental packages carry no stability, compatibility, migration, or support promise: they may change APIs, configuration, or data, or disappear without deprecation or migration. Internal-only packages may define narrower internal contracts but make no public release promise. Neither status relaxes engineering, security, documentation, lifecycle, testing, or snapshot requirements.
+
+The pending `@deepseek-ai/dsh-tui-session-changes` `/diff` viewer and `/btw` plugin are examples governed by this rule. Promotion into an official release requires explicit review of the public contract, limitations, test evidence, and a named owner accepting stable-package obligations.
+
+## Alternatives considered
+
+**Keep experimental and internal-only packages in product-role groups with README labels.** Labels are easy to miss and cannot enforce dependency boundaries.
+
+**Treat every package as experimental until the first tagged release.** This provides no durable incubation boundary.
+
+**Develop prototypes and internal packages elsewhere.** This loses the real plugin graph, examples, snapshots, and lifecycle checks needed to evaluate them.
+
+## Consequences
+
+The path makes release exclusion and dependency blast radius visible while retaining the real plugin graph for team sharing. It gives up product-role colocation and creates path churn on promotion, while the npm name remains stable. The subtree rules, repository [current-owner/current-need rule](../../../../packages/AGENTS.md), and unchanged engineering gates limit junk-drawer growth. Because official release tooling does not yet exist, contributor policy enforces the exclusion; when such tooling is added, the directory is its required exclusion boundary.

.agents/notes/implemented/architecture/2026-07-28-experimental-plugin-package-group.zh.md

@@ -0,0 +1,33 @@
+# Agent Note: 实验性与内部专用包（package）分组
+
+Status: implemented
+
+[English](2026-07-28-experimental-plugin-package-group.md) | 中文
+
+## 问题
+
+[包层级结构](../../../../packages/README.md)按产品角色对插件分组，但无法区分发布包、原型和内部专用包。团队需要一个明确的共享位置，存放不属于官方发布版本的有价值成果。
+
+## 决策
+
+[`packages/experimental/AGENTS.md`](../../../../packages/experimental/AGENTS.md) 中的子树规则要求所有公开契约整体处于实验状态或仅限内部使用的 Cordis 插件包位于 `packages/experimental/<pkg>/`。包名仍为 `@deepseek-ai/dsh-<pkg>`。
+
+该分组供团队在仓库内共享工程人员和产品经理制作的原型：成员可以基于真实插件图发现、运行、评审并扩展彼此的原型，但这不代表产品会提供支持。
+
+官方发布版本不包含此目录。包只有移入对应的产品角色分组后才会纳入发布版本；发布包不得在运行时依赖此处的包。示例可以使用这些包；其他任何运行时依赖方也必须位于此处。测试可以将它们用作开发依赖。
+
+实验性包不提供稳定性、兼容性、迁移或支持保证：其 API、配置或数据可以变更，包也可以移除，均不提供弃用期或迁移路径。内部专用包可以定义范围更窄的内部契约，但不作公开发布承诺。无论哪种状态，都不降低仓库对工程、安全、文档、生命周期、测试或快照的要求。
+
+尚待完成的 `@deepseek-ai/dsh-tui-session-changes` `/diff` 查看器和 `/btw` 插件都受这项规则约束。将包提升为稳定包并纳入官方发布版本，需要明确评审其公开契约、限制和测试证据，并指定一名愿意承担稳定包义务的负责人。
+
+## 考虑过的替代方案
+
+**将实验性和内部专用包留在产品角色分组中，并用 README 标注。** 标注容易被忽略，也无法强制执行依赖边界。
+
+**首个带标签的版本发布前，将所有包都视为实验性。** 这无法提供持久的孵化边界。
+
+**在其他位置开发原型和内部专用包。** 这会失去评估它们所需的真实插件图、示例、快照和生命周期检查。
+
+## 后果
+
+该路径明确标示不纳入发布版本的包及其依赖影响范围，同时保留供团队共享成果的真实插件图。代价是这些包无法与同产品角色的包共置，提升并纳入发布版本时还会产生路径变动，但 npm 包名保持稳定。子树规则、仓库已有的[「必须有当前负责人和实际需求」规则](../../../../packages/AGENTS.md)以及保持不变的工程门禁，可限制该分组无序膨胀。由于官方发布工具尚不存在，目前由贡献者政策执行这项排除规则；添加发布工具后，必须以该目录为排除边界。

packages/README.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 packages/README.md
-README.md: fd5e1e8ec1a0ca426ed717cfa9613c51728c60e1
-README.zh.md: ad4f315171377677a934d8bb02d15c2db96e0e91
+README.md: 3f467641bbc9eae14a94aa2d3bff0402116a9d3f
+README.zh.md: c9d11bbf6239b4239a4e037dac63b05d3a9a58f7

packages/README.md

@@ -47,11 +47,12 @@ Packages live at `packages/<group>/<pkg>/`; groups are containers, while names r
 | [`ui/`](ui/README.md) | TUI and JSON-RPC integrations, approval/interaction seams, ask-user tool | Product — stable surface |
 | [`host/`](host/README.md) | Web-GUI host half: API gateway + HTTP route server | Product — stable surface |
 | [`client/`](client/README.md) | Web-GUI browser half: shell, wire, object services, slots, `ui-*` plugins | Product — stable surface |
+| [`experimental/`](experimental/README.md) | Prototypes and internal plugins | Unreleased |
 | [`examples/`](examples/README.md) | Demo bundles (agent-spine + TUI/CLI/ACP/JSON-RPC bins) leaves load | Support — example infra |
 | [`support/`](support/README.md) | Support infrastructure (testkits, invariants, replay, Loader smokes) | Support — lower compatibility expectations |
 | [`util/`](util/README.md) | Low-level zero-dependency utilities shared across groups (`Branded<B>`, Harness home/path helpers, timeout, retention) | Support — small, stable, harness-dep-free |
 
-Groups distinguish product API from support infrastructure. New packages join an existing group; a new group updates its README and this table.
+New packages join existing groups; new groups update their README and this table.
 
 ## Dependencies
 

packages/README.zh.md

@@ -47,11 +47,12 @@
 | [`ui/`](ui/README.md) | TUI 与 JSON-RPC 集成、批准／交互 seam、用户问答工具 | 产品：稳定表面 |
 | [`host/`](host/README.md) | web GUI 宿主半侧：API 网关 + HTTP 路由服务器 | 产品：稳定表面 |
 | [`client/`](client/README.md) | web GUI 浏览器半侧：shell、协议层、对象服务、slot、`ui-*` 插件 | 产品：稳定表面 |
+| [`experimental/`](experimental/README.md) | 原型和内部插件 | 未发布 |
 | [`examples/`](examples/README.md) | 演示组合包（agent-spine + TUI/CLI/ACP/JSON-RPC bin），由叶节点加载 | 支持：示例基础设施 |
 | [`support/`](support/README.md) | 支持基础设施（testkit、不变式、回放、Loader 冒烟测试） | 支持：兼容性预期较低 |
 | [`util/`](util/README.md) | 组间共享的低层零依赖工具（`Branded<B>`、Harness home／路径辅助函数、超时、保留策略） | 支持：小型、稳定、无 harness 依赖 |
 
-组用于区分产品 API 与支持基础设施。新包加入现有组；新组则更新其 README 和此表。
+新包加入现有组；新组更新其 README 和此表。
 
 ## 依赖
 

packages/experimental/AGENTS.md

@@ -0,0 +1,11 @@
+# AGENTS.md — Experimental and internal packages
+
+These rules supplement the [package rules](../AGENTS.md). The [experimental and internal package group decision](../../.agents/notes/implemented/architecture/2026-07-28-experimental-plugin-package-group.md) owns the rationale.
+
+- All Cordis plugin packages whose whole public contract is experimental or internal-only belong here. An experimental option inside an otherwise stable package stays in that package's product-role group.
+- Use this directory to share engineering and product-manager prototypes across the team so others can discover, run, review, and extend them against the real plugin graph.
+- Official releases exclude this directory. A package enters a release only after moving to its product-role group; do not add packages here to release manifests or bundles.
+- Experimental packages carry no stability, compatibility, migration, or support promise. Internal-only packages may define narrower internal contracts but make no public release promise.
+- Experimental or internal-only status never relaxes repository engineering, security, documentation, lifecycle, testing, or snapshot requirements.
+- Release packages must not take runtime dependencies on packages here. Examples may; every other runtime dependent is also experimental or internal-only and belongs here. Tests may use them as development dependencies.
+- Promotion moves a package to its product-role group without renaming its `@deepseek-ai/dsh-*` package. Require explicit review of its public contract, limitations, test evidence, and a named owner accepting stable-package obligations.

packages/experimental/README.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# 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 packages/experimental/README.md
+README.md: db39af8bb1b1bcfd257e16e4ad1dd112f604ffb1
+README.zh.md: df9b8cb2a91faab7af782e0f53685368e99583ff

packages/experimental/README.md

@@ -0,0 +1,7 @@
+# experimental/ — experimental and internal packages
+
+English | [中文](README.zh.md)
+
+This group hosts team-shared engineering and product-manager prototypes plus internal-only Cordis plugins. It is excluded from official releases; packages move to their product-role group before release.
+
+No packages live here yet. The [subtree rules](AGENTS.md) define the no-warranty, dependency, and promotion boundaries.

packages/experimental/README.zh.md

@@ -0,0 +1,7 @@
+# experimental/：实验性与内部专用包（package）
+
+[English](README.md) | 中文
+
+该分组容纳工程人员与产品经理在团队内共享的原型，以及内部专用 Cordis 插件。该分组不纳入官方发布版本；包在发布前移入对应的产品角色分组。
+
+该分组尚未包含任何包。[子树规则](AGENTS.md)界定不作保证、依赖关系和提升机制的边界。