dsh-pstack 0.2.0-beta.1 → 0.2.0

package/dist/skills/authored/decision-write/SKILL.zh.md

@@ -0,0 +1,133 @@
+---
+name: decision-write
+description: 撰写、更新、落地或取代决策记录。用于已定取舍、缺失设计理由、推翻决策或记录文件改动；落地模式查找并校验实现，仅更新 `Review` 时保留当前状态。
+---
+
+# 撰写或更新决策记录
+
+将一项已收敛的选择交付为经校验的记录和证据报告。所有记录修改都通过本技能；`decision-audit` 只读报告。
+
+## 入口规则
+
+任何对 `Status`、`Implemented-by`、`Superseded-by`、`Review`、正文或链接的修改都执行本流程。流程无法运行时停下报告；本规则优先于 `<dir>/AGENTS.md` 中允许直接编辑的约定。
+
+## 定位记录目录
+
+按以下顺序定位 `<dir>`：
+
+1. 使用调用方提供的记录或目录路径。
+2. 否则，解析根目录 `AGENTS.md` 的 `## Project docs` 中的决策指针；目标为现存的 `<dir>/AGENTS.md` 时使用该目录。
+3. 否则，检查 `docs/decisions/`、`docs/adr/` 和 `doc/adr/`。
+
+沿用选中目录的命名约定，并在存在时读取其 `AGENTS.md` 与 `README.md` 约定。仍有多个候选时，询问哪个是当前目录并等待。都不存在时，报告未找到决策目录，建议使用 `/setup-project-docs`，然后停止。
+
+`AGENTS.md` 与 `README.md` 是约定而非记录；检索、分类与更新都排除它们。
+
+## 选择模式
+
+- **撰写：** 没有既有记录拥有这个决策、新记录取代旧记录，或既有记录需要实质更新正文或关系。重复与部分重叠的归类留在撰写模式；明确的状态字段更新走落地。执行步骤 1–5，在步骤 6 展示确认关口，仅在确认后写入，再执行步骤 7 报告。
+- **落地：** 用户明确要求把既有记录标为 `accepted` 或更新其状态字段。完整读取目标记录，再执行步骤 4、5、7。记录路径加 `accepted` 就是足够输入；不要自行进入落地。未给出路径时，列出 `Scope` 匹配落地改动的记录并询问更新哪一条。仅更新 `Review` 时保留 `Status` 与 `Implemented-by`，跳过步骤 4、5，执行步骤 7 报告。
+
+## 1. 确认选择
+
+先从改动与讨论中取得全部三项，只询问缺失内容并等待：
+
+- **目标：** 这个决策要解决的问题。
+- **约束：** 排除某个选项的边界。
+- **备选方案：** 实际被否决的选项，或者只考虑过单一候选这一明确事实。
+
+## 2. 查找相关记录
+
+用主题、受影响模块和备选方案的专有词检索：
+
+```bash
+grep -ril --exclude=AGENTS.md --exclude=README.md \
+  -e "<关键词 1>" -e "<关键词 2>" <dir>/*.md
+```
+
+读取每个命中至第一个 `## ` 标题；头部无法区分归类，或无法提供更新所需内容时再读正文。检索过宽时收紧关键词，不通读整个目录。给每个命中分类：
+
+- **重复：** 既有记录拥有这个决策。更新该记录，不另写第二条。
+- **完全取代：** 起草新记录，让两条记录互相链接；把旧记录的取代变更放进确认关口。
+- **部分重叠：** 保留两者，互相链接，并更正已变化的事实。
+- **无关：** 不作修改。
+- **未决：** 将关系与需要人工回答的问题带入报告。
+
+每个命中都有归类、每项由此产生的修改都已明确时，本步完成。
+
+## 3. 起草记录
+
+遵循 `<dir>/AGENTS.md`，包括标题语言；没有该文件时使用：
+
+```markdown
+# Decision: <one-line title>
+
+Status: proposed | accepted | superseded
+Date: YYYY-MM-DD
+Scope: <glob>[, <glob>...]
+Implemented-by: <PR #N | commit:SHA | ->
+Review: YYYY-MM-DD
+Superseded-by: <记录路径> — <一句原因>   （仅 Status 为 superseded 时）
+
+## Background
+## Decision
+## Alternatives
+## Consequences
+```
+
+让 `Background` 脱离所选方案也能读懂。已接受的记录在 `Decision` 中用现在时描述系统。每个实际考虑过的备选方案独立成段并写明落选原因；只有单一候选时如实说明。
+
+## 4. 设定状态并校验锚点
+
+`Status` 与 `Implemented-by` 是一对。按证据选中下表的一行，并在同一次修改中写入两个字段：
+
+| 证据 | Status | Implemented-by |
+|---|---|---|
+| 没有可核验的落地锚点 | `proposed` | `-` |
+| `PR #N` 为 `MERGED` | `accepted` | `PR #N` |
+| `commit:SHA` 是默认分支的祖先 | `accepted` | `commit:SHA` |
+| 用户确认仅记录提交的例外 | `accepted` | `commit:<记录提交>` |
+| 被更新的草稿取代 | `superseded` | 保留原值 |
+
+新记录在落地前保持 `proposed`。`Implemented-by` 指向实现改动；追溯性记录指向更早的实现。仅记录提交必须走用户确认的例外。squash 合并的仓库优先用已合并 PR。
+
+落地模式没有给定锚点，或需要“仅记录提交”例外时，编辑前读取[查找并校验实现](references/land.zh.md)。校验其他已有锚点时，只执行该参考中的校验流程，不执行查找步骤。
+
+`<base>` 取仓库默认分支，并报告选中的 ref。校验每个锚点。撰写模式中，证据不可用或基线无法解析时，新记录保持 `proposed` + `-`；落地模式中停止并报告，不编辑记录。既有 `accepted` 记录的锚点校验失败时，停下报告，不静默降级。只改证据要求的字段；单独推进 `Review` 不改变状态。
+
+新草稿取代旧记录时，在同一次获批的修改中把旧记录改为 `superseded`，即使旧记录原为 `accepted`。保留旧正文与锚点，添加互链，并在 `Review` 下方写 `Superseded-by: <新记录路径> — <一句原因>`。原因缺失时先询问并等待。原为 `proposed` 的旧记录保留 `Implemented-by: -`。
+
+## 5. 检查范围覆盖改动
+
+所有 glob/路径检查都使用[匹配 Scope 路径](references/scope.zh.md)，包括落地模式的锚点查找。调用方提供 `scope` 路径时直接使用。带已核验实现改动的落地分支，用以下命令列出实现路径：
+
+```bash
+gh pr view N --json files --jq '.files[].path'
+git show --pretty=format: --name-only SHA
+```
+
+经确认的“仅记录提交”回退跳过本项检查，并在报告中说明例外。其他分支收集相对基线的提交与未提交改动：
+
+```bash
+git diff --name-only "$(git merge-base HEAD <base>)"..HEAD
+git status --porcelain=v1 --untracked-files=all
+```
+
+解析 `git status` 中的路径，重命名取目标路径。每条新增或更新的记录都必须有至少一个所选改动路径匹配其 `Scope` glob。全部不匹配时，询问是放宽 glob，还是该记录不属于这次改动。将匹配路径留作报告。
+
+## 6. 草稿确认关口
+
+每次撰写写入（包括重复记录的更新）都要展示每条新增或更新记录的完整结果，以及每个相关记录的分类。包括每项拟议的旧记录取代变更及其 `Superseded-by` 路径和原因。请求用户明确确认并等待。确认后严格应用获批的修改；草稿被拒绝时保持所有文件不变。
+
+## 7. 报告
+
+根目录 `AGENTS.md` 没有可解析到所选 `<dir>` 的决策指针时，建议用 `/setup-project-docs` 登记。覆盖每个检索命中、改动的记录、关系判断、锚点校验、范围匹配和未决问题。等待落地的 `proposed` 记录在合并后需要一次“落地”更新。报告查到的实现及其改动路径；仅记录锚点须标明为经确认的例外。包括每个 `Superseded-by` 路径和原因。
+
+```text
+Record: docs/decisions/2026-10-27-use-postgres.md
+Status: accepted
+Related: 2026-03-02-mysql-setup.md -> overlapping, cross-linked
+Anchor: PR #412 -> MERGED (gh pr view 412 --json state,files)
+Scope: src/db/** matched src/db/client.ts
+Open: none
+```

