模型输出治理套件 PlayForm/DeepSeek

面向 PlayForm 的 DeepSeek Harness 插件家族

用一百一十九个 TypeScript 包管住模型的输出、管好项目的文件——59 个 Classic 包，60 个 EffectTS 包。

这套东西包含最初的 14 个插件（工厂、核心、治理三件套、七件套 normalize 家族、两个守护者和 live block），加上 2026-10-22 交付的 36 个插件（工作区家族、建议器、编排套件、客户端面板）及其 ETS 孪生版本，再加上完成度计划库（lib-dsh-trace、lib-dsh-pack）和注释过滤器。

全部内容以两套实现交付（[Classic 版本][classic]、[Effect-TS 版本][ets]），共用同一份 ledger-string 契约，配有 595 个 smoke 目录 / 7,288 项检查。

[!NOTE]

_一个 monorepo。每个 ledger 字节都校验。_

目录

1. 快速开始
2. 套件一览
3. 架构
4. 工具与配置
5. 验证
6. 文档地图
7. 开发
8. 故障排查
9. 与 deepseek-ai/deepseek-harness 的关系
10. 贡献
11. 许可证

快速开始

这套家族从源码发布：每个 bundle 都是自包含的 TypeScript 包，确定性构建，再手工接进 DeepSeek Harness 配置档。不走 registry 安装，也没有 setup 二进制。

从源码构建

Terminal（先到工作区根目录，再到各个 bundle）

pnpm install --ignore-scripts
pnpm run build:classic # the 59 Classic packages, one workspace pass
pnpm run build:effect-ts # the 60 EffectTS packages
pnpm run test # all 595 smoke folders - the arbiter

每个 bundle 的构建都保持同样三步（Source/ -> Target/，经 ESBuild + tsc + tsc-alias，压缩并生成 .d.ts 孪生文件）：

cd Classic/packages/<bundle>
pnpm install --ignore-scripts
pnpm run prepublishOnly

先构建基础库和工厂（lib-dsh-core、[plugin-dsh-factory][ours-plugin-dsh-factory]），再构建消费者；消费者通过各自 node_modules/ 下的目录链接导入同级包。

接入 DeepSeek Harness 配置档

接下来是四步。下面每一步都是加载器实际读取的接线方式，因为不存在单独的配置界面。
1. 把 bundle 加进配置档（~/.dsh/profiles/<name>/package.json）—— 在 link: 依赖和 dsh.profile.bundles 列表里列出这些 bundle；真正激活它们的是这个列表：

{
"name": "my-dsh-profile",
"dependencies": {
"@playform/plugin-dsh-factory": "link:../bundles/plugin-dsh-factory",
"@playform/hook-dsh-package-governor": "link:../bundles/hook-dsh-package-governor",
"@playform/hook-dsh-package-pinner": "link:../bundles/hook-dsh-package-pinner",
"@playform/hook-dsh-normalize-dash": "link:../bundles/hook-dsh-normalize-dash"
},
"dsh": {
"profile": {
"bundles": [
"@playform/plugin-dsh-factory",
"@playform/hook-dsh-package-governor",
"@playform/hook-dsh-package-pinner",
"@playform/hook-dsh-normalize-dash"
]
}
}
}

链接进来的 checkout 自带 node_modules，也自带 pnpm-workspace.yaml（packages: [.]）。所以在配置档的 workspace 下、在某个 bundle 里执行安装，实际作用在 workspace 根目录上，对这个 bundle 没有任何影响。

远程来源的 bundle 走同一条列表：已构建好的 bundle 目前用 dsh plugin --profile <name> add <tarball> 加入；等这一系列包发布到 npm 之后，在配置档目录里执行 pnpm add @playform/<pkg> 即可（发布是后面的事）。

2. 添加补丁条目（配置档的 cordis.patch.yml）—— 每个 bundle 一行 insert，配置字段直接照搬 bundle 的 schema：

