dsh-pstack 0.2.0-beta.1 → 0.2.0

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,103 @@
+---
+name: decision-audit
+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
+---
+
+# 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. 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`.
+
+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/`.
+
+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
+
+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. 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.
+
+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.
+
+## 3. Run the checks
+
+Apply A, B, B′, and D only to non-`superseded` records; apply C and E as specified below.
+
+**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` | `-` or missing | Landing lacks verified evidence |
+
+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.
+
+**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 matching changes since the decision date:
+
+```bash
+date +%F
+git log --since=<Date> --format=%H <base> --
+```
+
+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.
+
+## 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. 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

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

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 <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>"
+```
+
+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

@@ -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 <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>"
+```
+
+比较 patch 标识前，先用共享 `Scope` 匹配器筛选每个候选提交的路径。命中可支持建议改用替代 SHA；未命中则留给人判断替代项。使用 squash 合并的仓库优先采用 PR 锚点。

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

@@ -0,0 +1,133 @@
+---
+name: decision-write
+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
+
+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
+
+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, 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. 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
+
+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. 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 [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'
+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
+
+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
+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
+```