package/dist/skills/authored/decision-write/references/land.md

@@ -0,0 +1,48 @@
+# Find and verify the implementation
+
+Use this reference for Land anchor discovery, record-only fallback, and anchor verification. The main skill owns status pairs, supersession, scope, approval, and reporting.
+
+## Find the implementation
+
+In Land when no candidate anchor is available, resolve `<base>` as described under **Verify the anchor**, then search commits and merged PRs touching the record's `Scope`:
+
+```bash
+git log --since=<Date> --format='%H %cs %s' <base> --
+gh pr list --state merged --search "<record title or scope keyword>" --json number,title,mergedAt,files --limit 20
+```
+
+If `Scope` is absent, search commit subjects and PR titles for the record's title or keywords. Start at its `Date`; for a retrospective record, also inspect recent commits before `Date` that touch `Scope`. If `gh` is unavailable, search commits and report that PR discovery was skipped.
+
+Keep candidates whose changed paths intersect `Scope` and include at least one path outside `<dir>`; a change containing only decision records is not an implementation. Use one clearly matching candidate's `PR #N` or `commit:SHA`. If several match, list their dates, titles, and paths and ask which one. If none matches, use the fallback below.
+
+## Record-only fallback
+
+When no implementation exists and the user still wants `accepted`, explain both points and wait for explicit confirmation:
+
+- **Reason:** the record commit records the decision but does not implement it, so the anchor would claim a landing that never happened.
+- **Consequence:** `decision-audit` reports this anchor as a C finding; a later implementation should replace it.
+
+Ask whether to use `commit:<record-commit>` or leave `proposed` + `-`. Use `accepted` + `commit:<record-commit>` only after confirmation, and report the exception. This exception overrides an `<dir>/AGENTS.md` ban on record-only anchors. If that commit is outside the default branch, retain `proposed` + `-` until it merges.
+
+## Verify the anchor
+
+Resolve `<base>` as the default branch:
+
+```bash
+git symbolic-ref --short refs/remotes/origin/HEAD 2>/dev/null ||
+  git rev-parse --verify origin/main 2>/dev/null ||
+  git rev-parse --verify origin/master 2>/dev/null ||
+  git rev-parse --verify main 2>/dev/null ||
+  git rev-parse --verify master 2>/dev/null
+```
+
+Verify every proposed `Implemented-by` value:
+
+| Value | Command | Verified when |
+|---|---|---|
+| `PR #N` | `gh pr view N --json state,files` | `state` is `MERGED` and the change implements the decision |
+| `commit:SHA` | `git merge-base --is-ancestor SHA <base>` | Exit code 0 and the change implements the decision |
+
+List candidate paths with `gh pr view N --json files --jq '.files[].path'` or `git show --pretty=format: --name-only SHA`. A real implementation intersects `Scope` and includes a path outside `<dir>`; a record-only anchor needs the confirmed exception. Return these paths to the scope check.
+
+In Draft, unlanded work, failed verification, unavailable `gh`, or an unresolved `<base>` leaves a new record `proposed` + `-`; report the evidence or attempted refs. In Land, stop and report without editing. An unresolved base also blocks base-relative scope checks; use caller-supplied paths or report that evidence as unavailable. Never demote an existing `accepted` record on failed verification; return its broken anchor to the main skill's stop-and-report rule. A Review-only update skips this reference.

