dsh-plugin-guide 0.3.42 → 0.4.0

package/references/official-docs/docs/cookbook/maintaining-dsh-code-review.md

@@ -1,64 +0,0 @@
-# Maintaining the dsh-code-review skill
-
-English | [中文](maintaining-dsh-code-review.zh.md)
-
-The [`dsh-code-review`](../../.agents/skills/dsh-code-review/SKILL.md) skill is kept current by a single designated operator running a private periodic maintenance tool. This cookbook is the entry point for that operator — and for anyone taking over the role — and for repo contributors who want to understand why skill updates arrive as small periodic PRs rather than one-off audits. The workflow itself is specified in the [human-review skill-maintenance Agent Note](../../.agents/notes/proposed/process/2026-07-13-human-review-skill-maintenance.md).
-
-## What the maintainer receives
-
-The operator invokes the wrapper manually, daily with a two-UTC-day overlap; a manual weekly recovery run uses a seven-day window. The workflow:
-
-1. It selects PRs merged in the chosen window (default two UTC days for the daily cadence, seven for weekly) whose merge commit is reachable from `origin/master`. PRs whose merge commit is not reachable (stacked branches whose parent was squashed) or that exceed a 250-commit acquisition cap are logged to `skipped-pulls.json` and skipped rather than aborting the run.
-2. It collects pre-merge human review feedback with commit anchors (inline comments and review submissions), then compares feedback-time and final landed PR patches. It does not acquire PR conversation comments because current GitHub state cannot give them a force-push-safe feedback-time baseline, and it excludes target-branch-only changes from adoption evidence.
-3. Two independently configured reviewer adapters classify who wrote each item and whether the change adopted it, then classify agreed-adopted items against the current skill.
-4. The primary adapter drafts a complete revised `SKILL.md`; both adapters review the same diff; blocking findings loop until both approve.
-5. `pnpm run doc-sync` and `pnpm run lint` run against the candidate before the tool declares success.
-
-Each run stores its artifacts on the operator's machine. The saved diff, candidate `SKILL.md`, and promotion manifest land under `~/dsh-code-review-outputs/` named by timestamp. The manifest records the source master commit and skill blob, source feedback IDs and URLs, landed evidence ranges, adapter verdicts, and gate results; raw per-adapter I/O stays in a private temp directory whose path is written to the notification and to the daily log under `~/Library/Logs/dsh-code-review-maintainer/`. The maintenance worktree itself is restored clean after every run so the operator is never tempted to edit the maintenance copy in place.
-
-## What the operator does with a candidate diff
-
-When a run produces a candidate, a macOS notification arrives with a `dsh-code-review-promote <timestamp>` hint.
-
-1. **Read the diff on its own merits.** Do not defer to "the reviewers approved"; the maintainer contract is that the operator makes the final decision. Look for checklist bloat, historical prose, unsupported extrapolation from a single incident, and duplicated coverage with existing skill or authoritative-doc content.
-
-   ```sh
-   ls ~/dsh-code-review-outputs/                         # every candidate ever produced
-   less ~/dsh-code-review-outputs/2026-07-16T02-00-00Z.diff
-   less ~/dsh-code-review-outputs/2026-07-16T02-00-00Z.SKILL.md
-   less ~/dsh-code-review-outputs/2026-07-16T02-00-00Z.manifest.json
-   ```
-
-2. **Cross-check against the run artifacts.** The promotion manifest maps each proposed rule to source feedback and landed evidence; detailed per-adapter I/O, consensus, and adopted evidence live under the run's private temp directory (path shown in the log). Spot-check at least one candidate: does the linked human comment actually support the added rule? Does the linked PR actually adopt it?
-
-3. **Decide one of three:**
-   - **Discard.** Delete the saved candidate. The tool re-considers the same feedback on the next run under whatever the current skill then says.
-
-     ```sh
-     rm ~/dsh-code-review-outputs/2026-07-16T02-00-00Z.{diff,SKILL.md,manifest.json}
-     ```
-   - **Batch.** Keep the candidate aside if the update is small and could combine with a future one. The source-skill check still applies; rerun the analysis or manually rebase and re-review the diff if `master` changes first.
-   - **Promote.** From a clean `master` checkout of the repo, run the promote helper. It refreshes `master`, verifies that the current skill matches the recorded source blob, applies the saved diff, and opens a draft PR whose body lists the source feedback URLs or IDs, landed commit range, originating run, checks, and operator edits. It stops on skill drift rather than overwriting newer guidance; the operator still reviews the PR on GitHub and either merges it or closes it.
-
-     ```sh
-     cd ~/path/to/deepseek-harness   # clean master
-     dsh-code-review-promote 2026-07-16T02-00-00Z
-     ```
-
-4. **Do not commit adapter output verbatim.** Small edits during promotion — tightening wording, removing an example that only makes sense with the source PR's context, folding a rule into an existing one — are expected and preserve the "reviewer judgment" the workflow depends on. Amend the branch before merging.
-
-## When a run produces no candidate
-
-That is the common case after every nonempty classification stage has produced at least one valid adapter result. The tool records "no candidate" in its daily log, sends no notification (to avoid alert fatigue), and moves on. Days without a skill update are the workflow behaving correctly, not a stall.
-
-## Interruptions and handoff
-
-The mechanism lives on one machine. Interruptions the operator handles as they arise:
-
-- **Daily run missed.** The two-day overlap window catches one skipped day automatically; longer gaps recover by running the wrapper manually with `DSH_CODE_REVIEW_SINCE=<Nd>`. Overlapping windows are idempotent: guidance already in the current skill is classified `covered` and does not re-enter as a candidate.
-- **Adapter provider outage.** The tool refuses to run when the two reviewer commands resolve to byte-identical executables. A single batch whose adapter response fails schema or id validation is failed closed at the batch level (every item in the batch marked unclear) and the run continues; the raw output is preserved for debugging. If either adapter produces no valid result for any nonempty batch in an operation, the run fails, writes a failure record, and notifies the operator; it never collapses a total-provider outage into "no candidate."
-- **Handoff to another maintainer.** Open a follow-up Agent Note that supersedes the current one: either move the mechanism into the repository or record the new operator's private setup. Do not silently transfer the tool — the "single-maintainer bus factor" in the Agent Note's Risks section is the reason the handoff needs a documented decision.
-
-## Where the operator's private setup lives
-
-The tool source, reviewer adapters, provider credentials, and scheduler are the operator's private infrastructure and are outside this repository by design (see the Agent Note's "Where the mechanism lives" section). This cookbook and the Agent Note describe **what the workflow guarantees**; **how** those guarantees are implemented is a private-infrastructure concern. If you are the new operator, the Agent Note's `## Proposal` sections are the specification you build against.

