plan-governance-cli 2.0.2 → 3.0.0

package/scripts/graph_governance.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
-import { existsSync, readFileSync } from "node:fs";
-import { isAbsolute, resolve } from "node:path";
+import { existsSync, readFileSync, realpathSync, statSync } from "node:fs";
+import { isAbsolute, resolve, relative } from "node:path";
 import { spawnSync } from "node:child_process";
 import { parse as parseYaml } from "yaml";
 
@@ -61,9 +61,11 @@ function usage() {
 架构图谱入口：<root>/docs/graph/architecture/index.yaml`);
 }
 
-function error(message) {
+class UsageError extends Error { code = 2; }
+
+function error(message, status = 1) {
   console.error(`graph: ERROR: ${message}`);
-  return 1;
+  return status;
 }
 
 function graphPath(root) {
@@ -407,57 +409,58 @@ function validate(root, layer = "functional") {
   return 0;
 }
 
-function parseValidateArgs(args) {
-  const options = { layer: "functional", root: process.cwd() };
+function parseOptions(args, name, defaults, required = []) {
+  if (args.length === 1 && ["-h", "--help"].includes(args[0])) return null;
+  const options = { ...defaults, root: process.cwd() };
+  const seen = new Set();
   const positional = [];
-  for (let index = 0; index < args.length; index += 1) {
-    const arg = args[index];
-    if (arg === "--layer") options.layer = args[++index];
-    else if (arg === "-h" || arg === "--help") return null;
-    else positional.push(arg);
-  }
-  if (!["functional", "architecture"].includes(options.layer)) {
-    throw new Error("validate --layer 只能是 functional 或 architecture");
-  }
-  if (positional.length > 1) throw new Error("validate 只能接收一个 root 路径");
-  if (positional.length === 1) options.root = resolve(positional[0]);
+  let terminated = false;
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+    if (arg === "--" && !terminated) { terminated = true; continue; }
+    if (!terminated && arg.startsWith("-")) {
+      const key = arg.slice(2);
+      if (!arg.startsWith("--") || !Object.hasOwn(defaults, key)) throw new UsageError(`${name} 不支持参数：${arg}`);
+      if (seen.has(key)) throw new UsageError(`${arg} 只能指定一次`);
+      seen.add(key);
+      const value = args[++i];
+      if (!value?.trim() || value.startsWith("-")) throw new UsageError(`${arg} 缺少值`);
+      options[key] = value;
+    } else positional.push(arg);
+  }
+  if (positional.length > 1) throw new UsageError(`${name} 只能接收一个 root 路径`);
+  if (positional.some((value) => !value.trim())) throw new UsageError("root 不能为空");
+  if (positional.length) options.root = resolve(positional[0]);
+  for (const key of required) if (!options[key]) throw new UsageError(`${name} 必须指定 --${key} <value>`);
+  if ("format" in options && !["text", "json"].includes(options.format)) throw new UsageError("--format 只能是 text 或 json");
+  if ("depth" in options) {
+    if (!/^[0-9]+$/.test(String(options.depth)) || Number(options.depth) < 1 || Number(options.depth) > 10) throw new UsageError("--depth 必须是 1 到 10 的整数");
+    options.depth = Number(options.depth);
+  }
+  if (!existsSync(options.root) || !statSync(options.root).isDirectory()) throw new Error(`root 不存在或不是目录：${options.root}`);
   return options;
 }
 
-function parseImpactArgs(args) {
-  const options = { from: null, depth: 2, format: "text", root: process.cwd() };
-  const positional = [];
-  for (let index = 0; index < args.length; index += 1) {
-    const arg = args[index];
-    if (arg === "--from") options.from = args[++index];
-    else if (arg === "--depth") options.depth = Number(args[++index]);
-    else if (arg === "--format") options.format = args[++index];
-    else if (arg === "-h" || arg === "--help") return null;
-    else positional.push(arg);
-  }
-  if (positional.length > 0) options.root = resolve(positional.at(-1));
-  if (!options.from) throw new Error("impact 必须指定 --from <graph-node-id>");
-  if (!Number.isInteger(options.depth) || options.depth < 1 || options.depth > 10) throw new Error("--depth 必须是 1 到 10 的整数");
-  if (!["text", "json"].includes(options.format)) throw new Error("--format 只能是 text 或 json");
+function parseValidateArgs(args) {
+  const options = parseOptions(args, "validate", { layer: "functional" });
+  if (options && !["functional", "architecture"].includes(options.layer)) throw new UsageError("validate --layer 只能是 functional 或 architecture");
   return options;
 }
 
+function parseImpactArgs(args) {
+  return parseOptions(args, "impact", { from: null, depth: 2, format: "text" }, ["from"]);
+}
+
 function parsePlanImpactArgs(args) {
-  const options = { input: null, format: "text", root: process.cwd() };
-  const positional = [];
-  for (let index = 0; index < args.length; index += 1) {
-    const arg = args[index];
-    if (arg === "--input") options.input = args[++index];
-    else if (arg === "--format") options.format = args[++index];
-    else if (arg === "-h" || arg === "--help") return null;
-    else positional.push(arg);
-  }
-  if (positional.length > 1) throw new Error("plan impact 只能接收一个 root 路径");
-  if (positional.length === 1) options.root = resolve(positional[0]);
-  if (!options.input) throw new Error("plan impact 必须指定 --input <plan-impact-request.json>");
-  if (!options.format || !["text", "json"].includes(options.format)) throw new Error("--format 只能是 text 或 json");
-  if (!existsSync(options.root)) throw new Error(`root 不存在：${options.root}`);
-  return options;
+  return parseOptions(args, "plan impact", { input: null, format: "text" }, ["input"]);
+}
+
+function candidateFile(root, file) {
+  const path = resolve(root, file);
+  const inside = (candidate) => { const rel = relative(realpathSync(root), candidate); return rel !== ".." && !rel.startsWith("../") && !isAbsolute(rel); };
+  if (!existsSync(path) || !statSync(path).isFile()) throw new Error(`指定代码文件不存在或不是普通文件：${file}`);
+  if (!inside(realpathSync(path))) throw new Error(`代码文件必须位于 root 内：${file}`);
+  return relative(root, path);
 }
 
 function loadPlanImpactRequest(root, input) {
@@ -481,8 +484,9 @@ function loadPlanImpactRequest(root, input) {
     const anchor = request.code_anchor;
     if (!anchor || typeof anchor !== "object") throw new Error("code_locator_requested=true 时必须提供 code_anchor");
     for (const field of ["file", "symbol", "kind"]) {
-      if (typeof anchor[field] !== "string" || anchor[field].length === 0) throw new Error(`code_anchor.${field} 缺失`);
+      if (typeof anchor[field] !== "string" || anchor[field].trim().length === 0) throw new Error(`code_anchor.${field} 缺失`);
     }
+    if (!["class", "function"].includes(anchor.kind)) throw new Error("code_anchor.kind 只能是 class 或 function");
   } else if (request.code_anchor !== undefined) {
     throw new Error("未请求代码定位时不得提供 code_anchor");
   }
@@ -515,8 +519,8 @@ function listCodeFiles(root) {
 
 function runCodeCandidateSearch(root, options) {
   let files;
-  if (options.file && existsSync(resolve(root, options.file))) {
-    files = [options.file];
+  if (options.file) {
+    files = [candidateFile(root, options.file)];
   } else {
     files = listCodeFiles(root);
   }
@@ -539,28 +543,13 @@ function runCodeCandidateSearch(root, options) {
 }
 
 function parseCodeCandidatesArgs(args) {
-  const options = { file: null, symbol: null, kind: null, format: "text", root: process.cwd() };
-  const positional = [];
-  for (let index = 0; index < args.length; index += 1) {
-    const arg = args[index];
-    if (arg === "--file") options.file = args[++index];
-    else if (arg === "--symbol") options.symbol = args[++index];
-    else if (arg === "--kind") options.kind = args[++index];
-    else if (arg === "--format") options.format = args[++index];
-    else if (arg === "-h" || arg === "--help") return null;
-    else positional.push(arg);
-  }
-  if (positional.length > 1) throw new Error("code candidates 只能接收一个 root 路径");
-  if (positional.length === 1) options.root = resolve(positional[0]);
-  if (!options.symbol) throw new Error("code candidates 必须指定 --symbol <symbol>");
-  if (!options.kind) throw new Error("code candidates 必须指定 --kind <kind>");
-  if (!options.file && options.file !== null) throw new Error("--file 必须指定路径");
-  if (!options.format || !["text", "json"].includes(options.format)) throw new Error("--format 只能是 text 或 json");
-  if (!existsSync(options.root)) throw new Error(`root 不存在：${options.root}`);
+  const options = parseOptions(args, "code candidates", { file: null, symbol: null, kind: null, format: "text" }, ["symbol", "kind"]);
+  if (options && !["class", "function"].includes(options.kind)) throw new UsageError("--kind 只能是 class 或 function");
   return options;
 }
 
 function codeCandidates(root, options) {
+  if (!["class", "function"].includes(options.kind) || !options.symbol?.trim()) throw new Error("代码定位 kind/symbol 无效");
   const candidates = runCodeCandidateSearch(root, options);
   const resolution = candidates.length === 1
     ? "unique_candidate"
@@ -588,27 +577,8 @@ function printCodeCandidatesText(result) {
 }
 
 function parseCodeImpactArgs(args) {
-  const options = { repo: null, file: null, symbol: null, kind: null, depth: 3, format: "text", root: process.cwd() };
-  const positional = [];
-  for (let index = 0; index < args.length; index += 1) {
-    const arg = args[index];
-    if (arg === "--repo") options.repo = args[++index];
-    else if (arg === "--file") options.file = args[++index];
-    else if (arg === "--symbol") options.symbol = args[++index];
-    else if (arg === "--kind") options.kind = args[++index];
-    else if (arg === "--depth") options.depth = Number(args[++index]);
-    else if (arg === "--format") options.format = args[++index];
-    else if (arg === "-h" || arg === "--help") return null;
-    else positional.push(arg);
-  }
-  if (positional.length > 1) throw new Error("code impact 只能接收一个 root 路径");
-  if (positional.length === 1) options.root = resolve(positional[0]);
-  ["repo", "file", "symbol", "kind"].forEach((field) => {
-    if (!options[field]) throw new Error(`code impact 必须指定 --${field} <value>`);
-  });
-  if (!Number.isInteger(options.depth) || options.depth < 1 || options.depth > 10) throw new Error("--depth 必须是 1 到 10 的整数");
-  if (!options.format || !["text", "json"].includes(options.format)) throw new Error("--format 只能是 text 或 json");
-  if (!existsSync(options.root)) throw new Error(`root 不存在：${options.root}`);
+  const options = parseOptions(args, "code impact", { repo: null, file: null, symbol: null, kind: null, depth: 3, format: "text" }, ["repo", "file", "symbol", "kind"]);
+  if (options && !["class", "function", "method"].includes(options.kind)) throw new UsageError("--kind 只能是 class、function 或 method");
   return options;
 }
 
@@ -637,9 +607,11 @@ function codeImpact(root, options) {
   } catch (cause) {
     throw new Error(`GitNexus 代码级影响查询返回了无法解析的结果：${cause.message}`);
   }
-  if (gitnexusResult?.error) {
+  if (!gitnexusResult || typeof gitnexusResult !== "object" || Array.isArray(gitnexusResult)) throw new Error("GitNexus 响应必须是非空对象");
+  if (gitnexusResult.error) {
     throw new Error(`GitNexus 代码级影响查询失败：${String(gitnexusResult.error)}`);
   }
+  if (!Number.isInteger(gitnexusResult.impactedCount) || gitnexusResult.impactedCount < 0 || typeof gitnexusResult.risk !== "string") throw new Error("GitNexus 响应缺少有效 risk/impactedCount");
   return {
     schema_version: 1,
     query: {
@@ -920,7 +892,7 @@ function main(args) {
   const command = args[0];
   if (!command || command === "--help" || command === "-h") {
     usage();
-    return command ? 0 : 1;
+    return command ? 0 : 2;
   }
   try {
     if (command === "validate") {
@@ -943,7 +915,7 @@ function main(args) {
       return 0;
     }
     if (command === "plan") {
-      if (args[1] !== "impact") return error(`plan 不支持子命令：${args[1] ?? "<missing>"}`);
+      if (args[1] !== "impact") return error(`plan 不支持子命令：${args[1] ?? "<missing>"}`, 2);
       const options = parsePlanImpactArgs(args.slice(2));
       if (options === null) {
         usage();
@@ -977,11 +949,11 @@ function main(args) {
         else printCodeImpactText(result);
         return 0;
       }
-      return error(`code 不支持子命令：${args[1] ?? "<missing>"}`);
+      return error(`code 不支持子命令：${args[1] ?? "<missing>"}`, 2);
     }
-    return error(`不支持子命令：${command}`);
+    return error(`不支持子命令：${command}`, 2);
   } catch (cause) {
-    return error(cause.message);
+    return error(cause.message, cause.code === 2 ? 2 : 1);
   }
 }
 

package/scripts/init_plan_governance.py

@@ -1,5 +1,6 @@
 #!/usr/bin/env python3
 import argparse
+import importlib.util
 import re
 import shutil
 import subprocess
@@ -8,6 +9,11 @@ from datetime import date, datetime
 from pathlib import Path
 
 
+_checker_spec = importlib.util.spec_from_file_location("initializer_checker", Path(__file__).with_name("check_plan_governance.py"))
+checker = importlib.util.module_from_spec(_checker_spec)
+_checker_spec.loader.exec_module(checker)
+
+
 VALID_STATUSES = {
     "候选",
     "设计中",
@@ -21,6 +27,7 @@ VALID_STATUSES = {
 
 AGENTS_SECTION_BEGIN = "<!-- plan-governance:start -->"
 AGENTS_SECTION_END = "<!-- plan-governance:end -->"
+WRITTEN_FILES = []
 
 
 def slugify(value):
@@ -38,6 +45,7 @@ def write_file(path, content, force):
         raise FileExistsError(f"{path} 已存在；如需覆盖请加 --force")
     path.parent.mkdir(parents=True, exist_ok=True)
     path.write_text(content, encoding="utf-8")
+    WRITTEN_FILES.append(path)
 
 
 def init_git(root):
@@ -46,6 +54,7 @@ def init_git(root):
 
     root.mkdir(parents=True, exist_ok=True)
     subprocess.run(["git", "init"], cwd=root, check=True)
+    WRITTEN_FILES.append(root / ".git")
     return root / ".git"
 
 
@@ -61,6 +70,7 @@ def agent_rules_body():
 - 普通一次性任务直接处理；已有计划按共享 verification 验证。新旧计划均默认自验，仅在用户明确要求时独立复核；未解决问题继续阻塞。
 - 只实施已授权、已准入的当前阶段。每个阶段有自身 Step 0、验证/完成和失败边界；未解决问题不能记为完成，不可用或超时不能冒充已检查。已有授权不重复索取，新增高影响外部动作按实际授权处理。
 - 首次读取 `docs/PLAN_MAP.md`、索引登记的相关 `docs/plans/` 计划及适用契约/ADR/migration；恢复先核对当前工作集、最近证据和实际 diff，缺失或冲突再展开。
+- 多计划/多会话并行时，每个会话在 check/workset/hook 中显式传入自己的 `--plan ID`；必要前置与共享写入约束仍需读取，写入前重读相关事实，不设置全项目可变焦点。
 - 地图维护状态、阶段、关系、阻塞与证据入口；计划记录本次差异及验证，现行契约优先复用 Schema/OpenAPI。新事实不写回历史草案，变化同步地图及相关引用。
 - 完成时按共享规范记录实际验证与适用用户验收，运行 `plan-governance-cli check .`；准入/CI/发布显式使用 `--strict-readiness`，机械通过不等于业务验收。
 """
@@ -96,6 +106,7 @@ def update_managed_file(root, filename, section, begin, end):
             separator = newline if current.endswith(("\n", "\r")) else newline * 2
         updated = f"{current}{separator}{section}"
     target.write_bytes(updated.encode("utf-8"))
+    WRITTEN_FILES.append(target)
     return target
 
 
@@ -210,13 +221,15 @@ def copy_checker(root, force):
     source = Path(__file__).with_name("check_plan_governance.py")
     target = root / "scripts" / "check_plan_governance.py"
     if source.resolve() == target.resolve():
-        target.chmod(0o755)
         return target
     if target.exists() and not force:
         raise FileExistsError(f"{target} 已存在；如需覆盖请加 --force")
     target.parent.mkdir(parents=True, exist_ok=True)
-    shutil.copy2(source, target)
-    target.chmod(0o755)
+    if target.exists():
+        target.write_bytes(source.read_bytes())
+    else:
+        shutil.copy2(source, target)
+    WRITTEN_FILES.append(target)
     return target
 
 
@@ -281,6 +294,7 @@ def migrate_plan_map_last_updated(root, last_updated):
 
     if changed:
         plan_map.write_text("\n".join(migrated) + ("\n" if text.endswith("\n") else ""), encoding="utf-8")
+        WRITTEN_FILES.append(plan_map)
     return plan_map, changed
 
 
@@ -293,13 +307,13 @@ def upgrade_existing(root):
 
 
 def parse_args(argv):
-    parser = argparse.ArgumentParser(description="初始化中文 plan-governance 文档。")
-    parser.add_argument("--root", default=".", help="目标仓库根目录，默认当前目录。")
-    parser.add_argument("--plan", help="计划文件名或计划标识，例如 api-compat-migration。")
-    parser.add_argument("--title", help="计划显示名称，默认使用 --plan。")
-    parser.add_argument("--goal", help="计划目标，会写入计划文档。")
+    parser = argparse.ArgumentParser(description="初始化中文 plan-governance 文档。", allow_abbrev=False)
+    parser.add_argument("--root", type=checker.nonempty, default=".", help="目标仓库根目录，默认当前目录。")
+    parser.add_argument("--plan", type=checker.nonempty, help="计划文件名或计划标识，例如 api-compat-migration。")
+    parser.add_argument("--title", type=checker.nonempty, help="计划显示名称，默认使用 --plan。")
+    parser.add_argument("--goal", type=checker.nonempty, help="计划目标，会写入计划文档。")
     parser.add_argument("--status", default="设计中", choices=sorted(VALID_STATUSES), help="初始状态。")
-    parser.add_argument("--phase", default="阶段 0", help="当前阶段名称。")
+    parser.add_argument("--phase", type=checker.nonempty, default="阶段 0", help="当前阶段名称。")
     parser.add_argument("--copy-checker", action="store_true", help="复制检查脚本到目标仓库 scripts/。")
     parser.add_argument("--update-agents-md", action="store_true", help="创建或更新目标仓库 AGENTS.md 中的计划治理规则。")
     parser.add_argument("--update-agent-rules", action="store_true", help="创建或更新目标仓库 AGENTS.md 中的计划治理规则。")
@@ -309,6 +323,7 @@ def parse_args(argv):
     parser.add_argument("--migrate-plan-map-last-updated", action="store_true", help="将旧五列表 PLAN_MAP.md 迁移为包含最后更新的六列表。")
     parser.add_argument("--last-updated-date", default=date.today().isoformat(), help="迁移 PLAN_MAP.md 时填入的最后更新日期，默认今天。")
     parser.add_argument("--force", action="store_true", help="允许覆盖已存在的治理文件。")
+    checker.validate_options(parser, argv)
     args = parser.parse_args(argv)
     only_modes = [
         args.update_agents_md_only,
@@ -320,12 +335,47 @@ def parse_args(argv):
         parser.error("--update-*-only、--upgrade-existing 和 --migrate-plan-map-last-updated 不能同时使用")
     if not any(only_modes) and not args.plan:
         parser.error("正常初始化必须提供 --plan；已有项目可使用 --update-*-only、--upgrade-existing 或 --migrate-plan-map-last-updated")
+    supplied = {token.split("=", 1)[0] for token in argv if token.startswith("--")}
+    if any(only_modes):
+        allowed = {"--root", "--update-agents-md-only", "--update-agent-rules-only", "--upgrade-existing", "--migrate-plan-map-last-updated"}
+        if args.migrate_plan_map_last_updated:
+            allowed.add("--last-updated-date")
+        if supplied - allowed:
+            parser.error("当前模式不接受：" + "、".join(sorted(supplied - allowed)))
+    else:
+        if "--last-updated-date" in supplied:
+            parser.error("--last-updated-date 仅用于迁移")
+        if args.status not in {"候选", "设计中"}:
+            parser.error("新计划只能以 候选/设计中 初始化；准入后再同步状态")
+        if not checker.valid_phase_name(args.phase):
+            parser.error("--phase 必须为阶段身份，例如 阶段 0")
+        if args.update_agents_md and args.update_agent_rules:
+            parser.error("代理规则更新别名不能同时指定")
+    if args.migrate_plan_map_last_updated:
+        try:
+            date.fromisoformat(args.last_updated_date)
+        except ValueError:
+            parser.error("--last-updated-date 必须是有效 ISO 日期")
     return args
 
 
 def main(argv=None):
-    args = parse_args(argv or sys.argv[1:])
+    WRITTEN_FILES.clear()
+    args = parse_args(sys.argv[1:] if argv is None else argv)
     root = Path(args.root).expanduser().resolve()
+    if root.exists() and not root.is_dir():
+        raise NotADirectoryError(f"root 不是目录：{root}")
+    if any((args.update_agents_md_only, args.update_agent_rules_only, args.upgrade_existing,
+            args.update_agents_md, args.update_agent_rules)):
+        target = root / "AGENTS.md"
+        if target.exists():
+            target.read_text(encoding="utf-8")
+    if args.upgrade_existing:
+        target = root / "scripts/check_plan_governance.py"
+        if target.exists() and not target.is_file():
+            raise IsADirectoryError(f"checker 目标不是普通文件：{target}")
+        if target.parent.exists() and not target.parent.is_dir():
+            raise NotADirectoryError(f"checker 父路径不是目录：{target.parent}")
 
     if args.update_agents_md_only:
         target = update_agents_md(root)
@@ -366,14 +416,30 @@ def main(argv=None):
     created_on = date.today()
     plan_file = docs / "plans" / created_on.strftime("%Y%m%d") / f"{plan_slug}.md"
 
+    targets = [plan_map, plan_file]
+    if args.copy_checker:
+        targets.append(root / "scripts/check_plan_governance.py")
+    for target in targets:
+        if target.exists() and (not args.force or not target.is_file()):
+            raise FileExistsError(f"{target} 已存在；未写入任何治理文件")
+        for parent in target.parents:
+            if parent.exists() and not parent.is_dir():
+                raise NotADirectoryError(f"目标父路径不是目录：{parent}")
+    # 首次写入前读取全部必要来源。
+    map_text = plan_map_content(plan_slug, title, args.status, args.phase, created_on)
+    body = plan_content(plan_slug, title, args.status, args.phase, args.goal)
+    if args.update_agents_md or args.update_agent_rules:
+        target = root / "AGENTS.md"
+        if target.exists():
+            target.read_text(encoding="utf-8")
     created = []
     git_dir = init_git(root)
     if git_dir is not None:
         created.append(git_dir)
 
-    write_file(plan_map, plan_map_content(plan_slug, title, args.status, args.phase, created_on), args.force)
+    write_file(plan_map, map_text, args.force)
     created.append(plan_map)
-    write_file(plan_file, plan_content(plan_slug, title, args.status, args.phase, args.goal), args.force)
+    write_file(plan_file, body, args.force)
     created.append(plan_file)
 
     if args.copy_checker:
@@ -392,6 +458,7 @@ def main(argv=None):
 if __name__ == "__main__":
     try:
         raise SystemExit(main())
-    except (FileExistsError, FileNotFoundError, ValueError) as exc:
+    except (OSError, ValueError, subprocess.CalledProcessError) as exc:
         print(f"ERROR: {exc}", file=sys.stderr)
+        print("初始化未完成；已写入：" + ("、".join(str(p) for p in WRITTEN_FILES) or "无") + "；请核对出错目标后恢复或重试。", file=sys.stderr)
         raise SystemExit(1)

package/scripts/plan_governance_hook.py

@@ -136,7 +136,10 @@ def matching_plans(root, paths):
     return matches
 
 
-def print_session_start(root):
+def print_session_start(root, names=None):
+    if names:
+        print("[plan-governance] 会话聚焦计划：" + "、".join(names))
+        return print_gate_hints(root, names)
     active, _ = active_plans(root)
     if not active:
         print("[plan-governance] 未发现活跃计划。")
@@ -148,12 +151,16 @@ def print_session_start(root):
             f"- {plan['name']}: {plan['status']}，{plan['phase']}，"
             f"最后更新 {plan['last_updated']}，证据 {plan['evidence']}"
         )
-    print_gate_hints(root, {plan["name"] for plan in active})
+    print("[plan-governance] 尚未设置会话焦点；选择计划后显式传入 --plan ID。")
     return 0
 
 
 def print_gate_hints(root, names):
-    payload, _ = checker.workset_payload(root)
+    payload, _ = checker.workset_payload(root, requested=list(names))
+    for constraint in payload.get("scope", {}).get("shared_writes", []):
+        print(f"  共享写入约束：{constraint}")
+    for dependency in payload.get("scope", {}).get("dependencies", []):
+        print(f"  必要前置：{dependency['plan']}@{dependency['phase']}，通过={dependency['phase_passed']}")
     has_blockers = False
     for plan in payload["plans"]:
         if plan["plan"] not in names:
@@ -168,8 +175,19 @@ def print_gate_hints(root, names):
         print("[plan-governance] 当前阻塞项：无法确认，请核对诊断。" if payload["warnings"]
               else "[plan-governance] 当前阻塞项：无。")
 
+    return 0
+
 
-def print_pre_write(root, paths):
+def print_pre_write(root, paths, names=None):
+    if names:
+        print("[plan-governance] 写入前检查聚焦范围：" + "、".join(names))
+        plans, _ = load_plans(root)
+        targets = [target for plan in plans if plan["name"] in names for target in plan["targets"]]
+        targets += [plan["path"].relative_to(root).as_posix() for plan in plans if plan["name"] in names and plan["path"]]
+        for path in paths:
+            if path != "docs/PLAN_MAP.md" and not any(target_matches_path(target, path) for target in targets):
+                print(f"  WARNING: 写入路径超出聚焦计划声明范围：{path}；请先核对范围与授权。")
+        return print_gate_hints(root, names)
     matches = matching_plans(root, paths)
     if not matches:
         print("[plan-governance] 未匹配到相关活跃计划。")
@@ -179,7 +197,7 @@ def print_pre_write(root, paths):
     for plan in matches:
         print(f"- {plan['name']}: {plan['status']}，{plan['phase']}")
         print("  当前阶段门禁：确认 Step 0 证据、验证方式、完成条件和公共契约约束。")
-    print_gate_hints(root, {plan["name"] for plan in matches})
+    print("[plan-governance] 路径匹配仅为候选；请显式选择 --plan，不能据此授权或接管计划。")
     return 0
 
 
@@ -208,29 +226,25 @@ def print_post_write(paths):
     return 0
 
 
-def print_stop(root):
-    checker = root / "scripts" / "check_plan_governance.py"
-    if not checker.exists():
-        print("[plan-governance] 未找到 scripts/check_plan_governance.py，跳过停止前检查。")
-        return 0
-
+def print_stop(root, names=None):
     result = subprocess.run(
-        [sys.executable, str(checker), "."],
-        cwd=root,
-        check=False,
-        capture_output=True,
-        text=True,
+        [sys.executable, str(Path(__file__).with_name("check_plan_governance.py")),
+         str(root), *[token for name in names or [] for token in ("--plan", name)]],
+        check=False, capture_output=True, text=True,
     )
-    output = (result.stdout or result.stderr).strip()
-    if output:
-        print(output)
+    for output in (result.stdout, result.stderr):
+        if output.strip():
+            print(output.strip())
+    if result.returncode not in {0, 1}:
+        print("[plan-governance] 停止前检查未完成：检查器执行失败。", file=sys.stderr)
+        return 1
     print("[plan-governance] Stop 检查为非阻塞提示；请人工复核 WARNING/ERROR。")
     return 0
 
 
 def parse_args(argv):
-    parser = argparse.ArgumentParser(description="计划治理 hook runtime。")
-    parser.add_argument("--root", default=".", help="仓库根目录，默认当前目录。")
+    parser = argparse.ArgumentParser(description="计划治理 hook runtime。", allow_abbrev=False)
+    parser.add_argument("--root", default=".", type=checker.nonempty, help="仓库根目录，默认当前目录。")
     parser.add_argument(
         "--event",
         required=True,
@@ -238,23 +252,54 @@ def parse_args(argv):
         help="hook 事件类型。",
     )
     parser.add_argument("--paths", nargs="*", default=[], help="事件相关路径。")
-    return parser.parse_args(argv)
+    parser.add_argument("--plan", action="append", type=checker.nonempty, default=[], help="会话聚焦计划 ID，可重复。")
+    checker.validate_options(parser, argv, {"plan"})
+    args = parser.parse_args(argv)
+    if len(set(args.plan)) != len(args.plan):
+        parser.error("--plan 不接受重复 ID")
+    if "--paths" in argv and args.event not in {"pre-write", "post-write"}:
+        parser.error("--paths 仅用于 pre-write/post-write")
+    return args
 
 
 def main(argv=None):
     args = parse_args(sys.argv[1:] if argv is None else argv)
-    root = Path(args.root)
+    root = Path(args.root).expanduser().resolve()
+    if not root.is_dir():
+        print(f"ERROR: root 不存在或不是目录：{root}", file=sys.stderr)
+        return 1
+    if args.plan:
+        errors = []
+        text, _, plans = checker.load_plan_records(root, errors)
+        try:
+            checker.build_scope(root, args.plan, text, plans)
+        except checker.UsageError as exc:
+            print(f"ERROR: {exc}", file=sys.stderr)
+            return 2
+        if errors:
+            print("ERROR: 未完成检查：" + "；".join(errors), file=sys.stderr)
+            return 1
+    for path in args.paths:
+        candidate = (root / path).resolve()
+        if not path.strip() or not candidate.is_relative_to(root):
+            print(f"ERROR: paths 必须是 root 内的非空路径：{path}", file=sys.stderr)
+            return 2
+    args.paths = [(root / path).resolve().relative_to(root).as_posix() for path in args.paths]
 
     if args.event == "session-start":
-        return print_session_start(root)
+        return print_session_start(root, args.plan)
     if args.event == "pre-write":
-        return print_pre_write(root, args.paths)
+        return print_pre_write(root, args.paths, args.plan)
     if args.event == "post-write":
         return print_post_write(args.paths)
     if args.event == "stop":
-        return print_stop(root)
+        return print_stop(root, args.plan)
     return 0
 
 
 if __name__ == "__main__":
-    raise SystemExit(main())
+    try:
+        raise SystemExit(main())
+    except (OSError, ValueError) as exc:
+        print(f"ERROR: hook 未完成检查：{exc}", file=sys.stderr)
+        raise SystemExit(1)