package/dist/skills/authored/decision-write/references/land.zh.md

@@ -0,0 +1,48 @@
+# 查找并校验实现
+
+本参考用于落地锚点查找、仅记录提交回退和锚点校验。状态成对、取代、范围、确认和报告规则见主技能。
+
+## 查找实现
+
+落地模式没有可用的候选锚点时，先按“校验锚点”解析 `<base>`，再检索触及记录 `Scope` 的提交与已合并 PR：
+
+```bash
+git log --since=<Date> --format='%H %cs %s' <base> --
+gh pr list --state merged --search "<记录标题或范围关键词>" --json number,title,mergedAt,files --limit 20
+```
+
+没有 `Scope` 时，用记录标题或关键词检索提交主题与 PR 标题。从记录的 `Date` 开始；追溯性记录也检查 `Date` 之前最近触及 `Scope` 的提交。`gh` 不可用时只检索提交，并报告已跳过 PR 查找。
+
+保留改动路径与 `Scope` 相交、且至少有一个 `<dir>` 之外路径的候选；只含决策记录的改动不是实现。只有一个明确候选时，用它的 `PR #N` 或 `commit:SHA`。多个候选时列出日期、标题、路径并询问选哪个。没有候选时走下面的回退。
+
+## 仅记录提交的回退
+
+没有找到实现、而用户仍要求 `accepted` 时，解释以下两点并等待明确确认：
+
+- **原因：** 记录提交只记录决策，没有实现它，锚点会声称一个并未发生的落地。
+- **后果：** `decision-audit` 会把该锚点报为 C 类发现；后续实现落地后应替换它。
+
+直接询问是用 `commit:<记录提交>`，还是保持 `proposed` + `-`。只有用户确认后才写 `accepted` + `commit:<记录提交>`，并在报告中说明例外。本例外优先于 `<dir>/AGENTS.md` 中禁止仅记录锚点的约定。记录提交不在默认分支时，保持 `proposed` + `-` 直到合并。
+
+## 校验锚点
+
+将 `<base>` 解析为默认分支：
+
+```bash
+git symbolic-ref --short refs/remotes/origin/HEAD 2>/dev/null ||
+  git rev-parse --verify origin/main 2>/dev/null ||
+  git rev-parse --verify origin/master 2>/dev/null ||
+  git rev-parse --verify main 2>/dev/null ||
+  git rev-parse --verify master 2>/dev/null
+```
+
+校验每个拟写入的 `Implemented-by` 值：
+
+| 值 | 命令 | 通过条件 |
+|---|---|---|
+| `PR #N` | `gh pr view N --json state,files` | `state` 为 `MERGED`，且改动实现该决策 |
+| `commit:SHA` | `git merge-base --is-ancestor SHA <base>` | 退出码为 0，且改动实现该决策 |
+
+用 `gh pr view N --json files --jq '.files[].path'` 或 `git show --pretty=format: --name-only SHA` 列出候选路径。真实实现与 `Scope` 相交，且至少有一个 `<dir>` 之外的路径；仅记录锚点需要经确认的例外。将这些路径交给范围检查。
+
+撰写模式中，改动未落地、校验失败、`gh` 不可用或 `<base>` 无法解析时，新记录保持 `proposed` + `-`，并报告证据或尝试过的 ref。落地模式中停止并报告，不编辑记录。基线无法解析也会阻止相对基线的范围检查；此时使用调用方提供的路径，或报告该证据不可用。既有 `accepted` 记录校验失败时不得降级；回到主技能的停下报告规则处理断裂锚点。仅更新 `Review` 时不读取本参考。

package/dist/skills/authored/decision-write/references/scope.md

