dsh-pstack 0.2.0-beta.3 → 0.2.1

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

@@ -4,10 +4,10 @@ Use this reference for Land anchor discovery, record-only fallback, and anchor v
 
 ## Find the implementation
 
-In Land when no candidate anchor is available, search commits and merged PRs touching the record's `Scope`:
+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' -- <Scope paths>
+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
 ```
 
@@ -45,4 +45,4 @@ Verify every proposed `Implemented-by` value:
 
 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.
 
-For unlanded work, failed verification, unavailable `gh`, or an unresolved `<base>`, write `proposed` + `-` and report the evidence or attempted refs. 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.
+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

@@ -4,10 +4,10 @@
 
 ## 查找实现
 
-落地模式没有可用的候选锚点时，检索触及记录 `Scope` 的提交与已合并 PR：
+落地模式没有可用的候选锚点时，先按“校验锚点”解析 `<base>`，再检索触及记录 `Scope` 的提交与已合并 PR：
 
 ```bash
-git log --since=<Date> --format='%H %cs %s' -- <Scope paths>
+git log --since=<Date> --format='%H %cs %s' <base> --
 gh pr list --state merged --search "<记录标题或范围关键词>" --json number,title,mergedAt,files --limit 20
 ```
 
@@ -45,4 +45,4 @@ git symbolic-ref --short refs/remotes/origin/HEAD 2>/dev/null ||
 
 用 `gh pr view N --json files --jq '.files[].path'` 或 `git show --pretty=format: --name-only SHA` 列出候选路径。真实实现与 `Scope` 相交，且至少有一个 `<dir>` 之外的路径；仅记录锚点需要经确认的例外。将这些路径交给范围检查。
 
-改动未落地、校验失败、`gh` 不可用或 `<base>` 无法解析时，写入 `proposed` + `-`，并报告证据或尝试过的 ref。基线无法解析也会阻止相对基线的范围检查；此时使用调用方提供的路径，或报告该证据不可用。既有 `accepted` 记录校验失败时不得降级；回到主技能的停下报告规则处理断裂锚点。
+撰写模式中，改动未落地、校验失败、`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

@@ -1,6 +1,6 @@
 ---
 name: setup-project-docs
-description: Bootstrap architecture, glossary, decision-record documentation, and root agent-doc pointers; rerun to fill approved gaps.
+description: Bootstrap architecture, glossary, decision-record conventions, and root agent-doc pointers; rerun to fill approved gaps.
 disable-model-invocation: true
 ---
 
@@ -12,12 +12,18 @@ Create or complete living project documentation and its context pointers. Obtain
 |---|---|---|
 | Architecture | What is the system now? | `docs/architecture.md` |
 | Glossary | What is each concept called? | `docs/glossary.md` |
-| Decision records | Why did it turn out this way? | `docs/decisions/` |
+| 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`, existing architecture and glossary documents, and `docs/decisions/`, `docs/adr/`, `doc/adr/`. Reuse existing homes and conventions. If several decision directories exist, ask which is current and wait.
+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.
 
@@ -28,14 +34,13 @@ Present existing, missing, and proposed paths. Lead with recommendations for dec
 - **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 content. On a rerun, limit the plan to missing pieces and stale pointers. Step 3 supplies the final write approval.
+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.
-- **Decisions:** create no placeholder record. Leave any real record to `decision-write`; this skill only scaffolds the directory and conventions.
-- **Decision conventions:** when enabled, write `<dir>/AGENTS.md` following [the decision-record conventions](references/decision-conventions.md).
+- **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.
 
@@ -48,11 +53,11 @@ Create or update exactly the approved paths, editing existing files in place. Ke
 
 - 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 writing or reviewing decisions, read `docs/decisions/AGENTS.md` for format and search conventions.
+- Before starting any repository task, read `docs/decisions/AGENTS.md` and follow its search rules to read the records relevant to the task.
 ```
 