- insert:
- id: plugin-dsh-factory
name: "@playform/plugin-dsh-factory"
config: {}
- insert:
- id: hook-dsh-package-governor
name: "@playform/hook-dsh-package-governor"
config:
log: true
logFile: ~/.dsh/playform/hook-dsh-package-governor.log
updateCooldownMs: 3000
strict: false
mutationTools: [write, edit, str_replace_editor, raw-write]
maxUpdateFailures: 3
ncuBin: /usr/local/bin/ncu
updateMode: programmatic
policyFile: ""
exclude: [node_modules, .git, .dsh, .pnpm, .store, DeepSeek Harness.app]
- insert:
- id: hook-dsh-normalize-dash
name: "@playform/hook-dsh-normalize-dash"
config:
log: true
logFile: ~/.dsh/playform/hook-dsh-normalize-dash.log
replacement: "-"
normalizeReasoning: true

3. 重启宿主 —— 加载器会从 Target/Library.js 激活条目，并在启动时插入补丁行。

4. 核对日志 —— 每个插件启动时都会把自己的激活记录写进各自的 ~/.dsh/<identity>.log，这一行就是「有没有激活」的答案，可以从仅账本：

hook-dsh-package-governor: activated (anywhere mode, logFile=~/.dsh/playform/hook-dsh-package-governor.log, updateMode=programmatic, ncuBin=/usr/local/bin/ncu, exclude=[node_modules, .git, .dsh, .pnpm, .store, DeepSeek Harness.app], policyFile=(discovery))
hook-dsh-package-pinner: activated (pinner, logFile=~/.dsh/playform/hook-dsh-package-pinner.log, sections=[dependencies, devDependencies, peerDependencies, optionalDependencies], exclude=[node_modules, .git, .dsh, .pnpm, .store, DeepSeek Harness.app])
hook-dsh-normalize-dash: activated (replacement=-, reasoning=on, toolArgs=off, logFile=~/.dsh/playform/hook-dsh-normalize-dash.log)

套件一览

两个已发布的包组共用同一套契约：CLASSIC 包（@playform/dsh-，纯 TypeScript）和 EFFECT-TS 包（@playform/ets-，由 effect 支撑）。

安装你实际运行的那一组，绝不要在同一张依赖图里混用两组。因为 effect-ts 的 Update 返回的是 Effect 信封，而不是 classic 的 dispatch 信封：

- CLASSIC： pnpm add @playform/lib-dsh-core @playform/plugin-dsh-factory @playform/hook-dsh-package-governor - 纯 TypeScript，零框架依赖；
import { Govern } from "@playform/plugin-dsh-factory"。
- EFFECT-TS： pnpm add @playform/ets-lib-dsh-core @playform/ets-plugin-dsh-factory @playform/ets-hook-dsh-package-governor - 同样的契约，跑在 Effect-TS 的 service 和 layer 上；共享运行时依赖是 effect v4.0.7，基础包 @playform/ets-base-dsh 承载所有 ets-* 包赖以构建的底层管线。

一行版清单在 Documentation/Plugins/PLUGIN-SUITE-SUMMARY.md，各插件的实机测试计划在 Documentation/Testing/。

按领域划分：

| 领域 | 数量 | 内容 |
| 原有插件 | 14 | 工厂、治理三件套、六种流形态 + 文件规范化器、ccr、tool-coach、live-containers |
| 工作区家族 | 15 + 1 个库 | 十步隐形流程：观察 → 语义 → 操作 → 治理 → 授权 → 审批 → 合并 → 日志 → 审计 → 上下文/监控/证据/图谱/反思，外加 lib-dsh-workspace-live |
| 客户端家族 | 3 | client-dsh-panel-family、client-dsh-panel-family-host、client-dsh-workspace-live |
| 建议器 | 7 | hook-dsh-{search,edit,doc,convention,graph,replay,test}-suggester |
| 编排套件 | 10 | plugin-dsh-batch-edit、plugin-dsh-batchstate、plugin-dsh-gitguard、plugin-dsh-route、plugin-dsh-queue、plugin-dsh-feedback、plugin-dsh-pass-on、plugin-dsh-ingester、plugin-dsh-pattern、hook-dsh-batch-decision |
| 补全库 | 2 | lib-dsh-trace（trace 总线的库部分）、lib-dsh-pack（pack 层） |
| 成本家族 | 2 | plugin-dsh-cost（按文件记录推理成本的账本）、plugin-dsh-cost-analysis（只读的账本分析） |
| 学习家族 | 2 | plugin-dsh-lesson-review（回合结束后的自我改进复盘）、hook-dsh-lesson-nudge（空闲切换时的提醒） |
| 天桥过滤器 | 1 | hook-dsh-comment-filter（剥离注释的天桥） |
| 对话主干 | 1 个库 | lib-dsh-conversation（对话词汇表与纯 fold） |