@@ -0,0 +1,16 @@
+# Match Scope paths
+
+Use this one matcher for every `Scope` check in `decision-write` and `decision-audit`: changed paths, implementation paths, and existing files.
+
+Treat `Scope` as comma-separated Git ignore globs, anchored at the repository root. Paths are repository-relative with `/` separators. `*` stays within one path segment; `**` spans segments. A glob that matches a directory also covers its descendants: for example, `src/*` matches `src/client/index.ts` through `src/client/`.
+
+Initialize an isolated temporary Git directory once per run so the repository's own ignore rules cannot affect the result. For each glob, remove a leading `./` and any trailing `/`; reject a leading `/`, a `..` segment, or a newline. Test both forms:
+
+```bash
+sandbox="$(mktemp -d)"
+git init -q "$sandbox"
+printf '/%s\n/%s/**\n' "$glob" "$glob" >"$sandbox/rules"
+git -C "$sandbox" -c core.excludesFile="$sandbox/rules" check-ignore -v --no-index -- "$path"
+```
+
+The only files in the sandbox are Git metadata and the rule file; it needs no checkout. Overwrite the rule file for each glob, then remove the verified temporary directory after the run. The path is matcher input, not a file that must exist. Accept a match only when the verbose output names `$sandbox/rules` as its source. Exit 0 with that source is a match. Exit 1 is no match; report any other exit code with its error. Record each matching glob and path. Every record matches when at least one of its globs matches at least one selected path.

package/dist/skills/authored/decision-write/references/scope.zh.md

@@ -0,0 +1,16 @@
+# 匹配 Scope 路径
+
+`decision-write` 与 `decision-audit` 的所有 `Scope` 检查都使用这一个匹配器：改动路径、实现路径与现存文件均相同。
+
+`Scope` 是逗号分隔、以仓库根目录为锚点的 Git ignore glob。路径使用仓库相对形式和 `/` 分隔符。`*` 不跨路径段，`**` 可以跨段；匹配目录的 glob 也覆盖其所有后代，例如 `src/*` 通过匹配 `src/client/` 而匹配 `src/client/index.ts`。
+
+每次运行初始化一个隔离的临时 Git 目录，避免仓库自身的 ignore 规则影响结果。对每个 glob 去掉开头的 `./` 与末尾的 `/`；拒绝以 `/` 开头、包含 `..` 路径段或换行的 glob。再测试两种形式：
+
+```bash
+sandbox="$(mktemp -d)"
+git init -q "$sandbox"
+printf '/%s\n/%s/**\n' "$glob" "$glob" >"$sandbox/rules"
+git -C "$sandbox" -c core.excludesFile="$sandbox/rules" check-ignore -v --no-index -- "$path"
+```
+
+沙箱中只有 Git 元数据和规则文件，无需检出。每个 glob 都覆盖写入规则文件，运行结束后删除已确认路径的临时目录。路径是匹配器输入，不要求文件存在。仅当详细输出把 `$sandbox/rules` 标为来源时才接受匹配。退出码为 0 且来源正确即匹配；退出码为 1 则不匹配；其他退出码连同错误一起报告。记录每个匹配的 glob 与路径。只要任一 glob 匹配任一所选路径，该记录即匹配。