package/references/official-docs/docs/cookbook/maintaining-dsh-code-review.zh.md

@@ -1,64 +0,0 @@
-# 维护 dsh-code-review skill
-
-[English](maintaining-dsh-code-review.md) | 中文
-
-[`dsh-code-review`](../../.agents/skills/dsh-code-review/SKILL.md) skill（技能）由一名指定操作员通过私有的周期维护工具持续更新。本实操手册既是该操作员和接任者的入口，也帮助仓库贡献者理解为何 skill 更新会以小型周期 PR（Pull Request）的形式出现，而不是一次性审计。工作流本身由[人工评审 skill 维护 Agent Note](../../.agents/notes/proposed/process/2026-07-13-human-review-skill-maintenance.zh.md)规定。
-
-## 维护者会收到什么
-
-操作员每天手动调用包装脚本，并使用 2 个 UTC 日的重叠窗口；每周手动恢复运行使用 7 日窗口。工作流会：
-
-1. 选择指定窗口内合并、且合并 commit 可从 `origin/master` 到达的 PR（每天运行默认选择 2 个 UTC 日，每周运行选择 7 日）。合并 commit 无法到达的 PR（例如父分支被 squash 的堆叠分支），或超出 250 个 commit 获取上限的 PR，会记录到 `skipped-pulls.json` 并跳过，不会中止本次运行。
-2. 收集合并前带 commit 锚点的人工评审反馈（行内评论和评审提交），然后比较反馈时与最终落地的 PR patch。它不获取 PR 会话评论，因为 GitHub 当前状态无法为这些评论提供可抵抗 force-push 的反馈时基线；它也不会把只存在于目标分支的变更作为采纳证据。
-3. 两个独立配置的评审适配器先对每个条目的作者以及更改是否采纳了它进行分类，再根据当前 skill 对双方一致认定已采纳的条目分类。
-4. 主适配器起草完整修订版 `SKILL.md`；两个适配器评审同一份 diff；只要仍有阻塞性问题，循环就会继续，直到双方批准。
-5. 工具声明成功前，会针对候选版本运行 `pnpm run doc-sync` 和 `pnpm run lint`。
-
-每次运行都把产物保存在操作员的机器上。保存的 diff、候选 `SKILL.md` 和提升 manifest（元数据清单）按时间戳命名，存放在 `~/dsh-code-review-outputs/` 下。manifest 记录源 master commit 与 skill blob、源反馈 ID 和 URL、已落地证据范围、适配器裁决和门禁结果；每个适配器的原始 I/O 留在私有临时目录中，该目录路径会写入通知和 `~/Library/Logs/dsh-code-review-maintainer/` 下的每日日志。维护 worktree 在每次运行后都会恢复为干净状态，避免操作员直接在维护副本中编辑。
-
-## 操作员如何处理候选 diff
-
-某次运行产出候选版本时，macOS 会发出一条带 `dsh-code-review-promote <timestamp>` 提示的通知。
-
-1. **根据 diff 本身作出判断。** 不要因为「评审者已经批准」就直接接受；维护者约定规定由操作员作出最终决定。检查清单是否膨胀、是否有历史叙述、是否根据单次事件作出无依据的外推，以及是否与现有 skill 或权威文档重复。
-
-   ```sh
-   ls ~/dsh-code-review-outputs/                         # every candidate ever produced
-   less ~/dsh-code-review-outputs/2026-07-16T02-00-00Z.diff
-   less ~/dsh-code-review-outputs/2026-07-16T02-00-00Z.SKILL.md
-   less ~/dsh-code-review-outputs/2026-07-16T02-00-00Z.manifest.json
-   ```
-
-2. **与运行产物交叉核验。** 提升 manifest 会把每条拟议规则映射到源反馈和已落地证据；每个适配器的详细 I/O、共识和采纳证据位于本次运行的私有临时目录中（路径见日志）。至少抽查一个候选项：链接的人工评论是否确实支持新增规则？链接的 PR 是否确实采纳了它？
-
-3. **从三种处理方式中选择一种：**
-   - **丢弃。** 删除保存的候选版本。下一次运行会依据届时的当前 skill，重新考虑同一份反馈。
-
-     ```sh
-     rm ~/dsh-code-review-outputs/2026-07-16T02-00-00Z.{diff,SKILL.md,manifest.json}
-     ```
-   - **留待成批处理。** 如果更新很小，可以把候选版本留待与后续版本合并。源 skill 检查仍然适用；如果 `master` 先发生变化，请重新运行分析，或手动 rebase 并重新评审 diff。
-   - **提升。** 在仓库的干净 `master` checkout 中运行提升辅助工具。它会刷新 `master`、验证当前 skill 与记录的源 blob 一致、应用保存的 diff，并创建一份 draft PR，其正文列出原始反馈的 URL 或 ID、已落地的 commit 范围、发起这次更改的运行、检查以及操作员编辑。如果 skill 已发生漂移，它会停止而不是覆盖更新后的指导；操作员仍需在 GitHub 上评审 PR，并选择合并或关闭。
-
-     ```sh
-     cd ~/path/to/deepseek-harness   # clean master
-     dsh-code-review-promote 2026-07-16T02-00-00Z
-     ```
-
-4. **不要逐字提交适配器输出。** 提升过程中可以进行小幅编辑，例如收紧措辞、移除只有结合源 PR 上下文才有意义的示例、把规则并入现有规则。这些编辑是预期行为，也保留了工作流所依赖的「评审者判断」。合并前应在该分支上修订这些改动。
-
-## 运行未产出候选版本时
-
-只要每个非空分类阶段都至少产生一个有效的适配器结果，这就是常见情况。工具会在每日日志中记录「无候选版本」，不发送通知（避免提醒疲劳），然后继续。某天没有 skill 更新，说明工作流运行正常，而不是停滞。
-
-## 中断与交接
-
-该机制运行在一台机器上。操作员应随时处理以下中断：
-
-- **错过每日运行。** 2 日重叠窗口会自动覆盖一次漏跑；更长的间隔可通过设置 `DSH_CODE_REVIEW_SINCE=<Nd>` 手动运行包装脚本来恢复。重叠窗口具有幂等性：当前 skill 已包含的指导会被归类为 `covered`，不会再次成为候选项。
-- **适配器提供方中断。** 当两个评审命令解析为逐字节相同的可执行文件时，工具会拒绝运行。某个批次的适配器响应未通过 schema 或 ID 校验时，该批次会整体 fail-closed（其中每个条目都标记为不明确），运行则继续；原始输出会保留以便调试。如果任一适配器在某项操作的所有非空批次中都未产生有效结果，本次运行就会失败、写入失败记录并通知操作员；它绝不会把提供方完全中断折叠成「无候选版本」。
-- **交接给另一名维护者。** 新建一篇取代当前记录的后续 Agent Note：要么把机制移入仓库，要么记录新操作员的私有设置。不要暗中转交工具；Agent Note 的风险章节已把「单维护者关键人风险」列为交接必须记录决策的原因。
-
-## 操作员的私有设置位于何处
-
-工具源代码、评审适配器、提供方凭据和调度器属于操作员的私有基础设施，按设计位于本仓库之外（参见 Agent Note 的「机制位于何处」章节）。本实操手册和 Agent Note 描述的是**工作流保证什么**；这些保证**如何**实现则属于私有基础设施问题。如果你是新操作员，应以 Agent Note 的 `## Proposal` 各节作为实现依据。

