dsh-pstack 0.2.0-beta.1 → 0.2.0-beta.3

package/dist/skill.mjs

@@ -0,0 +1,183 @@
+import { resolve, sep } from "node:path";
+import { readFile } from "node:fs/promises";
+// src/skill.ts
+/**
+* `pstack_skill`: the trusted skill loader for pstack's own instructions.
+*
+* pstack hides most of its skills from the model catalog: `how`, `why`, `architect`,
+* `arena`, and the principle skills all declare `disable-model-invocation: true`, so
+* `poteto-mode` cannot route to them through DSH's `skill` tool. The registry's
+* `get()` is deliberately usable by trusted callers without that policy, which is the
+* public seam this tool consumes. It accepts a skill name, not a path, so a call can
+* only load a skill the package itself registered.
+*
+* The optional `resource` argument reads one file below the skill's directory. It is a
+* convenience for the references and playbooks that live beside `SKILL.md`; the path is
+* resolved and checked against the skill directory before reading, so `../` cannot
+* escape it.
+*/
+/** Model-facing tool name. */
+const TOOL_NAME = "pstack_skill";
+/** Cordis row name, used by Loader diagnostics. */
+const name = "pstack-skill";
+/** The tool registry and the skill registry. */
+const inject = ["skills", "tools"];
+const SKILL_NAME = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+/** Render one loaded skill in the canonical `<skill_content>` shape. */
+function renderLoadedSkill(result) {
+	const lines = [`<skill_content name="${escapeAttr(result.name)}">`, "<skill_resources>"];
+	if (result.resourceBase === void 0) lines.push(`Resources for this skill are managed by provider "${escapeText(result.provider)}".`, "Load referenced resources only as needed.");
+	else if (result.resourceBase.kind === "directory") lines.push(`Base directory for this skill: ${escapeText(result.resourceBase.path)}`, "Resolve relative paths mentioned by this skill against the base directory before using them. Load referenced resources only as needed.");
+	else if (result.resourceBase.kind === "url") lines.push(`Base URL for this skill: ${escapeText(result.resourceBase.url)}`, "Resolve relative URLs mentioned by this skill against the base URL before using them. Load referenced resources only as needed.");
+	else lines.push(`Resources for this skill: ${escapeText(result.resourceBase.description)}`, "Load referenced resources only as needed.");
+	lines.push("</skill_resources>", "", "<skill_instructions>", result.content, "</skill_instructions>");
+	if (result.resource !== void 0) lines.push("", `<skill_resource path="${escapeAttr(result.resource.path)}">`, result.resource.content, "</skill_resource>");
+	lines.push("</skill_content>");
+	return lines.join("\n");
+}
+function escapeAttr(value) {
+	return value.replaceAll("&", "&amp;").replaceAll("\"", "&quot;").replaceAll("<", "&lt;");
+}
+function escapeText(value) {
+	return value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;");
+}
+/** Read one resource below a directory skill, refusing traversal and absolute paths. */
+async function readSkillResource(definition, resource) {
+	const base = definition.resourceBase;
+	if (base === void 0 || base.kind !== "directory") throw new Error(`skill "${definition.name}" does not expose a directory resource base`);
+	if (resource.trim() === "" || resource.includes("\0")) throw new Error("resource must be a non-empty relative path");
+	if (resource.startsWith("/") || resource.startsWith("\\") || /^[a-zA-Z]:[\\/]/.test(resource)) throw new Error(`resource "${resource}" must be relative to the skill directory`);
+	const root = resolve(base.path);
+	const target = resolve(root, resource);
+	if (target !== root && !target.startsWith(root + sep)) throw new Error(`resource "${resource}" escapes the skill directory`);
+	try {
+		return {
+			path: resource,
+			content: await readFile(target, "utf8")
+		};
+	} catch (error) {
+		const code = error.code;
+		if (code === "ENOENT" || code === "EISDIR") throw new Error(`resource "${resource}" is not available for skill "${definition.name}"`);
+		throw error;
+	}
+}
+const OUTPUT_SCHEMA = {
+	type: "object",
+	additionalProperties: false,
+	properties: {
+		name: { type: "string" },
+		provider: { type: "string" },
+		resourceBase: { oneOf: [
+			{
+				type: "object",
+				additionalProperties: false,
+				properties: {
+					kind: {
+						type: "string",
+						const: "directory"
+					},
+					path: { type: "string" }
+				},
+				required: ["kind", "path"]
+			},
+			{
+				type: "object",
+				additionalProperties: false,
+				properties: {
+					kind: {
+						type: "string",
+						const: "url"
+					},
+					url: { type: "string" }
+				},
+				required: ["kind", "url"]
+			},
+			{
+				type: "object",
+				additionalProperties: false,
+				properties: {
+					kind: {
+						type: "string",
+						const: "opaque"
+					},
+					description: { type: "string" }
+				},
+				required: ["kind", "description"]
+			}
+		] },
+		content: { type: "string" },
+		resource: {
+			type: "object",
+			additionalProperties: false,
+			properties: {
+				path: { type: "string" },
+				content: { type: "string" }
+			},
+			required: ["path", "content"]
+		}
+	},
+	required: [
+		"name",
+		"provider",
+		"content"
+	]
+};
+const TOOL_DESCRIPTION = [
+	"Load the full instructions of any pstack skill by name, including skills hidden from the model catalog.",
+	"",
+	"Use this when a pstack skill tells you to route through another pstack skill (for example how, why, or architect) and the `skill` tool reports that it is unavailable because the skill disables model invocation.",
+	"",
+	"Pass `resource` with a path relative to the skill directory to read one reference or playbook beside its SKILL.md. The path cannot leave the skill directory."
+].join("\n");
+/** Build the tool definition. Exported so tests can drive `execute` directly. */
+function createPstackSkillTool(skills) {
+	return {
+		name: TOOL_NAME,
+		description: TOOL_DESCRIPTION,
+		parameters: {
+			type: "object",
+			additionalProperties: false,
+			properties: {
+				name: {
+					type: "string",
+					description: "Exact kebab-case skill name, such as `how` or `principle-prove-it-works`."
+				},
+				resource: {
+					type: "string",
+					description: "Optional path relative to the skill directory, such as `references/explorer-prompt.md`."
+				}
+			},
+			required: ["name"]
+		},
+		output: {
+			schema: OUTPUT_SCHEMA,
+			render: (_args, value) => [{
+				type: "text",
+				text: renderLoadedSkill(value)
+			}]
+		},
+		isConcurrencySafe: () => true,
+		async execute(rawArgs, exec) {
+			const args = rawArgs;
+			if (typeof args.name !== "string" || !SKILL_NAME.test(args.name)) throw new Error(`invalid skill name "${String(args.name)}"`);
+			if (args.resource !== void 0 && typeof args.resource !== "string") throw new Error("resource must be a string when present");
+			const definition = await skills.get(args.name, {
+				signal: exec.signal,
+				...exec.agent === void 0 ? {} : { scope: exec.agent }
+			});
+			if (definition === void 0) throw new Error(`skill "${args.name}" is unknown or no longer available`);
+			return {
+				name: definition.name,
+				provider: definition.provider,
+				...definition.resourceBase === void 0 ? {} : { resourceBase: definition.resourceBase },
+				content: definition.content,
+				...args.resource === void 0 ? {} : { resource: await readSkillResource(definition, args.resource) }
+			};
+		}
+	};
+}
+/** Register `pstack_skill` on one row. */
+function apply(ctx) {
+	ctx.tools.register(createPstackSkillTool(ctx.skills));
+}
+export { TOOL_NAME, apply, createPstackSkillTool, inject, name, readSkillResource, renderLoadedSkill };

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