package/dist/skills/authored/docs-drift/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: docs-drift
+description: Audit living project documentation for drift and redundancy; repair approved findings.
+disable-model-invocation: true
+---
+
+# Check project documentation drift
+
+Audit living project documents against current evidence, then stop after a read-only report or apply approved documentation repairs. Keep implementation changes outside this skill.
+
+## Choose the mode
+
+- **Report:** `/docs-drift` or `/docs-drift report`. Do steps 1–5 without writing files.
+- **Fix:** `/docs-drift fix`. Do the same inspection, then steps 6–7. Invoking Fix is not write approval.
+
+Accept optional paths or globs to add to or narrow the candidate set, plus optional exclusions. Ask when the requested mode or scope is ambiguous.
+
+## 1. Discover the maintained documents
+
+Start with the root agent documents and root README files that actually exist, including linked language variants. Record absent entry points without creating replacements.
+
+Read project maintenance rules and follow pointers designating documents that agents must read, update, or keep synchronized. Use the project's real document names and locations; conventional architecture, glossary, or decision-document paths are leads, not requirements. Ordinary links may supply evidence or receive link checks without recursively adding their targets to the full scan.
+
+Apply explicit paths, globs, narrowing, and exclusions to the candidate set. A whole-repository request broadens candidate discovery without making every stored document a maintained project document. Read the nested agent instructions governing each candidate.
+
+Classify every candidate using project pointers, governing instructions, and ownership and update conventions:
+
+- **Maintained:** owned by this project and updated as its implementation or workflows evolve. Apply all five checks.
+- **Reference-only:** documentation of a dependency, host product, library, or other external system, even when stored inside the repository. Use it as evidence without auditing its own drift.
+- **Excluded:** outside the requested scope or otherwise excluded by an explicit rule.
+- **Unresolved:** maintenance ownership is unclear. Ask before including it and continue classifying unrelated candidates.
+
+Determine ownership from evidence rather than paths, directory names, file types, or subjects. A project's own component documents may be maintained; bundled component-library documents may be reference-only. Include governing instruction files in the maintained set only under the same ownership rules.
+
+Keep generated, vendored, and upstream content outside the editable set. Record the authoritative source or upstream destination and any project generation procedure for their findings. Record missing pointer targets and links used only as evidence. Complete this step when every candidate has a classification or unresolved question and the maintained, reference-only, excluded, and editable boundaries have source-backed evidence.
+
+## 2. Build the evidence inventory
+
+Read every maintained document and the instructions governing it. Inventory its checkable claims about current modules, responsibilities, paths, entry points, commands, tools, configuration, dependencies, interfaces, behavior, counts, and status.
+
+Trace those claims to current code, configuration, manifests, real directories, entry points, and relevant tests. Treat paths mentioned by documentation as leads, not proof. Use existing read-only project checks when they answer a specific evidence question.
+
+Distinguish current facts, intended requirements, and historical statements. Current implementation establishes what exists, not whether that behavior is correct. Mark a claim unverified when the repository cannot supply sufficient evidence.
+
+Complete this step when every checkable claim in every maintained document has a source-backed disposition or an explicit evidence limitation.
+
+## 3. Apply all five checks
+
+**Implementation drift.** Find stale statements or statements contradicted by current evidence about architecture, behavior, paths, commands, interfaces, configuration, dependencies, counts, and status.
+
+**Contradictions.** Find incompatible statements within one document or across documents. Distinguish contradictions from intentionally different levels of detail.
+
+**Terminology.** Find one concept with conflicting names, one name denoting incompatible concepts, and definitions that diverge from actual usage. Check intentional language variants for corresponding meaning.
+
+**Links and pointers.** Resolve repository-relative links, referenced paths, and anchors from their containing document. Check external links when feasible; classify network or access failures as unverified rather than dead.
+
+**Redundancy and unsupported elaboration.** Find semantic duplication, scattered rules, obsolete passages, and unsupported facts, assumptions, or invented elaboration accumulated during iteration. Examples include fabricated module responsibilities, command behavior, configuration defaults, design rationale, compatibility, performance conclusions, test coverage, and acceptance status. Shrink disproven or unsupported elaboration to the smallest evidence-backed statement. Insufficient evidence alone makes a claim unverified, not a deletion candidate. Preserve the context of historical statements and explicit future plans.
+
+Before proposing consolidation, identify an authoritative location. Preserve intentional summaries, audience-specific views, language variants, and unique qualifications.
+
+Report style, formatting, or completeness preferences only when they substantiate one of these findings. Complete this step when every class has been applied to every maintained document and every potential finding has a location, observed statement, supporting evidence or evidence boundary, and proposed action.
+
+## 4. Resolve authority and classify findings
+
+Use the kind of question to determine authority:
+
+- Explicit user requirements govern requested behavior.
+- Current project specifications and binding conventions govern declared constraints.
+- Verifiable implementation evidence governs descriptions of current behavior.
+- A document's historical context governs statements about past events.
+
+Documentation repair is appropriate when evidence establishes the current fact and the edit only corrects its description or removes genuine redundancy or unsupported elaboration.
+
+Stop resolving an item and ask the user when:
+
+- The implementation may be wrong and the documentation may state the requirement.
+- A repair would change functionality, public contracts, acceptance criteria, or an established constraint.
+- Requirements, specifications, tests, and implementation support incompatible answers.
+- Evidence is insufficient or conflicting.
+- A fix requires changing implementation, generated output, vendored content, upstream content, or a protected source.
+- Existing uncommitted changes make the intended state unclear.
+
+Continue read-only inspection of unrelated items, but exclude unresolved items from the repair plan. Complete this step when every potential finding is classified as repairable, needs-user-decision, or unverified, and every repairable action is documentation-only.
+
+## 5. Report
+
+Report the candidate and maintained scopes, ownership evidence, reference-only documents, exclusions, missing pointer targets, evidence limitations, and every maintained document's disposition. Keep unresolved questions and unverified claims visible rather than counting them as clean.
+
+Use one entry per finding:
+
+```text
+[Implementation drift | Contradiction | Terminology | Link | Redundancy] Title
+  Location: <document>:<line or section>
+  Current: <statement, duplicated material, or unsupported elaboration>
+  Evidence: <source and observed fact, or the evidence boundary>
+  Proposal: <documentation-only correction, deletion, or consolidation>
+  Disposition: repairable | needs-user-decision | unverified
+```
+
+For redundancy, name the proposed authoritative location and what each other location will retain, merge, or link to. For unsupported elaboration, state whether to delete it or shrink it to an evidence-backed statement. When nothing needs attention, say so and list any remaining unverified items.
+
+Report mode ends here without writing files or creating a report artifact. Complete this step when every maintained document and potential finding has a reported outcome, and every candidate has a reported classification or unresolved question.
+
+## 6. Approve and repair
+
+For Fix, group the exact proposed edits by file and finding. Show exact replacement text or deletion boundaries for substantive rewrites, deletions, and consolidations, including all affected language variants. Identify edits excluded by unresolved questions.
+
+Request explicit approval and wait. The user may approve any subset. Apply exactly the approved edits, preserving unrelated content and existing user changes.
+
+Repair the authoritative source and synchronize intentional summaries and language variants where the evidence supports doing so. Use the project's generation procedure for generated results. Preserve every unique requirement, constraint, caveat, and evidence pointer during consolidation. If a new semantic conflict appears, stop that item and request a new decision rather than expanding the approved edit.
+
+Complete this step when every approved item has been applied exactly or remains explicitly unapplied with its reason, and no unapproved file changed.
+
+## 7. Verify and close
+
+Re-read every changed document. Confirm that approved findings are resolved, links resolve, corresponding language views agree, consolidated content remains traceable, and no unapproved semantic change occurred.
+
+Run relevant existing project checks and record their actual results. Report changed files, resolved findings, approved omissions, unresolved questions, unverified claims, and verification evidence. When no edits were approved or needed, state that no files changed.
+
+Complete this step when every approved edit has verification evidence or a concrete remaining failure, and every check has an actual result.