package/references/official-docs/docs/cookbook/responding-to-pr-review-on-a-stack.i18n.yaml

@@ -1,16 +0,0 @@
-# Bilingual-pair consistency record for responding-to-pr-review-on-a-stack.md (docs/i18n/README.md): per heading
-# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
-# After editing either side, bring the other along and re-record with:
-#   pnpm run verify-translation-pairing --write docs/cookbook/responding-to-pr-review-on-a-stack.md
-/responding-to-review-across-a-stacked-pr-chain:
-  en: f41561de1c6dbfef
-  zh: 83b863e1ac91d913
-/responding-to-review-across-a-stacked-pr-chain/ground-rules:
-  en: 5545e41aea74b5d6
-  zh: 7105f51939753a1a
-/responding-to-review-across-a-stacked-pr-chain/resolve-comments-through-the-stack:
-  en: 4d58b207c8ecbcaa
-  zh: 38673a460674b8d6
-/responding-to-review-across-a-stacked-pr-chain/verify:
-  en: 07cfbae7602fc30e
-  zh: 19782f06ee3c4a74

package/references/official-docs/docs/cookbook/responding-to-pr-review-on-a-stack.md

@@ -1,32 +0,0 @@
-# Responding to review across a stacked PR chain
-
-English | [中文](responding-to-pr-review-on-a-stack.zh.md)
-
-Review comments may target several PRs in a dependent stack (`A ← B ← C …`). Keep that chain linked through GitHub's official stacked-PR feature. This guide owns review-fix placement and propagation; the [dsh-merging-stacked-prs](../../.agents/skills/dsh-merging-stacked-prs/SKILL.md) skill owns linkage checks and landing.
-
-## Ground rules
-
-1. **One worktree per PR branch.** Each PR's fixes happen in that PR's own worktree; parallel fixes never share a checkout.
-2. **GitHub's stack object is authoritative.** Base branches establish the expected dependency order, while `PullRequest.stack` and `stackEntry.position` prove that GitHub recognizes it. Do not treat a matching branch chain as an official stack without checking those fields.
-3. **A fix lands on the PR that INTRODUCED the issue, then flows up-stack.** When a comment on PR `B` points at code `B` introduced, fix it on `B` and propagate `B` into `C` — even if `C` also carries the file. Originating the fix downstream leaves `B` shipping the unfixed code and hides the fix from `B`'s reviewer.
-4. **Each review fix remains a distinct commit.** A later rebase may change its OID, but do not amend a reviewed fix out of the branch history. Amend only your own not-yet-pushed, not-yet-reviewed work.
-5. **Choose merge-forward or rebase deliberately.** Both histories are allowed after review. A rewritten push must be lease-protected and must abort rather than overwrite a concurrently advanced remote head; raw `--force` is forbidden.
-
-## Resolve comments through the stack
-
-1. Triage every comment on the merits before acting: verify the claim against the code — a reviewer flagging the right symptom can still misdiagnose the cause.
-2. Map each accepted finding to its originating PR and fix it there.
-3. Propagate the fixed layer through every affected child in order:
-   - **Merge-forward:** merge the fixed parent branch into its child, validate the child, and continue upward. Preserve each in-progress checkpoint.
-   - **Native cascading rebase:** use `gh stack rebase`, validate the rewritten layers, then publish with `gh stack push`; or use `gh stack sync`, which may publish first and therefore requires immediate post-sync validation under [dsh-pre-push-checks](../../.agents/skills/dsh-pre-push-checks/SKILL.md).
-4. Treat delegated fixes as trust-but-verify: a sub-agent's report describes intent, not necessarily what landed. Re-run the gates yourself on the actual tree, and for a regression guard, prove it FAILS on the unfixed code (introduce the regression, watch red, revert) — a guard that passes both ways guards nothing. A sub-agent that reframes a problem as already handled is a signal to dig in personally.
-5. Reply in the review thread (`gh api repos/{owner}/{repo}/pulls/{pr}/comments/{id}/replies`), not as a top-level comment, stating the fix and the current commit or head that carries it.
-6. After any rewritten push, re-read unresolved threads, approvals, mergeability, and checks. A force-pushed commit OID or outdated inline anchor is not current evidence that the finding remains resolved.
-7. Land only through the official stack procedure. If the PRs are not yet linked, the landing skill automatically links a same-author chain, asks before linking mixed authors, and hard-stops when native stack support is unavailable.
-
-## Verify
-
-- Every fixed PR's current diff contains the intended correction at the layer that introduced the issue.
-- GraphQL reports one official stack in the expected order, and each child diff against its parent shows only that child's changes.
-- Unresolved threads, approvals, mergeability, and checks were re-audited after every rewritten push.
-- The relevant gates pass on every affected PR in the stack, not just the top.

