dsh-pstack 0.2.0-beta.3 → 0.2.0

package/dist/role-wire-DZwTn2wF.d.mts

@@ -0,0 +1,55 @@
+import "./models.mjs";
+import { n as RoleValueShape } from "./role-manifest-C3fUzjLI.mjs";
+/** Which spelling of "inherit the parent route" a role line uses. */
+type InheritAlias = "inherit-parent" | "auto";
+/** One role value as the configuration page sees it. */
+type RouteView = {
+  readonly kind: "inherit";
+  readonly alias: InheritAlias;
+} | {
+  readonly kind: "route";
+  readonly provider: string;
+  readonly model: string;
+  readonly effort?: string;
+};
+/** One of the 17 roles in manifest order. */
+interface RoleView {
+  readonly key: string;
+  readonly shape: RoleValueShape;
+  /** Whether the role file configures this role. */
+  readonly configured: boolean;
+  /** The winning line, when the role file configures this role. */
+  readonly line?: number;
+  readonly routes: readonly RouteView[];
+  readonly issues: readonly string[];
+}
+/** One file-level problem. Unknown and malformed lines are reported, never dropped. */
+interface RoleFileIssue {
+  readonly line?: number;
+  readonly message: string;
+}
+/** Everything the configuration page renders about `$DSH_HOME/pstack-models.mdc`. */
+interface RoleFileSnapshot {
+  readonly path: string;
+  readonly status: "missing" | "loaded" | "unreadable";
+  readonly reason?: string;
+  readonly budget?: string;
+  readonly roles: readonly RoleView[];
+  readonly issues: readonly RoleFileIssue[];
+  /** False only when the file cannot be read at all. */
+  readonly canSave: boolean;
+}
+/** One role save. List roles carry every route, never only the edited one. */
+interface SaveRoleRequest {
+  readonly key: string;
+  readonly routes: readonly RouteView[];
+}
+/** A refused save leaves the file untouched and names the reason. */
+type SaveRoleResult = {
+  readonly ok: true;
+  readonly snapshot: RoleFileSnapshot;
+} | {
+  readonly ok: false;
+  readonly reason: string;
+};
+export { SaveRoleRequest as n, SaveRoleResult as r, RoleFileSnapshot as t };

package/dist/roles.d.mts

@@ -0,0 +1,18 @@
+import { CatalogueResult } from "./models.mjs";
+import { n as SaveRoleRequest, r as SaveRoleResult, t as RoleFileSnapshot } from "./role-wire-DZwTn2wF.mjs";
+import { Context, Service } from "@deepseek-ai/cordis";
+import { TypertRemoteService } from "@deepseek-ai/dsh-typert-protocol";
+/** Read and write the role file for the Plugins configuration page. */
+export declare class PstackRolesService extends TypertRemoteService {
+  static inject: string[];
+  constructor(ctx: Context);
+  protected [Service.init](): void;
+  /** Current path, status, values, and per-line issues. */
+  status(): RoleFileSnapshot;
+  /** The live directory the page offers for its provider/model/effort selects. */
+  catalogue(signal: AbortSignal): Promise<CatalogueResult>;
+  /** Validate and save one role, then return the reloaded snapshot. */
+  save(request: SaveRoleRequest, signal: AbortSignal): Promise<SaveRoleResult>;
+  private get llm();
+}
+export { PstackRolesService as default };

package/dist/roles.mjs

@@ -0,0 +1,323 @@
+import { collectCatalogue } from "./models.mjs";
+import { REMOTE_PACKAGE, ROLES_SERVICE, pstackRolesRemote } from "./remote.mjs";
+import { a as resolveDshHome, c as ROLE_MANIFEST, l as findRoleSpec, n as normalizeRoleName, r as readRoleConfiguration, s as INHERIT_PARENT_ALIASES, t as modelsFilePath } from "./role-config-NNn5r1JX.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(", ");
+}
+function bodyStart(lines) {
+	if (lines[0]?.trim() !== "---") return 0;
+	for (let index = 1; index < lines.length; index += 1) if (lines[index]?.trim() === "---") return index + 1;
+	return 0;
+}
+/**
+* Replace the winning line for one role, or append one when absent.
+*
+* Every other line is returned verbatim. A role configured twice keeps its
+* earlier line and replaces the last one, which is the line the parser treats
+* as winning; the duplicate remains visible as a per-line issue.
+*/
+function updateRoleText(text, spec, value) {
+	const lines = text.split("\n");
+	const crlf = text.includes("\r\n");
+	if (lines.length > 0 && lines[lines.length - 1] === "") lines.pop();
+	let match = -1;
+	for (let index = bodyStart(lines); index < lines.length; index += 1) {
+		const line = lines[index];
+		const trimmed = line.endsWith("\r") ? line.slice(0, -1).trim() : line.trim();
+		if (trimmed === "" || trimmed.startsWith("#")) continue;
+		const separator = trimmed.indexOf(":");
+		if (separator === -1) continue;
+		if (normalizeRoleName(trimmed.slice(0, separator)) !== spec.key) continue;
+		match = index;
+	}
+	const rendered = `${spec.key}: ${value}`;
+	if (match >= 0) {
+		const original = lines[match];
+		const indent = /^\s*/.exec(original)?.[0] ?? "";
+		const ending = original.endsWith("\r") ? "\r" : "";
+		lines[match] = `${indent}${rendered}${ending}`;
+	} else lines.push(`${rendered}${crlf ? "\r" : ""}`);
+	return `${lines.join("\n")}\n`;
+}
+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/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 锚点。