package/dist/skills/authored/docs-drift/SKILL.zh.md

@@ -0,0 +1,120 @@
+---
+name: docs-drift
+description: 巡检项目持续维护的文档并修复获批的漂移、冗余与无依据扩写。
+disable-model-invocation: true
+---
+
+# 检查项目文档漂移
+
+将项目持续维护的文档与当前证据对照，然后以只读报告结束，或应用经批准的文档修复。实现改动不属于本技能。
+
+## 选择模式
+
+- **Report：**`/docs-drift` 或 `/docs-drift report`。执行步骤 1–5，不写文件。
+- **Fix：**`/docs-drift fix`。执行同样的检查，再执行步骤 6–7。调用 Fix 本身不构成写入批准。
+
+接受可选的路径或 glob，用于增加或收窄候选集合，也接受可选排除项。请求的模式或范围有歧义时先询问。
+
+## 1. 发现维护中的文档
+
+从实际存在的根 agent 文档和根 README 开始，包括链接到的语言版本。记录缺失的入口，不创建替代文件。
+
+读取项目维护规则，跟随将文档指定为 agent 必须阅读、更新或保持同步之对象的指针。使用项目真实的文档名称与位置；常规架构、术语或决策文档路径只是调查线索，不是必备条件。普通链接可以作为证据或接受链接检查，但不因此递归加入全文巡检。
+
+将显式路径、glob、收窄和排除应用于候选集合。“整个仓库”只扩大候选发现范围，不使仓库内每份文档都成为项目维护文档。读取管辖每份候选文档的嵌套 agent 指令。
+
+根据项目指针、管辖指令、归属及更新约定给每个候选文档分类：
+
+- **维护文档：**由本项目所有，并随项目实现或工作流迭代更新。执行全部五类检查。
+- **仅作参考：**依赖、宿主产品、程序库或其他外部系统的说明文档，即使存放在仓库内。只用作证据，不检查其自身漂移。
+- **已排除：**不在请求范围内，或被显式规则排除。
+- **未决：**维护归属不明确。纳入前先询问，同时继续分类无关候选文档。
+
+按证据判断维护归属，不按路径、目录名、文件类型或文档主题推断。项目自己的组件文档可能属于维护文档，附带的组件库文档则可能仅作参考。管辖指令文件也只有符合同样的归属规则时才纳入维护文档集合。
+
+生成、vendored 和上游内容不进入可编辑集合。相关发现须记录权威来源或上游去处，以及项目的生成流程（如有）。记录失效指针目标和仅用于取证的链接。每个候选文档都有分类或未决问题，且维护、参考、排除和可编辑边界都有来源依据时，本步完成。
+
+## 2. 建立证据清单
+
+阅读每份维护文档及管辖它的指令。盘点其中关于当前模块、职责、路径、入口、命令、工具、配置、依赖、接口、行为、数量和状态的可核验陈述。
+
+把这些陈述追溯到当前代码、配置、清单、真实目录、入口与相关测试。文档提到的路径只是调查线索，不是证据本身。现有只读项目检查能够回答具体证据问题时加以使用。
+
+区分当前事实、预期要求与历史陈述。当前实现证明现状，不证明行为正确。仓库无法提供充分证据时，将陈述标为未核验。
+
+每份维护文档中的每项可核验陈述都有来源依据的处置结果或明确的证据限制时，本步完成。
+
+## 3. 执行全部五类检查
+
+**实现漂移。** 查找关于架构、行为、路径、命令、接口、配置、依赖、数量和状态的过时段落，或与当前证据冲突的陈述。
+
+**矛盾。** 查找同一文档内部或跨文档的互斥陈述。区分真正矛盾与有意采用的不同详略层次。
+
+**术语。** 查找一个概念使用冲突名称、一个名称指代不兼容概念，以及定义偏离实际用法的情况。检查有意的语言版本是否保持对应含义。
+
+**链接与指针。** 从引用所在文档解析仓库相对链接、路径与锚点。条件允许时检查外链；网络或访问失败归为未核验，不直接判为死链。
+
+**冗余与无依据扩写。** 查找语义重复、规则散落、过时段落，以及持续迭代中积累的无依据事实、假设与臆造扩写。例子包括虚构的模块职责、命令行为、配置默认值、设计理由、兼容性、性能结论、测试覆盖与验收状态。将已证伪或无依据的扩写收缩为有证据支持的最小陈述；仅证据不足时标为未核验，不作为删除候选。历史陈述和明确的未来计划保留其语境。
+
+提出合并前确定权威位置。保留有意的摘要、面向不同读者的视图、语言版本与独有限定条件。
+
+文风、格式或完整性偏好只有构成上述发现时才报告。每份维护文档都执行过全部五类检查，且每项潜在发现都有位置、当前陈述、支持证据或证据边界及建议动作时，本步完成。
+
+## 4. 判定权威并分类发现
+
+按问题类型确定权威：
+
+- 用户明确要求决定预期行为。
+- 当前项目规格与有约束力的约定决定其声明的限制。
+- 可核验的实现证据决定当前行为的描述。
+- 文档的历史语境决定过去事件的表述。
+
+证据能够确定当前事实，且编辑只纠正描述、消除真正冗余或清理无依据扩写时，适合修复文档。
+
+出现下列情况时停止处理该项并询问用户：
+
+- 实现可能有误，而文档可能表达的是要求。
+- 修复会改变功能、公开契约、验收标准或既定约束。
+- 要求、规格、测试与实现支持互不兼容的答案。
+- 证据不足或相互冲突。
+- 修复需要修改实现、生成产物、vendored 内容、上游内容或受保护来源。
+- 已有未提交改动使预期状态无法确定。
+
+继续只读检查无关项，但未决项不进入修复计划。每项潜在发现都归为可修复、需要用户决定或未核验，且每项可修复动作都只涉及文档时，本步完成。
+
+## 5. 报告
+
+报告候选范围与维护文档范围、归属证据、仅作参考的文档、排除项、失效指针目标、证据限制和每份维护文档的处置结果。未决问题与未核验陈述保持可见，不计为无问题。
+
+每项发现使用以下结构：
+
+```text
+[实现漂移 | 矛盾 | 术语 | 链接 | 冗余] 标题
+  位置：<文档>:<行号或章节>
+  现状：<陈述、重复内容或无依据扩写>
+  证据：<来源与观察到的事实，或证据边界>
+  建议：<仅文档纠正、删除或合并>
+  处置：可修复 | 需要用户决定 | 未核验
+```
+
+冗余发现须写明拟定的权威位置，以及其他位置分别保留、合并或链接什么。无依据扩写须说明是删除，还是收缩为有证据支持的陈述。无需关注时明确说明，并列出仍存在的未核验项。
+
+Report 到此结束，不写文件，也不创建报告产物。每份维护文档和每项潜在发现都有已报告的结果，且每个候选文档都有已报告的分类或未决问题时，本步完成。
+
+## 6. 批准并修复
+
+Fix 按文件和发现分组展示精确的拟修改内容。实质改写、删除或合并须展示精确的替换文本或删除边界，并覆盖所有受影响语言版本。单独标明因未决问题而排除的修改。
+
+请求明确批准并等待。用户可以只批准其中一个子集。严格应用获批修改，保留无关内容与用户已有改动。
+
+证据支持时，修复权威来源并同步有意的摘要与语言版本。生成结果使用项目的生成流程。合并必须保留每项独有要求、约束、注意事项与证据指针。出现新的语义冲突时停止该项并请求新的决定，不借此扩大获批范围。
+
+每个获批项都已严格应用，或明确保持未应用并说明原因，且没有未获批文件变化时，本步完成。
+
+## 7. 核验并收尾
+
+重新阅读每份修改过的文档。确认获批发现已解决、链接可解析、对应语言视图一致、合并内容仍可追溯，且没有未批准的语义变化。
+
+运行相关的现有项目检查并记录实际结果。报告修改文件、已解决发现、获批保留项、未决问题、未核验陈述与验证证据。没有获批或需要修改的内容时，明确说明没有文件变化。
+
+每项获批修改都有验证证据或具体的剩余失败，且每项检查都有实际结果时，本步完成。