package/references/official-docs/docs/cookbook/responding-to-pr-review-on-a-stack.zh.md

@@ -1,32 +0,0 @@
-# 在堆叠 PR 链中回应评审意见
-
-[English](responding-to-pr-review-on-a-stack.md) | 中文
-
-评审意见可能同时针对一条依赖堆叠（`A ← B ← C …`）中的多个 PR（Pull Request）。请通过 GitHub 官方的堆叠 PR 功能保持这条链的关联。本指南负责评审修复的归属与传播；[dsh-merging-stacked-prs](../../.agents/skills/dsh-merging-stacked-prs/SKILL.md) skill（技能）负责检查关联关系和落地。
-
-## 基本规则
-
-1. **每个 PR 分支一个 worktree。** 每个 PR 的修复在该 PR 自己的 worktree 中进行；并行修复绝不共享同一个 checkout。
-2. **GitHub 的 stack 对象是权威依据。** base 分支确定预期的依赖顺序，`PullRequest.stack` 和 `stackEntry.position` 则证明 GitHub 已识别该堆叠。未经检查这些字段，不得仅凭分支链吻合就将其视为官方堆叠。
-3. **修复落在引入问题的那个 PR 上，然后沿堆叠向上流动。** 当 PR `B` 上的评论指向 `B` 引入的代码时，在 `B` 上修复，再将 `B` 的变更传播到 `C`，即使 `C` 也包含该文件。把修复发起在下游会导致 `B` 带着未修复的代码交付，并对 `B` 的评审者隐藏修复。
-4. **每项评审修复都保留为独立 commit。** 后续 rebase 可能改变其 OID，但不得通过 amend 把已经评审的修复从分支历史中抹去。只有你自己尚未推送且尚未评审的工作才可以 amend。
-5. **明确选择 merge-forward 或 rebase。** 评审后允许采用这两种历史更新方式。改写历史的推送必须受 lease 保护；如果远端 head 在此期间前移，操作必须中止，不得将其覆盖。禁止直接使用 `--force`。
-
-## 沿堆叠解决评审意见
-
-1. 在行动之前先就事论事地审视每条评论：对照代码验证其论断——评审者指出了正确的症状，但仍可能误诊原因。
-2. 将每个被接受的发现映射到引入该问题的 PR，并在那里修复。
-3. 将修复后的层按顺序传播到每个受影响的子 PR：
-   - **Merge-forward：** 将修复后的父分支合并到其子分支，验证子分支，然后继续沿堆叠向上传播。保留每个正在处理的检查点。
-   - **原生级联 rebase：** 使用 `gh stack rebase`，验证所有已改写的层，然后通过 `gh stack push` 发布；也可以使用 `gh stack sync`，该命令可能先发布，因此必须按照 [dsh-pre-push-checks](../../.agents/skills/dsh-pre-push-checks/SKILL.md) 在同步后立即验证。
-4. 委派的修复需要信任但验证：subagent 的报告描述的是意图，不一定是实际落地的内容。请亲自在实际代码树上重新运行门禁；对于回归守卫，要证明它在未修复的代码上**失败**（引入回归、观察变红、再还原）——两种情况都通过的守卫什么也守不住。subagent 将问题重新定性为「已处理」时，这是一个需要亲自深入的信号。
-5. 在评审线程中回复（`gh api repos/{owner}/{repo}/pulls/{pr}/comments/{id}/replies`），而非发顶层评论；说明修复内容及当前承载修复的 commit 或 head。
-6. 每次改写推送后，都要重新读取未解决线程、批准状态、可合并性和检查结果。经 force-push 改写的 commit OID 或已过时的内联锚点，都不足以证明该发现当前仍处于已解决状态。
-7. 仅可通过官方堆叠流程落地。如果这些 PR 尚未关联，落地 skill 会自动关联作者相同的链；如果作者不同，则先询问用户；如果原生堆叠支持不可用，则硬性停止流程。
-
-## 验证
-
-- 每个已修复 PR 的当前 diff 都在引入问题的那一层包含预期修正。
-- GraphQL 报告的官方堆叠只有一个且顺序符合预期；每个子 PR 相对于父 PR 的 diff 只显示该子 PR 自身的变更。
-- 每次改写推送后，均重新审计了未解决线程、批准状态、可合并性和检查结果。
-- 相关门禁在堆叠中的每个受影响 PR 上都通过，而不仅仅是顶部。

