dsh-gate-agent 0.1.4 → 0.1.6

package/README.md

@@ -72,7 +72,7 @@ Host 插件：用 phase/node 门禁组织讨论、规划、实施、评审、验
 | `reviewing/code-review-standalone` | 单独只读 code review | review worker；`gate-code-review` |
 | `reviewing/proposal-review` | 单独提案评审 | review worker；`gate-plan-review` |
 | `reviewing/verify-standalone` | 单独只读验收 | verify worker；`gate-user-verify` |
-| `docs` | 文档治理 | root；不调用 gate 技能 |
+| `docs` | 文档治理 | root；按项目文档规范处理 |
 | `blocked` | 冻结写入/派 worker，等待用户决定 | root；`/gate-resume` |
 | `complete` | 工作完成 | root；可重新进入 plan/implement |
 
@@ -111,7 +111,8 @@ Host 插件：用 phase/node 门禁组织讨论、规划、实施、评审、验
 | `/gate-init` | 无 | 初始化 notes、AGENTS.md、`verify-notes`、CI、git 与基础 `.gitignore`，保持 `discuss` |
 | `/gate-enter-plan [具体工作事项或上下文语义]` | 可选 | 基于讨论共识、既有决策与用户输入进入 `orchestrating/plan` |
 | `/gate-enter-implement [具体工作事项或上下文语义]` | 可选 | 基于已确认计划或讨论后的实施说明进入 `orchestrating/implement` |
-| `/gate-docs` | 无 | 进入文档治理，按项目文档规范处理 |
+| `/gate-prd [主题或上下文语义]` | 可选 | 用户级创建/更新 PRD；仅 discuss |
+| `/gate-docs [文档范围或上下文语义]` | 可选 | 进入文档治理，按项目文档规范处理 |
 | `/gate-implement-review [具体工作事项或上下文语义]` | 可选 | 对当前改动做独立只读 code review，只输出 findings |
 | `/gate-code-verify [具体工作事项或上下文语义]` | 可选 | 对当前改动做独立只读验收（gate-user-verify） |
 | `/gate-fix-bug [具体工作事项或上下文语义]` | 可选 | 基于描述或当前上下文派 fix worker 修复已授权缺陷 |
@@ -152,6 +153,36 @@ Host 插件：用 phase/node 门禁组织讨论、规划、实施、评审、验
 
 从 `discuss` 开始，不进入 planning/implement。
 
+初始化会生成：
+
+- `.agents/gate/verify-notes.mjs`
+- `.agents/gate/ci/*.ts`
+- `.agents/gate/artifact-policy.json`
+- `.agents/gate/init-manifest.json`
+
+`init-manifest.json` 记录生成物 hash、artifact-policy hash、AGENTS managed block、verify-notes script 和 notes 目录结构。它被 git 跟踪；同内容重跑 init 时字节稳定。
+
+只读核对：
+
+```text
+gate_init_verify
+```
+
+它会检查：
+
+- 5 个 CI 脚本 + launcher 的 SHA-256；
+- `artifact-policy.json` 的 schema；用户修改后有效则显示 `customized`；
+- AGENTS managed block；
+- `scripts.verify-notes`；
+- workflow 是否存在；
+- notes 四目录结构。
+
+不检查 Note 内容；Note 内容继续用：
+
+```text
+npm run verify-notes
+```
+
 ### Planning
 
 ```text
@@ -245,7 +276,7 @@ review worker 使用 `gate-plan-review` 做 Standards/Spec/Architecture 三轴
 /gate-docs
 ```
 
-进入 `docs` phase，不调用 gate 技能；由主代理按项目文档规范处理。
+进入 `docs` phase，由主代理按项目文档规范处理。
 
 ### 暂停、恢复与讨论
 