package/dist/skills/authored/setup-project-docs/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: setup-project-docs
+description: Bootstrap architecture, glossary, decision-record conventions, and root agent-doc pointers; rerun to fill approved gaps.
+disable-model-invocation: true
+---
+
+# Set up project docs
+
+Create or complete living project documentation and its context pointers. Obtain approval before writing or modifying files.
+
+| Piece | Answers | Default location |
+|---|---|---|
+| Architecture | What is the system now? | `docs/architecture.md` |
+| Glossary | What is each concept called? | `docs/glossary.md` |
+| Decision conventions | How are decisions recorded and found? | `docs/decisions/AGENTS.md` |
+| Pointers | When should an agent open each document? | Root `AGENTS.md` |
+
+## 1. Inventory the repository
+
+Inspect root `AGENTS.md` and existing architecture and glossary documents. Resolve `<dir>` in this order:
+
+1. Use a caller-supplied record or directory path.
+2. Otherwise, resolve the decision pointer in root `AGENTS.md` under `## Project docs` when it points to an existing `<dir>/AGENTS.md`.
+3. Otherwise, inspect `docs/decisions/`, `docs/adr/`, and `doc/adr/`.
+
+Use the selected directory and read its `AGENTS.md` and `README.md` conventions when present. If several candidates remain, ask which is current and wait. When none exists, use the default location from the table.
+
+Read build and workspace configuration, real directories, and entry points until every principal module has a source-backed responsibility. Finish with an outline for each proposed document and an explicit list of facts the repository cannot supply.
+
+## 2. Confirm the plan
+
+Present existing, missing, and proposed paths. Lead with recommendations for decisions the repository cannot supply:
+
+- **Decision records:** recommend them when choices are costly to reverse; a small script or disposable prototype usually needs none. Declining leaves the related skills inert.
+- **Glossary layout:** recommend one file; split by context only for genuinely separate bounded contexts.
+
+Confirm the proposed paths and scope. On a rerun, limit the plan to missing pieces and stale pointers. Confirming this plan is not write approval: step 3 presents the content for that approval.
+
+## 3. Draft source-backed content
+
+- **Architecture:** use a module table with real directories and entry points. Document dependency direction and extension points demonstrated by the code; put rationale in decision records.
+- **Glossary:** define three to five existing code terms whose ambiguity could produce divergent names.
+- **Decision conventions:** create no placeholder record. Leave any real record to `decision-write`; when enabled, draft `<dir>/AGENTS.md` following [the decision-record conventions](references/decision-conventions.md).
+
+Present every draft together and obtain approval before writing. The approved set is the write plan.
+
+## 4. Write or update
+
+Create or update exactly the approved paths, editing existing files in place. Keep one `## Project docs` block in root `AGENTS.md`, adapted to its language and actual paths:
+
+```markdown
+## Project docs
+
+- Read `docs/architecture.md` before changing a module; update it when module boundaries or entry points change.
+- Read `docs/glossary.md` when naming a concept; add terms when introducing concepts.
+- Before starting any repository task, read `docs/decisions/AGENTS.md` and follow its search rules to read the records relevant to the task.
+```
+
+This block contains only document pointers. Include each pointer only for a document retained in the approved plan. Translate the pointer text into the root document's language and adapt its target to the actual path. Replace an existing `## Project docs` block with these pointers; preserve the rest of root `AGENTS.md`. Leave decision status meanings and record-selection rules in the decision directory's `AGENTS.md`.
+
+## 5. Verify and report
+
+Confirm that every approved path was written or updated, root `AGENTS.md` contains one `## Project docs` block with only document pointers, and every pointer resolves to a retained document from the repository root. Report written, updated, and skipped paths with reasons. State that pointers take effect in the next session.