package/references/official-docs/docs/cookbook/reviewing-persistence-type-changes.i18n.yaml

@@ -1,31 +0,0 @@
-# Bilingual-pair consistency record for reviewing-persistence-type-changes.md (docs/i18n/README.md): per heading
-# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
-# After editing either side, bring the other along and re-record with:
-#   pnpm run verify-translation-pairing --write docs/cookbook/reviewing-persistence-type-changes.md
-/:
-  en: 81db5d0ea2dbd0e2
-  zh: 2eb04cd5b470fd53
-/cookbook-reviewing-persistence-type-changes:
-  en: 50fa0e1367687c7d
-  zh: cd76f6e9649351c9
-/cookbook-reviewing-persistence-type-changes/summary:
-  en: 58040d6422d9ef9d
-  zh: 7deda8fc45752e8c
-/cookbook-reviewing-persistence-type-changes/table-of-contents:
-  en: 5fca19ac2bb1ddac
-  zh: 00d78fe7e80ba4f7
-/cookbook-reviewing-persistence-type-changes/optional-inspect-the-change:
-  en: 14049617e3de750d
-  zh: 200456cf72bef77b
-/cookbook-reviewing-persistence-type-changes/1-record-the-change:
-  en: de16b6e1ac883317
-  zh: 21d367bb78e799d1
-/cookbook-reviewing-persistence-type-changes/2-check-commit-and-push:
-  en: 91d39719ec40b0f7
-  zh: 405116ae4c91b100
-/cookbook-reviewing-persistence-type-changes/update-an-unaccepted-record:
-  en: e3872db4ec9aad7d
-  zh: 18de4f6ebcb4b31c
-/cookbook-reviewing-persistence-type-changes/dev-note:
-  en: 5de1d6304e00c58f
-  zh: 8d8225361cfa29e5

package/references/official-docs/docs/cookbook/reviewing-persistence-type-changes.md