@@ -306,6 +337,28 @@ gate_record({
 gate_status()
 ```
 
+### gate_artifact_write
+
+按 `.agents/gate/artifact-policy.json` 写白名单 artifact；只写文件，不走普通 workspace write。支持精确文件、目录和 glob。
+
+### gate_research_dispatch
+
+root-only；在 discuss 或 `orchestrating/plan` 派 research worker。worker 只能通过 artifact policy 写 research 文档，不获得通用 workspace 写。
+
+### gate_init_verify
+
+root-only 只读校验 `/gate-init` 产物：
+
+- `.agents/gate/init-manifest.json` 是否存在且有效；
+- 5 个 CI 脚本 + `verify-notes.mjs` 的 hash；
+- `artifact-policy.json` schema（custom 有效也通过）；
+- AGENTS managed block；
+- `scripts.verify-notes`；
+- workflow 存在性；
+- notes 四目录。
+
+不修改文件，不运行 `verify-notes`；Note 内容校验仍用 `npm run verify-notes`。
+
 ### Note 工具
 
 - `gate_note_write`：planning worker 写 proposed Note，或原地更新 implemented Note；通用 `write`/`edit`/`apply_patch` 和仓库写被拒绝，只读 shell 可用。
@@ -334,7 +387,183 @@ gate_status()
 
 ## 配置
 
-插件 Config：
+### artifact-policy.json
+
+discuss 和 plan 默认不允许普通文件写。`handoff`、PRD、research 等产物通过**独立的 artifact 白名单**写入，而不是放开通用 `write`。
+
+`/gate-init` 会创建：
+
+```text
+.agents/gate/artifact-policy.json
+```
+
+- 文件不存在时写入基础配置；
+- 文件已存在时**不覆盖**，保留用户内容；
+- 新建 `.gitignore` 时包含 `.scratch/`；已有 `.gitignore` 不重写。
+
+#### 基础配置
+
+```json
+{
+  "version": 1,
+  "artifacts": {
+    "handoff": {
+      "phases": ["*"],
+      "roles": ["root"],
+      "paths": [".scratch/handoff/**"]
+    },
+    "prd": {
+      "phases": ["discuss"],
+      "roles": ["root"],
+      "paths": ["docs/prd/**", ".scratch/prd/**"]
+    },
+    "research": {
+      "phases": ["discuss", "orchestrating/plan"],
+      "roles": ["root", "worker"],
+      "paths": ["docs/research/**", ".scratch/research/**"]
+    }
+  }
+}
+```
+
+#### 字段
+
+| 字段 | 说明 |
+|---|---|
+| `version` | 必须为 `1` |
+| `artifacts` | artifact kind 到规则的映射 |
+| `kind` | 内置 `handoff`、`prd`、`research`；也可以增加自定义 kind |
+| `phases` | 允许的 canonical phase/node key，或 `*` |
+| `roles` | `root` 或 `worker` |
+| `paths` | 相对 workspace 的文件、目录或 glob |
+
+#### phases
+
+使用 `gate_status` 返回的 `methodologyKey` 形式：
+
+- `discuss`
+- `docs`
+- `complete`
+- `orchestrating/plan`
+- `orchestrating/plan-review`
+- `orchestrating/plan-revise`
+- `orchestrating/implement`
+- `orchestrating/code-review`
+- `orchestrating/implement-revise`
+- `orchestrating/verify`
+- `orchestrating/note-lifecycle`
+- `orchestrating/fix-bug`
+- `reviewing/code-review-standalone`
+- `reviewing/proposal-review`
+- `reviewing/verify-standalone`
+
+`*` 表示任意**非 blocked** 状态。`blocked` 始终拒绝，即使规则写了 `*`。
+
+#### roles
+
+- `root`：主代理；
+- `worker`：任何 gate worker，包括 planning worker 和 research worker。
+
+#### paths
+
+支持四种形式：
+
+```json
+"paths": [
+  "docs/prd/current.md",
+  "docs/prd/PRD-*.md",
+  ".scratch/research/**/*.md",
+  ".scratch/handoff/**"
+]
+```
+
+| 形式 | 含义 |
+|---|---|
+| `docs/prd/current.md` | 只允许这个文件 |
+| `docs/prd/*.md` | 只允许该目录下直接文件，不递归 |
+| `.scratch/research/**/*.md` | 递归匹配 Markdown |
+| `.scratch/handoff/**` | 允许该目录下任意层级文件 |
+| `docs/prd/**` | 允许该目录下任意层级文件 |
+
+规则：
+
+- `*` 只匹配一个路径段；
+- `**` 匹配零个或多个路径段；
+- 普通路径没有通配符时按**明确文件**处理；
+- 不允许绝对路径、`..`、workspace 外路径、symlink；
+- 保留路径永远拒绝：
+  - `.agents/gate/artifact-policy.json`
+  - `.agents/notes/**`
+- 只写文件；父目录可以由工具创建，但也要通过边界检查。
+
+#### 如何按项目填写
+
+只允许一个固定 PRD 文件：
+
+```json
+{
+  "version": 1,
+  "artifacts": {
+    "prd": {
+      "phases": ["discuss"],
+      "roles": ["root"],
+      "paths": ["docs/prd/current.md"]
+    }
+  }
+}
+```
+
+允许按命名规则新建多个 PRD：
+
+```json
+{
+  "version": 1,
+  "artifacts": {
+    "prd": {
+      "phases": ["discuss"],
+      "roles": ["root"],
+      "paths": ["docs/prd/PRD-*.md"]
+    }
+  }
+}
+```
+
+允许 research 在 discuss 和 plan 写文档目录：
+
+```json
+{
+  "version": 1,
+  "artifacts": {
+    "research": {
+      "phases": ["discuss", "orchestrating/plan"],
+      "roles": ["root", "worker"],
+      "paths": ["docs/research/**/*.md", ".scratch/research/**"]
+    }
+  }
+}
+```
+
+#### 相关工具与命令
+
+- `gate_artifact_write({ kind, path, content })`：root/worker 按 policy 写文件；
+- `gate_research_dispatch({ question, purpose? })`：root-only，在 discuss/plan 派 research worker；
+- `/gate-prd [主题]`：discuss 用户命令，加载 `gate-prd` skill 并通过 artifact policy 写 PRD；
+- `gate-handoff`：用户级 skill，产物写入 `.scratch/handoff/`。
+
+普通 `write`/`edit`/`apply_patch`/写型 shell 不受 artifact policy 放行，仍按 phase/role 矩阵处理。
+
+#### 常见失败
+
+| 错误 | 原因 |
+|---|---|
+| `artifact-policy-invalid` | policy 缺失、JSON 无效、version 不是 1、字段非法 |
+| `artifact-denied` | kind 不存在、phase 不匹配、role 不匹配、path 不在白名单、blocked、保留路径、越界或 symlink |
+| `subagents-unavailable` | research dispatch 时 `ctx.subagents` 不可用 |
+| `wrong-phase` | research dispatch 不在 discuss 或 `orchestrating/plan` |
+
+修改 policy 后不需要重启 DSH；每次 artifact 写入都会重新读取文件。
+
+### 插件 Config
 
 ```json
 { "reviewLimit": 5 }
@@ -342,6 +571,28 @@ gate_status()
 
 `reviewLimit` 是每个 review 节点的最大轮次；默认 5，范围 1–20。达到上限仍有 findings 时进入 blocked。
 
+它**不是项目文件**，而是 DSH profile 的插件 Config。当前 profile 的覆盖文件是：
+
+```text
+%USERPROFILE%\.dsh\profiles\<profile>\cordis.patch.yml
+```
+
+在 profile patch 中按 bundle 的 `id: gate` 覆盖：
+
+```yaml
+- id: gate
+  config:
+    reviewLimit: 8
+```
+
+- 没有 `gate` 条目时使用默认值 5；
+- 修改后重启 DSH 才生效；
+- 不要修改 `packages/gate/cordis.patch.yml` 来配置已有 profile；那是 bundle 默认层，profile patch 会覆盖它；
+- 如果使用自定义 Agent Preset，配置应放在该 preset 中对应的 `dsh-gate-agent` 条目。
+
+`.agents/gate/artifact-policy.json` 是项目级 artifact 白名单，与这里的插件 Config 是两套配置。
+
+
 ## 使用边界
 
 - gate 是流程门禁，不是 OS 安全边界；未知工具和任意 shell 语义不会被完整分析。

package/lib/index.js

@@ -126,7 +126,7 @@ var FIX_BUG_ORCHESTRATION = `## /gate-fix-bug \u7F16\u6392
 ## Step 4 \u2014 Record
 \u5B8C\u6210\u540E\u8C03 gate_record({node:'fix-bug', workerSessionIds})\uFF0CworkerSessionIds \u5305\u542B fix \u4E0E review worker\uFF1Bgate \u4E0D\u518D\u81EA\u52A8\u63D0\u4EA4\u3002`;
 var DOCS_ORCHESTRATION = `## /gate-docs \u7F16\u6392
-\u4E0D\u52A0\u8F7D gate \u6280\u80FD\uFF1B\u8303\u56F4\u7531\u6A21\u578B\u6309\u9879\u76EE\u5B9E\u9645\u6587\u6863\u9700\u8981\u5224\u65AD\u3002
+\u8303\u56F4\u7531\u6A21\u578B\u6309\u9879\u76EE\u5B9E\u9645\u6587\u6863\u9700\u8981\u5224\u65AD\u3002
 \u5B8C\u6210\u540E\u8C03 gate_record({node:'docs'}) \u56DE\u5230 discuss\u3002`;
 var NOTE_LIFECYCLE_ORCHESTRATION = `## Note lifecycle
 Verify \u5DF2 PASS\uFF1B\u5F53\u524D\u4E0D\u6D3E worker\uFF0C\u4E5F\u4E0D\u5199\u4E1A\u52A1\u4EE3\u7801\u3002
@@ -1365,7 +1365,7 @@ function installRestrictions(ctx, deps) {
 }
 
 // src/commands.ts
-import path9 from "node:path";
+import path11 from "node:path";
 
 // src/notes/provision.ts
 import { copyFileSync, existsSync as existsSync3, mkdirSync as mkdirSync3, readFileSync as readFileSync2, writeFileSync as writeFileSync3 } from "node:fs";
@@ -1439,6 +1439,7 @@ var BASE_GITIGNORE = `node_modules/
 Thumbs.db
 coverage/
 dist/
+.scratch/
 .agents/notes/.gate-finalize-*
 .agents/notes/.gate-validate-*
 .agents/notes/*.gate-backup
@@ -1486,16 +1487,331 @@ function provisionCi(root) {
   return { workflow: path8.relative(root, workflow).replaceAll("\\", "/"), scripts: path8.relative(root, ciDir).replaceAll("\\", "/"), changed: !existing };
 }
 
+// src/artifacts/policy.ts
+import { existsSync as existsSync4, lstatSync as lstatSync4, mkdirSync as mkdirSync4, readFileSync as readFileSync3, writeFileSync as writeFileSync4 } from "node:fs";
+import path9 from "node:path";
+var ARTIFACT_POLICY_PATH = ".agents/gate/artifact-policy.json";
+var BASE_ARTIFACT_POLICY = {
+  version: 1,
+  artifacts: {
+    handoff: { phases: ["*"], roles: ["root"], paths: [".scratch/handoff/**"] },
+    prd: { phases: ["discuss"], roles: ["root"], paths: ["docs/prd/**", ".scratch/prd/**"] },
+    research: {
+      phases: ["discuss", "orchestrating/plan"],
+      roles: ["root", "worker"],
+      paths: ["docs/research/**", ".scratch/research/**"]
+    }
+  }
+};
+var PHASES2 = new Set(METHODOLOGY_KEYS);
+var RESERVED = [".agents/gate/artifact-policy.json", ".agents/notes/"];
+function normalizeArtifactPath(value) {
+  return path9.posix.normalize(String(value).replaceAll("\\", "/").replace(/^\.\//u, ""));
+}
+function isReservedPath(value) {
+  const normalized = value.toLowerCase();
+  return RESERVED.some((prefix) => normalized === prefix || normalized.startsWith(prefix.endsWith("/") ? prefix : `${prefix}/`));
+}
+function artifactPolicyText(policy = BASE_ARTIFACT_POLICY) {
+  return `${JSON.stringify(policy, null, 2)}
+`;
+}
+function provisionArtifactPolicy(root) {
+  const file = path9.join(root, ARTIFACT_POLICY_PATH);
+  if (pathHasSymlink(root, file)) throw new Error("artifact policy \u8DEF\u5F84\u5305\u542B symlink");
+  mkdirSync4(path9.dirname(file), { recursive: true });
+  if (existsSync4(file)) return { path: ARTIFACT_POLICY_PATH, status: "existing" };
+  writeFileSync4(file, artifactPolicyText());
+  return { path: ARTIFACT_POLICY_PATH, status: "created" };
+}
+function parseArtifactPolicy(value) {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) return { error: "artifact policy \u5FC5\u987B\u662F\u5BF9\u8C61" };
+  const source = value;
+  if (source.version !== 1) return { error: "artifact policy version \u5FC5\u987B\u4E3A 1" };
+  if (source.artifacts === null || typeof source.artifacts !== "object" || Array.isArray(source.artifacts)) {
+    return { error: "artifact policy artifacts \u5FC5\u987B\u662F\u5BF9\u8C61" };
+  }
+  for (const key of Object.keys(source)) {
+    if (key !== "version" && key !== "artifacts") return { error: `artifact policy \u672A\u77E5\u5B57\u6BB5\uFF1A${key}` };
+  }
+  const artifacts = {};
+  for (const [kind, raw] of Object.entries(source.artifacts)) {
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw)) return { error: `artifact ${kind} \u5FC5\u987B\u662F\u5BF9\u8C61` };
+    const rule = raw;
+    for (const key of Object.keys(rule)) {
+      if (key !== "phases" && key !== "roles" && key !== "paths") return { error: `artifact ${kind} \u672A\u77E5\u5B57\u6BB5\uFF1A${key}` };
+    }
+    if (!Array.isArray(rule.phases) || rule.phases.length === 0 || !rule.phases.every((phase) => phase === "*" || typeof phase === "string" && PHASES2.has(phase))) {
+      return { error: `artifact ${kind} phases \u975E\u6CD5` };
+    }
+    if (!Array.isArray(rule.roles) || rule.roles.length === 0 || !rule.roles.every((role) => role === "root" || role === "worker")) {
+      return { error: `artifact ${kind} roles \u975E\u6CD5` };
+    }
+    if (!Array.isArray(rule.paths) || rule.paths.length === 0) return { error: `artifact ${kind} paths \u975E\u6CD5` };
+    const paths = [];
+    for (const item of rule.paths) {
+      if (typeof item !== "string" || item.trim() === "") return { error: `artifact ${kind} path \u975E\u6CD5` };
+      const normalized = normalizeArtifactPath(item);
+      if (path9.isAbsolute(normalized) || normalized.split("/").includes("..")) return { error: `artifact ${kind} path \u8D8A\u754C\uFF1A${item}` };
+      if (isReservedPath(normalized)) return { error: `artifact ${kind} path \u662F\u4FDD\u7559\u8DEF\u5F84\uFF1A${item}` };
+      paths.push(normalized);
+    }
+    artifacts[kind] = { phases: [...rule.phases], roles: [...rule.roles], paths };
+  }
+  return { policy: { version: 1, artifacts } };
+}
+function loadArtifactPolicy(root) {
+  const file = path9.join(root, ARTIFACT_POLICY_PATH);
+  if (!existsSync4(file)) return { error: "artifact policy \u4E0D\u5B58\u5728\uFF1B\u5148\u8FD0\u884C /gate-init \u5E76\u586B\u5199 .agents/gate/artifact-policy.json" };
+  if (lstatSync4(file).isSymbolicLink()) return { error: "artifact policy \u4E0D\u80FD\u662F symlink" };
+  try {
+    return parseArtifactPolicy(JSON.parse(readFileSync3(file, "utf8")));
+  } catch {
+    return { error: "artifact policy \u4E0D\u662F\u6709\u6548 JSON" };
+  }
+}
+function segmentMatches(pattern, value) {
+  const regex = new RegExp(`^${pattern.split("").map((char) => {
+    if (char === "*") return "[^/]*";
+    if (char === "?") return "[^/]";
+    return char.replace(/[\\^$.*+?()[\]{}|]/gu, "\\$&");
+  }).join("")}$`, "u");
+  return regex.test(value);
+}
+function pathMatches(pattern, relative) {
+  const patternParts = pattern.split("/").filter(Boolean);
+  const valueParts = relative.split("/").filter(Boolean);
+  const walk = (p, v) => {
+    if (p === patternParts.length) return v === valueParts.length;
+    const part = patternParts[p] ?? "";
+    if (part === "**") return walk(p + 1, v) || v < valueParts.length && walk(p, v + 1);
+    if (v >= valueParts.length) return false;
+    if (!segmentMatches(part, valueParts[v] ?? "")) return false;
+    return walk(p + 1, v + 1);
+  };
+  return walk(0, 0);
+}
+function artifactRuleAllows(policy, state, worker, kind) {
+  if (state.phase === "blocked") return { error: "blocked \u4E0D\u5141\u8BB8 artifact \u5199\u5165" };
+  const rule = policy.artifacts[kind];
+  if (rule === void 0) return { error: `artifact kind \u672A\u6388\u6743\uFF1A${kind}` };
+  const phaseKey = methodologyKeyFor(state);
+  if (!rule.phases.includes("*") && !rule.phases.includes(phaseKey)) return { error: `\u5F53\u524D\u9636\u6BB5 ${phaseKey} \u4E0D\u5141\u8BB8 artifact ${kind}` };
+  if (!rule.roles.includes(worker ? "worker" : "root")) return { error: `\u5F53\u524D\u89D2\u8272\u4E0D\u5141\u8BB8 artifact ${kind}` };
+  return { rule };
+}
+function checkArtifactPath(root, rule, requested, kind) {
+  const normalized = normalizeArtifactPath(requested);
+  if (path9.isAbsolute(normalized) || normalized.split("/").includes("..")) return { error: "artifact path \u8D8A\u754C" };
+  if (isReservedPath(normalized)) return { error: "artifact path \u662F\u4FDD\u7559\u8DEF\u5F84" };
+  if (!rule.paths.some((pattern) => pathMatches(pattern, normalized))) return { error: `artifact ${kind} path \u4E0D\u5728\u767D\u540D\u5355\uFF1A${requested}` };
+  const absolute = path9.resolve(root, normalized);
+  if (!isInside(root, absolute)) return { error: "artifact path \u8D8A\u754C" };
+  if (pathHasSymlink(root, absolute)) return { error: "artifact path \u5305\u542B symlink" };
+  return { absolute, relative: path9.relative(root, absolute).replaceAll("\\", "/") };
+}
+function writeArtifact(root, requested, content) {
+  const normalized = normalizeArtifactPath(requested);
+  if (path9.isAbsolute(normalized) || normalized.split("/").includes("..") || isReservedPath(normalized)) return { error: "artifact path \u88AB\u62D2\u7EDD" };
+  const target = path9.resolve(root, normalized);
+  if (!isInside(root, target)) return { error: "artifact path \u8D8A\u754C" };
+  if (pathHasSymlink(root, target)) return { error: "artifact path \u5305\u542B symlink" };
+  mkdirSync4(path9.dirname(target), { recursive: true });
+  writeFileSync4(target, content);
+  return { relative: path9.relative(root, target).replaceAll("\\", "/") };
+}
+
+// src/init-manifest.ts
+import { createHash } from "node:crypto";
+import { existsSync as existsSync5, mkdirSync as mkdirSync5, readFileSync as readFileSync4, writeFileSync as writeFileSync5 } from "node:fs";
+import path10 from "node:path";
+var INIT_MANIFEST_PATH = ".agents/gate/init-manifest.json";
+var ARTIFACT_POLICY_PATH2 = ".agents/gate/artifact-policy.json";
+var AGENTS_BLOCK = /<!-- gate-notes:start -->[\s\S]*?<!-- gate-notes:end -->/u;
+function sha256Bytes(value) {
+  return `sha256:${createHash("sha256").update(value).digest("hex")}`;
+}
+function sha256File(file) {
+  try {
+    return sha256Bytes(readFileSync4(file));
+  } catch {
+    return null;
+  }
+}
+function packageVersion() {
+  try {
+    const pkg = JSON.parse(readFileSync4(path10.join(PACKAGE_ROOT, "package.json"), "utf8"));
+    return typeof pkg.version === "string" ? pkg.version : "unknown";
+  } catch {
+    return "unknown";
+  }
+}
+function currentAgentsBlock(root) {
+  try {
+    const text = readFileSync4(path10.join(root, "AGENTS.md"), "utf8");
+    return AGENTS_BLOCK.exec(text)?.[0] ?? null;
+  } catch {
+    return null;
+  }
+}
+function readManifest(root) {
+  try {
+    const value = JSON.parse(readFileSync4(path10.join(root, INIT_MANIFEST_PATH), "utf8"));
+    if (value === null || typeof value !== "object" || value.version !== 1) return null;
+    if (typeof value.createdAt !== "string" || typeof value.gateVersion !== "string") return null;
+    if (value.immutable === null || typeof value.immutable !== "object" || Array.isArray(value.immutable)) return null;
+    if (value.managed === null || typeof value.managed !== "object" || Array.isArray(value.managed)) return null;
+    if (value.notes === null || typeof value.notes !== "object" || Array.isArray(value.notes)) return null;
+    return value;
+  } catch {
+    return null;
+  }
+}
+function immutablePaths() {
+  return [
+    ...NOTES_CI_SCRIPTS.map((name) => `.agents/gate/ci/${name}`),
+    ".agents/gate/verify-notes.mjs"
+  ];
+}
+function provisionInitManifest(root, packageScript) {
+  const previous = readManifest(root);
+  const createdAt = typeof previous?.createdAt === "string" ? previous.createdAt : (/* @__PURE__ */ new Date()).toISOString();
+  const immutable = {};
+  for (const relative of immutablePaths()) {
+    const hash = sha256File(path10.join(root, relative));
+    if (hash !== null) immutable[relative] = hash;
+  }
+  const policyFile = path10.join(root, ARTIFACT_POLICY_PATH2);
+  const policyHash = sha256File(policyFile) ?? sha256Bytes("");
+  const block = currentAgentsBlock(root);
+  let pkgScript = null;
+  try {
+    const pkg = JSON.parse(readFileSync4(path10.join(root, "package.json"), "utf8"));
+    pkgScript = typeof pkg.scripts?.["verify-notes"] === "string" ? pkg.scripts["verify-notes"] : null;
+  } catch {
+  }
+  const manifest = {
+    version: 1,
+    gateVersion: packageVersion(),
+    createdAt,
+    immutable,
+    managed: {
+      artifactPolicy: { path: ARTIFACT_POLICY_PATH2, schemaVersion: 1, sha256: policyHash },
+      agentsBlockHash: block === null ? null : sha256Bytes(block),
+      packageScript: pkgScript ?? packageScript,
+      workflow: ".github/workflows/verify-notes.yml"
+    },
+    notes: { path: ".agents/notes", lifecycles: ["proposed", "implemented", "rejected", "archived"] }
+  };
+  mkdirSync5(path10.dirname(path10.join(root, INIT_MANIFEST_PATH)), { recursive: true });
+  writeFileSync5(path10.join(root, INIT_MANIFEST_PATH), `${JSON.stringify(manifest, null, 2)}
+`);
+  return { path: INIT_MANIFEST_PATH, manifest, status: previous === null ? "created" : "updated" };
+}
+function verifyInit(root) {
+  const manifest = readManifest(root);
+  const issues = [];
+  const immutable = [];
+  for (const relative of immutablePaths()) {
+    const actual = sha256File(path10.join(root, relative));
+    const expected = manifest?.immutable?.[relative];
+    if (actual === null) {
+      immutable.push({ path: relative, status: manifest === null ? "unknown" : "missing" });
+      if (manifest !== null) issues.push({ severity: "error", code: "immutable-missing", message: `${relative} \u7F3A\u5931` });
+    } else if (manifest === null) {
+      immutable.push({ path: relative, status: "unknown" });
+    } else if (expected === void 0) {
+      immutable.push({ path: relative, status: "missing" });
+      issues.push({ severity: "error", code: "immutable-manifest-missing", message: `${relative} \u4E0D\u5728 init-manifest.immutable` });
+    } else if (actual !== expected) {
+      immutable.push({ path: relative, status: "modified" });
+      issues.push({ severity: "error", code: "immutable-modified", message: `${relative} \u4E0E init-manifest \u4E0D\u4E00\u81F4` });
+    } else {
+      immutable.push({ path: relative, status: "ok" });
+    }
+  }
+  const manifestExists = existsSync5(path10.join(root, INIT_MANIFEST_PATH));
+  if (manifest === null) issues.push({ severity: "error", code: manifestExists ? "manifest-invalid" : "manifest-missing", message: manifestExists ? "init-manifest \u65E0\u6548\uFF1B\u91CD\u65B0\u8FD0\u884C /gate-init" : "init-manifest \u7F3A\u5931\uFF1B\u91CD\u65B0\u8FD0\u884C /gate-init" });
+  let artifactPolicy = "missing";
+  const policyFile = path10.join(root, ARTIFACT_POLICY_PATH2);
+  if (existsSync5(policyFile)) {
+    try {
+      const parsed = parseArtifactPolicy(JSON.parse(readFileSync4(policyFile, "utf8")));
+      if (parsed.policy === void 0) artifactPolicy = "invalid";
+      else {
+        const actualHash = sha256File(policyFile);
+        artifactPolicy = manifest?.managed?.artifactPolicy?.sha256 !== void 0 && actualHash !== manifest.managed.artifactPolicy.sha256 ? "customized" : "ok";
+      }
+    } catch {
+      artifactPolicy = "invalid";
+    }
+  }
+  if (artifactPolicy === "missing") issues.push({ severity: "error", code: "artifact-policy-missing", message: "artifact-policy.json \u7F3A\u5931" });
+  if (artifactPolicy === "invalid") issues.push({ severity: "error", code: "artifact-policy-invalid", message: "artifact-policy.json \u65E0\u6548" });
+  const currentBlock = currentAgentsBlock(root);
+  let agentsBlock = manifest === null ? "unknown" : "missing";
+  if (currentBlock !== null && manifest !== null) {
+    agentsBlock = manifest.managed?.agentsBlockHash !== null && manifest.managed?.agentsBlockHash !== void 0 && sha256Bytes(currentBlock) !== manifest.managed.agentsBlockHash ? "modified" : "ok";
+  }
+  if (agentsBlock === "missing") issues.push({ severity: "error", code: "agents-block-missing", message: "AGENTS.md \u7F3A\u5C11 gate managed block" });
+  if (agentsBlock === "modified") issues.push({ severity: "warning", code: "agents-block-modified", message: "AGENTS.md managed block \u5DF2\u4FEE\u6539" });
+  let packageScript = manifest === null ? "unknown" : "missing";
+  let currentScript = null;
+  try {
+    const pkg = JSON.parse(readFileSync4(path10.join(root, "package.json"), "utf8"));
+    currentScript = typeof pkg.scripts?.["verify-notes"] === "string" ? pkg.scripts["verify-notes"] : null;
+  } catch {
+  }
+  if (currentScript === null) {
+    packageScript = "missing";
+    issues.push({ severity: "error", code: "package-script-missing", message: "package.json \u7F3A\u5C11 scripts.verify-notes" });
+  } else if (manifest === null) {
+    packageScript = "unknown";
+  } else if (manifest.managed?.packageScript !== null && manifest.managed?.packageScript !== void 0 && currentScript !== manifest.managed.packageScript) {
+    packageScript = "customized";
+    issues.push({ severity: "warning", code: "package-script-customized", message: "scripts.verify-notes \u4E0E init \u65F6\u4E0D\u540C" });
+  } else packageScript = "ok";
+  const workflowPath = manifest?.managed?.workflow ?? ".github/workflows/verify-notes.yml";
+  const workflow = existsSync5(path10.join(root, workflowPath)) ? "existing" : "missing";
+  if (workflow === "missing") issues.push({ severity: "warning", code: "workflow-missing", message: `${workflowPath} \u7F3A\u5931` });
+  let notes = "ok";
+  for (const lifecycle of ["proposed", "implemented", "rejected", "archived"]) {
+    if (!existsSync5(path10.join(root, ".agents", "notes", lifecycle))) {
+      notes = "missing";
+      issues.push({ severity: "error", code: "notes-missing", message: `.agents/notes/${lifecycle} \u7F3A\u5931` });
+    }
+  }
+  const currentVersion = packageVersion();
+  if (manifest !== null && manifest.gateVersion !== currentVersion) {
+    issues.push({ severity: "warning", code: "stale-init", message: `init gateVersion=${manifest.gateVersion}\uFF0C\u5F53\u524D=${currentVersion}\uFF1B\u5EFA\u8BAE\u91CD\u65B0\u8FD0\u884C /gate-init` });
+  }
+  const ok = !issues.some((issue) => issue.severity === "error");
+  const lines = [
+    `init verify\uFF1A${ok ? "ok" : "FAILED"}`,
+    `manifest\uFF1A${manifest === null ? "missing/invalid" : "ok"}`,
+    `gateVersion\uFF1A${manifest?.gateVersion ?? "unknown"}\uFF08current ${currentVersion}\uFF09`,
+    `artifact-policy\uFF1A${artifactPolicy}`,
+    `agents block\uFF1A${agentsBlock}`,
+    `package script\uFF1A${packageScript}`,
+    `workflow\uFF1A${workflow}`,
+    `notes\uFF1A${notes}`,
+    ...issues.map((issue) => `${issue.severity}: ${issue.message}`)
+  ];
+  return { ok, manifest: manifest === null ? manifestExists ? "invalid" : "missing" : "ok", immutable, artifactPolicy, agentsBlock, packageScript, workflow, notes, issues, text: lines.join("\n") };
+}
+
 // src/commands.ts
 import { execFileSync as execFileSync3 } from "node:child_process";