package/dist/skills/authored/setup-project-docs/SKILL.zh.md

@@ -0,0 +1,63 @@
+---
+name: setup-project-docs
+description: 初始化架构、术语表、决策记录约定及根目录 agent 文档指针；重跑时补齐已批准的缺口。
+disable-model-invocation: true
+---
+
+# 建立项目文档
+
+创建或补齐持续维护的项目文档及其上下文指针。写入或修改文件前必须获得批准。
+
+| 部分 | 回答 | 默认位置 |
+|---|---|---|
+| 架构 | 系统现在是什么？ | `docs/architecture.md` |
+| 术语表 | 每个概念叫什么？ | `docs/glossary.md` |
+| 决策约定 | 如何记录并查找决策？ | `docs/decisions/AGENTS.md` |
+| 指针 | agent 何时打开每份文档？ | 根目录 `AGENTS.md` |
+
+## 1. 盘点仓库
+
+检查根目录 `AGENTS.md`、既有架构与术语文档。按以下顺序定位 `<dir>`：
+
+1. 使用调用方提供的记录或目录路径。
+2. 否则，解析根目录 `AGENTS.md` 的 `## Project docs` 中的决策指针；目标为现存的 `<dir>/AGENTS.md` 时使用该目录。
+3. 否则，检查 `docs/decisions/`、`docs/adr/` 和 `doc/adr/`。
+
+沿用选中的目录，并在存在时读取其 `AGENTS.md` 与 `README.md` 约定。仍有多个候选时，询问哪个是当前目录并等待。都不存在时使用表中的默认位置。
+
+读取构建与工作区配置、真实目录和入口点，直到每个主要模块的职责都有代码依据。最终为每份拟建文档形成提纲，并明确列出仓库无法提供的事实。
+
+## 2. 确认计划
+
+列出已有内容、缺失内容与拟用路径。对仓库无法决定的事项先给建议：
+
+- **决策记录：** 选择难以逆转时建议启用；小脚本或一次性原型通常不需要。拒绝会让相关技能保持惰性。
+- **术语表布局：** 建议单个文件；仅对真正独立的限界上下文按上下文拆分。
+
+确认拟用路径与范围。重跑时，计划只覆盖缺失部分和失效指针。确认计划不等于批准写入；步骤 3 展示内容以取得写入批准。
+
+## 3. 起草有依据的内容
+
+- **架构：** 用真实目录与入口点列出模块表；记录代码已体现的依赖方向与扩展点，理由写入决策记录。
+- **术语表：** 定义代码中已有且易引发不同命名的三到五个术语。
+- **决策约定：** 不创建占位记录。真实决策交给 `decision-write`；启用时按[决策记录约定](references/decision-conventions.zh.md)起草 `<dir>/AGENTS.md`。
+
+集中展示所有草稿，获得批准后再写入。批准集合就是写入计划。
+
+## 4. 写入或更新
+
+只创建或更新已批准的路径，既有文件就地编辑。根目录 `AGENTS.md` 只保留一个 `## Project docs` 块，并适配其语言与实际路径：
+
+```markdown
+## Project docs
+
+- Read `docs/architecture.md` before changing a module; update it when module boundaries or entry points change.
+- Read `docs/glossary.md` when naming a concept; add terms when introducing concepts.
+- Before starting any repository task, read `docs/decisions/AGENTS.md` and follow its search rules to read the records relevant to the task.
+```
+
+此块只写文档指针。只包含获批计划中保留的文档指针，将指针文字翻译为根文档的语言，并按实际路径调整目标。已有 `## Project docs` 块替换为这些指针，根目录 `AGENTS.md` 的其他内容保持不变。决策状态的含义与记录筛选规则留在决策目录的 `AGENTS.md`。
+
+## 5. 验证并报告
+
+确认每个已批准的路径均已写入或更新，根目录 `AGENTS.md` 只有一个 `## Project docs` 块且只含文档指针，每个指针都能从仓库根目录解析到保留的文档。报告写入、更新和跳过的路径及原因。说明指针从下个会话开始生效。