@@ -0,0 +1,99 @@
+---
+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.
+disable-model-invocation: true
+---
+
+# Audit decision records
+
+Produce a read-only report of records needing human attention, without judging whether code still honors a decision. Cite each finding with its command and observed output; leave every edit to `decision-write`.
+
+## 1. Resolve the inputs
+
+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.
+
+Inspect `docs/decisions/`, `docs/adr/`, and `doc/adr/`:
+
+- 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.
+
+## 2. Collect the evidence
+
+When `scope` is absent, compute the change set:
+
+```bash
+# pr
+git diff --name-only "$(git merge-base HEAD <base>)"..HEAD
+
+# local: base-relative commits plus the working tree and index
+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.
+
+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.
+
+## 3. Apply all six checks
+
+**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.
+
+**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 |
+
+For `proposed`, `-` or a pending anchor is not a finding; 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.
+
+**C — Broken anchor.** For each non-`superseded` `Implemented-by` value, classify it with evidence:
+
+| Value | Verification | Result |
+|---|---|---|
+| `-` or missing | None | Pending |
+| `PR #N` | `gh pr view N --json state,files` | `MERGED`: continue below; `OPEN`: pending; `CLOSED`: C; otherwise: unverified |
+| `commit:SHA` | `git merge-base --is-ancestor SHA <base>` | Exit 0: continue below; exit 1: C; otherwise: unverified |
+| Any value | Command unavailable, authentication fails, or object cannot be read | Unverified |
+
+For a landed PR or ancestral commit, list its paths with `gh pr view N --json files --jq '.files[].path'` or `git show --pretty=format: --name-only SHA`. `Verified` requires a path matching `Scope` and at least one path outside `<dir>`; otherwise report C with the path evidence.
+
+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:
+
+```bash
+date +%F
+git log --since=<Date> --oneline -- <Scope paths>
+```
+
+Include the count and latest subject when present; 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.
+
+## 4. Report and trim
+
+Account for every current record as pending, clean, unverified, or carrying one or more findings. Order findings `C`, `B`, `B′`, `E`, `D`, `A`; within each class, put more matched files first.
+
+- `pr`: at most 15 findings, followed by the omitted count.
+- `local`: at most 8 findings, including at most 3 class-A findings.
+- `full`: no trimming; report every class count, including zeroes.
+
+Use this structure for findings; include `Evidence` for every class:
+
+```text
+[C] Decision title
+  Record: docs/decisions/2026-08-14-use-postgres.md
+  Basis: commit:3f9a1c2 is not in history
+  Evidence: git merge-base --is-ancestor 3f9a1c2 origin/main -> exit 1
+  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.

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

@@ -0,0 +1,99 @@
+---
+name: decision-audit
+description: 按改动集合或整个仓库审计决策记录，报告路由、状态、范围、锚点、取代与复核发现，并附命令证据。
+disable-model-invocation: true
+---
+
+# 审计决策记录
+
+以只读方式报告需要人工关注的记录，不判断代码是否仍符合决策。每项发现都附上支持它的命令与实际输出；所有修改交给 `decision-write`。
+
+## 1. 确定输入
+
+接受 `mode`（`pr`、`local` 或 `full`，默认 `pr`）、可选的 `base`，以及用于替代计算所得改动集合的可选 `scope` 路径。
+
+`pr` 解析 PR 基线，其他模式先尝试 `origin/main`。不存在时依次尝试 `origin/master`、`main`、`master`、最新 tag、`HEAD~20`。报告实际选中的 ref；全部无法解析时停止并列出每个尝试过的 ref。
+
+检查 `docs/decisions/`、`docs/adr/` 和 `doc/adr/`：
+
+- 只有一个存在：记为 `<dir>` 并报告路径。
+- 多个存在：询问哪个是当前目录并等待。
+- 都不存在或没有记录：报告这一正常结果并停止。
+
+## 2. 收集证据
+
+未提供 `scope` 时计算改动集合：
+
+```bash
+# pr
+git diff --name-only "$(git merge-base HEAD <base>)"..HEAD
+
+# local：相对基线的提交，加上工作区与暂存区
+git diff --name-only "$(git merge-base HEAD <base>)"..HEAD
+git status --porcelain=v1 --untracked-files=all
+```
+
+解析 `git status` 中的路径，重命名取目标路径。`full` 使用所有受 Git 跟踪的文件。从计算结果中剔除锁文件、生成文件、快照和纯资源文件；记录这些排除项与最终集合。
+
+存在 `<dir>/AGENTS.md` 和 `<dir>/README.md` 时读取；它们是约定而非记录。将其约定应用到其他所有 `*.md`。读取每条记录至第一个 `## ` 标题并解析头部。缺少 `Status`、`Date`、`Scope`、`Implemented-by`、`Review` 中任一项的记录单列为 `Legacy`，不参与以下六项检查。
+
+对每条现行记录执行所有适用的检查；同一记录可以产生多项发现。
+
+## 3. 执行全部六项检查
+
+**A——路由。** 对每条非 `superseded` 且 `Scope` 匹配改动集合的记录，用一行报告标题、路径、匹配路径及改动集合证据。
+
+**B——状态成对。** 使用下方的锚点结果，报告每个匹配行：
+
+| Status | 锚点结果 | 发现 |
+|---|---|---|
+| `proposed` | 已核验 | 应改为 `accepted` |
+| `accepted` | `-`、缺失、待落地或未核验 | 落地状态缺少已核验证据 |
+
+`proposed` 带 `-` 或待落地锚点不是发现；带未核验锚点时归入 `Unverified`，不归入 B 或 C。
+
+**B′——范围失效。** 对 `Scope` 中所有 glob 都不匹配现存文件的每条 `accepted` 记录，报告路径与 glob 检查证据，并询问是决策已过时还是范围写错。
+
+**C——锚点断裂。** 对每条非 `superseded` 记录的每个 `Implemented-by` 值，按证据分类：
+
+| 值 | 校验 | 结果 |
+|---|---|---|
+| `-` 或缺失 | 无 | 待落地 |
+| `PR #N` | `gh pr view N --json state,files` | `MERGED`：继续下方检查；`OPEN`：待落地；`CLOSED`：C；其他：未核验 |
+| `commit:SHA` | `git merge-base --is-ancestor SHA <base>` | 退出码 0：继续下方检查；1：C；其他：未核验 |
+| 任意值 | 命令不可用、认证失败或对象无法读取 | 未核验 |
+
+对已合并 PR 或祖先提交，用 `gh pr view N --json files --jq '.files[].path'` 或 `git show --pretty=format: --name-only SHA` 列出路径。“已核验”要求至少一个路径匹配 `Scope`，且至少一个路径在 `<dir>` 之外；否则附路径证据报告 C。
+
+报告提交丢失前，读取[恢复被改写的提交](references/recover-commit.zh.md)；只要其对象仍可用，就尝试恢复 patch 标识。
+
+**D——复核逾期。** 仅在 `full` 模式，报告 `Review` 日期早于当前日期的每条记录，并收集决策日期以来的改动：
+
+```bash
+date +%F
+git log --since=<Date> --oneline -- <Scope paths>
+```
+
+附上提交数量和最新主题（如有），建议人工复核并更新 `Review` 日期。
+
+**E——取代记录。** 对每条现行 `superseded` 记录，在 `Superseded-by` 缺失、无法解析到 `<dir>` 内的记录，或没有 ` — <原因>` 文本时报告。建议补上替代记录路径和一句原因。
+
+## 4. 报告与裁剪
+
+每条现行记录都必须归为待落地、无发现、未核验，或带一项或多项发现。按 `C`、`B`、`B′`、`E`、`D`、`A` 排列；同类中匹配文件更多的在前。
+
+- `pr`：最多 15 项，随后给出省略数量。
+- `local`：最多 8 项，其中 A 类最多 3 项。
+- `full`：不裁剪，报告每类计数，包括零。
+
+各项发现使用以下结构；每一类都要包含 `Evidence`：
+
+```text
+[C] Decision title
+  Record: docs/decisions/2026-08-14-use-postgres.md
+  Basis: commit:3f9a1c2 is not in history
+  Evidence: git merge-base --is-ancestor 3f9a1c2 origin/main -> exit 1
+  Suggest: replace the anchor with commit:8ff9f762 (matching patch-id d064e03f4e53)
+```
+
+`Legacy` 与 `Unverified` 分别单列，不计为发现。无需关注时用一行说明。`gh` 缺失或未认证时，将 PR 锚点标为未核验，继续其他检查。

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