-Lead each pointer with its trigger and target; include only approved branches. Point decision work to the plain reference.
+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 root `AGENTS.md` contains one `## Project docs` block, every approved path was written or updated, and every pointer resolves from the repository root. Report written, updated, and skipped paths with reasons. State that pointers take effect in the next session.
+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

@@ -1,6 +1,6 @@
 ---
 name: setup-project-docs
-description: 初始化架构、术语表、决策记录文档及根目录 agent 文档指针；重跑时补齐已批准的缺口。
+description: 初始化架构、术语表、决策记录约定及根目录 agent 文档指针；重跑时补齐已批准的缺口。
 disable-model-invocation: true
 ---
 
@@ -12,12 +12,18 @@ disable-model-invocation: true
 |---|---|---|
 | 架构 | 系统现在是什么？ | `docs/architecture.md` |
 | 术语表 | 每个概念叫什么？ | `docs/glossary.md` |
-| 决策记录 | 为何演变成现在这样？ | `docs/decisions/` |
+| 决策约定 | 如何记录并查找决策？ | `docs/decisions/AGENTS.md` |
 | 指针 | agent 何时打开每份文档？ | 根目录 `AGENTS.md` |
 
 ## 1. 盘点仓库
 
-检查根目录 `AGENTS.md`、既有架构与术语文档，以及 `docs/decisions/`、`docs/adr/`、`doc/adr/`。沿用已有路径与约定。存在多个决策目录时，询问哪个是当前目录并等待。
+检查根目录 `AGENTS.md`、既有架构与术语文档。按以下顺序定位 `<dir>`：
+
+1. 使用调用方提供的记录或目录路径。
+2. 否则，解析根目录 `AGENTS.md` 的 `## Project docs` 中的决策指针；目标为现存的 `<dir>/AGENTS.md` 时使用该目录。
+3. 否则，检查 `docs/decisions/`、`docs/adr/` 和 `doc/adr/`。
+
+沿用选中的目录，并在存在时读取其 `AGENTS.md` 与 `README.md` 约定。仍有多个候选时，询问哪个是当前目录并等待。都不存在时使用表中的默认位置。
 
 读取构建与工作区配置、真实目录和入口点，直到每个主要模块的职责都有代码依据。最终为每份拟建文档形成提纲，并明确列出仓库无法提供的事实。
 
@@ -28,14 +34,13 @@ disable-model-invocation: true
 - **决策记录：** 选择难以逆转时建议启用；小脚本或一次性原型通常不需要。拒绝会让相关技能保持惰性。
 - **术语表布局：** 建议单个文件；仅对真正独立的限界上下文按上下文拆分。
 
-确认拟用路径与内容。重跑时，计划只覆盖缺失部分和失效指针。步骤 3 提供最终写入批准。
+确认拟用路径与范围。重跑时，计划只覆盖缺失部分和失效指针。确认计划不等于批准写入；步骤 3 展示内容以取得写入批准。
 
 ## 3. 起草有依据的内容
 
 - **架构：** 用真实目录与入口点列出模块表；记录代码已体现的依赖方向与扩展点，理由写入决策记录。
 - **术语表：** 定义代码中已有且易引发不同命名的三到五个术语。
-- **决策记录：** 不创建占位记录。真实决策交给 `decision-write`；本技能只搭建目录与约定。
-- **决策约定：** 启用时，按[决策记录约定](references/decision-conventions.zh.md)起草 `<dir>/AGENTS.md`。
+- **决策约定：** 不创建占位记录。真实决策交给 `decision-write`；启用时按[决策记录约定](references/decision-conventions.zh.md)起草 `<dir>/AGENTS.md`。
 
 集中展示所有草稿，获得批准后再写入。批准集合就是写入计划。
 
@@ -48,11 +53,11 @@ disable-model-invocation: true
 
 - 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 writing or reviewing decisions, read `docs/decisions/AGENTS.md` for format and search conventions.
