dsh-pstack 0.2.0-beta.3 → 0.2.1

package/dist/roles.mjs

@@ -0,0 +1,293 @@
+import { collectCatalogue } from "./models.mjs";
+import { i as findRoleSpec, o as normalizeRoleName, r as ROLE_MANIFEST, t as INHERIT_PARENT_ALIASES } from "./role-manifest-79cnFfDM.mjs";
+import { REMOTE_PACKAGE, ROLES_SERVICE, pstackRolesRemote } from "./remote.mjs";
+import { i as resolveDshHome, n as readRoleConfiguration, o as updateRoleDocument, t as modelsFilePath } from "./role-config-a4JpVdc-.mjs";
+import { dirname } from "node:path";
+import { mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { Service } from "@deepseek-ai/cordis";
+import { TypertRemoteService } from "@deepseek-ai/dsh-typert-protocol";
+import { randomUUID } from "node:crypto";
+// src/internal/role-editor.ts
+/**
+* Role-file editing behind the Plugins configuration page.
+*
+* The writer changes exactly one role line and leaves every other byte of the
+* file alone: unknown lines, malformed lines, comments, and `# budget` survive a
+* save. Saves are validated against the live `pstack_models` catalogue before
+* the first byte is written, so a rejected save leaves the file unchanged.
+*/
+function routeView(route) {
+	if (route.kind === "inherit") return {
+		kind: "inherit",
+		alias: route.alias ?? "inherit-parent"
+	};
+	return {
+		kind: "route",
+		provider: route.provider,
+		model: route.model,
+		...route.effort === void 0 ? {} : { effort: route.effort }
+	};
+}
+function roleView(spec, entry) {
+	return {
+		key: spec.key,
+		shape: spec.shape,
+		configured: entry !== void 0,
+		...entry === void 0 ? {} : { line: entry.line },
+		routes: entry === void 0 ? [] : entry.routes.map(routeView),
+		issues: entry === void 0 ? [] : [...entry.issues]
+	};
+}
+/** Project a parsed file onto the manifest, preserving order and per-line issues. */
+function snapshotFromConfiguration(config) {
+	if (config.status === "unreadable") return {
+		path: config.path,
+		status: "unreadable",
+		reason: config.reason,
+		roles: ROLE_MANIFEST.map((spec) => roleView(spec, void 0)),
+		issues: [],
+		canSave: false
+	};
+	if (config.status === "missing") return {
+		path: config.path,
+		status: "missing",
+		roles: ROLE_MANIFEST.map((spec) => roleView(spec, void 0)),
+		issues: [],
+		canSave: true
+	};
+	return {
+		path: config.path,
+		status: "loaded",
+		...config.budget === void 0 ? {} : { budget: config.budget },
+		roles: ROLE_MANIFEST.map((spec) => roleView(spec, config.roles.get(spec.key))),
+		issues: config.issues.map((issue) => ({
+			...issue.line === void 0 ? {} : { line: issue.line },
+			message: issue.message
+		})),
+		canSave: true
+	};
+}
+/** Validate one save against the manifest and the live catalogue. */
+function validateSaveRequest(request, catalogue) {
+	if (typeof request !== "object" || request === null || Array.isArray(request)) return {
+		ok: false,
+		reason: "the save request must be an object"
+	};
+	if (typeof request.key !== "string") return {
+		ok: false,
+		reason: "the save request must name a role"
+	};
+	const spec = findRoleSpec(normalizeRoleName(request.key));
+	if (spec === void 0) return {
+		ok: false,
+		reason: `unknown role ${JSON.stringify(request.key)}`
+	};
+	if (!Array.isArray(request.routes)) return {
+		ok: false,
+		reason: `role "${spec.key}" must carry a route list`
+	};
+	if (spec.shape === "single" && request.routes.length !== 1) return {
+		ok: false,
+		reason: `role "${spec.key}" holds a single route; save exactly one`
+	};
+	if (request.routes.length === 0) return {
+		ok: false,
+		reason: `role "${spec.key}" must keep at least one route`
+	};
+	const routes = [];
+	for (let index = 0; index < request.routes.length; index += 1) {
+		const route = request.routes[index];
+		const position = request.routes.length === 1 ? "the route" : `route ${index + 1}`;
+		if (typeof route !== "object" || route === null || Array.isArray(route)) return {
+			ok: false,
+			reason: `${position} must be an object`
+		};
+		if (route.kind === "inherit") {
+			const alias = route.alias ?? "inherit-parent";
+			if (!INHERIT_PARENT_ALIASES.includes(alias)) return {
+				ok: false,
+				reason: `${position} has unknown inheritance alias ${JSON.stringify(alias)}; use \`inherit-parent\` or \`auto\``
+			};
+			routes.push({
+				kind: "inherit",
+				alias
+			});
+			continue;
+		}
+		const unknownKind = route.kind;
+		if (unknownKind !== "route") return {
+			ok: false,
+			reason: `${position} has unknown kind ${JSON.stringify(unknownKind)}`
+		};
+		const provider = typeof route.provider === "string" ? route.provider.trim() : "";
+		const model = typeof route.model === "string" ? route.model.trim() : "";
+		if (provider === "" || model === "") return {
+			ok: false,
+			reason: `${position} needs both a provider and a model`
+		};
+		const providerEntry = catalogue.providers.find((candidate) => candidate.provider === provider);
+		if (providerEntry === void 0) return {
+			ok: false,
+			reason: `provider ${JSON.stringify(provider)} is not in the live model directory; run \`pstack_models\` and pick a registered provider`
+		};
+		if (providerEntry.error !== void 0) return {
+			ok: false,
+			reason: `provider ${JSON.stringify(provider)} could not be discovered: ${providerEntry.error}`
+		};
+		const modelEntry = providerEntry.models.find((candidate) => candidate.id === model);
+		if (modelEntry === void 0) return {
+			ok: false,
+			reason: `provider ${JSON.stringify(provider)} does not advertise model ${JSON.stringify(model)}`
+		};
+		if (modelEntry.error !== void 0) return {
+			ok: false,
+			reason: `model ${JSON.stringify(`${provider}/${model}`)} could not be resolved: ${modelEntry.error}`
+		};
+		const effort = typeof route.effort === "string" ? route.effort.trim() : route.effort;
+		if (effort !== void 0 && effort !== "") {
+			if (!modelEntry.efforts.includes(effort)) return {
+				ok: false,
+				reason: `model ${JSON.stringify(`${provider}/${model}`)} does not declare effort ${JSON.stringify(effort)}; declared efforts: ${modelEntry.efforts.length === 0 ? "none" : modelEntry.efforts.join(", ")}`
+			};
+			routes.push({
+				kind: "route",
+				provider,
+				model,
+				effort
+			});
+			continue;
+		}
+		if (effort === "") return {
+			ok: false,
+			reason: `${position} has an empty effort; drop the effort or pick one`
+		};
+		routes.push({
+			kind: "route",
+			provider,
+			model
+		});
+	}
+	return {
+		ok: true,
+		value: {
+			spec,
+			routes
+		}
+	};
+}
+/** Render one role's routes in the role-file grammar. */
+function renderRoleValue(routes) {
+	return routes.map((route) => route.kind === "inherit" ? route.alias ?? "inherit-parent" : route.effort === void 0 ? `${route.provider}/${route.model}` : `${route.provider}/${route.model} [${route.effort}]`).join(", ");
+}
+/** Update the winning role through the same line grammar used by the parser. */
+function updateRoleText(text, spec, value) {
+	return updateRoleDocument(text, spec, value);
+}
+function writeAtomically(path, text) {
+	mkdirSync(dirname(path), { recursive: true });
+	const temporary = `${path}.${process.pid}.${randomUUID()}.tmp`;
+	try {
+		writeFileSync(temporary, text, "utf8");
+		renameSync(temporary, path);
+	} catch (error) {
+		rmSync(temporary, { force: true });
+		throw error;
+	}
+}
+/**
+* Save one role and return the reloaded snapshot.
+*
+* A missing file is created with just this role. An unreadable file is never
+* overwritten. Every refusal leaves the existing bytes untouched.
+*/
+function saveRoleConfiguration(path, request, catalogue) {
+	const current = readRoleConfiguration(path);
+	if (current.status === "unreadable") return {
+		ok: false,
+		reason: `the role file is unreadable: ${current.reason}`
+	};
+	const validation = validateSaveRequest(request, catalogue);
+	if (!validation.ok) return validation;
+	let existing = "";
+	if (current.status === "loaded") try {
+		existing = readFileSync(path, "utf8");
+	} catch (error) {
+		return {
+			ok: false,
+			reason: `the role file could not be read: ${describeError(error)}`
+		};
+	}
+	const next = updateRoleText(existing, validation.value.spec, renderRoleValue(validation.value.routes));
+	try {
+		writeAtomically(path, next);
+	} catch (error) {
+		return {
+			ok: false,
+			reason: `the role file could not be written: ${describeError(error)}`
+		};
+	}
+	return {
+		ok: true,
+		snapshot: snapshotFromConfiguration(readRoleConfiguration(path))
+	};
+}
+function describeError(error) {
+	if (error instanceof Error) {
+		const code = error.code;
+		return typeof code === "string" ? `${error.message} (${code})` : error.message;
+	}
+	return String(error);
+}
+// src/roles.ts
+/**
+* `pstack-roles`: the Host half of the role model configuration page.
+*
+* It owns no cached policy: every read and write goes to
+* `$DSH_HOME/pstack-models.mdc`, which `pstack_subagent` also re-reads on every
+* delegation. Saving therefore takes effect on the next delegation without a
+* restart, and an already running child keeps the route it started with.
+*/
+/** Read and write the role file for the Plugins configuration page. */
+var PstackRolesService = class extends TypertRemoteService {
+	static inject = ["llm", "typert"];
+	constructor(ctx) {
+		super(ctx, ROLES_SERVICE);
+	}
+	[Service.init]() {
+		const typert = this.ctx.typert;
+		if (typert === void 0) throw new Error("pstack-roles requires the Typert registry service");
+		typert.register({
+			package: REMOTE_PACKAGE,
+			face: "host",
+			schemas: [],
+			model: {
+				services: [],
+				events: [],
+				objects: []
+			},
+			invocations: pstackRolesRemote.descriptors
+		});
+	}
+	/** Current path, status, values, and per-line issues. */
+	status() {
+		return snapshotFromConfiguration(readRoleConfiguration(roleFilePath()));
+	}
+	/** The live directory the page offers for its provider/model/effort selects. */
+	async catalogue(signal) {
+		return collectCatalogue(this.llm, void 0, signal);
+	}
+	/** Validate and save one role, then return the reloaded snapshot. */
+	async save(request, signal) {
+		signal.throwIfAborted();
+		const catalogue = await collectCatalogue(this.llm, void 0, signal);
+		signal.throwIfAborted();
+		return saveRoleConfiguration(roleFilePath(), request, catalogue);
+	}
+	get llm() {
+		return this.ctx.llm;
+	}
+};
+function roleFilePath() {
+	return modelsFilePath(resolveDshHome());
+}
+export { PstackRolesService, PstackRolesService as default };

package/dist/script.mjs

@@ -1,4 +1,4 @@
-import { i as PORT_ROOT } from "./paths-BT77khwm.mjs";
+import { i as PORT_ROOT } from "./paths-yji9SNak.mjs";
 import { isAbsolute, join, resolve } from "node:path";
 import { spawn } from "node:child_process";
 // src/internal/script-registry.ts

package/dist/skills/authored/decision-audit/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: decision-audit
-description: Audit decision records against a change set or the whole repository; report routing, status, scope, anchor, supersession, and review findings with command evidence.
+description: Read-only audit of decision records for a PR, local changes, or the whole repository. Report routing, status, scope, anchor, supersession, and overdue-review findings with command evidence.
 disable-model-invocation: true
 ---
 
@@ -12,13 +12,15 @@ Produce a read-only report of records needing human attention, without judging w
 
 Accept `mode` (`pr`, `local`, or `full`; default `pr`), optional `base`, and optional `scope` paths replacing the computed change set.
 
-For `pr`, resolve the PR base; otherwise try `origin/main`. When absent, try `origin/master`, `main`, `master`, the newest tag, then `HEAD~20`. Report the selected ref, or stop and list every attempted ref.
+For `pr`, resolve the PR base. For `local` or `full`, try `origin/main`. When absent, try `origin/master`, `main`, `master`, the newest tag, then `HEAD~20`. Report the selected ref. An unresolved base blocks base-relative change sets and commit-anchor checks; continue the other checks and list every attempted ref under `Unverified`.
 
-Inspect `docs/decisions/`, `docs/adr/`, and `doc/adr/`:
+Resolve `<dir>` in this order:
 
-- One exists: call it `<dir>` and report its path.
-- Several exist: ask which is current and wait.
-- None exists or it contains no records: report that normal result and stop.
+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/`.
+
+Report the selected path. If several candidates remain, ask which is current and wait. If none exists or it contains no records, report that normal result and stop.
 
 ## 2. Collect the evidence
 
@@ -33,24 +35,26 @@ git diff --name-only "$(git merge-base HEAD <base>)"..HEAD
 git status --porcelain=v1 --untracked-files=all
 ```
 
-Decode `git status` paths, including the destination of a rename. For `full`, use all tracked files. Exclude lock files, generated files, snapshots, and pure assets from the computed set; record these exclusions and the final set.
+Decode `git status` paths, including the destination of a rename. For `full`, use all tracked files. Exclude lock files, generated files, snapshots, and pure assets from the computed set; record these exclusions and the final set. An explicit `scope` replaces the computed set but does not change base-dependent anchor checks.
+
+Read `<dir>/AGENTS.md` and `<dir>/README.md` when present; these are conventions, not records. Apply their conventions to every other `*.md`. Parse each header through its first `## ` heading. List records missing any of `Status`, `Date`, `Scope`, `Implemented-by`, or `Review` separately as `Legacy`; they receive no further checks until the required fields are restored. `Superseded-by` is optional for current records; check it only under E.
 
-Read `<dir>/AGENTS.md` and `<dir>/README.md` when present; these are conventions, not records. Apply their conventions to every other `*.md`. Parse each header through its first `## ` heading. List records missing any of `Status`, `Date`, `Scope`, `Implemented-by`, or `Review` separately as `Legacy`, exempt from all six checks.
+Apply every applicable check to every current record; a record may have multiple findings. Use [Match Scope paths](../decision-write/references/scope.md) for every glob/path check and retain the matches as evidence.
 
-Apply every applicable check to every current record; a record may have multiple findings.
+## 3. Run the checks
 
-## 3. Apply all six checks
+Apply A, B, B′, and D only to non-`superseded` records; apply C and E as specified below.
 
-**A — Route.** For each non-`superseded` record whose `Scope` matches the change set, report its title, path, matched paths, and change-set evidence in one line.
+**A — Route.** For each record whose `Scope` matches the change set, report its title, path, matched paths, and change-set evidence in one line.
 
 **B — Status pair.** Use the anchor results below and report each matching row:
 
 | Status | Anchor result | Finding |
 |---|---|---|
 | `proposed` | verified | Should be `accepted` |
-| `accepted` | `-`, missing, pending, or unverified | Landing lacks verified evidence |
+| `accepted` | `-` or missing | Landing lacks verified evidence |
 
-For `proposed`, `-` or a pending anchor is not a finding; an unverified anchor belongs in `Unverified`, outside B and C.
+For `proposed`, `-` is pending. For either `proposed` or `accepted`, a pending anchor is not a finding; report the record as pending. An unverified anchor belongs in `Unverified`, outside B and C.
 
 **B′ — Dead scope.** For each `accepted` record with no `Scope` glob matching an existing file, report its path and glob-check evidence. Ask whether the decision is obsolete or its scope is wrong.
 
@@ -67,14 +71,14 @@ For a landed PR or ancestral commit, list its paths with `gh pr view N --json fi
 
 Before reporting a commit as lost, read [Recover a rewritten commit](references/recover-commit.md) and attempt patch-identity recovery while its object remains available.
 
-**D — Overdue review.** In `full` mode only, report each record whose `Review` date is before the current date. Collect the changes since the decision date:
+**D — Overdue review.** In `full` mode only, report each record whose `Review` date is before the current date. Collect matching changes since the decision date:
 
 ```bash
 date +%F
-git log --since=<Date> --oneline -- <Scope paths>
+git log --since=<Date> --format=%H <base> --
 ```
 
-Include the count and latest subject when present; suggest human review and a new `Review` date.
+List each commit's paths and filter them with the shared matcher before counting it; the record's `Scope` value is matcher input, not a Git pathspec. Include the matched-commit count and latest subject when present. An overdue date is the finding even when there are no matching changes; suggest human review and a new `Review` date.
 
 **E — Superseded record.** For each current `superseded` record, report when `Superseded-by` is missing, does not resolve to a record in `<dir>`, or carries no ` — <reason>` text. Suggest adding the replacing record path and a one-line reason.
 
@@ -96,4 +100,4 @@ Use this structure for findings; include `Evidence` for every class:
   Suggest: replace the anchor with commit:8ff9f762 (matching patch-id d064e03f4e53)
 ```
 
-List `Legacy` and `Unverified` separately from findings. When nothing needs attention, say so in one line. An unavailable or unauthenticated `gh` leaves PR anchors unverified while the other checks continue.
+List `Legacy` and `Unverified` separately from findings. An unavailable or unauthenticated `gh` leaves PR anchors unverified while the other checks continue. Say when no current record carries a finding. Route all edits to `decision-write`; suggest `/setup-project-docs` only when the decision directory or its root pointer is missing.

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

@@ -1,6 +1,6 @@
 ---
 name: decision-audit
-description: 按改动集合或整个仓库审计决策记录，报告路由、状态、范围、锚点、取代与复核发现，并附命令证据。
+description: 只读审计 PR、本地改动或整个仓库的决策记录，报告路由、状态、范围、锚点、取代与复核逾期发现，并附命令证据。
 disable-model-invocation: true
 ---
 
@@ -12,13 +12,15 @@ disable-model-invocation: true
 
 接受 `mode`（`pr`、`local` 或 `full`，默认 `pr`）、可选的 `base`，以及用于替代计算所得改动集合的可选 `scope` 路径。
 
-`pr` 解析 PR 基线，其他模式先尝试 `origin/main`。不存在时依次尝试 `origin/master`、`main`、`master`、最新 tag、`HEAD~20`。报告实际选中的 ref；全部无法解析时停止并列出每个尝试过的 ref。
+`pr` 解析 PR 基线，`local` 或 `full` 先尝试 `origin/main`。不存在时依次尝试 `origin/master`、`main`、`master`、最新 tag、`HEAD~20`。报告实际选中的 ref。基线无法解析会阻止相对基线的改动集合计算与提交锚点校验；继续其他检查，并在 `Unverified` 中列出每个尝试过的 ref。
 
-检查 `docs/decisions/`、`docs/adr/` 和 `doc/adr/`：
+按以下顺序定位 `<dir>`：
 
-- 只有一个存在：记为 `<dir>` 并报告路径。
-- 多个存在：询问哪个是当前目录并等待。
-- 都不存在或没有记录：报告这一正常结果并停止。
+1. 使用调用方提供的记录或目录路径。
+2. 否则，解析根目录 `AGENTS.md` 的 `## Project docs` 中的决策指针；目标为现存的 `<dir>/AGENTS.md` 时使用该目录。
+3. 否则，检查 `docs/decisions/`、`docs/adr/` 和 `doc/adr/`。
+
+报告选中的路径。仍有多个候选时，询问哪个是当前目录并等待。都不存在或没有记录时，报告这一正常结果并停止。
 
 ## 2. 收集证据
 
@@ -33,24 +35,26 @@ git diff --name-only "$(git merge-base HEAD <base>)"..HEAD
 git status --porcelain=v1 --untracked-files=all
 ```
 
-解析 `git status` 中的路径，重命名取目标路径。`full` 使用所有受 Git 跟踪的文件。从计算结果中剔除锁文件、生成文件、快照和纯资源文件；记录这些排除项与最终集合。
+解析 `git status` 中的路径，重命名取目标路径。`full` 使用所有受 Git 跟踪的文件。从计算结果中剔除锁文件、生成文件、快照和纯资源文件；记录这些排除项与最终集合。显式 `scope` 替换计算所得集合，但不改变依赖基线的锚点校验。
+
+存在 `<dir>/AGENTS.md` 和 `<dir>/README.md` 时读取；它们是约定而非记录。将其约定应用到其他所有 `*.md`。读取每条记录至第一个 `## ` 标题并解析头部。缺少 `Status`、`Date`、`Scope`、`Implemented-by`、`Review` 中任一项的记录单列为 `Legacy`，补齐必需字段前不执行后续检查。现行记录的 `Superseded-by` 可选，只在 E 类检查中处理。
 
-存在 `<dir>/AGENTS.md` 和 `<dir>/README.md` 时读取；它们是约定而非记录。将其约定应用到其他所有 `*.md`。读取每条记录至第一个 `## ` 标题并解析头部。缺少 `Status`、`Date`、`Scope`、`Implemented-by`、`Review` 中任一项的记录单列为 `Legacy`，不参与以下六项检查。
+对每条现行记录执行所有适用的检查；同一记录可以产生多项发现。所有 glob/路径检查都使用[匹配 Scope 路径](../decision-write/references/scope.zh.md)，并保留匹配结果作为证据。
 
-对每条现行记录执行所有适用的检查；同一记录可以产生多项发现。
+## 3. 执行检查
 
-## 3. 执行全部六项检查
+A、B、B′ 和 D 只用于非 `superseded` 记录；C 和 E 按下方说明执行。
 
-**A——路由。** 对每条非 `superseded` 且 `Scope` 匹配改动集合的记录，用一行报告标题、路径、匹配路径及改动集合证据。
+**A——路由。** 对每条 `Scope` 匹配改动集合的记录，用一行报告标题、路径、匹配路径及改动集合证据。
 
 **B——状态成对。** 使用下方的锚点结果，报告每个匹配行：
 
 | Status | 锚点结果 | 发现 |
 |---|---|---|
 | `proposed` | 已核验 | 应改为 `accepted` |
-| `accepted` | `-`、缺失、待落地或未核验 | 落地状态缺少已核验证据 |
+| `accepted` | `-` 或缺失 | 落地状态缺少已核验证据 |
 
-`proposed` 带 `-` 或待落地锚点不是发现；带未核验锚点时归入 `Unverified`，不归入 B 或 C。
+`proposed` 带 `-` 时归为待落地。`proposed` 或 `accepted` 带待落地锚点都不是发现；将记录归为待落地。带未核验锚点时归入 `Unverified`，不归入 B 或 C。
 
 **B′——范围失效。** 对 `Scope` 中所有 glob 都不匹配现存文件的每条 `accepted` 记录，报告路径与 glob 检查证据，并询问是决策已过时还是范围写错。
 
@@ -67,14 +71,14 @@ git status --porcelain=v1 --untracked-files=all
 
 报告提交丢失前，读取[恢复被改写的提交](references/recover-commit.zh.md)；只要其对象仍可用，就尝试恢复 patch 标识。
 
-**D——复核逾期。** 仅在 `full` 模式，报告 `Review` 日期早于当前日期的每条记录，并收集决策日期以来的改动：
+**D——复核逾期。** 仅在 `full` 模式，报告 `Review` 日期早于当前日期的每条记录，并收集决策日期以来匹配 `Scope` 的改动：
 
 ```bash
 date +%F
-git log --since=<Date> --oneline -- <Scope paths>
+git log --since=<Date> --format=%H <base> --
 ```
 
-附上提交数量和最新主题（如有），建议人工复核并更新 `Review` 日期。
+列出每个提交的路径，先用共享匹配器筛选，再计数；记录的 `Scope` 是匹配器输入，不是 Git pathspec。附上匹配提交的数量和最新主题（如有）。日期逾期本身就是发现，即使没有匹配改动；建议人工复核并更新 `Review` 日期。
 
 **E——取代记录。** 对每条现行 `superseded` 记录，在 `Superseded-by` 缺失、无法解析到 `<dir>` 内的记录，或没有 ` — <原因>` 文本时报告。建议补上替代记录路径和一句原因。
 
@@ -96,4 +100,4 @@ git log --since=<Date> --oneline -- <Scope paths>
   Suggest: replace the anchor with commit:8ff9f762 (matching patch-id d064e03f4e53)
 ```
 
-`Legacy` 与 `Unverified` 分别单列，不计为发现。无需关注时用一行说明。`gh` 缺失或未认证时，将 PR 锚点标为未核验，继续其他检查。
+`Legacy` 与 `Unverified` 分别单列，不计为发现。`gh` 缺失或未认证时，将 PR 锚点标为未核验，继续其他检查。没有现行记录带发现时明确说明。所有修改都交给 `decision-write`；仅在决策目录或根指针缺失时建议使用 `/setup-project-docs`。

package/dist/skills/authored/decision-audit/references/recover-commit.md

@@ -9,9 +9,9 @@ git show <dead-sha> | git patch-id --stable
 Search plausible replacements within the record's date and scope:
 
 ```bash
-git log --since=<Date> --format=%H -- <Scope paths> |
-  while read -r sha; do git show "$sha" | git patch-id --stable; done |
+git log --since=<Date> --format=%H <base> -- |
+  while read -r sha; do git show "$sha" | git patch-id --stable | awk -v sha="$sha" '{print $1, sha}'; done |
   grep -F "<patch-id>"
 ```
 
-A match supports suggesting the replacement SHA; otherwise leave replacement to a human. Prefer PR anchors in squash-merged repositories.
+Filter each candidate commit's paths with the shared `Scope` matcher before comparing its patch identity. A match supports suggesting the replacement SHA; otherwise leave replacement to a human. Prefer PR anchors in squash-merged repositories.

package/dist/skills/authored/decision-audit/references/recover-commit.zh.md

@@ -9,9 +9,9 @@ git show <dead-sha> | git patch-id --stable
 在记录的日期与范围内搜索可能的替代提交：
 
 ```bash
-git log --since=<Date> --format=%H -- <Scope paths> |
-  while read -r sha; do git show "$sha" | git patch-id --stable; done |
+git log --since=<Date> --format=%H <base> -- |
+  while read -r sha; do git show "$sha" | git patch-id --stable | awk -v sha="$sha" '{print $1, sha}'; done |
   grep -F "<patch-id>"
 ```
 
-命中可支持建议改用替代 SHA；未命中则留给人判断替代项。使用 squash 合并的仓库优先采用 PR 锚点。
+比较 patch 标识前，先用共享 `Scope` 匹配器筛选每个候选提交的路径。命中可支持建议改用替代 SHA；未命中则留给人判断替代项。使用 squash 合并的仓库优先采用 PR 锚点。

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

@@ -1,6 +1,6 @@
 ---
 name: decision-write
-description: Write, update, land, or supersede a decision record. Use for resolved alternatives, missing design rationale, reversed decisions, or any record-file change. Land discovers and verifies the implementation.
+description: Write, update, land, or supersede decision records. Use for resolved alternatives, missing rationale, reversed decisions, or record-file changes. Land finds and verifies the implementation; Review-only updates keep the current status.
 ---
 
 # Write or update a decision record
@@ -13,18 +13,20 @@ Use this procedure for every change to `Status`, `Implemented-by`, `Superseded-b
 
 ## Locate the records
 
-Inspect `docs/decisions/`, `docs/adr/`, and `doc/adr/`:
+Resolve `<dir>` in this order:
 
-- One exists: call it `<dir>`, follow its naming convention, and read its `AGENTS.md` when present.
-- Several exist: ask which is current and wait.
-- None exists: report that this repository keeps no decision records, suggest `/setup-project-docs`, and stop.
+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, follow its naming convention, and read its `AGENTS.md` and `README.md` conventions when present. If several candidates remain, ask which is current and wait. If none exists, report that no decision directory was found, suggest `/setup-project-docs`, and stop.
 
 `AGENTS.md` and `README.md` are conventions, not records; exclude both from searches, classification, and updates.
 
 ## Choose the mode
 
 - **Draft:** no record owns this decision, a new record replaces an old one, or an existing record needs substantive body or relationship updates. Duplicate and overlapping dispositions stay in Draft; explicit status-field updates use Land. Do steps 1–5, present the approval gate in step 6, then write only after confirmation and report with step 7.
-- **Land:** the user explicitly asks to mark an existing record `accepted` or update its status fields. Do steps 4, 5, and 7. A record path plus `accepted` is sufficient input; never enter Land autonomously. Without a path, list records whose `Scope` matches the landed change and ask which to update.
+- **Land:** the user explicitly asks to mark an existing record `accepted` or update its status fields. Read the full target record, then do steps 4, 5, and 7. A record path plus `accepted` is sufficient input; never enter Land autonomously. Without a path, list records whose `Scope` matches the landed change and ask which to update. For a Review-only update, preserve `Status` and `Implemented-by`, skip steps 4 and 5, and report with step 7.
 
 ## 1. Establish the choice
 
@@ -91,13 +93,13 @@ A new record stays `proposed` until it lands. `Implemented-by` identifies the im
 
 For Land without an anchor, or the record-only exception, read [Find and verify the implementation](references/land.md) before editing. For any other proposed anchor, use that reference's verification procedure without its discovery steps.
 
-Resolve `<base>` as the repository's default branch and report the selected ref. Verify every anchor; unavailable evidence or an unresolved base leaves a new record `proposed` + `-`. If an existing `accepted` record's anchor fails verification, stop and report it rather than silently demoting it. Change only fields required by evidence; advancing `Review` alone leaves status unchanged.
+Resolve `<base>` as the repository's default branch and report the selected ref. Verify every anchor. In Draft, unavailable evidence or an unresolved base leaves a new record `proposed` + `-`; in Land, stop and report without editing. If an existing `accepted` record's anchor fails verification, stop and report it rather than silently demoting it. Change only fields required by evidence; advancing `Review` alone leaves status unchanged.
 
 When a new draft replaces an old record, set the old record to `superseded` in the same approved edit set, even when it was `accepted`. Keep its body and anchor, add the cross-link, and write `Superseded-by: <new record path> — <one-line reason>` below `Review`. Ask for a missing reason and wait. A `proposed` old record keeps `Implemented-by: -`.
 
 ## 5. Check scope covers the change
 
-Use caller-supplied `scope` paths when present. For Land with a verified implementing change, list its paths with:
+Use [Match Scope paths](references/scope.md) for every glob/path check, including anchor discovery in Land. Use caller-supplied `scope` paths when present. For Land with a verified implementing change, list its paths with:
 
 ```bash
 gh pr view N --json files --jq '.files[].path'
@@ -119,7 +121,7 @@ For every Draft write, including a Duplicate update, present the complete result
 
 ## 7. Report
 
-Account for every search hit, changed record, relationship, anchor verification, scope match, and unresolved question. A `proposed` record awaiting landing needs a Land update after merge. Name any discovered implementation and its changed paths; mark a record-only anchor as a confirmed exception. Include every `Superseded-by` path and reason.
+When root `AGENTS.md` has no resolving decision pointer for the selected `<dir>`, suggest `/setup-project-docs` to register it. Account for every search hit, changed record, relationship, anchor verification, scope match, and unresolved question. A `proposed` record awaiting landing needs a Land update after merge. Name any discovered implementation and its changed paths; mark a record-only anchor as a confirmed exception. Include every `Superseded-by` path and reason.
 
 ```text
 Record: docs/decisions/2026-10-27-use-postgres.md

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

@@ -1,6 +1,6 @@
 ---
 name: decision-write
-description: 撰写、更新、落地或取代决策记录。用于已定取舍、缺失设计理由、推翻决策或任何记录文件改动；落地模式查找并校验实现。
+description: 撰写、更新、落地或取代决策记录。用于已定取舍、缺失设计理由、推翻决策或记录文件改动；落地模式查找并校验实现，仅更新 `Review` 时保留当前状态。
 ---
 
 # 撰写或更新决策记录
@@ -13,18 +13,20 @@ description: 撰写、更新、落地或取代决策记录。用于已定取舍
 
 ## 定位记录目录
 
-检查 `docs/decisions/`、`docs/adr/` 和 `doc/adr/`：
+按以下顺序定位 `<dir>`：
 
-- 只有一个存在：记为 `<dir>`，沿用其命名约定，并在存在时读取其 `AGENTS.md`。
-- 多个存在：询问哪个是当前目录并等待。
-- 都不存在：说明本仓库不保存决策记录，建议使用 `/setup-project-docs`，然后停止。
+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` 匹配落地改动的记录并询问更新哪一条。
+- **落地：** 用户明确要求把既有记录标为 `accepted` 或更新其状态字段。完整读取目标记录，再执行步骤 4、5、7。记录路径加 `accepted` 就是足够输入；不要自行进入落地。未给出路径时，列出 `Scope` 匹配落地改动的记录并询问更新哪一条。仅更新 `Review` 时保留 `Status` 与 `Implemented-by`，跳过步骤 4、5，执行步骤 7 报告。
 
 ## 1. 确认选择
 
@@ -91,13 +93,13 @@ Superseded-by: <记录路径> — <一句原因>   （仅 Status 为 superseded
 
 落地模式没有给定锚点，或需要“仅记录提交”例外时，编辑前读取[查找并校验实现](references/land.zh.md)。校验其他已有锚点时，只执行该参考中的校验流程，不执行查找步骤。
 
-`<base>` 取仓库默认分支，并报告选中的 ref。校验每个锚点；证据不可用或基线无法解析时，新记录保持 `proposed` + `-`。既有 `accepted` 记录的锚点校验失败时，停下报告，不静默降级。只改证据要求的字段；单独推进 `Review` 不改变状态。
+`<base>` 取仓库默认分支，并报告选中的 ref。校验每个锚点。撰写模式中，证据不可用或基线无法解析时，新记录保持 `proposed` + `-`；落地模式中停止并报告，不编辑记录。既有 `accepted` 记录的锚点校验失败时，停下报告，不静默降级。只改证据要求的字段；单独推进 `Review` 不改变状态。
 
 新草稿取代旧记录时，在同一次获批的修改中把旧记录改为 `superseded`，即使旧记录原为 `accepted`。保留旧正文与锚点，添加互链，并在 `Review` 下方写 `Superseded-by: <新记录路径> — <一句原因>`。原因缺失时先询问并等待。原为 `proposed` 的旧记录保留 `Implemented-by: -`。
 
 ## 5. 检查范围覆盖改动
 
-调用方提供 `scope` 路径时直接使用。带已核验实现改动的落地分支，用以下命令列出实现路径：
+所有 glob/路径检查都使用[匹配 Scope 路径](references/scope.zh.md)，包括落地模式的锚点查找。调用方提供 `scope` 路径时直接使用。带已核验实现改动的落地分支，用以下命令列出实现路径：
 
 ```bash
 gh pr view N --json files --jq '.files[].path'
@@ -119,7 +121,7 @@ git status --porcelain=v1 --untracked-files=all
 
 ## 7. 报告
 
-覆盖每个检索命中、改动的记录、关系判断、锚点校验、范围匹配和未决问题。等待落地的 `proposed` 记录在合并后需要一次“落地”更新。报告查到的实现及其改动路径；仅记录锚点须标明为经确认的例外。包括每个 `Superseded-by` 路径和原因。
+根目录 `AGENTS.md` 没有可解析到所选 `<dir>` 的决策指针时，建议用 `/setup-project-docs` 登记。覆盖每个检索命中、改动的记录、关系判断、锚点校验、范围匹配和未决问题。等待落地的 `proposed` 记录在合并后需要一次“落地”更新。报告查到的实现及其改动路径；仅记录锚点须标明为经确认的例外。包括每个 `Superseded-by` 路径和原因。
 
 ```text
 Record: docs/decisions/2026-10-27-use-postgres.md