+import { readFileSync as readFileSync5 } from "node:fs";
 
 // src/command-catalog.ts
 var GATE_COMMANDS = [
   { name: "gate-init", description: "\u521D\u59CB\u5316 notes\u3001AGENTS.md\u3001verify-notes\u3001CI\u3001git \u4E0E\u57FA\u7840 .gitignore", hint: null, when: "any" },
-  { name: "gate-enter-plan", description: "\u57FA\u4E8E\u8BA8\u8BBA\u5171\u8BC6\u3001\u65E2\u6709\u51B3\u7B56\u4E0E\u7528\u6237\u8F93\u5165\u8FDB\u5165 planning", hint: "<\u5177\u4F53\u5DE5\u4F5C\u4E8B\u9879\u6216\u4E0A\u4E0B\u6587\u8BED\u4E49>", when: "discuss/complete" },
+  { name: "gate-enter-plan", description: "\u57FA\u4E8E\u8BA8\u8BBA\u5171\u8BC6\u3001\u65E2\u6709\u51B3\u7B56\u4E0E\u7528\u6237\u9700\u6C42\u8FDB\u5165 planning", hint: "<\u5177\u4F53\u5DE5\u4F5C\u4E8B\u9879\u6216\u4E0A\u4E0B\u6587\u8BED\u4E49>", when: "discuss/complete" },
   { name: "gate-enter-implement", description: "\u57FA\u4E8E\u5DF2\u786E\u8BA4\u8BA1\u5212\u6216\u8BA8\u8BBA\u540E\u7684\u5B9E\u65BD\u8BF4\u660E\u8FDB\u5165 implementation", hint: "<\u5177\u4F53\u5DE5\u4F5C\u4E8B\u9879\u6216\u4E0A\u4E0B\u6587\u8BED\u4E49>", when: "discuss/complete" },
+  { name: "gate-prd", description: "\u5728 discuss \u4E2D\u6309\u7528\u6237\u8981\u6C42\u521B\u5EFA\u6216\u66F4\u65B0 PRD", hint: "[\u4E3B\u9898\u6216\u4E0A\u4E0B\u6587\u8BED\u4E49]", when: "discuss" },
   { name: "gate-fix-bug", description: "\u4E3A\u5DF2\u6388\u6743\u7F3A\u9677\u6D3E\u53D1 fix worker\uFF0C\u57FA\u4E8E\u63CF\u8FF0\u6216\u5F53\u524D\u4E0A\u4E0B\u6587\u4FEE\u590D", hint: "<\u5177\u4F53\u5DE5\u4F5C\u4E8B\u9879\u6216\u4E0A\u4E0B\u6587\u8BED\u4E49>", when: "discuss/complete" },
-  { name: "gate-docs", description: "\u8FDB\u5165\u6587\u6863\u6CBB\u7406\uFF0C\u6309\u9879\u76EE\u6587\u6863\u89C4\u8303\u5904\u7406", hint: null, when: "discuss/complete" },
+  { name: "gate-docs", description: "\u8FDB\u5165\u6587\u6863\u6CBB\u7406\uFF0C\u6309\u9879\u76EE\u6587\u6863\u89C4\u8303\u5904\u7406", hint: "[\u6587\u6863\u8303\u56F4\u6216\u4E0A\u4E0B\u6587\u8BED\u4E49]", when: "discuss/complete" },
   { name: "gate-implement-review", description: "\u5BF9\u5F53\u524D\u6539\u52A8\u505A\u72EC\u7ACB\u53EA\u8BFB code review", hint: "<\u5177\u4F53\u5DE5\u4F5C\u4E8B\u9879\u6216\u4E0A\u4E0B\u6587\u8BED\u4E49>", when: "discuss/complete" },
   { name: "gate-code-verify", description: "\u5BF9\u5F53\u524D\u6539\u52A8\u505A\u72EC\u7ACB\u53EA\u8BFB\u9A8C\u6536\uFF08gate-user-verify\uFF09", hint: "<\u5177\u4F53\u5DE5\u4F5C\u4E8B\u9879\u6216\u4E0A\u4E0B\u6587\u8BED\u4E49>", when: "discuss/complete" },
   { name: "gate-propose-review", description: "\u5BF9\u63D0\u6848\u505A\u72EC\u7ACB\u53EA\u8BFB\u4E09\u8F74\u8BC4\u5BA1", hint: "<\u5177\u4F53\u5DE5\u4F5C\u4E8B\u9879\u6216\u4E0A\u4E0B\u6587\u8BED\u4E49>", when: "discuss/complete" },
@@ -1554,22 +1870,28 @@ function registerCommands(ctx, deps) {
     command2("gate-init", async (invocation) => {
       const workspace = workspaceBoundary(ctx, invocation.agent);
       if (workspace === void 0) return { kind: "error", text: "\u65E0\u6CD5\u786E\u5B9A\u5F53\u524D\u4F1A\u8BDD\u5DE5\u4F5C\u533A" };
-      const root = path9.resolve(workspace);
+      const root = path11.resolve(workspace);
       let provisioned;
       let projectScripts;
       let projectCi;
       let projectGit;
+      let artifactPolicy;
+      let initManifest;
       try {
         provisioned = provisionNotes(root);
+        artifactPolicy = provisionArtifactPolicy(root);
         projectCi = provisionCi(root);
         projectScripts = provisionProjectScripts(root);
         projectGit = provisionGit(root);
+        initManifest = provisionInitManifest(root, projectScripts.command);
       } catch (error) {
         return { kind: "error", text: `notes \u521D\u59CB\u5316\u5931\u8D25\uFF1A${error instanceof Error ? error.message : String(error)}` };
       }
-      wake(invocation, store.read(root, invocation.agent), `Gate \u5DF2\u521D\u59CB\u5316\uFF1A${root}\uFF08phase=discuss\uFF09\uFF0Cnotes \u5DF2\u521D\u59CB\u5316\u4E3A ${provisioned.notes}\uFF0CAGENTS.md \u5DF2\u66F4\u65B0\uFF0Cverify-notes \u5DF2\u914D\u7F6E\u4E3A ${projectScripts.command}\uFF0CCI \u5DF2\u914D\u7F6E\u4E3A ${projectCi.workflow}\uFF0Cgit\uFF1A${projectGit.git}${projectGit.gitError === null ? "" : `\uFF08${projectGit.gitError}\uFF09`}\uFF0Cignore\uFF1A${projectGit.ignore}\u3002`, "gate-init");
+      wake(invocation, store.read(root, invocation.agent), `Gate \u5DF2\u521D\u59CB\u5316\uFF1A${root}\uFF08phase=discuss\uFF09\uFF0Cnotes \u5DF2\u521D\u59CB\u5316\u4E3A ${provisioned.notes}\uFF0Cartifact policy \u4E3A ${artifactPolicy.path}\uFF08${artifactPolicy.status}\uFF09\uFF0Cinit manifest \u4E3A ${initManifest.path}\uFF08${initManifest.status}\uFF09\uFF0CAGENTS.md \u5DF2\u66F4\u65B0\uFF0Cverify-notes \u5DF2\u914D\u7F6E\u4E3A ${projectScripts.command}\uFF0CCI \u5DF2\u914D\u7F6E\u4E3A ${projectCi.workflow}\uFF0Cgit\uFF1A${projectGit.git}${projectGit.gitError === null ? "" : `\uFF08${projectGit.gitError}\uFF09`}\uFF0Cignore\uFF1A${projectGit.ignore}\u3002`, "gate-init");
       return { kind: "success", text: `Gate \u5DF2\u521D\u59CB\u5316\uFF1A${root}\uFF08phase=discuss\uFF09
 notes\uFF1A${provisioned.notes}
+artifact policy\uFF1A${artifactPolicy.path}\uFF08${artifactPolicy.status}\uFF09
+init manifest\uFF1A${initManifest.path}\uFF08${initManifest.status}\uFF09
 AGENTS\uFF1A${provisioned.agents}
 verify-notes\uFF1A${projectScripts.command}
 CI\uFF1A${projectCi.workflow}
@@ -1606,6 +1928,19 @@ ignore\uFF1A${projectGit.ignore}` };
       wake(invocation, result.state, `Gate \u5DF2\u8FDB\u5165 implement\uFF1A${result.state.task ?? ""}${direct ? "\uFF08\u76F4\u63A5\u5B9E\u65BD\uFF0C\u672A\u8D70 planning\uFF09" : ""}\u3002\u7528\u6237\u8BF4\u660E\uFF1A${constraints}\u3002`, "gate-enter-implement");
       return { kind: "success", text: `\u8FDB\u5165 implement\uFF1A${result.state.task}${direct ? "\uFF08\u76F4\u63A5\u5B9E\u65BD\uFF09" : ""}` };
     });
+    command2("gate-prd", async (invocation) => {
+      const gate = resolveGate(ctx, invocation.agent);
+      const state = store.read(gate.root, invocation.agent);
+      if (state.phase !== "discuss") return { kind: "error", text: "gate-prd \u53EA\u5728 discuss \u9636\u6BB5\u53EF\u7528" };
+      const topic = String(invocation.rawInput ?? "").trim() || "\u5F53\u524D\u8BA8\u8BBA";
+      let skill = "";
+      try {
+        skill = readFileSync5(path11.join(SKILLS, "gate-prd", "SKILL.md"), "utf8");
+      } catch {
+      }
+      wake(invocation, state, ["\u8BF7\u6309 gate-prd \u6280\u80FD\u521B\u5EFA\u6216\u66F4\u65B0 PRD\u3002", "\u4E3B\u9898/\u4E0A\u4E0B\u6587\uFF1A" + topic, skill].filter(Boolean).join("\n\n"), "gate-prd");
+      return { kind: "success", text: "\u5DF2\u8BF7\u6C42 PRD\uFF1A" + topic };
+    });
     command2("gate-fix-bug", async (invocation) => {
       const brief = String(invocation.rawInput ?? "").trim();
       const gate = resolveGate(ctx, invocation.agent);
@@ -1624,19 +1959,20 @@ ignore\uFF1A${projectGit.ignore}` };
       return { kind: "success", text: `\u8FDB\u5165 fix-bug\uFF1A${scope2}` };
     });
     command2("gate-docs", async (invocation) => {
+      const scope2 = String(invocation.rawInput ?? "").trim() || "\u6587\u6863\u6CBB\u7406";
       const gate = resolveGate(ctx, invocation.agent);
       const state = store.read(gate.root, invocation.agent);
       if (state.phase !== "discuss" && state.phase !== "complete") return { kind: "error", text: `\u5F53\u524D phase \u662F ${state.phase}` };
       if (state.work === "blocked" || state.blockReason !== null) return { kind: "error", text: `\u5F53\u524D\u88AB blocked\uFF1A${state.blockReason ?? "unknown"}\uFF1B\u5148 /gate-resume` };
       state.phase = "docs";
-      state.task = "\u6587\u6863\u6CBB\u7406";
+      state.task = scope2;
       state.work = "active";
       state.blockReason = null;
       state.blockedFrom = null;
       state.node = null;
       store.write(gate.root, invocation.agent, state);
-      wake(invocation, state, "Gate \u5DF2\u8FDB\u5165 docs\u3002", "gate-docs");
-      return { kind: "success", text: "\u8FDB\u5165 docs\uFF1A\u6587\u6863\u6CBB\u7406" };
+      wake(invocation, state, `Gate \u5DF2\u8FDB\u5165 docs\uFF1A${scope2}\u3002`, "gate-docs");
+      return { kind: "success", text: `\u8FDB\u5165 docs\uFF1A${scope2}` };
     });
     command2("gate-implement-review", async (invocation) => {
       const brief = String(invocation.rawInput ?? "").trim();
@@ -1766,8 +2102,8 @@ ${JSON.stringify(check.results, null, 2)}` };
       const node = resolveNodeBinary();
       if (node === void 0) return { kind: "error", text: "notes-runtime-unavailable" };
       try {
-        const script = path9.join(NOTES_SKILL_DIR, "scripts", "archive-agent-note.ts");
-        const output = execFileSync3(node, [script, "--root", path9.join(gate.root, ".agents", "notes"), ...args], { cwd: gate.root, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] });
+        const script = path11.join(NOTES_SKILL_DIR, "scripts", "archive-agent-note.ts");
+        const output = execFileSync3(node, [script, "--root", path11.join(gate.root, ".agents", "notes"), ...args], { cwd: gate.root, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] });
         return { kind: "success", text: String(output).trim() || "Note \u5DF2\u5F52\u6863" };
       } catch (error) {
         return { kind: "error", text: String(error?.stderr ?? error?.message ?? error).trim() };
@@ -1778,11 +2114,11 @@ ${JSON.stringify(check.results, null, 2)}` };
       const raw = String(invocation.rawInput ?? "").trim();
       const args = raw === "" ? [] : raw.split(/\s+/u);
       const target = args[0] ?? "board.html";
-      const title = args[1] ?? `${path9.basename(gate.root)} \u51B3\u7B56\u770B\u677F`;
+      const title = args[1] ?? `${path11.basename(gate.root)} \u51B3\u7B56\u770B\u677F`;
       const node = resolveNodeBinary();
       if (node === void 0) return { kind: "error", text: "notes-runtime-unavailable" };
       try {
-        const script = path9.join(NOTES_SKILL_DIR, "scripts", "build-board.ts");
+        const script = path11.join(NOTES_SKILL_DIR, "scripts", "build-board.ts");
         const output = execFileSync3(node, [script, "--init", target, title], { cwd: gate.root, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] });
         return { kind: "success", text: String(output).trim() || `\u51B3\u7B56\u770B\u677F\u5DF2\u751F\u6210\uFF1A${target}` };
       } catch (error) {
@@ -1794,8 +2130,8 @@ ${JSON.stringify(check.results, null, 2)}` };
       const node = resolveNodeBinary();
       if (node === void 0) return { kind: "error", text: "notes-runtime-unavailable" };
       try {
-        const script = path9.join(NOTES_SKILL_DIR, "scripts", "verify-archived-agent-notes.ts");
-        const output = execFileSync3(node, [script, "--root", path9.join(gate.root, ".agents", "notes"), "--write"], { cwd: gate.root, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] });
+        const script = path11.join(NOTES_SKILL_DIR, "scripts", "verify-archived-agent-notes.ts");
+        const output = execFileSync3(node, [script, "--root", path11.join(gate.root, ".agents", "notes"), "--write"], { cwd: gate.root, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] });
         return { kind: "success", text: String(output).trim() || "archived manifest \u5DF2\u5199\u5165" };
       } catch (error) {
         return { kind: "error", text: String(error?.stderr ?? error?.message ?? error).trim() };
@@ -1863,8 +2199,8 @@ function registerStartPhase(ctx, deps) {
 }
 
 // src/tools/record.ts
-import { createHash } from "node:crypto";
-import { existsSync as existsSync4, lstatSync as lstatSync4, readFileSync as readFileSync3 } from "node:fs";
+import { createHash as createHash2 } from "node:crypto";
+import { existsSync as existsSync6, lstatSync as lstatSync5, readFileSync as readFileSync6 } from "node:fs";
 function registerRecord(ctx, deps) {
   const { store, reviewLimit, wake } = deps;
   ctx.tools.register({
@@ -2070,12 +2406,12 @@ function registerRecord(ctx, deps) {
         for (const item of evidence) {
           const target = classifyPath(gate.workspace, item);
           try {
-            if (target.outside || !existsSync4(target.absolute) || !lstatSync4(target.absolute).isFile()) {
+            if (target.outside || !existsSync6(target.absolute) || !lstatSync5(target.absolute).isFile()) {
               invalidEvidence.push(item);
               continue;
             }
-            const bytes = readFileSync3(target.absolute);
-            records.push({ path: target.relative, size: bytes.length, sha256: createHash("sha256").update(bytes).digest("hex") });
+            const bytes = readFileSync6(target.absolute);
+            records.push({ path: target.relative, size: bytes.length, sha256: createHash2("sha256").update(bytes).digest("hex") });
           } catch {
             invalidEvidence.push(item);
           }
@@ -2193,8 +2529,8 @@ function registerStatus(ctx, deps) {
 }
 
 // src/tools/notes.ts
-import { existsSync as existsSync5, mkdirSync as mkdirSync4, writeFileSync as writeFileSync4 } from "node:fs";
-import path10 from "node:path";
+import { existsSync as existsSync7, mkdirSync as mkdirSync6, writeFileSync as writeFileSync6 } from "node:fs";
+import path12 from "node:path";
 function registerNoteTools(ctx, deps) {
   const { store, reviewLimit, wake } = deps;
   ctx.tools.register({
@@ -2220,7 +2556,7 @@ function registerNoteTools(ctx, deps) {
         return { ok: false, code: "planning-only", reason: "gate_note_write \u53EA\u5141\u8BB8 planning worker \u5728 plan/plan-revise \u8282\u70B9\u4F7F\u7528\u3002" };
       }
       let relative = String(args.path ?? "").replaceAll("\\", "/").replace(/^\.?\//u, "");
-      if (relative === "" || relative.includes("..") || path10.isAbsolute(relative) || !relative.endsWith(".md")) {
+      if (relative === "" || relative.includes("..") || path12.isAbsolute(relative) || !relative.endsWith(".md")) {
         return { ok: false, code: "invalid-path" };
       }
       let lifecycle = "proposed";
@@ -2232,16 +2568,16 @@ function registerNoteTools(ctx, deps) {
       if (!/^(?:feature|bug-fix|simplification|architecture|process|testing)\/\d{4}-\d{2}-\d{2}-.+\.md$/u.test(relative)) {
         return { ok: false, code: "invalid-path", reason: "\u9700\u8981 <class>/yyyy-mm-dd-topic.md\uFF0C\u6216 proposed|implemented/<class>/...\u3002" };
       }
-      const base = path10.join(gate.root, ".agents", "notes", String(lifecycle));
-      const absolute = path10.resolve(base, relative);
+      const base = path12.join(gate.root, ".agents", "notes", String(lifecycle));
+      const absolute = path12.resolve(base, relative);
       if (!isInside(base, absolute)) return { ok: false, code: "invalid-path" };
       if (pathHasSymlink(base, absolute)) return { ok: false, code: "invalid-path" };
-      if (lifecycle === "implemented" && !existsSync5(absolute)) {
+      if (lifecycle === "implemented" && !existsSync7(absolute)) {
         return { ok: false, code: "implemented-must-exist", reason: "implemented Note \u53EA\u80FD\u539F\u5730\u7F16\u8F91\uFF0C\u4E0D\u80FD\u65B0\u5EFA\u3002" };
       }
-      mkdirSync4(path10.dirname(absolute), { recursive: true });
-      writeFileSync4(absolute, String(args.content ?? ""));
-      return { ok: true, path: path10.relative(gate.root, absolute).replaceAll("\\", "/"), lifecycle };
+      mkdirSync6(path12.dirname(absolute), { recursive: true });
+      writeFileSync6(absolute, String(args.content ?? ""));
+      return { ok: true, path: path12.relative(gate.root, absolute).replaceAll("\\", "/"), lifecycle };
     }
   });
   ctx.tools.register({
@@ -2264,7 +2600,7 @@ function registerNoteTools(ctx, deps) {
       if (!check.ok) return { ...check, state: normalizeState(state) };
       if (state.node === "note-lifecycle") {
         if (state.noteFinalized !== true) return { ok: false, code: "note-lifecycle-incomplete", reason: "\u5148\u8C03\u7528 gate_note_finalize\u3002", state: normalizeState(state) };
-        const implemented = state.notePaths.length > 0 && state.notePaths.every((entry) => entry.lifecycle === "implemented" && existsSync5(path10.join(gate.root, entry.path)));
+        const implemented = state.notePaths.length > 0 && state.notePaths.every((entry) => entry.lifecycle === "implemented" && existsSync7(path12.join(gate.root, entry.path)));
         if (!implemented) return { ok: false, code: "note-lifecycle-incomplete", reason: "notePaths \u5C1A\u672A\u5168\u90E8\u8FDB\u5165 implemented\u3002", results: check.results, state: normalizeState(state) };
         state.noteVerified = true;
         store.write(gate.root, exec.agent, state);
@@ -2312,9 +2648,9 @@ function registerNoteTools(ctx, deps) {
       const recovered = recoverFinalize(gate.root, sessionId);
       for (const entry of state.notePaths) {
         if (entry.lifecycle !== "proposed") continue;
-        const source = path10.join(gate.root, entry.path);
+        const source = path12.join(gate.root, entry.path);
         const targetRelative = entry.path.replaceAll("\\", "/").replace(".agents/notes/proposed/", ".agents/notes/implemented/");
-        if (!existsSync5(source) && existsSync5(path10.join(gate.root, targetRelative))) {
+        if (!existsSync7(source) && existsSync7(path12.join(gate.root, targetRelative))) {
           entry.path = targetRelative;
           entry.lifecycle = "implemented";
           recovered.push("adopted-target");
@@ -2355,7 +2691,10 @@ var GATE_TOOLS = [
   { name: "gate_note_write", summary: "planning worker \u5199 proposed Note \u6216\u539F\u5730\u66F4\u65B0 implemented Note\u3002" },
   { name: "gate_note_verify", summary: "\u5728 note-lifecycle \u4E2D\u8FD0\u884C notes \u6821\u9A8C\uFF1Broot-only\u3002" },
   { name: "gate_note_finalize", summary: "\u628A proposed Note \u79FB\u5230 implemented \u5E76\u66F4\u65B0\u5934\u5757\uFF1Broot-only\u3002" },
-  { name: "gate_help", summary: "\u5217\u51FA gate \u547D\u4EE4\u3001\u5DE5\u5177\u548C\u5F53\u524D phase/node\uFF1B\u53EA\u8BFB\uFF0Croot-only\u3002" }
+  { name: "gate_help", summary: "\u5217\u51FA gate \u547D\u4EE4\u3001\u5DE5\u5177\u548C\u5F53\u524D phase/node\uFF1B\u53EA\u8BFB\uFF0Croot-only\u3002" },
+  { name: "gate_artifact_write", summary: "\u6309 artifact policy \u5199\u767D\u540D\u5355\u6587\u4EF6\uFF1B\u4E0D\u8D70\u666E\u901A workspace write\u3002" },
+  { name: "gate_research_dispatch", summary: "root-only \u5728 discuss/plan \u6D3E research worker\uFF1Bworker \u53EA\u5199 research artifact\u3002" },
+  { name: "gate_init_verify", summary: "root-only \u53EA\u8BFB\u6821\u9A8C init-manifest\u3001\u751F\u6210\u7269 hash\u3001policy \u4E0E init \u7ED3\u6784\u3002" }
 ];
 
 // src/tools/help.ts
@@ -2407,6 +2746,143 @@ function registerHelp(ctx, deps) {
   });
 }
 
+// src/tools/artifact.ts
+function registerArtifactTools(ctx, deps) {
+  const { store } = deps;
+  ctx.tools.register({
+    name: "gate_artifact_write",
+    description: "\u6309 .agents/gate/artifact-policy.json \u5199\u767D\u540D\u5355 artifact\uFF08handoff/prd/research \u7B49\uFF09\u3002\u53EA\u5199\u6587\u4EF6\uFF0C\u4E0D\u8D70\u666E\u901A workspace write \u6743\u9650\u3002",
+    parameters: {
+      type: "object",
+      additionalProperties: false,
+      properties: {
+        kind: { type: "string", description: "policy \u4E2D\u7684 artifact kind\u3002" },
+        path: { type: "string", description: "workspace \u5185\u76F8\u5BF9\u8DEF\u5F84\u3002" },
+        content: { type: "string" }
+      },
+      required: ["kind", "path", "content"]
+    },
+    output: {
+      schema: { type: "object", additionalProperties: true },
+      render: (_args, value) => [{ type: "text", text: typeof value?.text === "string" ? value.text : JSON.stringify(value) }]
+    },
+    async execute(args, exec) {
+      const gate = resolveGate(ctx, exec.agent);
+      if (gate.root === void 0) return { ok: false, code: "state-unavailable", reason: "\u65E0\u6CD5\u786E\u5B9A\u5DE5\u4F5C\u533A\u3002" };
+      const effective = effectiveState(ctx, exec.agent, gate, store);
+      const loaded = loadArtifactPolicy(gate.root);
+      if (loaded.policy === void 0) return { ok: false, code: "artifact-policy-invalid", reason: loaded.error };
+      const allowed = artifactRuleAllows(loaded.policy, effective.state, effective.worker, String(args?.kind ?? ""));
+      if (allowed.rule === void 0) return { ok: false, code: "artifact-denied", reason: allowed.error };
+      const checked = checkArtifactPath(gate.root, allowed.rule, String(args?.path ?? ""), String(args?.kind ?? ""));
+      if (checked.absolute === void 0) return { ok: false, code: "artifact-denied", reason: checked.error };
+      const written = writeArtifact(gate.root, checked.relative ?? String(args?.path ?? ""), String(args?.content ?? ""));
+      if (written.relative === void 0) return { ok: false, code: "artifact-write-failed", reason: written.error };
+      return { ok: true, kind: String(args.kind), path: written.relative, bytes: Buffer.byteLength(String(args.content ?? "")) };
+    }
+  });
+}
+
+// src/tools/research.ts
+function registerResearchDispatch(ctx, deps) {
+  const { store } = deps;
+  ctx.tools.register({
+    name: "gate_research_dispatch",
+    description: "root-only\uFF1A\u5728 discuss \u6216 orchestrating/plan \u6D3E research worker\uFF0C\u7B49\u5F85\u7ED3\u679C\uFF1Bworker \u53EA\u80FD\u901A\u8FC7 artifact policy \u5199 research \u6587\u6863\u3002",
+    parameters: {
+      type: "object",
+      additionalProperties: false,
+      properties: {
+        question: { type: "string" },
+        purpose: { type: "string" }
+      },
+      required: ["question"]
+    },
+    output: {
+      schema: { type: "object", additionalProperties: true },
+      render: (_args, value) => [{ type: "text", text: typeof value?.text === "string" ? value.text : JSON.stringify(value) }]
+    },
+    async execute(args, exec) {
+      const root = rootAgentOf(ctx, exec.agent);
+      if (root?.id !== exec.agent?.id) return { ok: false, code: "root-only", reason: "gate_research_dispatch \u53EA\u80FD\u7531 root agent \u8C03\u7528\u3002" };
+      const gate = resolveGate(ctx, exec.agent);
+      if (gate.root === void 0) return { ok: false, code: "state-unavailable", reason: "\u65E0\u6CD5\u786E\u5B9A\u5DE5\u4F5C\u533A\u3002" };
+      const state = store.read(gate.root, root);
+      if (!(state.phase === "discuss" || state.phase === "orchestrating" && state.node === "plan")) {
+        return { ok: false, code: "wrong-phase", reason: "research dispatch \u53EA\u5141\u8BB8 discuss \u6216 orchestrating/plan\u3002" };
+      }
+      const loaded = loadArtifactPolicy(gate.root);
+      if (loaded.policy === void 0) return { ok: false, code: "artifact-policy-invalid", reason: loaded.error };
+      const allowed = artifactRuleAllows(loaded.policy, state, true, "research");
+      if (allowed.rule === void 0) return { ok: false, code: "artifact-denied", reason: allowed.error };
+      const subagents = typeof ctx.get === "function" ? ctx.get("subagents") : void 0;
+      if (subagents?.startActivation === void 0 || subagents?.getProvider === void 0) {
+        return { ok: false, code: "subagents-unavailable", reason: "ctx.subagents \u4E0D\u53EF\u7528\uFF0C\u65E0\u6CD5\u6D3E research worker\u3002" };
+      }
+      const provider = subagents.getProvider("spawn");
+      if (provider === void 0) return { ok: false, code: "provider-unavailable", reason: "ctx.subagents \u6CA1\u6709 spawn provider\u3002" };
+      const question = String(args?.question ?? "").trim();
+      if (question === "") return { ok: false, code: "question-required", reason: "research \u9700\u8981 question\u3002" };
+      const purpose = String(args?.purpose ?? "").trim();
+      const prompt = [{
+        type: "text",
+        text: [
+          "Research worker task. Investigate primary sources and write a Markdown report.",
+          `Question: ${question}`,
+          purpose === "" ? "" : `Purpose: ${purpose}`,
+          "Use gate_artifact_write({ kind: 'research', path, content }) to save the report.",
+          "Prefer project docs research location; otherwise .scratch/research/. Cite sources. Do not modify product code."
+        ].filter(Boolean).join("\n")
+      }];
+      let activation;
+      try {
+        activation = await subagents.startActivation({
+          provider: "spawn",
+          label: "gate-research",
+          prompt,
+          parent: exec.agent,
+          signal: exec.signal,
+          delivery: "caller"
+        });
+        const result = await activation.result;
+        const output = result?.output;
+        const text = typeof output === "string" ? output : JSON.stringify(output ?? result);
+        return { ok: true, name: activation.name, text };
+      } catch (error) {
+        return { ok: false, code: "research-dispatch-failed", reason: error instanceof Error ? error.message : String(error) };
+      } finally {
+        if (activation?.dispose !== void 0) {
+          try {
+            await activation.dispose();
+          } catch {
+          }
+        }
+      }
+    }
+  });
+}
+
+// src/tools/init-verify.ts
+function registerInitVerify(ctx, _deps) {
+  ctx.tools.register({
+    name: "gate_init_verify",
+    description: "root-only \u53EA\u8BFB\u6821\u9A8C /gate-init \u4EA7\u7269\uFF1Ainit-manifest\u3001immutable hash\u3001artifact policy\u3001AGENTS managed block\u3001verify-notes script\u3001workflow\u3001notes \u76EE\u5F55\u3002",
+    parameters: { type: "object", additionalProperties: false, properties: {} },
+    output: {
+      schema: { type: "object", additionalProperties: true },
+      render: (_args, value) => [{ type: "text", text: typeof value?.text === "string" ? value.text : JSON.stringify(value) }]
+    },
+    async execute(_args, exec) {
+      if (rootAgentOf(ctx, exec.agent)?.id !== exec.agent?.id) {
+        return { ok: false, code: "root-only", reason: "gate_init_verify \u53EA\u80FD\u7531 root agent \u8C03\u7528\u3002" };
+      }
+      const gate = resolveGate(ctx, exec.agent);
+      if (gate.root === void 0) return { ok: false, code: "state-unavailable", reason: "\u65E0\u6CD5\u786E\u5B9A\u5DE5\u4F5C\u533A\u3002" };
+      return verifyInit(gate.root);
+    }
+  });
+}
+
 // src/tools/index.ts
 function registerTools(ctx, deps) {
   registerStartPhase(ctx, deps);
@@ -2414,6 +2890,9 @@ function registerTools(ctx, deps) {
   registerStatus(ctx, deps);
   registerNoteTools(ctx, deps);
   registerHelp(ctx, deps);
+  registerArtifactTools(ctx, deps);
+  registerResearchDispatch(ctx, deps);
+  registerInitVerify(ctx, deps);
 }
 
 // src/index.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-gate-agent",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "type": "module",
   "description": "Phase/node workflow gate with built-in commands, tools, and skills.",
   "exports": {

package/skills/gate-handoff/SKILL.md

@@ -5,7 +5,7 @@ argument-hint: "What will the next session be used for?"
 disable-model-invocation: true
 ---
 
-Write a handoff document summarising the current conversation so a fresh agent can continue the work. Save to the temporary directory of the user's OS - not the current workspace.
+Write a handoff document summarising the current conversation so a fresh agent can continue the work. Save under `.scratch/handoff/` in the workspace. Use `gate_artifact_write({ kind: 'handoff', path: '.scratch/handoff/<name>.md', content })`; do not use generic `write`.
 
 Include a "suggested skills" section in the document, which suggests skills that the agent should invoke.
 

package/skills/gate-playwright-e2e/SKILL.md

@@ -6,6 +6,10 @@ argument-hint: "项目路径，或要覆盖的功能 / bug"
 
 # Playwright E2E 配置
 
+在 gate 中：模型启用本技能时走 implement；用户在 discuss 调用时只讨论方案，写 config/spec/AGENTS 与安装依赖在 implement 进行。
+
+
+
 分工是固定的：**Agent 写 spec，Playwright runner 跑 spec。** 提需求的这一轮里，Agent 不打开浏览器一格格点页面——那是它最贵、最慢、最不可回归的用法；它只写 Node.js + Playwright 脚本，然后跑命令。脚本一旦落盘，「这个功能对不对」就从一轮轮截图变成一条几秒钟、几乎不花 token、随时可重跑的断言。
 
 这个 skill 一次跑完，产出三样**落盘**的东西：可跑的 `playwright.config.ts`、项目里长期生效的测试规则、覆盖目标行为的 spec。之后日常由项目里的规则接管，换项目、换技术栈、或规则要改的时候再调它。

package/skills/gate-prd/SKILL.md

@@ -10,7 +10,7 @@ disable-model-invocation: true
 
 ## 位置与复用
 
-遵循项目文档分层和既有 PRD 格式。优先更新同一产品主题已有的 PRD；没有已配置的存放位置时，先在对话中起草并请用户决定位置，不自行发布到外部系统。
+遵循项目文档分层和既有 PRD 格式。写入使用 `gate_artifact_write({ kind: 'prd', path, content })`，不要使用通用 `write`。优先更新同一产品主题已有的 PRD；没有已配置的存放位置时，先在对话中起草并请用户决定位置，不自行发布到外部系统。
 
 ## 内容
 

package/skills/gate-research/SKILL.md

@@ -4,11 +4,11 @@ description: Investigate a question against high-trust primary sources and captu
 user-invocable: false
 ---
 
-Spin up a **background agent** to do the research, so you keep working while it reads.
+调用 `gate_research_dispatch({ question, purpose })` 派 research worker，并等待结果。
 
-Its job:
+worker 的职责：
 
 1. Investigate the question against **primary sources** — official docs, source code, specs, first-party APIs — not a secondary write-up of them. Follow every claim back to the source that owns it.
 2. Write the findings to a single Markdown file, citing each claim's source.
-3. Save it where the repo already keeps such notes; match the existing convention, and if there is none, put it somewhere sensible and say where.
+3. Save it with `gate_artifact_write({ kind: 'research', path, content })`；优先项目文档位置，否则 `.scratch/research/`。不要使用通用 `write`。
 

package/skills/gate-write-agent-notes/SKILL.md

@@ -158,7 +158,9 @@ Status: <状态>
 "verify-notes": "node .agents/gate/verify-notes.mjs"
 ```
 
-这个启动器只调用插件内置脚本，不复制技能。
+这个启动器只调用插件内置脚本，不复制技能。
+
+`/gate-init` 还会生成 `.agents/gate/init-manifest.json`，记录 CI 脚本/启动器的 hash 和 init 结构。需要核对初始化是否被改坏时，用 root-only 只读工具 `gate_init_verify`；它不检查 Note 内容，也不要在每次 Note 操作后运行。`init-manifest.json` 由 git 跟踪，同内容重跑 init 时字节稳定。
 
 - 计划完成前或提交前，运行 `npm run verify-notes`，检查 tree、format、lifecycle、archived。
 - `/gate-init` 同时生成 `.github/workflows/verify-notes.yml` 和 `.agents/gate/ci/` 校验脚本副本；CI 使用项目内副本，不依赖插件安装路径。

package/skills/gate-write-agent-notes/references/verification.md

@@ -33,7 +33,9 @@ Notes 读取/写入命令均接受 `--root <path>` 或 `--root=<path>`，每次
 ## 接入建议
 
 - 轻量（个人/无 git）：前两个脚本即可，归档封印在第一次归档后自然生效。
-- 完整：运行 `npm run verify-notes` 跑 tree/format/lifecycle/archived 四检；该脚本由 `/gate-init` 生成，只调用插件内置脚本。gate 会话内也可用 `/gate-note-verify`。
+- 完整：运行 `npm run verify-notes` 跑 tree/format/lifecycle/archived 四检；该脚本由 `/gate-init` 生成，只调用插件内置脚本。gate 会话内也可用 `/gate-note-verify`。
+
+初始化结构核对用 root-only 的 `gate_init_verify`；它检查 `init-manifest.json`、生成物 hash、artifact-policy schema、AGENTS block、package script、workflow 和 notes 四目录，不检查 Note 内容，也不应随每次 Note 操作运行。
 
 
 ## 脚本路径

package/skills/gate-writing-for-agents/SKILL.md

@@ -3,6 +3,8 @@ name: gate-writing-for-agents
 description: Writing documents for agents. Use when creating or editing skills, or modifying AGENTS.md or CLAUDE.md.
 ---
 
+在 gate 中：修改 skill、AGENTS.md 或 agent 文档属于 implement 工作；discuss/plan 只讨论写法，不落盘。
+
 Reference for writing any document an agent consumes — a skill, an `AGENTS.md`, a doc reached by a pointer. The packaging differs; the writing does not: the same levers make each one predictable — the agent taking the same _process_ every run, not producing the same output.
 
 When the document you're writing is a skill, read [`SKILL-MECHANICS.md`](SKILL-MECHANICS.md) for frontmatter, invocation choice, and router skills.