@@ -1,122 +0,0 @@
----
-description: "Generate, acknowledge, and verify Session persistence-type changes locally before opening a pull request."
----
-
-# Cookbook: reviewing persistence-type changes
-
-English | [中文](reviewing-persistence-type-changes.zh.md)
-
-## Summary
-
-Use this tutorial after changing a declared Session persistence type in a contributor checkout with dependencies installed. Supply a bilingual compatibility explanation, then let one command classify the change and generate its records. The [record reference](../persistence-changes/README.md) explains the files and automatic rules. All comparison inputs live in the checkout; no base branch or network access is required.
-
-## Table of Contents
-
-- [Optional: inspect the change](#generate)
-- [1. Record the change](#acknowledge)
-- [2. Check, commit, and push](#verify)
-- [Update an unaccepted record](#competing-records)
-- [Dev Note](#dev-note)
-
------
-
-<a id="generate"></a>
-## Optional: inspect the change
-
-For a preview before recording, run from the repository root:
-
-```sh
-pnpm --silent run verify-persistence-changes --json
-```
-
-Use `--silent` when consuming JSON: pnpm otherwise appends lifecycle failure text to stdout. Failed commands still exit with code 1.
-
-Read the reported root, path, change kind, and compatibility-review requirement. A referenced type can affect several event digests; inspect every affected root. Until the history covers the new schemas, verification fails. A stale generated inventory also fails verification; the recording command refreshes it. If `changes` is empty after reordering fields or union alternatives, run `pnpm run gen-persistence-catalog` and repeat the check. An unchanged digest needs no new acknowledgement even when copied declarations or source locations produce a catalog diff.
-
-To review a PR independently of its acknowledgement history, save the base and head inventories as local JSON files and run:
-
-```sh
-pnpm --silent run persistence-review --before .artifacts/base.schema.json --after docs/persistence-schema.json
-```
-
-A recorded decision does not hide the transition from this comparison. `--check` only compares current source with acknowledged history; after recording, it cannot replace a base/head review or establish that a human reviewed the change.
-
-Record the commits supplying those files with the report. Add `--json` for structured output. This read-only comparison groups shared changes with their affected roots and uses actual literal `kind`/`form` values instead of union positions. Ambiguous alternatives remain separate additions and removals. Its compatibility section copies every root's authoritative classifier result; the structural explanation does not replace acknowledgement checks. Current catalog labels and declaration names are descriptive metadata; structural anchors and fingerprints identify types.
-
-The current machine inventory stores complete graphs in `roots`. A `types` entry contains `digest`, `names`, and `sources`, plus an explicit `schema` when roots cannot reconstruct that graph exactly. Readers resolve omitted graphs from root subgraphs by digest and validate explicit graphs directly, preserving every type and its metadata. Historical full entries remain readable. `formatVersion` identifies normalization rules; storage compaction does not change root fingerprints or require an acknowledgement.
-
-<a id="acknowledge"></a>
-## 1. Record the change
-
-Check the [accepted baseline](../session-format-status.md#finalization-record) first and preserve its locked records. Assess both reader directions under the [compatibility rules](../persistence-changes/README.md#compatibility-rules). A structural difference can remain same-version with evidence of safe interpretation or refusal; it does not automatically require a higher writer version.
-
-Write a local JSON file containing `en` and `zh`, each with `summary`, `compatibility`, and `verification` strings. The following input describes an exercised required-to-optional hook audit field change. Replace the explanation and test evidence with facts about your change; the CLI does not establish these claims.
-
-Save the input as `.artifacts/persistence-change.prose.json`, creating the ignored directory if needed:
-
-```json
-{
-  "en": {
-    "summary": "Makes the persisted hook audit decision optional.",
-    "compatibility": "Existing records remain valid. Hook execution consumes HookOutput instead of replaying this audit field. Producers still write decisions, and absence does not imply pass.",
-    "verification": "pnpm exec vitest run packages/experimental/hook-protocol/tests/events.spec.ts: 10 tests passed."
-  },
-  "zh": {
-    "summary": "将持久化的钩子审计决策改为可选。",
-    "compatibility": "已有记录仍然有效。钩子执行消费 HookOutput，不回放此审计字段。写入方仍然记录决策，缺失不代表 pass。",
-    "verification": "pnpm exec vitest run packages/experimental/hook-protocol/tests/events.spec.ts：10 个测试通过。"
-  }
-}
-```
-
-Use a date and descriptive slug in place of this example id:
-
-```sh
-pnpm --silent run persistence-changes --record 2026-09-11-poc-optional --prose .artifacts/persistence-change.prose.json --json
-```
-
-The command validates the history and paired prose, infers established same-version decisions, and checks explicit compatibility decisions before writing. It generates the record pair, complete after schemas, both catalogs, the machine inventory, and pairing records. Review the explanations and returned `changes`, `roots`, and `files` before committing. Omitting `--prose` creates unfinished drafts that verification rejects until their explanations are completed.
-
-For a change marked `requiresCompatibilityReview`, explain both reader directions in the acknowledgement’s Compatibility section and record executed checks in Verification. Supply `--decision same-version` when that evidence supports keeping the version; recording or updating a flagged change with an unchanged header version and no explicit decision fails with `decision-required`. Structural differences alone do not infer a bump. An actual header version increase can infer `version-bump`. If an effective discriminator cannot prevent unsafe interpretation, follow [adding a Session format version](adding-a-session-format-version.md) and select `--decision version-bump`. That record must include its own increasing `SessionHeader.version` transition; an unrelated historical bump cannot authorize it. Routine changes never create another baseline.
-
-<a id="verify"></a>
-## 2. Check, commit, and push
-
-Select the changed owner's behavior checks through the [testing policy](../testing.md), then run the documentation checks:
-
-```sh
-pnpm run doc-sync
-```
-
-`doc-sync` checks persistence inventory and catalog freshness, the complete history, and bilingual pairing. A recording command's `ok: true` does not replace these checks or the owner's behavior and migration tests. JSON failures retain `ok: false`, a diagnostic `code`, and exit code 1. Structured changes include stable kinds and per-root before/after digests, so automation need not parse descriptions.
-
-Record generation owns its catalog and record pairs; edits to a package README or other bilingual page still follow their normal pairing workflow. Review and stage the intended diff, then commit and push normally. The staged lint, pairing, and whitespace hooks and the pre-push Host/Client typecheck still apply.
-
-<a id="competing-records"></a>
-## Update an unaccepted record
-
-If source changes after recording, review the compatibility explanation and refresh the same unaccepted terminal record:
-
-```sh
-pnpm --silent run persistence-changes --update 2026-09-11-poc-optional --prose .artifacts/persistence-change.prose.json --json
-```
-
-The command refreshes the machine declaration, schemas, catalogs, and pairing. Without `--prose`, it preserves the existing explanation. Reassess that explanation against the complete transition and supply `--decision same-version` for any flagged same-version update. Update refuses the initial baseline, records that another record depends on, and finalized checkpoint records. Outside finalized checkpoints, the tree does not infer review acceptance: preserve accepted history and create a successor instead.
-
-When integration creates competing terminal records, update the unaccepted record against the remaining history, then reassess the resulting diff. An unrelated root's acknowledgement does not need refreshing. The [mechanism decision](../../.agents/notes/implemented/process/2026-09-11-persistence-type-history.md) explains why complete snapshots and per-root predecessors are retained.
-
-For an existing property value-type change requiring review, first revise the prose file’s Compatibility and Verification sections to explain the actual new transition and its executed checks. Do not reuse the earlier required-to-optional explanation for a different change. Then update the record with that prose and the explicit same-version choice:
-
-```sh
-pnpm --silent run persistence-changes --update 2026-09-11-poc-optional --decision same-version --prose .artifacts/persistence-change.prose.json --json
-```
-
-<a id="dev-note"></a>
-## Dev Note
-
-<details>
-<summary>Working context for maintainers — click to expand</summary>
-
-None.
-
-</details>

package/references/official-docs/docs/cookbook/reviewing-persistence-type-changes.zh.md

@@ -1,122 +0,0 @@
----
-description: "在创建 PR 前，本地生成、确认并验证会话持久化类型变更。"
----
-
-# 实操手册：审阅持久化类型变更
-
-[English](reviewing-persistence-type-changes.md) | 中文
-
-## 概述
-
-在已安装依赖的贡献者检出目录中修改会话持久化类型声明后，使用本教程。提供双语兼容性说明，再用一条命令分类变更并生成记录。[记录参考](../persistence-changes/README.zh.md)解释文件和自动规则。所有比较输入都在检出目录中；不需要基线分支或网络访问。
-
-## 目录
-
-- [可选：检查变更](#generate)
-- [1. 记录变更](#acknowledge)
-- [2. 检查、提交并推送](#verify)
-- [更新尚未接受的记录](#competing-records)
-- [开发备注](#dev-note)
-
------
-
-<a id="generate"></a>
-## 可选：检查变更
-
-若需在记录前预览，在仓库根目录运行：
-
-```sh
-pnpm --silent run verify-persistence-changes --json
-```
-
-消费 JSON 时使用 `--silent`：否则 pnpm 会把生命周期失败文本追加到标准输出。失败命令仍以退出码 1 结束。
-
-阅读报告中的根、路径、变更种类和兼容性评审要求。被引用类型可能影响多个事件摘要；检查每个受影响的根。在历史覆盖新 schema 之前，验证会失败。陈旧生成清单也会导致验证失败；记录命令会刷新它。若重排字段或联合类型分支后 `changes` 为空，运行 `pnpm run gen-persistence-catalog` 并重新检查。即使复制的声明或源码位置产生目录 diff，未变的摘要也无需新增确认记录。
-
-要独立于确认历史评审 PR，先将 base 和 head 的目录保存为本地 JSON 文件，再运行：
-
-```sh
-pnpm --silent run persistence-review --before .artifacts/base.schema.json --after docs/persistence-schema.json
-```
-
-记录决策不会使转换从此比较中消失。`--check` 仅比较当前源码与已确认历史；记录完成后，它不能替代 base/head 评审，也不能证明人类已评审该变更。
-
-在报告旁记录这些文件对应的 commit。添加 `--json` 可获取结构化输出。此只读比较将共享变更与受影响的根类型归组，使用实际字面量 `kind`/`form` 值代替联合类型位置。无法唯一匹配的候选项保留为独立的新增与删除。兼容性部分复制每个根类型的权威分类结果；结构说明不替代确认检查。当前目录标签和声明名称是描述元数据；结构锚点和指纹标识类型。
-
-当前机器清单在 `roots` 中保存完整图。每个 `types` 条目包含 `digest`、`names` 和 `sources`；若根无法精确重建该图，条目还会保存显式 `schema`。读取器按摘要从根的子图恢复省略的图，并直接验证显式图，保留每个类型及其元数据。历史完整条目仍然可读。`formatVersion` 标识规范化规则；存储压缩不改变根指纹，也不需要确认记录。
-
-<a id="acknowledge"></a>
-## 1. 记录变更
-
-先检查[已接受基线](../session-format-status.zh.md#finalization-record)，保留其锁定记录。按[兼容性规则](../persistence-changes/README.zh.md#compatibility-rules)评估两个读取方向。若有安全解释或拒绝的证据，结构差异可以保留同一版本，不会自动要求更高的写入器版本。
-
-编写包含 `en` 和 `zh` 的本地 JSON 文件，两者分别包含 `summary`、`compatibility` 和 `verification` 字符串。以下输入描述一个经过验证的钩子审计字段从必选改为可选的变更。用你所做变更的事实替换说明和测试证据；CLI（命令行界面）不会证明这些声明。
-
-将输入保存为 `.artifacts/persistence-change.prose.json`，必要时创建该被忽略的目录：
-
-```json
-{
-  "en": {
-    "summary": "Makes the persisted hook audit decision optional.",
-    "compatibility": "Existing records remain valid. Hook execution consumes HookOutput instead of replaying this audit field. Producers still write decisions, and absence does not imply pass.",
-    "verification": "pnpm exec vitest run packages/experimental/hook-protocol/tests/events.spec.ts: 10 tests passed."
-  },
-  "zh": {
-    "summary": "将持久化的钩子审计决策改为可选。",
-    "compatibility": "已有记录仍然有效。钩子执行消费 HookOutput，不回放此审计字段。写入方仍然记录决策，缺失不代表 pass。",
-    "verification": "pnpm exec vitest run packages/experimental/hook-protocol/tests/events.spec.ts：10 个测试通过。"
-  }
-}
-```
-
-用日期和描述性短名替换示例 id：
-
-```sh
-pnpm --silent run persistence-changes --record 2026-09-11-poc-optional --prose .artifacts/persistence-change.prose.json --json
-```
-
-命令在写入前验证历史与双语说明、推断已明确允许的同版本决策，并检查显式兼容性决策。它生成记录对、完整的 after schema、两个目录、机器清单与配对记录。提交前检查说明及返回的 `changes`、`roots`、`files`。省略 `--prose` 会生成未完成草稿；说明填写完成前，验证会拒绝它们。
-
-对于标为 `requiresCompatibilityReview` 的变更，在确认记录的兼容性部分说明两个方向的读取器行为，并在验证部分记录已执行的检查。证据支持保持版本时，提供 `--decision same-version`；记录或更新被标记的变更时，若头版本未变且缺少显式决策，会以 `decision-required` 失败。仅凭结构差异不会推断升版本。实际头版本递增可以推断出 `version-bump`。若有效判别信息无法阻止不安全解释，遵循[添加会话格式版本](adding-a-session-format-version.zh.md)，并选择 `--decision version-bump`。该记录必须包含自身的 `SessionHeader.version` 递增转换；无关的历史升版本不能授权它。日常变更不创建另一条基线。
-
-<a id="verify"></a>
-## 2. 检查、提交并推送
-
-根据[测试政策](../testing.zh.md)选择变更所属模块的行为检查，再运行文档检查：
-
-```sh
-pnpm run doc-sync
-```
-
-`doc-sync` 检查持久化清单和目录新鲜度、完整历史及双语配对。记录命令的 `ok: true` 不能替代这些检查，也不能替代所属模块的行为与迁移测试。JSON 失败响应保留 `ok: false`、诊断 `code` 和退出码 1。结构化变更包含稳定种类和逐根的变更前后摘要，自动化无需解析描述文本。
-
-记录生成负责其目录和记录的双语对；包 README 或其他双语页面的编辑仍遵循常规配对流程。审阅并暂存预期差异，然后正常提交和推送。暂存 lint、配对、空白 hooks，以及 pre-push Host/Client 类型检查仍须执行。
-
-<a id="competing-records"></a>
-## 更新尚未接受的记录
-
-记录后源码再次变化时，审阅兼容性说明，并刷新同一条尚未接受的末端记录：
-
-```sh
-pnpm --silent run persistence-changes --update 2026-09-11-poc-optional --prose .artifacts/persistence-change.prose.json --json
-```
-
-命令刷新机器声明、schema、目录和配对。没有 `--prose` 时，它保留已有说明。根据完整转换重新评估说明，并为任何被标记的同版本更新提供 `--decision same-version`。更新会拒绝初始基线、其他记录所依赖的记录，以及已被定稿检查点锁定的记录。定稿检查点之外，目录不会推断审阅接受状态：保留已接受历史，并创建后继。
-
-集成产生竞争末端记录时，根据剩余历史更新尚未接受的记录，再重新评估最终差异。无关根的确认无需刷新。[机制决策](../../.agents/notes/implemented/process/2026-09-11-persistence-type-history.zh.md)解释为何保留完整快照和逐根前驱。
-
-若已有属性的值类型变化需要评审，先修改说明文件中的兼容性与验证部分，解释实际的新转换及已执行检查。不要为不同变更复用先前必选改可选的说明。然后使用该说明与显式同版本选择更新记录：
-
-```sh
-pnpm --silent run persistence-changes --update 2026-09-11-poc-optional --decision same-version --prose .artifacts/persistence-change.prose.json --json
-```
-
-<a id="dev-note"></a>
-## 开发备注
-
-<details>
-<summary>维护者的工作上下文——点击展开</summary>
-
-无。
-
-</details>

package/references/official-docs/docs/cordis-api/context.i18n.yaml

@@ -1,73 +0,0 @@
-# Bilingual-pair consistency record for context.md (docs/i18n/README.md): per heading
-# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
-# After editing either side, bring the other along and re-record with:
-#   pnpm run verify-translation-pairing --write docs/cordis-api/context.md
-/:
-  en: d2c0c5bce430d1be
-  zh: a317d7ff7fc9f112
-/context:
-  en: fc6fd9ae25b8e9e5
-  zh: 1a2407d299404ace
-/context/ctx-extend-meta:
-  en: 2c407cb9589b001f
-  zh: 70dc8650250cd4c5
-/context/ctx-isolate-name-label:
-  en: ab77052c3bf31e2b
-  zh: 686ca829ea5b8170
-/context/ctx-intercept-name-config:
-  en: 1bd1e349f5c8687d
-  zh: 7634b27d2c9bade4
-/context/ctx-root:
-  en: eb89a7f0d2bc1753
-  zh: 263219126a310d3b
-/context/ctx-baseurl:
-  en: 29c28e7558cea0ad
-  zh: 9b591e449c1bfd72
-/context/ctx-events:
-  en: 6ce1e444e9dc3c48
-  zh: d4ca16ff2aeaa9f4
-/context/ctx-logger:
-  en: da8400d2e8dac772
-  zh: 8dd6fea850dd3b90
-/context/ctx-reflect:
-  en: 31e86abee38e9040
-  zh: 77ab752a7e69ccfe
-/context/ctx-registry:
-  en: d2f27d281bbf9f56
-  zh: 9193074fac7e9bfc
-/context/static-members:
-  en: ceb197529207a8ed
-  zh: 7d444c03f8be0f0d
-/context/static-members/context-effect:
-  en: 19f4aaef44a7e8eb
-  zh: 2179cf28a7ee3f6a
-/context/static-members/context-filter:
-  en: e8ca384b9a1ea98b
-  zh: 82189892bf0afcb0
-/context/static-members/context-isolate:
-  en: b8673b719837ce51
-  zh: 83892f9f96c3ac28
-/context/static-members/context-intercept:
-  en: f3ebe6568cc9a863
-  zh: bb51ab61a4e47d33
-/context/static-members/context-is-value:
-  en: 7425e0ee4bc1ada7
-  zh: 93dee27133ded9e0
-/context/service-store-and-mixins:
-  en: 9f7ca8a6a0f80512
-  zh: 05e8cbc30e5709fc
-/context/service-store-and-mixins/ctx-get-name-strict:
-  en: 5a9a1212850a136f
-  zh: 2b6f287c8bbcc0c6
-/context/service-store-and-mixins/ctx-set-name-value:
-  en: a04668f00e1cbe91
-  zh: 8e8444e6b393358e
-/context/service-store-and-mixins/ctx-provide-name-value:
-  en: 5887dc4233a37a5b
-  zh: 810dcde64664170b
-/context/service-store-and-mixins/ctx-accessor-name-options:
-  en: 82ccb33229d3cf32
-  zh: d969904f023380b4
-/context/service-store-and-mixins/ctx-mixin-name-mixins:
-  en: 777f36aed85fa512
-  zh: 47b809ad5f799134