59 个 Classic 包，每一个都有对应的 ETS 孪生包。

架构

问题

每个智能体会话里，都会悄悄冒出两类腐化：

- 模型的排版。 每段流式转录都会攒下模型顺手打出的 unicode：em dash、en dash、弯引号、水平省略号、异形空格、零宽字符、全角形式。这些字符会一路留进文件、diff、搜索和终端，在那里破坏逐字节比较，放到别处也显得不对劲。
- 项目的清单文件。 package.json 里的链式版本锁定指向的解析结果早已漂走，范围依赖在每台机器上解析出的版本都不一样，Cargo.toml 里的条目则攒下一堆没人统一过的版本。
DeepSeek Harness 把两处接缝都开放出来，供你修补（文件事件用 [fs/observed][dsh-fs]，模型输出用 [llm/stream][dsh-llm] 瀑布流），但自带的插件里没有哪个拿它们做这件事。

这一族插件就是干这个的。

工作原理

三处接缝、三种行为，底下是一个服务：

MODEL STREAM ───► the stream gate (the llm/stream waterfall) ───► the transcript, normalized
│ one flavor, one table: em dash → - " → " ... → ...
FILE EVENT ─────► the seam (fs/observed) ───► the gate set ───► the ledger + the chain
│ target → actor → kind → idempotence → basename → exclusion
RAW-WRITE ──────► the direct-govern registry (factory.Govern) ─► the same chain, per call

- 流闸门 -
每种归一化风格都挂上 [llm/stream][dsh-llm] 瀑布流（包住每次流式模型调用的可拦截外壳），
在对话记录里实时改写它负责的那一族字符：破折号族改成 -，八个弯引号码位改成对应的直引号，省略号改成 ...，Unicode 空格族改成普通空格，零宽/不可见字符族直接删掉，全角形式改成对应的 ASCII 半角。调度机制（Chunk/Block、组装好的推理块、工具参数闸门）由核心共享，每种风格只贡献一张表和一次替换。
- 观测文件接缝 - 治理三件套挂上 [fs/observed][dsh-fs]：变更工具发起的一次受治理写入先过闸门集，然后这一趟作为分离的、受约束的续跑执行（governor 跑链式一趟，pinner 跑钉住一趟，
cargo governor 做 TOML 手术），更新阶段按冷却时间派发，带熔断。每个插件写自己的账本
（~/.dsh/<identity>.log），并记日志到共享的 package_governance 存储域。
- [直接治理注册表][ours-govern] - raw-write 工具每次调用时的 govern 选择，
通过 [factory.Govern][ours-govern] 直接驱动同一条链（[顺序折叠][ours-govern]：
一步的链跑完，下一步才读文件），而不是等事件。

最初的 14 个插件（外加核心库）

最初的 14 个插件（外加 lib-dsh-core）每个都读作一句 @ 句： <kind> @ <platform> @ <role> @ <domain>。

