@mengyuly/dsh-ponytail 0.3.3 → 0.4.0

package/CHANGELOG.md

@@ -4,7 +4,65 @@ All notable changes to `@mengyuly/dsh-ponytail` are documented here.
 Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## Unreleased
+
+## [0.4.0] - 2026-10-08
+
+### Added
+
+- Native Web settings card: default-mode selection, five optional-skill toggles,
+  atomic revision-fenced saves, panel-only reset, retained drafts on failure,
+  read-only guards, and Chinese/English help.
+- Optional native `/ponytail` mode picker; status/reset/help run through the
+  existing command boundary without requesting a model turn.
+- `/ponytail help` and detailed default-source status. DSH Settings persistence
+  is optional; legacy/headless deployments keep their config-file path.
+- Browser interaction tests and downstream build/source hash provenance.
+
+### Fixed
+
+- Normalize repository text line endings to LF so downstream SHA-256 build
+  provenance is reproducible across Windows and Linux checkouts.
+- Mark bundled DSH host-contract peers as optional for package resolution,
+  retaining their version contracts and required host services. Plain npm/pnpm
+  installs now resolve only the two runtime externals instead of following the
+  host's transitive unpublished `dsh-type-meta` peer. Add clean pnpm 11 default
+  installation and runtime-load regression coverage.
+- Restore the complete seven-rung ladder in every active prompt, mandatory
+  Lite alternatives, unnecessary-dependency and fewest-file guards, full-scope
+  acceptance without re-arguing, and upstream minimal-test limits. Full/Ultra
+  enforce the ladder; Lite leaves the scope choice to the user.
+- Downstream builds now compile the instruction fragment from source, avoiding
+  stale rules in the installed bundle.
+- Older DSH Web settings scopes now save through the host's atomic settings RPC,
+  preserving revision conflicts and surfacing write failures instead of calling
+  an unavailable `scope.mutate` method.
+- Restore explicit upstream rules in every active level: all-caller root-cause
+  checks, same-size algorithm edge cases, shortcut ceiling/upgrade annotations,
+  hardware calibration, requested explanations, and coding-only scope.
+- Debt scans now recognize block comments, keep source files under `lib`, and
+  exclude nested dependency/build output in both ripgrep and Git fallbacks.
+
+### Changed
+
+- Review prompt budgets around required semantics instead of enforcing the old
+  compressed sizes. Update bilingual measurements without claiming model savings.
+- Execute debt scan commands against controlled source/vendor/build fixtures;
+  verify exact installed/source prompt and skill parity in the pack smoke test.
+  These checks do not establish model compliance or performance.
 