@@ -0,0 +1,17 @@
+# Recover a rewritten commit
+
+When an `Implemented-by: commit:SHA` is outside `<base>` but its object remains available, recover its patch identity before reporting it as lost:
+
+```bash
+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 |
+  grep -F "<patch-id>"
+```
+
+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

@@ -0,0 +1,17 @@
+# 恢复被改写的提交
+
+`Implemented-by: commit:SHA` 不在 `<base>` 中、但其对象仍可用时，先恢复 patch 标识，再报告提交丢失：
+
+```bash
+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 |
+  grep -F "<patch-id>"
+```
+
+命中可支持建议改用替代 SHA；未命中则留给人判断替代项。使用 squash 合并的仓库优先采用 PR 锚点。

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

@@ -0,0 +1,131 @@
+---
+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.
+---
+
+# Write or update a decision record
+
+Deliver one settled choice as a verified record and evidence report. All record edits go through this skill; `decision-audit` only reports.
+
+## Entry rule
+
+Use this procedure for every change to `Status`, `Implemented-by`, `Superseded-by`, `Review`, body, or links. If it cannot run, stop and report; this rule overrides `<dir>/AGENTS.md` conventions permitting direct edits.
+
+## Locate the records
+
+Inspect `docs/decisions/`, `docs/adr/`, and `doc/adr/`:
+
+- 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.
+
+`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.
+
+## 1. Establish the choice
+
+Obtain all three from the change and discussion; ask only about missing items and wait:
+
+- **Goal:** the problem this decision answers.
+- **Constraint:** the boundary that eliminates an option.
+- **Alternative:** an option actually rejected, or the explicit fact that only one candidate was considered.
+
+## 2. Find related records
+
+Search for distinctive terms from the topic, affected modules, and alternatives:
+
+```bash
+grep -ril --exclude=AGENTS.md --exclude=README.md \
+  -e "<keyword-1>" -e "<keyword-2>" <dir>/*.md
+```
+
+Read each hit through its first `## ` heading; read the body only when the header cannot distinguish its disposition or cannot supply the content needed for an update. Tighten broad searches rather than reading the whole directory. Classify every hit:
+
+- **Duplicate:** the existing record owns this decision. Update it instead of writing a second one.
+- **Replaced:** draft the new record and cross-link both records. Include the old record's supersession in the approval gate.
+- **Overlapping:** keep both, cross-link them, and reconcile changed facts.
+- **Unrelated:** leave it unchanged.
+- **Unresolved:** carry the relationship and human question into the report.
+
+This step is complete when every hit has a disposition and every resulting edit is explicit.
+
+## 3. Draft the record
+
+Follow `<dir>/AGENTS.md`, including heading language. In its absence, use:
+
+```markdown
+# Decision: <one-line title>
+
+Status: proposed | accepted | superseded
+Date: YYYY-MM-DD
+Scope: <glob>[, <glob>...]
+Implemented-by: <PR #N | commit:SHA | ->
+Review: YYYY-MM-DD
+Superseded-by: <record path> — <one-line reason>   (only when Status is superseded)
+
+## Background
+## Decision
+## Alternatives
+## Consequences
+```
+
+Write `Background` independently of the chosen solution. For an accepted record, write `Decision` in the present tense. Give every considered alternative its own paragraph and rejection reason; when there was only one candidate, state that fact.
+
+## 4. Set status and verify the anchor
+
+`Status` and `Implemented-by` are one pair. Select the row supported by evidence and write both fields together:
+
+| Evidence | Status | Implemented-by |
+|---|---|---|
+| No verified landing anchor | `proposed` | `-` |
+| `PR #N` is `MERGED` | `accepted` | `PR #N` |
+| `commit:SHA` is an ancestor of the default branch | `accepted` | `commit:SHA` |
+| Confirmed record-only exception | `accepted` | `commit:<record-commit>` |
+| Replaced by a newer draft | `superseded` | Keep the existing value |
+
+A new record stays `proposed` until it lands. `Implemented-by` identifies the implementing change, including an earlier implementation for a retrospective record; a record-only commit requires the confirmed exception. Prefer a merged PR in a squash-merged repository.
+
+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.
+
+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:
+
+```bash
+gh pr view N --json files --jq '.files[].path'
+git show --pretty=format: --name-only SHA
+```
+
+For the confirmed record-only fallback, skip this check and report the exception. For every other mode, collect base-relative commits and uncommitted changes:
+
+```bash
+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. Require each new or updated record to match at least one selected path to a `Scope` glob. When none matches, ask whether to widen the glob or omit the record. Record matched paths for the report.
+
+## 6. Draft approval gate
+
+For every Draft write, including a Duplicate update, present the complete resulting content of every new or updated record and every related-record disposition. Include each proposed supersession with its `Superseded-by` path and reason. Request explicit confirmation and wait. After confirmation, apply exactly the approved edits; a declined draft leaves every file unchanged.
+
+## 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.
+
+```text
+Record: docs/decisions/2026-10-27-use-postgres.md
+Status: accepted
+Related: 2026-03-02-mysql-setup.md -> overlapping, cross-linked
+Anchor: PR #412 -> MERGED (gh pr view 412 --json state,files)
+Scope: src/db/** matched src/db/client.ts
+Open: none
+```