- [plugin-dsh-factory][ours-plugin-dsh-factory]（Plugin @ DSH @ Factory）- 这一族的第一个服务：加载它就注册一个类插件（static inject = ["fs"]），暴露 ctx.pluginFactory，带十九个可调用方法，覆盖钩子过去做的所有事
- 重复项——账本（Append）、排除匹配（Match）、注册表发现（Discover/Parse）、并集保留列表（ResolvePolicy）、门控集合（Gate）、共享写入执行器（Write/GuardedWrite，带版本守卫的围栏写入）、[fs/observed][dsh-fs] 重新发射（Refresh）、分离的受控续体（Continue）、State 构建器、fiber 持有的接线（Wire）、effect 注册（Attach——jobs、inflight、storage）、P5 日志（Journal）、schema 工厂（Schema）、一次性探测接缝（Seam）、Inflight 键（UpdateKey），以及[直接治理注册表][ours-govern]和入口（RegisterGovern/Govern，顺序折叠）。
- lib-dsh-core（Lib @ DSH @ Core）——纯库层，零运行时依赖，不是插件：依赖段列表、排除段、抑制行组合器、更新策略加载器、拒绝守卫、更新信封、激活行组合器，以及 normalize/stream 机制（六张表、Replace/ReplaceMap、Chunk/Block）。
- hook-dsh-package-governor
（Hook @ DSH @ Governor @ Package）——静默的 package.json 治理器：它钩住
[fs/observed][dsh-fs]，把链治理的固定版本（^x、~x、workspace:）改写为有效注册表的已解析
版本，并在冷却期后运行更新阶段（ncu，编程库或通过[子进程接缝][dsh-subprocess]调用外部二进制），
带断路器；strict 会剥离未知依赖，且仅限显式指定，绝不作为默认删除。
- hook-dsh-package-pinner
（Hook @ DSH @ Pinner @ Package）——静默的版本固定器：它确定性地把每个范围依赖版本改写为其静态版本（^0.3.4 -> 0.3.4），受 pin-policy.json 保留列表保护，保留列表优先于固定，但绝不优先于链。
- hook-dsh-cargo-governor
（Hook @ DSH @ Governor @ Cargo）——治理器的 Rust 侧变体：在原始 TOML 行上做外科手术式的链固定改写（注释保留）、完整版本规范化（1.0 -> 1.0.0），以及通过[子进程接缝][dsh-subprocess]运行 cargo upgrade（cargo-edit）作为唯一更新路径，因为 Rust 不会并入 TypeScript 生态；strict 会移除整个 name = "..." 条目，绝不使用继承条目或 path/git 条目。
- hook-dsh-normalize-dash
（Hook @ DSH @ Normalize @ Dash）- 破折号风格：把 em dash、en dash 及其各种冷门变体转成 ASCII 连字符减号，落在参考工具链缺失的注入点上。
- hook-dsh-normalize-quotes
（Hook @ DSH @ Normalize @ Quotes）- 引号风格：把八个弯引号码点转成对应的 ASCII 直引号。
- hook-dsh-normalize-ellipsis
（Hook @ DSH @ Normalize @ Ellipsis）- 省略号风格：把水平省略号（U+2026）转成普通的三点序列。
- hook-dsh-normalize-spaces
（Hook @ DSH @ Normalize @ Spaces）- 空格风格：把 unicode 空格家族（Zs 去掉 ASCII 空格）转成普通空格。
- hook-dsh-normalize-invisible
（Hook @ DSH @ Normalize @ Invisible）- 不可见字符风格：移除零宽/不可见字符家族（软连字符、零宽空格与连接符、双向控制符、BOM）。
- hook-dsh-normalize-fullwidth
（Hook @ DSH @ Normalize @ Fullwidth）- 全角风格：把整个 FULLWIDTH FORMS 区段（U+FF01-FF5E）转成对应的 ASCII 半角字符。
- plugin-dsh-normalize-file
（Plugin @ DSH @ Normalize @ File）- 文件内容规范化插件：读取、计数、写入流水线，对磁盘上已有的文件应用全部六种转换，只在内容有变化时才写入。
- hook-dsh-ccr
（Hook @ DSH @ CCR）- 压缩-缓存-取回守卫：超大的白名单工具结果变成一行类型感知预览加一个取回标记，原始字节由 ccr_retrieve 工具按需还原。
- hook-dsh-tool-coach
（Hook @ DSH @ Tool @ Coach）- 终端内容教练守卫：对终端调用施加四级阶梯（台账、提示、常驻段落、可选拒绝），并给出正确的专用工具名及其实时注册表描述。
- hook-dsh-live-containers
（钩子 @ DSH @ Live @ Containers）—— 动态系统提示词块：一个 live-containers 段，带标签的小节在请求时重新计算，默认以禁用状态发布，只有显式 activate 才启用。

2026-10-22 交付的 36 个包