+## [0.3.4] - 2026-10-07
+
+### Added
+
+- English README and bilingual navigation (PR #1), included in the npm package.
+
+### Fixed
+
+- Mode/default status notices now use non-waking injection instead of steering
+  an idle agent into an extra model turn (issue #2). Mode changes apply
+  immediately; notices reach the model on its next real step. Explicit
+  review/audit/debt/gain/help invocations still request an ordinary turn.
+
 ## [0.3.3] - 2026-09-09
 
 ### Changed

package/README.md

@@ -1,5 +1,7 @@
 # dsh-ponytail
 
+[English](README_EN.md) | 简体中文
+
 ![CI](https://github.com/MengYuil/dsh-ponytail/actions/workflows/ci.yml/badge.svg)
 ![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)
 [![npm](https://img.shields.io/npm/v/@mengyuly/dsh-ponytail)](https://www.npmjs.com/package/@mengyuly/dsh-ponytail)
@@ -13,15 +15,15 @@
 
 - **最新版（latest）**：
   `https://github.com/MengYuil/dsh-ponytail/releases/latest/download/mengyuly-dsh-ponytail.tgz`
-- **固定版本 v0.3.2**（按 Tag 不可变）：
-  `https://github.com/MengYuil/dsh-ponytail/releases/download/v0.3.2/mengyuly-dsh-ponytail.tgz`
+- **固定版本 v0.3.4**（按 Tag 不可变）：
+  `https://github.com/MengYuil/dsh-ponytail/releases/download/v0.3.4/mengyuly-dsh-ponytail.tgz`
 
 说明：
 
 - **latest**：适合快速安装体验，会随最新 Release 更新；固定资产名
   `mengyuly-dsh-ponytail.tgz` 在每个 Release 中保持不变，因此该 URL
   不会因版本号变化而失效，**不适合作为不可变依赖**。
-- **固定版本**：适合可复现安装，URL 中固定 Tag（如 `v0.3.2`），按 Tag
+- **固定版本**：适合可复现安装，URL 中固定 Tag（如 `v0.3.4`），按 Tag
   不可变；资产名同样为 `mengyuly-dsh-ponytail.tgz`。
 - npm 安装仍走 npm Registry 或 `dsh plugin` 命令。
 - 固定资产名由 `scripts/release-assets.mjs` 生成并验证（`node scripts/release-assets.mjs`，仅仓库维护者）。
@@ -54,28 +56,30 @@ dsh plugin --profile web add @mengyuly/dsh-ponytail
 ## 功能
 
 - **核心模式** `/ponytail` — 每轮注入结构化的懒惰开发者规则集，**三个档位是真实不同的 Prompt 片段**（不只是换一行）：
-  - **Common（所有非 off 档共享）**：先把请求转成可观察的完成条件；沿真实调用流取证，但决策阶梯是快速反射、不是研究项目；按“检查 → 修改 → 最窄有效验证 → 检查最终 diff”闭环执行；非平凡逻辑只留一个最小可执行检查，不额外搭测试框架或 fixtures；只汇报已验证结果。
+  - **Common（所有非 off 档共享）**：先把请求转成可观察的完成条件；沿真实调用流取证，但决策阶梯是快速反射、不是研究项目；按“检查 → 修改 → 最窄有效验证 → 检查最终 diff”闭环执行；非平凡逻辑只留一个最小可执行检查，不额外搭测试框架或 fixtures；只汇报已验证结果。
   - **Safety（任何档位都不可删）**：输入校验、防数据丢失的错误处理、安全措施、无障碍、明确验收项、先理解问题、「最小 diff ≠ 正确修复」。
-  - **`lite`**：直接执行、减少仪式；完整交付明确要求；可以一句话指出更简方案，但**不挑战明确需求**。
+  - **`lite`**：直接执行、减少仪式；完整交付明确要求；可以一句话指出更简方案，但**不挑战明确需求**。
   - **`full`（默认）**：完整七级阶梯（YAGNI → 复用 → 标准库 → 原生 → 已装依赖 → 一行 → 最小实现），默认选最短正确实现，修根因而非症状。
-  - **`ultra`**：新增代码前先要证据，优先删除或复用；主动质疑投机性功能/缓存/抽象/配置/新依赖；复杂需求先给最小正确版并说明扩大条件；**不是无脑拒绝**。
+  - **`ultra`**：新增代码前先要证据，优先删除或复用；主动质疑投机性功能/缓存/抽象/配置/新依赖；复杂需求先给最小正确版并说明扩大条件；**不是无脑拒绝**。
   - `off`：完全不注入。
   - 档位**会话级**（会话 A 不影响会话 B，会话结束自动释放）。
   - 裸 `/ponytail`：已启用时只报告；`off` 时恢复到有效默认档（默认也是 `off` 则回 `full`）。
-  - `/ponytail status`：只查询、永不修改，并显示当前模式来自会话覆盖还是配置默认值。
-  - `/ponytail reset`：清除当前会话覆盖，重新跟随有效配置默认值。
+  - `/ponytail status`：只查询、永不修改，并显示当前模式来自会话覆盖还是配置默认值。
+  - `/ponytail reset`：清除当前会话覆盖，重新跟随有效配置默认值。
   - `/ponytail lite|full|ultra|off`：显式切换。
-  - `/ponytail default <mode>`：持久化默认值到**用户级配置文件**（env/Profile 仍优先，命令分别提示 saved 与 effective）。
+  - `/ponytail help`：直接显示操作帮助，不调用模型。
+  - `/ponytail default <mode>`：有 DSH Settings 时保存到宿主设置；没有时回退到用户级配置文件（env/Profile 仍优先，命令分别提示 saved 与 effective）。
+  - 状态操作立即生效，但不唤醒空闲 Agent；模型通知在下一次真实请求时接收，避免切档位额外触发模型调用。
 - **一次性技能**（用哪个载哪个，不进常驻 prompt）：
-  - `/ponytail-review` — 针对最近改动找过度工程；每条包含位置、替代方案和实际调用证据，不猜测精确收益。
-  - `/ponytail-audit` — 全仓库过度工程审计；区分可安全删除与需要先验证的候选，最多返回 10 条高价值发现。
+  - `/ponytail-review` — 针对最近改动找过度工程；每条包含位置、替代方案和实际调用证据，不猜测精确收益。
+  - `/ponytail-audit` — 全仓库过度工程审计；区分可安全删除与需要先验证的候选，最多返回 10 条高价值发现。
   - `/ponytail-debt` — 收割所有 `ponytail:` 注释成债务账本。
   - `/ponytail-gain` — 上游 Benchmark 参考计分板（代码减少；Token/成本/延迟效果取决于模型与任务，**非本适配版保证**）。
   - `/ponytail-help` — 参考卡。
-- **停用**：说 `stop ponytail`、`normal mode`、`停止 ponytail`、`关闭 ponytail`、`普通模式` 或 `正常模式`（兼容中英文句末标点）；随时 `/ponytail` 恢复。
+- **停用**：说 `stop ponytail`、`normal mode`、`停止 ponytail`、`关闭 ponytail`、`普通模式` 或 `正常模式`（兼容中英文句末标点）；随时 `/ponytail` 恢复。
 - **默认值优先级**（代码/测试/文档一致）：
   ```
-  会话 override > PONYTAIL_DEFAULT_MODE > Profile config.defaultMode > 用户 config.json > full
+  会话 override > PONYTAIL_DEFAULT_MODE > Profile config.defaultMode > DSH Settings > 用户 config.json > full
   ```
   - **Profile 级配置**（Cordis 官方插件配置 API，各 profile 可不同）：
     ```yaml
@@ -91,6 +95,36 @@ dsh plugin --profile web add @mengyuly/dsh-ponytail
 - **子代理（如实边界）**：DSH 内置 `subagent` 工具是**隔离派生**，但全局 system-prompt section 默认也会参与子代理的独立组装；这不是父代理 Prompt 或会话状态继承。`PONYTAIL_SUBAGENT_MATCHER`（匹配子代理 `agentPreset` 的正则）只用于筛选能进入本 Prompt 管线的子代理，不是继承开关；无 preset 时不会被 matcher 排除。DSH 当前没有公开的父子 Prompt 继承 API，因此**不宣称父子 Prompt 继承**（有官方 API 后再考虑只读模式快照传播）。非法正则告警一次并 fail-open。
 - **配置错误**：非法 JSON / 非法 `defaultMode` / 读取失败 / 非法正则只告警一次（不刷屏）；配置文件不存在属正常、不告警。
 
+## 图形操作
+
+支持原生 `settingsScope`/`settings.plugin.item` 接口的 DSH Web 中，打开
+**设置 → 插件 → Ponytail**：选择默认模式、分别开关五个附加技能、保存设置，
+或一键恢复面板默认。选择「跟随现有配置」会沿用旧配置，不替用户覆盖环境变量或 Profile。
+面板默认值不是当前会话模式；已有会话覆盖不变，实际模式与来源用 `/ponytail status` 查询。
+附加技能开关不会移除常驻核心规则，只有 `off` 模式关闭规则注入。
+
+原生命令菜单支持时，裸 `/ponytail` 打开模式选择器，并提供状态、会话重置和帮助入口。
+有参数的命令、TUI/CLI 用法保持原样。没有这些界面服务的旧宿主保留命令与文件配置路径。
+保存失败不显示成功，面板保留修改；只读连接禁用写入。面板重置仅清除自身设置，
+不删除旧配置、不清除已有会话覆盖，也不请求模型工作。
+
+已在 WSL Debian 的真实 DSH checkout `b150a551` 上用隔离 profile 联调界面与文件设置。
+旧版仅有 `set/unset` 的 Settings scope 通过宿主原子 RPC 保存，仍保留版本冲突检查。
+DSH 宿主契约 peer 保留版本声明，但标记为包管理器可选，由实际宿主提供；
+`cordis` 与 `schemastery` 仍是必需的运行时 peer。正常安装不需要关闭自动 peer 安装，
+也不会为了安装本插件拉取整套 DSH 和尚未发布的 `dsh-type-meta`。
+「可选」仅指依赖解析：实际运行仍需要 DSH 的 systemPrompt、skills 等宿主服务，不能脱离 DSH 独立运行。
+
+开发者界面验证（工具安装在仓库外，不进入 npm 包）：
+```powershell
+$env:PONYTAIL_TOOL_ROOT = Join-Path $env:TEMP 'ponytail-ui-tools'
+npm install --prefix $env:PONYTAIL_TOOL_ROOT --ignore-scripts typescript@6.0.3 esbuild@0.28.2 react@18.3.1 react-dom@18.3.1 jsdom@26.1.0
+node scripts/build-ui.mjs
+node scripts/test-ui.mjs
+```
+`build-ui` 保留已有内联宿主依赖，编译下游规则片段、插件入口和浏览器界面，**不是权威 monorepo 完整重建**。
+`dist-provenance.json` 中旧 `sourceCommit` 表示基线，`downstreamBuild` 记录当前修改的源码和产物 SHA-256。
+
 ## 效率（条件性收益，非保证）
 
 Ponytail 会给每次模型请求增加一小段固定规则。它的收益是**有条件的**：
@@ -104,14 +138,25 @@ prompt 与推理开销变得更贵。
 
 | 档位 | 字符数 | UTF-8 字节 | 说明 |
 |------|--------|-----------|------|
-| lite | 1915 | 1917 | 实测生成 |
-| full | 3022 | 3038 | 实测生成 |
-| ultra | 2797 | 2813 | 实测生成 |
+| lite | 3911 | 3913 | 实测生成 |
+| full | 4818 | 4834 | 实测生成 |
+| ultra | 5034 | 5050 | 实测生成 |
 | off | 0 | 0 | 不注入 |
 
 这些是 **Prompt 体积测量，不是账单金额，也不是对所有模型成立的节省
 比例**（无统一 tokenizer，`measure:prompt` 输出中 `estimated_tokens` 为
-null；字符数/4 只是粗略估算）。同模式字节级稳定，KV-cache 前缀命中。
+null；字符数/4 只是粗略估算）。同模式字节级稳定，有利于 Prompt 缓存，但不保证宿主或模型缓存命中。
+
+所有启用档位均保留上游边界：修复前检查所有调用方、同等大小方案优先边界正确性、
+有已知局限的捷径留下 `ponytail: <ceiling>, <upgrade path>` 注释、保留硬件校准，
+以及完整回答用户明确要求的解释。规则仅用于编码任务，不改写一般问答或翻译。
+所有启用档位包含完整七阶梯。Lite 必须用一句话指出更简单的替代方案，但由用户选定范围；
+Full 执行阶梯；Ultra 执行阶梯并更积极质疑不必要的复杂度。几行代码足够时不得新增依赖，
+在正确完整的前提下触及最少文件；用户坚持完整版本后直接实现，不反复争辩。
+非平凡逻辑保留一个最小可运行检查，不擅自增加逐函数测试套件；简单一行代码不要求额外测试。
+`ponytail-debt` 支持块注释和 `lib` 源码，两条扫描路径均跳过嵌套依赖与构建目录。
+验证覆盖规则内容、真实搜索命令及安装产物与源码的 Prompt/Skill 一致性；
+这些检查不代表模型遵循率或实际性能已经通过对照评测。
 
 **上游数据不是本 DSH 适配版的保证**：上游 Ponytail 的 single-shot
 （代码 −80~94%、成本 −42~75%、延迟 3.1–5.8×）与 agentic（LOC −54% 等）
@@ -144,7 +189,7 @@ Smoke Benchmark 只提供方向性证据（见 `docs/dsh-smoke-summary.md`）。
 ## 测试环境与权威关系
 
 - 本机（Linux，Node.js **v24.16.0**，deepseek-harness checkout 构建）与 CI 矩阵（**ubuntu-latest + windows-latest × Node 22/24**）上验证通过。与之精确匹配的已发布 DSH/Cordis 版本**待确认**——checkout 是预发布工作树，非发布 tag。
-- 权威源码在 deepseek-harness monorepo 的 `packages/community/ponytail`（`@deepseek-ai/dsh-ponytail`）；本仓库（`@mengyuly/dsh-ponytail`）是**发行镜像**：随包附构建产物，不是独立真源。
+- 历史宿主构建基线来自 deepseek-harness monorepo 的 `packages/community/ponytail`；当前 `@mengyuly/dsh-ponytail` 的下游适配修改以本仓库 `src/` 为准，随包附构建产物。
 
 ## 发行维护
 
@@ -154,7 +199,7 @@ Smoke Benchmark 只提供方向性证据（见 `docs/dsh-smoke-summary.md`）。
 > `scripts/` 命令（无维护脚本入口、无安装生命周期钩子），由
 > `node scripts/verify-pack.mjs` 回归检查强制。
 
-- **权威源码**：deepseek-harness monorepo 的 `packages/community/ponytail`（本仓库是发行镜像，只随包发布构建产物）。
+- **构建来源**：monorepo 提供历史内联依赖基线；当前下游适配源码在本仓库。`build-ui` 与完整 `sync:dist` 的证据范围不同，不能混称。
 - **维护者命令**（源码仓库内直接运行 `node scripts/<script>.mjs`；快捷清单见
   `package.dev.json`）：
   ```bash
@@ -162,8 +207,9 @@ Smoke Benchmark 只提供方向性证据（见 `docs/dsh-smoke-summary.md`）。
   node scripts/verify-dist.mjs         # 静态一致性：src/d.ts 导出一致、关键签名、运行时导出、provenance
   node scripts/verify-pack.mjs         # tarball 边界（含无 scripts/ 暴露回归检查）、版本、安装后 smoke
   node scripts/test-consumer.mjs       # NodeNext + skipLibCheck:false 声明消费测试（对打包产物）
-  node scripts/test-regressions.mjs    # 验证工具自身的回归测试
-  node scripts/test-core.mjs           # 核心 Prompt 字节、安全边界、模式与 Skill 表面
+  node scripts/test-regressions.mjs    # 验证工具自身的回归测试
+  node scripts/test-core.mjs           # 核心 Prompt 字节、安全边界、模式与 Skill 表面
+  node scripts/test-install.mjs        # pnpm 11 默认 peer 安装，无宿主源码树或规避配置
   node scripts/measure-prompt.mjs      # 各模式 Prompt 段体积（依赖未发布的 src/）
   node scripts/check-release-links.mjs # README/CHANGELOG/docs 无版本化 latest 资产链接
   node scripts/check-release-consistency.mjs --version <v>  # 四方发布一致性（git tag/npm/GitHub/provenance）
@@ -180,4 +226,4 @@ Smoke Benchmark 只提供方向性证据（见 `docs/dsh-smoke-summary.md`）。
 
 ## 许可
 
-MIT，© 2026 DietrichGebert（上游）+ MengYuil（移植）。详见 [LICENSE](LICENSE)。
+MIT，© 2026 DietrichGebert（上游）+ MengYuil（移植）。详见 [LICENSE](LICENSE)。

package/README_EN.md

@@ -0,0 +1,366 @@
+# dsh-ponytail
+
+English | [简体中文](README.md)
+
+![CI](https://github.com/MengYuil/dsh-ponytail/actions/workflows/ci.yml/badge.svg)
+![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)
+[![npm](https://img.shields.io/npm/v/@mengyuly/dsh-ponytail)](https://www.npmjs.com/package/@mengyuly/dsh-ponytail)
+[![dsh.so security](https://www.dsh.so/badge/dsh-ponytail-4.svg)](https://www.dsh.so/artifact/dsh-ponytail-4/)
+
+Adapts the minimal-coding principles and skills of
+[DietrichGebert/ponytail](https://github.com/DietrichGebert/ponytail) to
+[DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness): a YAGNI
+decision ladder, session-level Lite / Full / Ultra / Off modes, and a set of
+skills for code slimming, review, auditing, and technical-debt tracking.
+
+This project aligns with the upstream core ideas and main workflows, but DSH's
+model loop, prompt assembly, skill mechanism, and tool calls differ. **The
+upstream benchmark is a reference only and does not imply that this port has
+the same token, cost, or latency gains** (see “Efficiency (conditional gains,
+not guarantees)”).
+
+## Download from GitHub Releases
+
+- **Latest release**:
+  `https://github.com/MengYuil/dsh-ponytail/releases/latest/download/mengyuly-dsh-ponytail.tgz`
+- **Pinned version v0.3.4** (immutable per tag):
+  `https://github.com/MengYuil/dsh-ponytail/releases/download/v0.3.4/mengyuly-dsh-ponytail.tgz`
+
+Notes:
+
+- **latest**: good for a quick install; it tracks the newest release. The fixed
+  asset name `mengyuly-dsh-ponytail.tgz` stays the same in every release, so
+  the URL never breaks on a version bump — which also means it is **not
+  suitable as an immutable dependency**.
+- **Pinned version**: good for reproducible installs; the URL pins a tag
+  (e.g. `v0.3.4`) that is immutable per tag; the asset name is likewise
+  `mengyuly-dsh-ponytail.tgz`.
+- npm installs still go through the npm Registry or the `dsh plugin` command.
+- The fixed asset name is produced and verified by
+  `scripts/release-assets.mjs` (`node scripts/release-assets.mjs`, maintainers
+  only).
+
+## Installation
+
+Install into a profile (replace `web` with `tui` or a custom name):
+
+```bash
+# Option 1: local link (current dsh cores >= 0.1.x)
+dsh plugin --profile web add link:$(pwd)
+
+# Option 2: install straight from GitHub
+dsh plugin --profile web add github:MengYuil/dsh-ponytail
+
+# Option 3: Release tarball (download the tgz first — the latest fixed asset
+# name never changes)
+#   https://github.com/MengYuil/dsh-ponytail/releases/latest/download/mengyuly-dsh-ponytail.tgz
+dsh plugin --profile web add file:./mengyuly-dsh-ponytail.tgz
+
+# Option 4: npm
+dsh plugin --profile web add @mengyuly/dsh-ponytail
+```
+
+Restart the profile after installing (`dsh web` / `dsh tui`) for it to take
+effect. Once loaded, the session skill catalog shows 6 `ponytail*` skills; send
+`/ponytail-help` to verify immediately.
+
+> `lib/index.js` is a self-contained bundle (`dsh-llm` / `dsh-skill` are
+> already inlined — npm has no compatible versions) with two published
+> runtime peers: `@deepseek-ai/cordis` (4.0.1) and
+> `@deepseek-ai/schemastery` (3.18.x). `schemastery` is deliberately kept
+> external rather than inlined: its schema DSL compiles `callback` strings
+> with `new Function`, so keeping it out means **the shipped artifact contains
+> no dynamic code execution** (CI has a dedicated check). None of the three
+> install paths — GitHub, tgz, npm — needs a dsh source tree.
+
+> Note: `src/` is the source, `lib/` is the prebuilt artifact (loadable
+> out of the box, no build step). The authoritative source lives in the
+> deepseek-harness monorepo at `packages/community/ponytail`; after changing
+> source, rebuild and sync the full `lib/` with
+> `DSH_CHECKOUT=/path/to/deepseek-harness node scripts/sync-dist.mjs`
+> (see “Release maintenance” below).
+
+## Features
+
+- **Core mode** `/ponytail` — injects a structured lazy-developer ruleset
+  every turn; **the three levels are genuinely different prompt fragments**
+  (not just a swapped line):
+  - **Common (shared by every non-off level)**: turn the request into an
+    observable completion condition first; gather evidence along the real call
+    flow, but the decision ladder is a quick reflex, not a research project;
+    follow the “inspect → change → narrowest effective verification → inspect
+    the final diff” loop; non-trivial logic keeps exactly one minimal runnable
+    check, without standing up a test framework or fixtures; report only
+    verified results.
+  - **Safety (never removable in any level)**: input validation, error
+    handling that prevents data loss, security measures, accessibility,
+    explicit acceptance criteria, understanding the problem first, and
+    “minimal diff ≠ correct fix”.
+  - **`lite`**: execute directly, less ceremony; still complete explicit
+    deliverables; you may point out a simpler approach in one sentence, but
+    **do not challenge explicit requirements**.
+  - **`full`** (default): the full seven-rung ladder (YAGNI → reuse → stdlib
+    → native → installed dependencies → one line → minimal implementation);
+    pick the shortest correct implementation by default; fix root causes, not
+    symptoms.
+  - **`ultra`**: demand evidence before adding code; prefer deleting or
+    reusing; proactively question speculative features/caching/abstraction/
+    configuration/new dependencies; for complex requests deliver the minimal
+    correct version first and state the conditions for expanding — **not a
+    blanket refusal**.
+  - `off`: no injection at all.
+  - Levels are **session-scoped** (session A does not affect session B;
+    released automatically when the session ends).
+  - Bare `/ponytail`: when enabled it only reports; when `off` it restores the
+    effective default level (falling back to `full` if that default is also
+    `off`).
+  - `/ponytail status`: query only, never modifies, and shows whether the
+    current mode comes from a session override or the configured default.
+  - `/ponytail reset`: clears the current session override and follows the
+    effective configured default again.
+  - `/ponytail lite|full|ultra|off`: explicit switch.
+  - `/ponytail help`: displays command help without calling the model.
+  - `/ponytail default <mode>`: persists through DSH Settings when available,
+    otherwise the user-level config file (env/profile still take priority; the command reports both
+    `saved` and `effective`).
+  - Status changes take effect immediately without waking an idle agent.
+    Notices reach the model on its next real step, avoiding an extra model
+    turn just to switch levels.
+- **One-shot skills** (load on demand, never part of the standing prompt):
+  - `/ponytail-review` — find over-engineering in recent changes; every
+    finding includes location, replacement, and actual call evidence; no
+    guessed savings numbers.
+  - `/ponytail-audit` — whole-repo over-engineering audit; distinguishes
+    safe-to-delete from verify-first candidates; at most 10 high-value
+    findings.
+  - `/ponytail-debt` — harvests all `ponytail:` comments into a debt ledger.
+  - `/ponytail-gain` — upstream benchmark reference scoreboard (less code;
+    token/cost/latency effects depend on model and task, **not guaranteed by
+    this port**).
+  - `/ponytail-help` — reference card.
+- **Deactivation**: say `stop ponytail`, `normal mode`, `停止 ponytail`,
+  `关闭 ponytail`, `普通模式`, or `正常模式` (trailing Chinese/English
+  punctuation tolerated); `/ponytail` re-enables at any time.
+- **Default priority** (consistent across code/tests/docs):
+  ```
+  session override > PONYTAIL_DEFAULT_MODE > Profile config.defaultMode > DSH Settings > user config.json > full
+  ```
+  - **Profile-level config** (official Cordis plugin config API; each profile
+    can differ):
+    ```yaml
+    # add config to the ponytail row in ~/.dsh/profiles/tui/cordis.patch.yml
+    - insert:
+        - id: ponytail
+          name: '@mengyuly/dsh-ponytail'
+          config:
+            defaultMode: lite
+    ```
+    Example: `web → full`, `tui → lite`, `automation → off`. Profile config is
+    read when the plugin initializes (Cordis has no public config-change
+    event), so **restart that profile after changing it**; an invalid value
+    warns once and falls back without breaking startup. The user `config.json`
+    stays hot-reloaded.
+  - **User config.json** (`~/.config/ponytail/config.json`, Windows
+    `%APPDATA%\ponytail\config.json`): `{"defaultMode": "lite"}`,
+    hot-reloaded (~1s polling); invalid content keeps the last valid value.
+- **Subagents (honest boundaries)**: DSH's built-in `subagent` tool is an
+  **isolated fork**, but the global system-prompt section participates in each
+  subagent's own assembly by default; this is not parent-prompt or session
+  state inheritance. `PONYTAIL_SUBAGENT_MATCHER` (a regex matched against the
+  subagent's `agentPreset`) only filters which subagents can enter this prompt
+  pipeline — it is not an inheritance switch; without a preset nothing is
+  excluded by the matcher. DSH currently has no public parent→child prompt
+  inheritance API, so **no parent-child prompt inheritance is claimed** (a
+  read-only mode-snapshot propagation may follow once an official API
+  exists). An invalid regex warns once and fails open.
+- **Config errors**: invalid JSON / invalid `defaultMode` / read failures /
+  invalid regex warn exactly once (no log spam); a missing config file is
+  normal and never warns.
+
+## Graphical controls
+
+On DSH Web hosts with the native `settingsScope`/`settings.plugin.item` APIs,
+open **Settings → Plugins → Ponytail** to select a default mode, toggle five
+optional skills, save, or reset panel defaults. “Follow existing configuration”
+preserves legacy configuration. Environment/profile values still take priority;
+existing session overrides stay intact. Use `/ponytail status` for the actual
+session mode and source. Optional-skill toggles never remove the core rules.
+
+When supported, bare `/ponytail` opens a native picker with mode/status/reset/help
+actions. Argued commands and TUI/CLI behavior remain unchanged. Older hosts
+without these services keep the command/config-file paths. Failed saves retain
+drafts; read-only connections cannot write. Panel reset clears only its own
+overrides, not legacy files or session state, and requests no model work.
+
+The native UI and file-backed settings were integration-tested in an isolated
+profile on the real WSL Debian DSH checkout `b150a551`. Older Settings scopes
+with only `set/unset` save through the host's atomic RPC with revision checks.
+DSH contract peers retain their version ranges but are optional for package
+resolution and supplied by the host. Cordis and schemastery remain required
+runtime peers. Normal installation needs no auto-peer workaround and does not
+fetch a second DSH or the unpublished `dsh-type-meta` peer. Optional metadata
+does not make host services optional: runtime still requires DSH systemPrompt,
+skills, and the other services used by the plugin.
+
+Developer UI checks use isolated tools, excluded from the npm tarball:
+```powershell
+$env:PONYTAIL_TOOL_ROOT = Join-Path $env:TEMP 'ponytail-ui-tools'
+npm install --prefix $env:PONYTAIL_TOOL_ROOT --ignore-scripts typescript@6.0.3 esbuild@0.28.2 react@18.3.1 react-dom@18.3.1 jsdom@26.1.0
+node scripts/build-ui.mjs
+node scripts/test-ui.mjs
+```
+`build-ui` retains baseline inlined host dependencies and compiles downstream
+rule fragments and entry/UI code; it is **not an authoritative monorepo rebuild**. Provenance's
+`sourceCommit` identifies the baseline; `downstreamBuild` records current source
+and artifact hashes.
+
+## Efficiency (conditional gains, not guarantees)
+
+Ponytail adds a small fixed ruleset to every model request. Its benefit is
+**conditional**: when the agent tends to over-engineer, the reduced code,
+tool calls, and rework may offset or exceed that overhead; when the task is
+already simple, the gain may be near zero — or the extra input overhead may
+lose outright. It is not a “save tokens switch” and does not guarantee savings
+across models — some reasoning models may get more expensive due to prompt
+and reasoning overhead.
+
+Measured prompt-section sizes for this DSH port (`node
+scripts/measure-prompt.mjs`, generated from the real
+`getPonytailInstructions()`):
+
+| Level | Characters | UTF-8 bytes | Notes |
+|------|--------|-----------|------|
+| lite | 3911 | 3913 | measured output |
+| full | 4818 | 4834 | measured output |
+| ultra | 5034 | 5050 | measured output |
+| off | 0 | 0 | not injected |
+
+These are **prompt-size measurements, not billing amounts, and not a savings
+ratio that holds for every model** (there is no universal tokenizer;
+`estimated_tokens` in `measure:prompt` output is null; characters/4 is only a
+rough estimate). Same-mode output is byte-stable, which helps prompt caching,
+but does not guarantee a host or model cache hit.
+
+Every active level preserves upstream boundaries: check all callers before a
+bug fix, prefer edge-case correctness between same-size options, annotate real
+shortcuts with `ponytail: <ceiling>, <upgrade path>`, retain hardware calibration,
+and give explicitly requested explanations in full. Rules apply to coding only,
+not unrelated prose or translation. Debt scans support block comments and `lib`
+sources; both scan paths exclude nested dependency and build directories.
+Checks cover prompt contracts, actual scan commands, and exact installed/source
+prompt and skill parity, not model compliance rates or measured performance.
+
+Every active prompt contains the complete seven-rung ladder. Lite must name a
+simpler alternative in one line while leaving scope to the user; Full enforces
+the ladder; Ultra enforces it and challenges unnecessary complexity more actively.
+Do not add dependencies for work a few lines can do; touch the fewest files that
+deliver a correct complete fix. If the user insists on full scope, build it
+without re-arguing. Non-trivial logic keeps one minimal runnable check, not an
+unrequested per-function suite; trivial one-liners need no extra test.
+
+**Upstream numbers are not a guarantee for this DSH port**: the upstream
+Ponytail single-shot results (code −80–94%, cost −42–75%, latency 3.1–5.8×)
+and agentic results (LOC −54% etc.) are references only; this DSH port has
+**not** established stable token/cost/latency savings rates. The DSH smoke
+benchmark provides directional evidence only (see
+`docs/dsh-smoke-summary.md`).
+
+## Known limitations
+
+- The levels differ in **rule semantics** (see above); the three prompt
+  sizes are similar (measured in the table above).
+- The upstream Claude-only statusline badge has no DSH counterpart; the MCP
+  server was dropped because DSH has a first-class system-prompt injection
+  point.
+- User `config.json` hot-reloads; `PONYTAIL_DEFAULT_MODE` and profile config
+  need a restart.
+- The shipped `lib/` is a prebuilt artifact; to change behavior, rebuild in
+  the main repo and re-sync.
+
+## Compatibility matrix (measured, not fabricated)
+
+| Component | Verified environment | Notes |
+|---|---|---|
+| Node.js | 22.x / 24.x | CI matrix, 4 combinations green |
+| OS | ubuntu-latest / windows-latest | CI matrix |
+| DSH | commit `b150a551` (build checkout) | exact mapping to an official release **TBD** |
+| Cordis | 4.0.1 (build vendor) | same |
+| web profile | verified | long-running on a real local profile + three isolated install-path tests (npm / GitHub / tgz) |
+| tui profile | not verified | not started inside a tui profile |
+| headless profile | not verified | not fully started; plugin unit tests run in a UI-less environment |
+| npm tarball | verified | contents/version/post-install smoke/NodeNext consumer |
+
+- `dist-provenance.json` records the actual build sources (checkout commit +
+  node/typescript/tsdown/cordis versions).
+- Do not hide failures with `continue-on-error` — the matrix is green only if
+  every cell is green.
+
+## Test environments and source of truth
+
+- Verified locally (Linux, Node.js **v24.16.0**, deepseek-harness checkout
+  build) and in the CI matrix (**ubuntu-latest + windows-latest × Node
+  22/24**). The exact published DSH/Cordis release they correspond to is
+  **TBD** — the checkout is a prerelease working tree, not a release tag.
+- The historical host build baseline is `packages/community/ponytail` in the
+  deepseek-harness monorepo. Current `@mengyuly/dsh-ponytail` downstream changes
+  are maintained in this repository's `src/`, alongside shipped artifacts.
+
+## Release maintenance
+
+> **The commands below are for source-repository maintainers only.** The
+> `scripts/` directory is deliberately **excluded from the npm tarball**, so
+> these commands are unavailable after installing the published package — npm
+> users never need to run maintenance checks; they exist for maintainers and
+> CI before a release. The published `package.json` exposes no `scripts/`
+> commands (no maintenance entry points, no install lifecycle hooks),
+> enforced by a regression check in `node scripts/verify-pack.mjs`.
+
+- **Build sources**: the monorepo supplies the historical inlined dependency
+  baseline; this repository owns current downstream source. `build-ui` and a
+  full `sync:dist` provide different evidence and must not be conflated.
+- **Maintainer commands** (run `node scripts/<script>.mjs` inside the source
+  repository; see `package.dev.json` for the shortcut list):
+  ```bash
+  node scripts/check-bundle.mjs        # bundle external-dependency allowlist + no new Function/eval
+  node scripts/verify-dist.mjs         # static consistency: src/d.ts export parity, key signatures, runtime exports, provenance
+  node scripts/verify-pack.mjs         # tarball boundary (incl. no scripts/ exposure regression), versions, post-install smoke
+  node scripts/test-consumer.mjs       # NodeNext + skipLibCheck:false declaration consumer test (against the packed artifact)
+  node scripts/test-regressions.mjs    # regression tests for the verification tooling itself
+  node scripts/test-core.mjs           # core prompt bytes, safety boundaries, modes and skill surface
+  node scripts/test-install.mjs        # pnpm 11 default peer installation, no host tree/workaround
+  node scripts/measure-prompt.mjs      # prompt-section size per mode (depends on the unpublished src/)
+  node scripts/check-release-links.mjs # README/CHANGELOG/docs contain no versioned latest asset links
+  node scripts/check-release-consistency.mjs --version <v>  # four-way release consistency (git tag/npm/GitHub/provenance)
+  ```
+- **Fully regenerate and sync `lib/`** (JS and declarations must be synced as
+  one artifact; copying a single JS file is forbidden):
+  ```bash
+  DSH_CHECKOUT=/path/to/deepseek-harness node scripts/sync-dist.mjs
+  ```
+  This rebuilds inside the authoritative checkout (`tsc` for declarations +
+  `tsdown` for the runtime bundle), syncs `lib/index.js`, `lib/invariant.js`,
+  `lib/types/*.d.ts`, generates `dist-provenance.json` (recording the
+  authoritative checkout's real commit SHA and toolchain versions), and runs
+  the consistency checks automatically; it prompts you to commit when
+  artifacts changed. **Full build consistency is produced by this command in
+  the release process — the mirror repository's CI never rebuilds the
+  authoritative monorepo.**
+- **CI capability boundary (honest)**: CI (ubuntu + windows matrix) runs the
+  static verification and pack/consumer tests above, but **does not rebuild
+  the authoritative monorepo**; `verify:dist` is an export-surface/signature/
+  runtime-export consistency check, **not** a byte-level equivalence proof
+  against the authoritative build — that is guaranteed by `sync:dist` in the
+  release process.
+- `dist-provenance.json` ships with the npm package for build-source audits.
+- When verifying locally, if `npm_execpath` points at another package manager
+  (e.g. a pnpm/yarn shim), the scripts fall back to `npm` on PATH; set
+  `PONYTAIL_VERIFY_KEEP_TEMP=1` to keep temp directories on failure.
+- **Security**: `scripts/**` exists only for development/build/release
+  verification — **not in the npm tarball**, no install lifecycle hooks, not
+  referenced by the runtime entry point, and not exposed in the published
+  `package.json`; `child_process` warnings there are accepted development-tool
+  risk. See [SECURITY.md](SECURITY.md).
+
+## License
+
+MIT, © 2026 DietrichGebert (upstream) + MengYuil (port). See [LICENSE](LICENSE).

package/cordis.patch.yml

@@ -1,4 +1,4 @@
 # dsh bundle patch: inserts the ponytail persona plugin into a profile's layer stack.
 - insert:
     - id: ponytail
-      name: '@mengyuly/dsh-ponytail'
+      name: '@mengyuly/dsh-ponytail'

package/dist-provenance.json

@@ -1,11 +1,26 @@
-{
-  "sourceRepository": "https://github.com/deepseek-ai/deepseek-harness.git",
-  "sourceCommit": "b150a551b8d465e31e418e1b2eaf5e79bbb7d28e",
-  "sourcePackage": "packages/community/ponytail",
-  "generatedBy": {
-    "node": "v24.16.0",
-    "typescript": "6.0.3",
-    "tsdown": "0.22.2",
-    "cordis": "4.0.1"
-  }
-}
+{
+  "sourceRepository": "https://github.com/deepseek-ai/deepseek-harness.git",
+  "sourceCommit": "b150a551b8d465e31e418e1b2eaf5e79bbb7d28e",
+  "sourcePackage": "packages/community/ponytail",
+  "generatedBy": {
+    "node": "v24.16.0",
+    "typescript": "6.0.3",
+    "tsdown": "0.22.2",
+    "cordis": "4.0.1"
+  },
+  "downstreamBuild": {
+    "method": "scripts/build-ui.mjs; retains baseline inlined host dependencies",
+    "node": "v24.15.0",
+    "typescript": "6.0.3",
+    "esbuild": "0.28.2",
+    "sha256": {
+      "src/index.ts": "8421733adf8c801c1578b070cf789b5bd77588acbe90403dd69ee5467375c955",
+      "src/client.ts": "7a2c941b8a85096d863da16982ba9c6b82c709cb0561057f1b221239bbb6688a",
+      "src/content.ts": "9dc57919da6cbfcf06ae26a19e81bb0299e44d2b9c016d3477572758d9ade375",
+      "src/instructions.ts": "d96deb078f6f633fffb0e3da2750eb9d3afb37bce4cea11145db045c8cceb935",
+      "src/modes.ts": "74b8b885d145759ce17007a054ab6adc295f726f47518f56a3d37de67bd14231",
+      "lib/index.js": "b5856ca9147b78111edcd9d43be3edec4c15295ddb7539f4bf48244fef7f6ffb",
+      "lib/client.js": "84ea84dc9a6148e822f9830999cca0229a27b3696ab000394a53cc2fef3454b4"
+    }
+  }
+}