+- 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` 块，每个已批准的路径均已写入或更新，且每个指针都能从仓库根目录解析。报告写入、更新和跳过的路径及原因。说明指针从下个会话开始生效。
+确认每个已批准的路径均已写入或更新，根目录 `AGENTS.md` 只有一个 `## Project docs` 块且只含文档指针，每个指针都能从仓库根目录解析到保留的文档。报告写入、更新和跳过的路径及原因。说明指针从下个会话开始生效。

package/dist/skills/authored/setup-project-docs/references/decision-conventions.md

@@ -4,8 +4,10 @@ When decision records are enabled, draft `<dir>/AGENTS.md` as the repository's a
 
 - The five-field header: `Status`, `Date`, `Scope`, `Implemented-by`, `Review`.
 - The status/anchor pair rule and transitions, including immediate supersession by a new draft. A replaced `proposed` record retains `Implemented-by: -`; preserve its body rather than deleting or reverting it.
-- Related-record search and classification.
+- Before starting any repository task, read the headers of every `proposed` and `accepted` record, then select by `Scope` against the task and its affected paths and read the full text of relevant records. `accepted` records constrain current implementation; `proposed` records state the intended direction. When the task conflicts with a relevant record, report the conflict and obtain the user's direction before proceeding.
+- Related-record search and classification before writing or substantially updating a record.
 - `decision-write` as the entry rule for every record change.
+- One `Scope` matcher shared by writing and auditing, including repository-relative paths and directory globs that cover descendants.
 - `Superseded-by` with the replacing record path and one-line reason for every `superseded` record.
 
 Adapt `decision-write`'s fallback template to the repository's language and conventions. Require a real implementation anchor to intersect `Scope` and include a path outside `<dir>`. Permit a record-only commit only through `decision-write`'s explicitly confirmed Land exception, and state that audits continue to report it.

package/dist/skills/authored/setup-project-docs/references/decision-conventions.zh.md

@@ -4,8 +4,10 @@
 
 - 五字段头部：`Status`、`Date`、`Scope`、`Implemented-by`、`Review`。
 - 状态/锚点成对规则与状态流转，包括新草稿立即取代旧记录。被取代的 `proposed` 记录保留 `Implemented-by: -`；保留旧正文，不删除、不回退。
-- 相关记录检索与分类。
+- 开始每项仓库任务前，读取所有 `proposed` 与 `accepted` 记录的头部，再按任务及其涉及的路径与 `Scope` 筛选并读取相关记录的正文。`accepted` 记录约束当前实现；`proposed` 记录表示待落地方向。任务与相关记录冲突时，先报告冲突并取得用户指示，再继续。
+- 写入或实质更新记录前检索并分类相关记录。
 - 以 `decision-write` 作为所有记录修改的入口。
+- 写入与审计共用同一 `Scope` 匹配规则，路径相对于仓库根目录，目录 glob 覆盖所有后代。
 - 每条 `superseded` 记录都带 `Superseded-by`，包含替代记录路径和一句原因。
 
 以 `decision-write` 的回退模板为基础，适配仓库的语言与约定。真实实现锚点的路径须与 `Scope` 相交，且至少一个路径在 `<dir>` 之外；仅允许通过 `decision-write` 落地模式中经用户明确确认的例外使用仅记录提交，并写明审计仍会报告该例外。

package/dist/subagent.d.mts

@@ -1,25 +1,10 @@
 import { _ as ToolsHost, g as ToolDefinition, h as SubagentsHost, m as SubagentCapabilities, n as AgentOptions, r as AgentsHost, s as LlmHost, t as Agent, v as WorkingDirectoryHost } from "./host-contract-CUPSpeNk.mjs";