- workspace 家族（15 个 + 库） —— plugin-dsh-workspace（操作视图，以及 map/find/expand/context 工具）、hook-dsh-workspace-observe（版本戳）、plugin-dsh-workspace-semantics（符号解析与重命名规划）、hook-dsh-workspace-operate（类型化提案）、hook-dsh-workspace-govern（means-check 门禁）、plugin-dsh-workspace-authority（capability/lease/residency）、hook-dsh-workspace-approve（审批绑定器）、hook-dsh-workspace-merge（原子批量合并）、hook-dsh-workspace-journal（前像、回滚、崩溃恢复）、hook-dsh-workspace-audit（问责记录）、plugin-dsh-workspace-context（定位信息包）、hook-dsh-workspace-monitor（检查集监视器）、plugin-dsh-workspace-evidence（真相记录）、plugin-dsh-workspace-graph（文件/符号/块索引）、plugin-dsh-workspace-reflect（单次调用反射操作），外加 lib-dsh-workspace-live（共享客户端库）。
- 客户端家族（3 个） —— client-dsh-panel-family、client-dsh-panel-family-host、client-dsh-workspace-live。
- 建议器（7 个） —— hook-dsh-{search,edit,doc,convention,graph,replay,test}-suggester。
- 编排套件（10 个） —— plugin-dsh-batch-edit（批量编辑引擎）、plugin-dsh-batchstate（实时看板）、plugin-dsh-gitguard、plugin-dsh-route、plugin-dsh-queue、plugin-dsh-feedback、plugin-dsh-pass-on、plugin-dsh-ingester、plugin-dsh-pattern，以及 hook-dsh-batch-decision。

59 个 Classic 包每一个都有对应的 ETS 孪生包。

两棵树与目录布局

| 树 | 是什么 |
| Classic/ | 纯 TypeScript 版本 —— 类、Map 和普通函数，零运行时框架依赖。59 个包；299 个 smoke 目录。 |
| EffectTS/ | Effect v4 移植版 —— 同样的契约，改用 Effect-TS 的 service 和 layer 重新表达（锁定 effect 4.0.7）。60 个包；296 个 smoke 目录。 |

每个包都带一个 ets- 孪生包，59 个 Classic 包对应 59 个孪生包。

Classic/ the plain-TypeScript release: 59 packages + smokes
EffectTS/ the Effect v4 port: 60 packages + smokes
Site/ the static site (its own repository)
Test/ the fixture archive: the governance batteries, the markdown proofs, the probes
Documentation/ 框架、指南、技能、计划、报告、测试计划 Maintain/ 格式化入口点和聚合运行器

工厂与账本字符串契约

每条激活行、拒绝行、链传递行和日志记录都由冒烟测试逐字节断言。

字符串就是契约：不能改，而且两棵树里的字符串必须一致。

每个插件一个账本，位于 ~/.dsh/<identity>.log，冒烟测试加载每个 bundle 实际构建出的 Target/Library.js，在字符串之上断言完整的行为契约（加载器契约、身份断言、效果接线）。

工具与配置

工具

这一族附带两个工具：

| 工具 | 作用 |
| raw-write | 流式变体注册的写入包装器：显式 normalize 参数（默认 false = 原样写入）—— 缺省或 false 时逐字节写入，true 应用全部六种变换，数组则只应用指定的变体。按名称豁免流式归一化，和 edit 一样。每次调用的 govern 选择（true、名称数组，或 false = 逃生舱）驱动[直接治理折叠][ours-govern]。 |
| normalize-file | 整文件处理：读取文件，应用变换（默认全部六种，或按变体选择），报告数量，仅在内容有变化时写入。 |

配置

每个插件的配置 schema 都通过工厂的 Schema 工厂构建：一个共享的易变块（log、logFile、updateCooldownMs、mutationTools）加上模块自身的字段。

