@house365/comate 0.6.0 → 0.7.0

package/README.md

@@ -61,6 +61,21 @@ cd your-project && comate init
 
 输入 `/comate` 自动探测当前阶段并分派,或直接调用某个阶段 skill。状态记录在每个 change 的 `openspec/changes/<name>/.comate.yaml` 中,支持上下文压缩后断点恢复。
 
+## Token 用量:`comate usage`
+
+查看**当前项目**的 token 消耗与估算成本(封装 [ccusage](https://github.com/ryoppippi/ccusage),随 comate 一起装):
+
+```bash
+comate usage            # 本项目按会话(session)统计
+comate usage daily      # 本项目按天
+comate usage --global   # 全部项目(不做项目隔离)
+comate usage --json -s 2026-08-01   # 其余参数原样透传给 ccusage
+```
+
+默认只统计当前工作目录这一个项目:Claude Code 数据按 `~/.claude/projects/<项目>/` 隔离,Codex 数据按会话记录里的 `cwd` 过滤,两者都不会混入其它项目的用量。加 `--global` 看全量,或用 `comate usage codex ...` 单看某个 agent。
+
+> 粒度到项目/会话级;不做 open/design/build 阶段级归因(那需要在状态机打时间戳,属后续增强)。
+
 ## 目录结构
 
 ```

package/bin/cli.mjs

@@ -21,12 +21,18 @@ if (args[0] === 'doctor') {
   process.exit(doctor(args.slice(1)));
 }
 
+if (args[0] === 'usage') {
+  const { usage } = await import('./usage.mjs');
+  process.exit(await usage(args.slice(1), { pkgRoot }));
+}
+
 if (args[0] === '--help' || args[0] === '-h') {
   console.log(`comate — OpenSpec + Superpowers 规约驱动的开发编排器
 
 用法:
   comate init      安装 comate 和依赖到用户级，并在当前项目创建 openspec/
   comate doctor    健康检查
+  comate usage     查看本项目 token 用量（--global 看全部；参数透传给 ccusage）
 
 装好后在 agent 中输入 /comate 开始使用。`);
   process.exit(0);

package/bin/doctor.mjs

@@ -3,8 +3,12 @@
 // ponytail: comate.sh already implements every check. This only locates the
 // installed copy so the user doesn't have to remember the path.
 import { spawnSync } from 'node:child_process';
-import { existsSync } from 'node:fs';
-import { delimiter, join, resolve } from 'node:path';
+import { existsSync, readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { delimiter, dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { atLeast, capture, npmInvocation } from './init.mjs';
 
 // Where the skills CLI puts things. `init` installs user-level, but a project
 // copy shadows it for the agent, so check cwd first and report on the same one
@@ -67,5 +71,85 @@ export function doctor(argv) {
     console.error(`无法执行 bash (${bash}) — comate 的脚本需要 bash。${error.message}`);
     return 1;
   }
+
+  // ccusage is a node dependency (for `comate usage`), not a bash-side tool, so
+  // it lives here rather than in comate.sh's doctor. A miss is a warning, never
+  // a failure: usage falls back to `npx ccusage@latest`, so it still works.
+  reportCcusage();
+
+  // Version check is the only place a user learns a newer comate exists: the
+  // npm package doesn't self-update and `~/.agents/skills` keeps the copied
+  // skills until `comate init` is re-run. Never blocks or fails doctor — a
+  // network miss / offline just skips the line (see checkForUpdate).
+  reportUpdate();
+
   return status ?? 1;
 }
+
+// resolvable = shipped as comate's pinned dependency; the common, happy case
+// after `npm i -g @house365/comate`. Otherwise point at the two ways out.
+export function ccusageResolvable(pkgRoot = defaultPkgRoot()) {
+  try {
+    createRequire(join(pkgRoot, 'package.json')).resolve('ccusage/package.json');
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function reportCcusage() {
+  if (ccusageResolvable()) {
+    console.log('  ✓ ccusage present (comate usage 可用)');
+  } else {
+    console.log(
+      '  ⚠ ccusage not found — reinstall with  npm i -g @house365/comate  ' +
+        '(comate usage 会回退到 npx ccusage@latest)',
+    );
+  }
+}
+
+// Read {name, version} from the installed package.json. Both come from the same
+// file so the check keys off whatever package this binary actually belongs to —
+// no hardcoded name/version to drift when the package is renamed or bumped.
+export function localPackage(pkgRoot = defaultPkgRoot()) {
+  try {
+    const { name, version } = JSON.parse(readFileSync(join(pkgRoot, 'package.json'), 'utf8'));
+    return name && version ? { name, version } : null;
+  } catch {
+    return null;
+  }
+}
+
+// Compare the installed version against npm's latest. Returns null (silent) on
+// anything uncertain — no package.json, no npm, offline, timeout, unparseable
+// output — because a *diagnostic* command must never hang or error on a network
+// miss. `fetchLatest` is injectable so this is unit-testable without the network.
+export function checkForUpdate({
+  pkg = localPackage(),
+  fetchLatest = defaultFetchLatest,
+} = {}) {
+  if (!pkg) return null;
+  const latest = fetchLatest(pkg.name);
+  if (!latest || !/^\d+\.\d+\.\d+/.test(latest)) return null;
+  // outdated when current is NOT at least latest (atLeast is >=).
+  return { name: pkg.name, current: pkg.version, latest, outdated: !atLeast(pkg.version, latest) };
+}
+
+// `npm view <pkg> version` — capture() already caps at 15s and returns null on
+// any non-zero exit, so offline/timeout falls through to a skipped check.
+function defaultFetchLatest(name) {
+  const { command, args, shell } = npmInvocation(['view', name, 'version']);
+  return capture(command, args, { shell: Boolean(shell) });
+}
+
+function reportUpdate(info = checkForUpdate()) {
+  if (!info || !info.outdated) return; // up to date or couldn't tell → say nothing
+  console.log(
+    `  ⬆ 有新版 comate：${info.current} → ${info.latest}。升级：` +
+      `npm i -g ${info.name}@latest 然后重跑 comate init`,
+  );
+}
+
+function defaultPkgRoot() {
+  return resolve(dirname(fileURLToPath(import.meta.url)), '..');
+}

package/bin/usage.mjs

@@ -0,0 +1,252 @@
+// `comate usage` — show this project's Claude Code / Codex token usage by
+// wrapping ccusage.
+//
+// Why a wrapper and not just `npx ccusage`: ccusage aggregates every project
+// globally and there is no "just this repo" flag. Scoping has to be done per
+// agent, because the two store data differently:
+//
+//   Claude Code — one dir per project: ~/.claude/projects/<encoded-cwd>/*.jsonl.
+//                 Honours CLAUDE_CONFIG_DIR. So: a throwaway root whose
+//                 projects/ holds a single symlink to this project's dir.
+//   Codex       — flat by date: ~/.codex/sessions/YYYY/MM/DD/*.jsonl, project
+//                 identified only by a `cwd` inside each file's session_meta.
+//                 Honours CODEX_HOME. So: filter files by cwd, symlink the
+//                 matches into a throwaway sessions/ dir.
+//
+// Both env vars are set to the scoped roots even when a root is empty — an empty
+// scoped root reports zero for that agent, which is correct, whereas leaving the
+// var unset would let ccusage fall back to the global dir and leak every other
+// project's usage in. `--global` skips all scoping and forwards straight through.
+import { spawnSync } from 'node:child_process';
+import {
+  existsSync,
+  mkdtempSync,
+  mkdirSync,
+  openSync,
+  readSync,
+  closeSync,
+  readdirSync,
+  rmSync,
+  linkSync,
+  copyFileSync,
+} from 'node:fs';
+import { createRequire } from 'node:module';
+import { tmpdir } from 'node:os';
+import { basename, dirname, join, relative } from 'node:path';
+
+// Claude Code encodes a project's cwd into a directory name by replacing every
+// path separator and the drive colon with a dash: D:\a\b -> D--a-b, /a/b -> -a-b.
+// Verified against a real ~/.claude/projects entry on Windows.
+export function encodeProjectDir(cwd) {
+  return cwd.replace(/[:\\/]/g, '-');
+}
+
+function home() {
+  return process.env.HOME ?? process.env.USERPROFILE ?? '';
+}
+
+// Where Claude Code keeps this project's transcripts. CLAUDE_CONFIG_DIR wins if
+// the user has relocated the config dir, matching ccusage's own resolution.
+export function claudeDataDir(cwd = process.cwd(), env = process.env) {
+  const configRoot = env.CLAUDE_CONFIG_DIR || join(home(), '.claude');
+  return join(configRoot, 'projects', encodeProjectDir(cwd));
+}
+
+// Codex's sessions root. CODEX_HOME wins, else ~/.codex.
+export function codexSessionsDir(env = process.env) {
+  const root = env.CODEX_HOME || join(home(), '.codex');
+  return join(root, 'sessions');
+}
+
+// Read just the head of a file — enough to catch the session_meta record, which
+// Codex writes first. Avoids slurping multi-MB transcripts to read one cwd.
+function readHead(file, bytes = 8192) {
+  const fd = openSync(file, 'r');
+  try {
+    const buf = Buffer.alloc(bytes);
+    const n = readSync(fd, buf, 0, bytes, 0);
+    return buf.toString('utf8', 0, n);
+  } finally {
+    closeSync(fd);
+  }
+}
+
+// The cwd recorded in a Codex session file, or null. session_meta is the first
+// record; its payload.cwd (older: top-level cwd) is the project path.
+export function codexFileCwd(file, read = readHead) {
+  const head = read(file);
+  const line = head.split('\n').find((l) => l.includes('session_meta'));
+  if (!line) return null;
+  try {
+    const o = JSON.parse(line);
+    return o.payload?.cwd ?? o.cwd ?? null;
+  } catch {
+    return null;
+  }
+}
+
+// Every *.jsonl under a Codex sessions dir whose recorded cwd matches this
+// project. Bounded head-reads only; returns [] if the sessions dir is absent.
+export function codexFilesForCwd(sessionsDir, cwd, { read = readHead } = {}) {
+  if (!existsSync(sessionsDir)) return [];
+  const out = [];
+  const walk = (dir) => {
+    for (const e of readdirSync(dir, { withFileTypes: true })) {
+      const p = join(dir, e.name);
+      if (e.isDirectory()) walk(p);
+      else if (e.name.endsWith('.jsonl') && codexFileCwd(p, read) === cwd) out.push(p);
+    }
+  };
+  walk(sessionsDir);
+  return out;
+}
+
+// Prefer the pinned ccusage dependency (offline, version-locked); fall back to
+// npx when resolution fails (e.g. a hoisting layout we can't see). Mirrors
+// init.mjs's skillsInvocation so the two behave the same across install shapes.
+export function ccusageInvocation(pkgRoot, args) {
+  try {
+    const require = createRequire(join(pkgRoot, 'package.json'));
+    const manifest = require('ccusage/package.json');
+    const rel = typeof manifest.bin === 'string' ? manifest.bin : manifest.bin.ccusage;
+    const entry = join(dirnameOf(require.resolve('ccusage/package.json')), rel);
+    return { command: process.execPath, args: [entry, ...args] };
+  } catch {
+    return {
+      command: process.platform === 'win32' ? 'npx.cmd' : 'npx',
+      args: ['--yes', 'ccusage@latest', ...args],
+      shell: process.platform === 'win32',
+    };
+  }
+}
+
+function dirnameOf(file) {
+  return file.slice(0, Math.max(file.lastIndexOf('/'), file.lastIndexOf('\\')));
+}
+
+// Materialise one source file into the scoped tree. Hardlink first — it is
+// instant, uses no extra disk, and (unlike a symlink or junction) is a real
+// directory entry that ccusage's globber traverses on Windows, where symlinked
+// and junctioned dirs are silently skipped. Copy is the cross-volume fallback
+// (hardlinks can't span drives). Creates parent dirs as needed.
+function linkFile(src, dst) {
+  mkdirSync(dirname(dst), { recursive: true });
+  try {
+    linkSync(src, dst);
+  } catch {
+    copyFileSync(src, dst);
+  }
+}
+
+// Every *.jsonl under a dir, as [absolutePath, relativePath] pairs so the scoped
+// copy can preserve Claude's per-project subdir layout.
+function jsonlFiles(dir, base = dir, out = []) {
+  for (const e of readdirSync(dir, { withFileTypes: true })) {
+    const p = join(dir, e.name);
+    if (e.isDirectory()) jsonlFiles(p, base, out);
+    else if (e.name.endsWith('.jsonl')) out.push([p, relative(base, p)]);
+  }
+  return out;
+}
+
+// Build a throwaway config root scoped to this project, for both agents. Always
+// returns { root, env, cleanup }: env carries CLAUDE_CONFIG_DIR + CODEX_HOME
+// pointing at the scoped roots, so unset agents report zero rather than leaking
+// global data. `found` says whether any agent had data for this project.
+//
+// Files are hardlinked (see linkFile) rather than the dir symlinked, because
+// ccusage does not traverse symlinked/junctioned directories on Windows.
+export function buildScopedEnv(
+  { claudeDir, codexSessionsDir: codexDir, cwd },
+  { mkdtemp = defaultMkdtemp, linkFn = linkFile, codexFiles = codexFilesForCwd } = {},
+) {
+  const root = mkdtemp();
+
+  // Claude: hardlink this project's transcripts under projects/proj/, keeping
+  // any subdir structure so ccusage sees them exactly as it would in place.
+  const claudeConfig = join(root, 'claude');
+  const claudeProj = join(claudeConfig, 'projects', 'proj');
+  mkdirSync(claudeProj, { recursive: true });
+  let found = false;
+  if (claudeDir && existsSync(claudeDir)) {
+    for (const [abs, rel] of jsonlFiles(claudeDir)) {
+      linkFn(abs, join(claudeProj, rel));
+      found = true;
+    }
+  }
+
+  // Codex: hardlink only the session files whose cwd matches this project,
+  // flattened under sessions/ (ccusage globs recursively, so layout is moot).
+  const codexHome = join(root, 'codex');
+  const codexSessions = join(codexHome, 'sessions');
+  mkdirSync(codexSessions, { recursive: true });
+  const matches = codexDir ? codexFiles(codexDir, cwd) : [];
+  matches.forEach((f, i) => linkFn(f, join(codexSessions, `${i}-${basename(f)}`)));
+  if (matches.length > 0) found = true;
+
+  return {
+    root,
+    found,
+    env: { ...process.env, CLAUDE_CONFIG_DIR: claudeConfig, CODEX_HOME: codexHome },
+    cleanup: () => rmSync(root, { recursive: true, force: true }),
+  };
+}
+
+function defaultMkdtemp() {
+  return mkdtempSync(join(tmpdir(), 'comate-usage-'));
+}
+
+// Split comate's own flags (--global) from everything else, which is forwarded
+// to ccusage untouched. Default subcommand is `session` — the per-conversation
+// view is what "how much did this project cost" usually means.
+export function parseArgs(argv) {
+  const global = argv.includes('--global');
+  const rest = argv.filter((a) => a !== '--global');
+  const hasCommand = rest.length > 0 && !rest[0].startsWith('-');
+  const forwarded = hasCommand ? rest : ['session', ...rest];
+  return { global, forwarded };
+}
+
+export async function usage(argv, { pkgRoot = defaultPkgRoot() } = {}) {
+  const { global, forwarded } = parseArgs(argv);
+
+  let scoped = null;
+  let env = process.env;
+  if (!global) {
+    const cwd = process.cwd();
+    scoped = buildScopedEnv({
+      claudeDir: claudeDataDir(cwd),
+      codexSessionsDir: codexSessionsDir(),
+      cwd,
+    });
+    if (!scoped.found) {
+      scoped.cleanup();
+      console.error(
+        '本项目暂无 Claude Code / Codex 会话记录。\n' +
+          '用  comate usage --global  查看全部项目的用量。',
+      );
+      return 1;
+    }
+    env = scoped.env;
+  }
+
+  try {
+    const { command, args, shell } = ccusageInvocation(pkgRoot, forwarded);
+    const { status, error } = spawnSync(command, args, {
+      stdio: 'inherit',
+      env,
+      ...(shell ? { shell: true } : {}),
+    });
+    if (error) {
+      console.error(`无法运行 ccusage：${error.message}\n试试  npx ccusage@latest`);
+      return 1;
+    }
+    return status ?? 1;
+  } finally {
+    scoped?.cleanup();
+  }
+}
+
+function defaultPkgRoot() {
+  return dirnameOf(dirnameOf(import.meta.url.replace(/^file:\/\/\/?/, '')));
+}

package/docs/COMATE_MANUAL.md

@@ -43,7 +43,7 @@ comate 是一个规约驱动、AI 辅助的开发编排器。它将 **OpenSpec**
 
 流程链：(gate ->) open -> design -> build -> verify -> archive
 
-**阶段 0（可选，PRD 门禁与拆分）**：需求来自一份**原始 PRD**时，先过 `/comate-gate`：审阅 PRD 质量、百分制评分、建阻断台账，门禁通过前禁止建任何 change；通过后按依赖/整体性/独立性/规模把 PRD 拆成 1 或 N 个 change（粒度由用户定），逐个交给 `/comate-open`。门禁状态钉在 PRD 同级 `<PRD>.gate.yaml`（机器真相源），评审报告为 `PRD-REVIEW-<PRD名>.md`（人类可读）。PRD 通过门禁后被改会因哈希漂移自动失效（stale），需重跑 gate。需求来自对话时无需此阶段。
+**阶段 0（可选，PRD 门禁与拆分）**：需求来自一份**原始 PRD**时，先过 `/comate-gate`：审阅 PRD 质量、百分制评分、建阻断台账，门禁通过前禁止建任何 change；通过后按依赖/整体性/独立性/规模把 PRD 拆成 1 或 N 个 change（粒度由用户定），逐个交给 `/comate-open`。门禁状态钉在 PRD 同级 `PRD-<NNN>.gate.yaml`（如 `PRD-001.gate.yaml`，机器真相源），评审报告为 `PRD-<NNN>-REVIEW.md`（如 `PRD-001-REVIEW.md`，人类可读）。PRD 通过门禁后被改会因哈希漂移自动失效（stale），需重跑 gate。需求来自对话时无需此阶段。
 
 单次 `/comate` 调用从检测到的阶段开始，当退出条件满足时推进到下一阶段。智能体会自动推进后续阶段，但必须在决策阻塞点暂停，直到收到用户确认。
 
@@ -72,6 +72,8 @@ comate 是一个规约驱动、AI 辅助的开发编排器。它将 **OpenSpec**
 | `/comate-grill` | 工具 | Claude | 决策台账（逐决策点澄清，附推荐 + 用户答案） |
 | `/comate-kb-integration` | 工具 | Claude | 第三方对接档案（从官方文档 URL 生成 integrations 目录档案 + 索引行） |
 
+此外，终端命令 `comate usage` 查看当前项目的 token 用量与估算成本（见 §2.7）。
+
 ---
 
 ## 2. 安装与前置条件
@@ -172,6 +174,29 @@ skills/
 
 ---
 
+### 2.7 Token 用量：`comate usage`
+
+终端命令，查看**当前项目**的 token 消耗与估算成本。封装 [ccusage](https://github.com/ryoppippi/ccusage)——它作为 comate 的依赖随包安装，`comate doctor` 会检测其可用性（缺失时回退 `npx ccusage@latest`）。
+
+```bash
+comate usage            # 本项目按会话(session)统计（默认）
+comate usage daily      # 本项目按天
+comate usage --global   # 全部项目，不做项目隔离
+comate usage codex daily            # 单看某个 agent
+comate usage --json -s 2026-08-01   # 其余参数原样透传给 ccusage
+```
+
+**项目隔离原理**：ccusage 默认全局聚合、无项目过滤。comate 在临时目录里为当前项目重建一个 scoped 配置根，用 `CLAUDE_CONFIG_DIR` + `CODEX_HOME` 指过去，命令结束即清理：
+
+- **Claude Code**：数据本就按 `~/.claude/projects/<编码 cwd>/` 分目录，硬链接本项目那一个目录的 `*.jsonl` 进 scoped 根。
+- **Codex**：数据按日期平铺（`~/.codex/sessions/YYYY/MM/DD/`），项目路径藏在每个文件的 `session_meta.cwd`，故按 `cwd` 过滤后硬链接命中的文件。
+
+用硬链接而非目录 symlink/junction：Windows 下 ccusage 的文件扫描不遍历 symlink/junction 目录，硬链接则表现为真实文件。硬链接跨盘失败时回退复制。两个 agent 的 scoped 根都会设，未命中的 agent 报 0 而非泄漏全局数据。
+
+**边界**：粒度到项目/会话级，不做 open/design/build 阶段级归因（需在状态机流转处打时间戳，属后续增强）。
+
+---
+
 ## 3. 快速开始
 
 ### 3.1 基本用法
@@ -561,7 +586,7 @@ bash "$COMATE" doctor
 
 ### gate - PRD 门禁（阶段 0）
 
-对**原始 PRD** 做质量门禁，通过前禁止从该 PRD 建 change。状态钉在 PRD 同级 `<PRD>.gate.yaml`（独立于 change 的 `.comate.yaml`），评审报告为 `PRD-REVIEW-<PRD名>.md`。由 `/comate-gate` 驱动。
+对**原始 PRD** 做质量门禁，通过前禁止从该 PRD 建 change。状态钉在 PRD 同级 `PRD-<NNN>.gate.yaml`（如 `PRD-001.gate.yaml`，独立于 change 的 `.comate.yaml`），评审报告为 `PRD-<NNN>-REVIEW.md`（如 `PRD-001-REVIEW.md`）。由 `/comate-gate` 驱动。
 
 | 命令 | 描述 |
 |---------|-------------|

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@house365/comate",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "comate —— OpenSpec + Superpowers 规约驱动的 AI 开发编排器（Agent Skills）",
   "type": "module",
   "license": "MIT",
@@ -41,11 +41,12 @@
     "node": ">=20"
   },
   "dependencies": {
+    "ccusage": "^20.0.19",
     "skills": "^1.5.21"
   },
   "scripts": {
     "postinstall": "node bin/postinstall.mjs",
-    "test": "node bin/init.test.mjs && bash skills/comate/tests/run.sh",
+    "test": "node bin/init.test.mjs && node bin/usage.test.mjs && bash skills/comate/tests/run.sh",
     "doctor": "cd skills && bash comate/scripts/comate.sh doctor",
     "prepublish-check": "node scripts/prepublish-check.mjs",
     "pack-check": "node scripts/pack-check.mjs",

package/skills/comate/scripts/comate-lib.sh

@@ -460,23 +460,40 @@ declare -A GATE_ENUMS=(
   [gate_status]="reviewing blocked passed passed-with-tbd stale"
 )
 
+# gate_stem_for <prd> — derive the short stem used to name a PRD's gate.yaml
+# and review report. A conforming PRD file is `PRD-<NNN>-<title>.md`, whose
+# gate/report drop the title and key off `PRD-<NNN>` (so one dir with
+# PRD-001/PRD-002 gets PRD-001.gate.yaml / PRD-002.gate.yaml). Non-conforming
+# names (no PRD-NNN prefix) fall back to the full basename so callers still get
+# a stable, collision-free stem instead of an error.
+gate_stem_for() {
+  local base
+  base=$(basename "$1")
+  base="${base%.markdown}"
+  base="${base%.md}"
+  if [[ "$base" =~ ^([Pp][Rr][Dd]-[0-9]+) ]]; then
+    echo "${BASH_REMATCH[1]}"
+  else
+    echo "$base"
+  fi
+}
+
 # gate_path_for <prd> — echo the gate.yaml path adjacent to the PRD.
-# Strips a trailing .md/.markdown and appends .gate.yaml.
+# Named `<stem>.gate.yaml` where stem is PRD-<NNN> (see gate_stem_for).
 gate_path_for() {
-  local prd="$1" base
-  base="${prd%.markdown}"
-  base="${base%.md}"
-  echo "${base}.gate.yaml"
+  local prd="$1" dir stem
+  dir=$(dirname "$prd")
+  stem=$(gate_stem_for "$prd")
+  echo "${dir}/${stem}.gate.yaml"
 }
 
 # gate_report_for <prd> — echo the review report path (PRD same dir).
+# Named `<stem>-REVIEW.md` where stem is PRD-<NNN> (see gate_stem_for).
 gate_report_for() {
-  local prd="$1" dir base
+  local prd="$1" dir stem
   dir=$(dirname "$prd")
-  base=$(basename "$prd")
-  base="${base%.markdown}"
-  base="${base%.md}"
-  echo "${dir}/PRD-REVIEW-${base}.md"
+  stem=$(gate_stem_for "$prd")
+  echo "${dir}/${stem}-REVIEW.md"
 }
 
 # gate_yaml_set <file> <key> <value> — gate-file analogue of yaml_set: validate

package/skills/comate/tests/comate.bats

@@ -454,13 +454,25 @@ seed_prd() {
   local prd; prd=$(seed_prd)
   run comate gate "$prd" review
   [ "$status" -eq 0 ]
-  [ -f "docs/knowledge-base/requirements/test/PRD-001-demo.gate.yaml" ]
+  [ -f "docs/knowledge-base/requirements/test/PRD-001.gate.yaml" ]
+}
+
+@test "gate names key off PRD-NNN stem, dropping title" {
+  local prd; prd=$(seed_prd)
+  run comate gate "$prd" review
+  [ "$status" -eq 0 ]
+  # gate.yaml and review report drop the -demo title, key off PRD-001
+  [ -f "docs/knowledge-base/requirements/test/PRD-001.gate.yaml" ]
+  [ ! -f "docs/knowledge-base/requirements/test/PRD-001-demo.gate.yaml" ]
+  [[ "$output" == *"PRD-001-REVIEW.md"* ]]
+  grep -q "review_report: docs/knowledge-base/requirements/test/PRD-001-REVIEW.md" \
+    "docs/knowledge-base/requirements/test/PRD-001.gate.yaml"
 }
 
 @test "gate review writes reviewing status and pins prd_hash" {
   local prd; prd=$(seed_prd)
   comate gate "$prd" review >/dev/null
-  local gate="docs/knowledge-base/requirements/test/PRD-001-demo.gate.yaml"
+  local gate="docs/knowledge-base/requirements/test/PRD-001.gate.yaml"
   run comate gate "$prd" status
   [ "$status" -eq 0 ]
   [[ "$output" == *"reviewing"* ]]
@@ -502,7 +514,7 @@ seed_prd() {
   comate gate "$prd" set score 90 >/dev/null
   comate gate "$prd" set blocking_open 0 >/dev/null
   printf '# 评审报告\n' > \
-    "docs/knowledge-base/requirements/test/PRD-REVIEW-PRD-001-demo.md"
+    "docs/knowledge-base/requirements/test/PRD-001-REVIEW.md"
   run comate gate "$prd" pass
   [ "$status" -eq 0 ]
   run comate gate "$prd" check
@@ -515,7 +527,7 @@ seed_prd() {
   comate gate "$prd" set score 65 >/dev/null
   comate gate "$prd" set blocking_open 0 >/dev/null
   printf '# 评审报告\n' > \
-    "docs/knowledge-base/requirements/test/PRD-REVIEW-PRD-001-demo.md"
+    "docs/knowledge-base/requirements/test/PRD-001-REVIEW.md"
   run comate gate "$prd" pass --tbd
   [ "$status" -eq 0 ]
   run comate gate "$prd" status
@@ -528,7 +540,7 @@ seed_prd() {
   comate gate "$prd" set score 90 >/dev/null
   comate gate "$prd" set blocking_open 0 >/dev/null
   printf '# 评审报告\n' > \
-    "docs/knowledge-base/requirements/test/PRD-REVIEW-PRD-001-demo.md"
+    "docs/knowledge-base/requirements/test/PRD-001-REVIEW.md"
   comate gate "$prd" pass >/dev/null
   # mutate PRD after passing
   printf '\n额外内容\n' >> "$prd"
@@ -543,14 +555,14 @@ seed_prd() {
   comate gate "$prd" set score 90 >/dev/null
   comate gate "$prd" set blocking_open 0 >/dev/null
   printf '# 评审报告\n' > \
-    "docs/knowledge-base/requirements/test/PRD-REVIEW-PRD-001-demo.md"
+    "docs/knowledge-base/requirements/test/PRD-001-REVIEW.md"
   comate gate "$prd" pass >/dev/null
   printf '\n改动\n' >> "$prd"
   run comate gate "$prd" status
   [ "$status" -eq 0 ]
   [[ "$output" == *"stale"* ]]
   # gate.yaml should still say passed (status is computed, not written by status cmd)
-  local gate="docs/knowledge-base/requirements/test/PRD-001-demo.gate.yaml"
+  local gate="docs/knowledge-base/requirements/test/PRD-001.gate.yaml"
   local stored; stored=$(grep '^gate_status:' "$gate" | awk '{print $2}')
   [ "$stored" = "passed" ]
 }
@@ -561,11 +573,11 @@ seed_prd() {
   comate gate "$prd" set score 90 >/dev/null
   comate gate "$prd" set blocking_open 0 >/dev/null
   printf '# 报告\n' > \
-    "docs/knowledge-base/requirements/test/PRD-REVIEW-PRD-001-demo.md"
+    "docs/knowledge-base/requirements/test/PRD-001-REVIEW.md"
   comate gate "$prd" pass >/dev/null
   run comate gate "$prd" spawned login-flow
   [ "$status" -eq 0 ]
-  local gate="docs/knowledge-base/requirements/test/PRD-001-demo.gate.yaml"
+  local gate="docs/knowledge-base/requirements/test/PRD-001.gate.yaml"
   local sc; sc=$(grep '^spawned_changes:' "$gate" | sed 's/spawned_changes: //')
   [[ "$sc" == *"login-flow"* ]]
 }
@@ -576,11 +588,11 @@ seed_prd() {
   comate gate "$prd" set score 90 >/dev/null
   comate gate "$prd" set blocking_open 0 >/dev/null
   printf '# 报告\n' > \
-    "docs/knowledge-base/requirements/test/PRD-REVIEW-PRD-001-demo.md"
+    "docs/knowledge-base/requirements/test/PRD-001-REVIEW.md"
   comate gate "$prd" pass >/dev/null
   comate gate "$prd" spawned login-flow >/dev/null
   comate gate "$prd" spawned logout-flow >/dev/null
-  local gate="docs/knowledge-base/requirements/test/PRD-001-demo.gate.yaml"
+  local gate="docs/knowledge-base/requirements/test/PRD-001.gate.yaml"
   local sc; sc=$(grep '^spawned_changes:' "$gate" | sed 's/spawned_changes: //')
   [[ "$sc" == *"login-flow"* ]]
   [[ "$sc" == *"logout-flow"* ]]
@@ -605,7 +617,7 @@ seed_prd() {
   comate gate "$prd" set score 90 >/dev/null
   comate gate "$prd" set blocking_open 0 >/dev/null
   printf '# 报告\n' > \
-    "docs/knowledge-base/requirements/test/PRD-REVIEW-PRD-001-demo.md"
+    "docs/knowledge-base/requirements/test/PRD-001-REVIEW.md"
   comate gate "$prd" pass >/dev/null
   printf '\n改动\n' >> "$prd"
   # re-run review after PRD change — should reset to reviewing

package/skills/comate-gate/SKILL.md

@@ -17,7 +17,7 @@ description: "comate 阶段 0：PRD 门禁与拆分。用 /comate-gate 调用。
 
 ## 核心铁律
 
-- **门禁状态是可验证的文件真相源**：钉在 PRD 同级 `<PRD>.gate.yaml`。评审报告 `PRD-REVIEW-<PRD名>.md` 是给人看的派生物，**不是**状态源。
+- **门禁状态是可验证的文件真相源**：钉在 PRD 同级 `<PRD-NNN>.gate.yaml`（如 `PRD-001.gate.yaml`）。评审报告 `<PRD-NNN>-REVIEW.md`（如 `PRD-001-REVIEW.md`）是给人看的派生物，**不是**状态源。
 - **AskUserQuestion 是真阻塞点**：文字提示、推荐方案、默认值、历史偏好、用户未反对，都**不能**替代明确回答。
 - **只审不改**：门禁只暴露 PRD 问题，不替 PRD 补内容、不替产品拍板。
 - **门禁未通过禁止建 change**：`gate_status ∈ {passed, passed-with-tbd}` 且 PRD 哈希未漂移，才允许 comate-open 建 change（由 `gate check` 硬强制）。
@@ -59,6 +59,26 @@ bash "$COMATE" gate <prd> check                # comate-open 建 change 前的
 - 读取后重点提取：**功能清单**（各功能项 + 优先级 P0/P1/P2）、**范围（In/Out）**、**第三方依赖**、**验收标准**、文档状态。
 - 若 PRD 明显未定稿（状态字段非「已定稿」等），用 **AskUserQuestion** 提示可能未冻结并暂停确认；确认前只审阅，不建 gate。
 
+### 1.5 命名规范化（前置，定位到 PRD 即检测）
+
+用户一旦指到 `docs/knowledge-base/requirements/` 下的文件，**先检测命名是否规范，再进门禁**——因为 gate.yaml 与评审报告的名字都从 PRD 的 `PRD-<NNN>` 前缀派生，名字不规范会连带派生错。comate 只有 PRD 一层（无 MRD/FRD、无固定负责人），只查这三样：
+
+| 对象 | 规范 | 反例 → 规范名 |
+|------|------|--------------|
+| 功能目录 | `<YYYYMMDD-功能名>/` | `图片素材管理/` → `20260614-图片素材管理/` |
+| PRD 文件 | 目录内 `PRD-<三位序号>-<功能名>.md`（序号紧跟类型在前） | `图片素材管理_PRD_V1.md` → `PRD-001-图片素材管理.md`；`PRD-1.md` → `PRD-001-图片素材管理.md` |
+| 派生文件 | `PRD-<NNN>.gate.yaml`、`PRD-<NNN>-REVIEW.md`（脚本自动按 PRD-NNN 前缀生成，无需手动命名） | 旧式 `PRD-001-图片素材管理.gate.yaml`、`PRD-REVIEW-PRD-001-图片素材管理.md` → 迁移到新名 |
+
+**检测到不规范时**（顺序很重要，避免断链）：
+
+1. 先 **Grep** 全仓搜旧文件名/旧路径的所有引用（正文、其它文档、`.comate.yaml` 的 `source_manifest`、gate.yaml 的 `prd_path`/`review_report`）。
+2. 用 **AskUserQuestion** 给出「旧名 → 建议新名」让用户确认（改名影响引用，不自作主张；功能名/日期推断不出时一并问）。
+3. 确认后 **`git mv`** 改名（目录、PRD 文件；已存在的旧 gate.yaml/报告一并 `git mv` 到新名），保留 git 历史，**不要** Write 新文件+删旧。
+4. **Edit** 把第 1 步搜到的引用全部改成新名/新路径。
+5. 再 **Grep** 一次旧名确认零残留。
+
+已规范或用户确认改名后，才进第 2 步门禁——此时 `gate review` 生成的 gate.yaml/报告自然是新名。若 PRD 名已规范，本步无操作，直接进门禁。
+
 ### 2. 门禁：质量审阅 + 评分（不可跳过）
 
 先初始化 gate（钉当前 PRD 哈希、拿到报告路径）：
@@ -88,7 +108,7 @@ bash "$COMATE" gate <prd> review
 - **仓库事实**（已有架构约定、字段、接口、对接档案）：先用 Read/Glob/rg 核实并引用来源，不丢给用户决定。
 - **产品决策**（范围、优先级、用户可见行为、状态流转、权限、数据口径、失败处理、验收规则）：必须用 **AskUserQuestion** 问用户，不得用推荐方案/历史偏好/「待确认」代替确认。
 
-**写评审报告（必生成）** 到 `gate review` 回显的 `review_report` 路径（PRD 同级 `PRD-REVIEW-<PRD名>.md`）。内容含：评分 + 评级 + 一句话总评、问题台账表（`ID` / 维度 / 严重程度 / 原文依据 / 影响章节 / 是否阻断 / 建议 / 产品回填列）、逐条问题。若无问题，明确写「审阅通过，未发现阻断项」。
+**写评审报告（必生成）** 到 `gate review` 回显的 `review_report` 路径（PRD 同级 `<PRD-NNN>-REVIEW.md`，如 `PRD-001-REVIEW.md`）。内容含：评分 + 评级 + 一句话总评、问题台账表（`ID` / 维度 / 严重程度 / 原文依据 / 影响章节 / 是否阻断 / 建议 / 产品回填列）、逐条问题。若无问题，明确写「审阅通过，未发现阻断项」。
 
 **阻断规则**：影响范围、用户行为、状态流转、数据契约、权限、异常处理或验收标准的问题标「阻断」。把当前未关闭的阻断问题数写入 gate：
 

package/skills/comate-gate/scaffold/docs/knowledge-base/README.md

@@ -8,9 +8,9 @@
 docs/knowledge-base/requirements/
   ├─ _templates/              PRD 模板
   └─ <YYYYMMDD-功能名>/        一个功能一个目录,日期=该功能起始日   ──┐
-       ├─ PRD-001-<功能名>.md           产品需求文档                  │
-       ├─ PRD-001-<功能名>.gate.yaml    门禁状态(机器真相源)          │
-       ├─ PRD-REVIEW-PRD-001-<功能名>.md 门禁评审报告(人类可读)       │
+       ├─ PRD-001-<功能名>.md          产品需求文档                  │
+       ├─ PRD-001.gate.yaml            门禁状态(机器真相源)          │
+       ├─ PRD-001-REVIEW.md            门禁评审报告(人类可读)        │
        └─ CHANGES-MAP.md               (多 change 时)功能项→change 映射 │
                                                                     ├─→ /comate-gate (门禁+拆分)
 docs/knowledge-base/integrations/                                   │         ↓
@@ -24,7 +24,7 @@ comate 采用**简化需求流**:只保留 **PRD**(产品需求文档),通过 `/
 1. **门禁**:审阅 PRD 质量、百分制评分、建阻断台账。阻断问题未清零,禁止建任何 change。
 2. **拆分**:按依赖/整体性/独立性/规模判定该 PRD 变成 1 或 N 个 comate change(粒度由用户定),逐个交给 `/comate-open`。
 
-PRD 门禁状态钉在同级 `<PRD名>.gate.yaml`(机器真相源,含 `gate_status` / `score` / `blocking_open` / `prd_hash` / `spawned_changes`)。评审报告为 `PRD-REVIEW-<PRD名>.md`(人类可读,含问题台账)。PRD 通过门禁后被改会因哈希漂移自动失效(`stale`),需重跑 gate。
+PRD 门禁状态钉在同级 `PRD-<三位序号>.gate.yaml`(机器真相源,含 `gate_status` / `score` / `blocking_open` / `prd_hash` / `spawned_changes`)。评审报告为 `PRD-<三位序号>-REVIEW.md`(人类可读,含问题台账)。PRD 通过门禁后被改会因哈希漂移自动失效(`stale`),需重跑 gate。
 
 扇出的 comate change 内部用 proposal / design / tasks 承接 PRD 的功能项内容——**不再产独立 FRD 文档**,PRD 直接作为 change 的源文档被 `sources track` 钉住。
 
@@ -32,8 +32,8 @@ PRD 门禁状态钉在同级 `<PRD名>.gate.yaml`(机器真相源,含 `gate_stat
 
 - 功能目录: `<YYYYMMDD-功能名>/`,日期为该功能需求起始日,功能名用中文短名,如 `20260805-积分商城/`
 - PRD: 目录内 `PRD-<三位序号>-<功能名>.md`,功能名用目录功能名,如 `PRD-001-积分商城.md`
-- gate: 自动生成,`PRD-<三位序号>-<功能名>.gate.yaml`,与 PRD 同级
-- 评审报告: 自动生成,`PRD-REVIEW-PRD-<三位序号>-<功能名>.md`,与 PRD 同级
+- gate: 自动生成,`PRD-<三位序号>.gate.yaml`(去 title,只用 PRD-NNN),与 PRD 同级,如 `PRD-001.gate.yaml`
+- 评审报告: 自动生成,`PRD-<三位序号>-REVIEW.md`,与 PRD 同级,如 `PRD-001-REVIEW.md`
 
 ## 横向 (integrations/)