-/**
- * The one pstack role manifest.
- *
- * Keys are matched exactly after normalization, and commas belong to some keys
- * (`feature, refactoring`, `reflect judgment, divergent, synthesizer`), so nothing here
- * may split a key on a comma. A second literal role list anywhere is a bug.
- *
- * This module has no Node imports: the bundle imports it directly.
- */
-/** Whether a role holds one route or a comma-separated list of routes. */
-type RoleValueShape = "single" | "list";
-interface RoleSpec {
-  /** Exact key as written in the role file. Commas belong to the key. */
-  readonly key: string;
-  readonly shape: RoleValueShape;
-  /** A list role that starts one child per entry automatically. */
-  readonly autoPanel: boolean;
-}
+import { n as RoleSpec } from "./role-manifest-8OERX9-s.mjs";
 /** One resolved child route. */
 type Route = {
   readonly kind: "inherit";
+  /** The spelling the file used; `undefined` for an implicit fallback. */
+  readonly alias?: "inherit-parent" | "auto";
 } | {
   readonly kind: "route";
   readonly provider: string;
@@ -58,6 +43,13 @@ export interface PstackSubagentConfig {
   readonly provider: string;
   readonly maxDepth?: number;
 }
+/**
+ * Depth a child runs at when a call omits `maxDepth` or passes an unusable value.
+ *
+ * A child is always at least depth 1 (it is one level below its parent), so this is the
+ * smallest value that can start a child while forbidding it from delegating further.
+ */
+export declare const DEFAULT_CHILD_MAX_DEPTH = 1;
 /** What a call asked for, after every required argument has been validated. */
 export interface DelegationArgs {
   readonly description: string;
@@ -65,7 +57,7 @@ export interface DelegationArgs {
   readonly agent: AgentKind;
   readonly role: string | null;
   readonly cwd: string | null;
-  readonly maxDepth: number;
+  readonly maxDepth: number | null;
   readonly roleIndex: number | null;
   readonly reasoningEffort: string | null;
 }
@@ -122,6 +114,13 @@ export declare function composeChildPrompt(input: {
   }[];
   readonly task: string;
 }): string;
+export declare const DELEGATION_ARGUMENT_KEYS: readonly ["description", "prompt", "agent", "role", "roleIndex", "reasoningEffort", "cwd", "maxDepth"];
+/**
+ * Keys a call must pass. `maxDepth` is accepted but not required: a missing or unusable
+ * value resolves to `DEFAULT_CHILD_MAX_DEPTH` instead of forcing the caller to guess an
+ * integer, which is where the reflexive `0` came from.
+ */
+export declare const REQUIRED_DELEGATION_ARGUMENT_KEYS: readonly ["description", "prompt", "agent", "role", "roleIndex", "reasoningEffort", "cwd"];
 /** Validate every required model-facing argument. Null declines an optional setting. */
 export declare function parseDelegationArgs(raw: unknown): DelegationArgs;
 /** One planned child, before any Host call. */
@@ -155,7 +154,15 @@ export interface DelegationPlan {
 /** Route text as reported to the model. */
 export declare function routeLabel(route: Route, effortOverride?: string): string;
 /** Take the smallest of the requested depth, this row's cap, and the Host setting. */
-export declare function resolveDelegationDepth(configured: number | undefined, requested: number | undefined, hostLimit: number | undefined): number | undefined;
+export declare function resolveDelegationDepth(configured: number | undefined, requested: number | null | undefined, hostLimit: number | undefined): number | undefined;
+/**
+ * Turn the per-call `maxDepth` request into an effective depth request.
+ *
+ * A child is always at least depth 1, so `0` can never start one: it is reported and
+ * replaced with `DEFAULT_CHILD_MAX_DEPTH` rather than failing the whole call. Omitting
+ * `maxDepth` (null) also uses the default, so a caller never has to guess an integer.
+ */
+export declare function requestedChildDepth(requested: number | null, diagnostics: string[]): number;
 /** Resolve the role file, routes, prompt, and depth into one plan. Pure of service calls. */
 export declare function planDelegation(args: DelegationArgs, runtime: SubagentRuntime, config?: PstackSubagentConfig): DelegationPlan;
 /** Check the backend can enforce what this call asks for. */