按插件类型分组的接口面：
| 类别 | 字段 | 作用 |
| 治理三件套 | log / logFile | 持久化账本文件（每个插件各存一份，默认相互独立） |
| | mutationTools | 哪些操作类工具算作触发源——部署层设为 [write, edit, str_replace_editor, raw-write] |
| | exclude | 排除段——插件自带的围栏（node_modules、.git、.dsh 等） |
| | updateCooldownMs / maxUpdateFailures | 更新阶段的节奏控制与熔断机制（失败 3 次就暂停该目录） |
| | updateMode + ncuBin / cargoBin | 程序化（库）与 bin（外部二进制，走 [子进程接缝][dsh-subprocess]）两种模式；绝对路径——宿主 PATH 不等于 shell PATH |
| | strict | 剥离未知依赖——仅显式开启，绝不默认删除 |
| | policyFile / keepFile / sections | update-policy 和 keep-list 两个 sidecar 文件，以及 pinner 会处理哪些依赖分组 |

| The stream flavors | replacement | the transform's only knob on class flavors (-, ", ..., plain space, empty) - hot-editable, no remount |
| | normalizeReasoning | default ON - normalize reasoning deltas and the assembled reasoning block too |
| | normalizeToolArguments | default OFF - tool-call arguments are execution-critical raw JSON; opt-in (deprecated in favor of scopes.toolInput, kept and OR-ed in) |
| | scopes | the granular scope gates - all volatile, per hook: conversation (text/block-end, ON), reasoning (sub-gate, ON), toolInput (OR-ed with normalizeToolArguments, OFF), toolResults (the tools/post-execute arm, OFF), files (the normalize-file tool, ON), batch (the agent/pre-step arm, OFF) |
| | toolResultsExempt | volatile list of exec names that pass the tool-results arm by identity (read, edit, raw-write, normalize-file, ccr_retrieve, subagent, ask_user_question) |
| The file tool | normalize (per call) | absent/false = verbatim, true = all six transforms, or the flavor-name array |

The defaults-off posture keeps strict off, normalizeToolArguments off, raw-write normalize
off, and scopes.toolInput / scopes.toolResults / scopes.batch off, so the family changes
nothing until it is told to.

The escape hatches are the exclude fence, the keep-list sidecars, the raw-marker opt-out, and the
govern: false selection.

The granular scopes and the overpass arms

Because the scopes schema shape is identical in every family hook, one grouped override in the
profile patch (cordis.patch.yml) turns the whole family off in one edit, live and silent, with no
remount and no new activation line:
yaml
- id: hook-dsh-normalize-dash
config:
scopes:
conversation: false
reasoning: false
toolInput: false
toolResults: false
files: false
batch: false

Repeat the block for the other flavors (or just the ones you want dark), because every scope is
volatile and flipping it applies to the next dispatch.

The overpass arms (both opt-in and off by default) normalize content at its natural boundaries
without ever rewriting the durable transcript:

- tools/post-execute - the tool result is normalized before it re-enters the model and is appended
to the transcript going forward (text blocks only; the read/edit/raw-write/normalize-file/
ccr_retrieve/subagent/ask_user_question exec names pass by identity via toolResultsExempt,
and the <<<CCR: marker bytes make the arm order-safe against the ccr hook).
- agent/pre-step - the incoming user-role batch is normalized before the model sees it, never the
assistant/tool history, which is append-only.

Each hook also registers a human command, normalize-overpass:
text
normalize-overpass batch # arm a one-shot step-batch overpass (one use)
normalize-overpass results on # flip scopes.toolResults via the settings service
normalize-overpass results off
normalize-overpass scopes # read-only report of the current effective values
normalize-overpass files <path...> # the file sweep - implemented by the normalize-file hook only

The command writes one ledger line per action:
overpass: normalized N char(s) in tool result <toolName> <callId>,
overpass: normalized N char(s) in step batch (turn T step S), and
overpass: swept K file(s), normalized M char(s).

Verification

The suites are the speed and coverage story:

- 299 Classic / 296 EffectTS folders, 7,288 checks, all green. The aggregate runner is
node Maintain/Run/Smokes/Index.mjs, and the heaviest single original suite (cargo, 62 checks
including the real TOML surgery and the subprocess-seam stubs) runs in ~0.6 s.
- Zero runtime framework dependencies in Classic - the release tree runs on plain TypeScript,
and EffectTS adds the single effect 4.0.7 dependency.
- Deterministic builds - ESBuild + tsc + tsc-alias, minified Target/ with .d.ts twins,
and byte-identical ledger strings on every rebuild.

One suite per test folder per tree runs with the aggregate node Maintain/Run/Smokes/Index.mjs,
which also guards each folder's printed PASS count against its folder README (the vacuously-green
guard):

| Measure | Value |
| Test folders (Classic) | 299 |
| Test folders (EffectTS) | 296 |
| Total suites | 595 |
| Total checks (both trees) | 7,288 |
| The wiring battery | <tree>/smokes/Test/, run by Maintain/Run/Wiring/Index.mjs under DSH_TEST_SCRATCH |

The per-suite before/after totals live in the totals ledger of
Documentation/Plans/SMOKE-SUITE-RESTRUCTURE-BLUEPRINT.md, where the original 14 mechanics suites
total 1314 Classic / 1324 EffectTS checks and the rest is the suites of the 2026-10-22 delivery.

The counts are the release contract: they must not change.

The docs map

Everything is documented under Documentation/, and the index lists every
document with its status:

| Section | Contents |
| Documentation/ root | INDEX.md, ARCHIVE-STYLE.md (the frontmatter template), FRAMEWORK.md |
| Brand/ | BRANDING.md |
| Plans/ | the living + queued plans (30) and the granular families (Batch-Edit-Tool/, Representation-First/, UI-Family/, Workspace-Family/, Completion-Spec/) |
| Researches/ | the research outputs (8) |
| Guides/ | the operating manuals (7) |
| Reports/ | the audits and diagnoses (6) |
| Plugins/ | the registry documents (3): PLUGIN-FAMILY.md, ORCHESTRATION-PLUGINS.md, PLUGIN-SUITE-SUMMARY.md |
| Testing/ | the per-plugin live test plans: README.md + 35 per-plugin files |
| Archive/ | the one-shot records (45, in 8 topics) |
| Handoff/, Skill/ | untouched trees (the delivery record; the loadable skills) |

Development

The workflow, root-first - every step is a root package.json script:

| Script | What it does |
| pnpm install | the workspace install (--ignore-scripts); the per-bundle standalone workspaces take their own install |
| pnpm run build:classic / build:effect-ts | the packages of one tree, one workspace pass (prepublishOnly per package) |
| pnpm run build | both trees in order (build:classic then build:effect-ts) - the whole-build trigger |
| pnpm test | all 595 smoke suites via Maintain/Run/Smokes/Index.mjs - the behavioral arbiter, exit non-zero on any failure |
| pnpm run test:types | Maintain/Run/Types/Index.mjs - the type check across the trees |
| pnpm run test:wiring | Maintain/Run/Wiring/Index.mjs - the live wiring battery under DSH_TEST_SCRATCH |
| pnpm site | the static site build (Site/) |
| pnpm lychee | Maintain/Check/Lychee/Index.sh - the three-pass link check composing lychee-report.md |
| pnpm format / format:check | Maintain/Format/Index.sh - line endings + Prettier (never the markdown - byte-integrity-protected) |

The regime: the smokes (and the site build) are the arbiter after every change, the ledger strings
stay byte-identical at the same counts, the byte-scan stays clean (no NUL bytes in the tracked
tree), and the tree is committed by the maintainer, never by tooling.

The hazards, documented:

- The duplicate-name relink. Resolved by the namespace split (SPLICE-ETS.md): the two trees now
carry unique names (@playform/dsh- vs @playform/ets-), so no install can re-relink a
consumer's @playform/* links to the other tree. Re-run the smokes after every install anyway.
- The verifyCommand trap. An update-policy verifyCommand fails on a vendored-fork workspace
(no registry to install from), and the ledger records it, which is the expected outcome.
- The smoke/live fidelity gap. The smokes prove the mechanics, the live battery proves the
wiring, and the ledgers answer "did it activate".

Troubleshooting

The known gaps stay stated as they are, with the corrected claims kept and no marketing gloss.

- Load order is not list order. The pinner can activate before the governor at boot, because the
registration order is not controlled. Never rely on the bundle-list order for step ordering: the
sequential fold and the fresh-version writes make the order irrelevant, and each plugin's ledger
answers for its own activation.
- The verifyCommand trap. An update-policy verifyCommand can fail with a non-zero status: on a
vendored-fork workspace (the live battery of the family), pnpm install has no registry to
install from, and the ledger records the failure as the documented cordis registry trap, the
expected outcome and not a bug. Exit 127 (the runner unavailable) is non-fatal, while any other
failure fails the stage and counts toward the circuit breaker (maxUpdateFailures):

text
update: running verifyCommand: pnpm install
update: verifyCommand failed (status 1)
update: verifyCommand runner unavailable (exit 127) - skipped, non-fatal
update stage FAILED (1) for <dir>; consecutive=2

- The smoke/live fidelity gap. The smokes prove the mechanics and the live battery proves the
wiring. Every real bug (the patch layers, the v2 journal open, the version guard) was found live
and not by the smokes, so both green does not prove the profile wiring; the ledgers do.
- The fixture paths. The Test/ fixtures carry the neutralized display forms (<repo-root>/,
$DSH_HOME/), and the personal absolute paths exist only in the internal Boilerplate copies.
Never copy a live battery into the release archive as-is.
- The byte-integrity law. The NUL-byte incident class: a write that emits bytes the format of
the file forbids (NUL bytes) corrupts the file, which is the URL-registry corruption lesson.
Verbatim is the default, the normalize family restores the integrity, and the byte-scan is the
arbiter.
- The timestamp confusion. The ledger lines are ISO UTC, the storage records are epoch
milliseconds, and the local display adds +03, so the "missing records" scares were filter mistakes
and not lost data.
- The raw-write marker semantics. An absent govern means no chain (the escape hatch), and the
raw marker (__normalize: false) passes a call through unnormalized. Markers are stripped before
the tool validates, because the harness tools reject unknown argument keys.

Relationship to deepseek-ai/deepseek-harness

The family extends the DeepSeek Harness (DSH),
the desktop agent platform published as the @deepseek-ai packages.

Everything the family builds on is the public plugin API of the harness:

| Harness package | What the family uses it for |
| @deepseek-ai/cordis | the loader contract: the service/class plugins, the patch inserts, the fiber-owned hooks |
| @deepseek-ai/schemastery | the config schemas (the factory's Schema factory emits real schemastery instances) |
| @deepseek-ai/dsh-fs | ctx.fs - the governed reads, the version-guarded writes, the [fs/observed][dsh-fs] event vocabulary |
| [@deepseek-ai/dsh-subprocess][dsh-subprocess] | [the subprocess seam][dsh-subprocess] - the ncu and cargo upgrade dispatches |
| @deepseek-ai/dsh-sandbox | the sandbox policy - the fenced write postures |

The harness ships the seams and no plugins that use them this way, so the family adds the
normalization and the governance on top.

Contributing

| Want to... | Start here |
| Fix a plugin | the bundle's README.md + SCHEME.md under Classic/packages/<bundle>/ |
| Add a flavor | lib-dsh-core (one table) + a new hook-dsh-normalize-<name> bundle |
| Change behavior | the smokes first - the counts (595 suites / 7,288 checks) and the ledger strings are the contract |
| Understand the design | Documentation/FRAMEWORK.md and the skills under Documentation/Skill/ |

The regime: the smokes (and the site build) are the arbiter after every change, the ledger strings
stay byte-identical, and the tree is committed by the maintainer, never by tooling.

License

Released under CC0-1.0 - public domain.

[classic]: https://github.com/PlayForm/DeepSeek/tree/Current/Classic
[ets]: https://github.com/PlayForm/DeepSeek/tree/Current/EffectTS
[ours-plugin-dsh-factory]:
https://github.com/PlayForm/DeepSeek/tree/Current/Classic/packages/plugin-dsh-factory/Source
[dsh-fs]: https://github.com/deepseek-ai/deepseek-harness/tree/master/packages/fs/fs/src/index.ts
[dsh-llm]: https://github.com/deepseek-ai/deepseek-harness/tree/master/packages/llm/llm/src/index.ts
[ours-govern]:
https://github.com/PlayForm/DeepSeek/tree/Current/Classic/packages/plugin-dsh-factory/Source/Function/Govern.ts
[dsh-subprocess]:
https://github.com/deepseek-ai/deepseek-harness/tree/master/packages/subprocess/subprocess