@xulthekl/team-flow 0.60.0 → 0.62.0

package/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "team-flow",
   "description": "Unified workflow plugin: team-flow (spec-driven dev) + compound-engineering core subset + architecture-design (4A/DDD) + prototype (local HTML) + business-analysis (independent requirement/scenario artifact) + jarvis (team-flow decision agent, opt-in). 28 skills, one install.",
-  "version": "0.60.0",
+  "version": "0.62.0",
   "contextFileName": "GEMINI.md"
 }

package/hooks/session-start

@@ -1,11 +1,11 @@
 #!/usr/bin/env bash
-# v0.60.0: auto-sync CLI version with plugin version
+# v0.62.0: auto-sync CLI version with plugin version
 set -e
 
 # ═══════════════════════════════════════════════════════════════
 # Plugin version (update this when releasing new versions)
 # ═══════════════════════════════════════════════════════════════
-PLUGIN_VERSION="0.60.0"
+PLUGIN_VERSION="0.62.0"
 
 # ═══════════════════════════════════════════════════════════════
 # Step 1: Auto-sync CLI version with plugin version

package/llms.txt

@@ -3,7 +3,7 @@
 ## Overview
 spec-superflow is a self-contained workflow integration plugin for Claude Code, Cursor, OpenAI Codex CLI/App, GitHub Copilot CLI, Gemini CLI, OpenCode, WorkBuddy, and Trae. It merges spec-driven planning artifacts (proposal, specs, design, tasks) with disciplined execution guardrails (TDD, review gates, controlled handoff) into one unified workflow.
 
-Current version: v0.60.0.
+Current version: v0.62.0.
 
 ## Key Documents
 - README.md: Chinese homepage with full usage guide and FAQ

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xulthekl/team-flow",
-  "version": "0.60.0",
+  "version": "0.62.0",
   "description": "Unified plugin (28 skills + 17 agents) integrating team-flow, compound-engineering, architecture-design, prototype, design-system, workflow-orchestrator, workflow-bootstrap, e2e, session-handoff, workflow-feedback, business-analysis for multi-agent coding tools.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "team-flow",
-  "version": "0.60.0",
+  "version": "0.62.0",
   "description": "Unified workflow plugin: team-flow (spec-driven dev: TDD/SDD/code-review/debugging) + compound-engineering core subset (brainstorm/plan/compound/strategy/ideate/proof, global compounding) + architecture-design (4A+DDD incremental design & global compounding) + prototype (local HTML prototype, zero external deps) + e2e (Playwright E2E, AC-driven) + workflow-orchestrator (product-level workflow orchestration) + workflow-bootstrap (existing project onboarding) + session-handoff (context transfer) + workflow-feedback (issue tracking) + business-analysis (independent requirement/scenario artifact) + design-system (design tokens + component contract + AI primer + showcase) + test-strategy (test strategy design) + project-initialize (new service onboarding) + jarvis (team-flow decision agent, opt-in). 28 skills + 17 agents, one install.",
   "author": {
     "name": "LT"

package/scripts/check-project-config.mjs

@@ -14,16 +14,25 @@
 //   零消费者：`prototype.designSystemC` / `prototype.versionWorktree`（全仓无引用）
 // → 前两类做**存在性检查**；后两类只报"未被消费"（不是错误，是配置残留）。
 //
+// ── v0.62.0 新增维度⑤：PRD 模板漂移（F3）─────────────────────────────────────
+//   动机同 F1 的根因：模板副本会随时间落后且**无任何提示**（项目侧无感知）。
+//   真消费点（`prd.template` 指向项目内文件）→ 与插件内置比对，落后给两条出路；
+//   零消费者（`.team-flow/templates/` 有副本但 config 未指向）→ 报"影子副本未被消费"。
+//   **exit 0 不阻断**——与既有语义一致：提示而非门禁。
+//
 // Usage: node scripts/check-project-config.mjs [项目根，默认 cwd]
 // 退出码：0 = 正常（含仅警告）；1 = 配置存在但不可解析
 
 import { readFileSync, existsSync } from 'node:fs';
 import { resolve, join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { resolveConfigWritePath } from './lib/config-loader.mjs';
+import { hashTemplateFile, shortHash } from './lib/template-hash.mjs';
 
 const PLUGIN_DIR = dirname(dirname(fileURLToPath(import.meta.url)));
 const root = resolve(process.argv[2] || process.cwd());
-const cfgPath = join(root, '.team-flow', 'team-flow.config.json');
+// v0.62.0（G5 对齐）：改用与读取一致的解析（原硬编码只读 .team-flow/，会漏掉 legacy 根目录配置）
+const cfgPath = resolveConfigWritePath(root) || join(root, '.team-flow', 'team-flow.config.json');
 
 if (!existsSync(cfgPath)) {
   console.log(`ℹ️  未找到 ${cfgPath}（跳过配置漂移检查）`);
@@ -74,6 +83,48 @@ if (cfg.version) {
   }
 }
 
+// ⑤ PRD 模板漂移（v0.62.0 · F3）
+{
+  const prd = cfg.prd || {};
+  const tplCfg = prd.template;
+  const builtinTpl = join(PLUGIN_DIR, 'templates', 'prd.md');
+  const shadowTpl = join(root, '.team-flow', 'templates', 'prd.md');
+  const shadowProfile = join(root, '.team-flow', 'templates', 'prd-brainstorm-profile.md');
+
+  if (tplCfg) {
+    // 真消费点：config 显式指向某模板
+    const tplPath = resolve(root, tplCfg);
+    if (!existsSync(tplPath)) {
+      warnings.push(`prd.template 指向的路径不存在：${tplCfg}（将导致撰写读不到模板）`);
+    } else {
+      const a = hashTemplateFile(tplPath);
+      const b = hashTemplateFile(builtinTpl);
+      if (a && b && a !== b) {
+        warnings.push(
+          `prd.template 指向的模板与插件内置**不一致**（配置 ${shortHash(a)} vs 内置 ${shortHash(b)}）。` +
+            `两条出路：① 保留定制 → 人工比对合并；② 回归内置 → tf config --set prd.template=templates/prd.md`
+        );
+      }
+      // profile 成对性（真消费点侧）
+      const pairedProfile = `${tplPath.slice(0, -3)}-brainstorm-profile.md`;
+      if (!existsSync(pairedProfile)) {
+        warnings.push(`模板 ${tplCfg} 未配套 brainstorm profile（期望同目录 …-brainstorm-profile.md），将回退内置 profile——二者应成对处置`);
+      }
+    }
+  } else if (existsSync(shadowTpl)) {
+    // 零消费者：有副本但 config 未指向
+    warnings.push(
+      `存在**未被消费的影子副本** .team-flow/templates/prd.md —— v0.62.0（F2）起默认改用插件内置模板，` +
+        `该副本不会被读取。建议删除；若确要定制，用 tf config --set prd.template=.team-flow/templates/prd.md 显式指向`
+    );
+    if (!existsSync(shadowProfile)) {
+      warnings.push(`影子副本未配套 profile：.team-flow/templates/ 下有 prd.md 但无 prd-brainstorm-profile.md（二者应成对处置）`);
+    }
+  } else if (existsSync(shadowProfile) && !existsSync(shadowTpl)) {
+    warnings.push(`.team-flow/templates/ 下有 prd-brainstorm-profile.md 但无 prd.md（二者应成对处置）`);
+  }
+}
+
 if (warnings.length === 0) {
   console.log(`✅ 配置无漂移（${cfgPath}）`);
   process.exit(0);

package/scripts/check-version-consistency.mjs

@@ -73,7 +73,7 @@ const TEXT_CHECKS = [
   { file: 'GEMINI.md',              extract: /# team-flow v(\d+\.\d+\.\d+) \|/ },
   // v0.59.0：新增 usage-guide 版本锚点（此前不在扫描面内，0.58.0 与 0.59.0 两次发版均靠人工改；
   // P3-15 ② 半项闭合——**检出**已覆盖，本段仍无 --fix 分支，自动修复待做）
-  { file: 'docs/usage-guide.md',    extract: /版本锚点：v(\d+\.\d+\.\d+)/ },
+  { file: 'docs/team-flow 使用说明（研发团队版）.md',    extract: /版本锚点：v(\d+\.\d+\.\d+)/ },
 ];
 
 for (const check of TEXT_CHECKS) {
@@ -165,7 +165,7 @@ for (const check of SKILL_COUNT_JSON_CHECKS) {
 const SKILL_COUNT_TEXT_CHECKS = [
   { file: 'README.md', extract: /(\d+) skills/, replace: (content, count) => content.replace(/(\d+) skills/, `${count} skills`) },
   { file: 'AGENTS.md', extract: /Skills 索引（(\d+) 个）/, replace: (content, count) => content.replace(/Skills 索引（(\d+) 个）/, `Skills 索引（${count} 个）`) },
-  { file: 'docs/usage-guide.md', extract: /(\d+) 个 skills/, replace: (content, count) => content.replace(/(\d+) 个 skills/, `${count} 个 skills`) },
+  { file: 'docs/team-flow 使用说明（研发团队版）.md', extract: /(\d+) 个 skills/, replace: (content, count) => content.replace(/(\d+) 个 skills/, `${count} 个 skills`) },
   { file: 'docs/platform-matrix.md', extract: /(\d+) 个 skill 部署/, replace: (content, count) => content.replace(/(\d+) 个 skill 部署/, `${count} 个 skill 部署`) },
   { file: 'INSTALL.md', extract: /应有 (\d+) 个 skill 目录/, replace: (content, count) => content.replace(/(\d+) 个 skill 目录/g, `${count} 个 skill 目录`) },
   { file: 'INSTALL.md', extract: /包含 (\d+) 个 skill、/, replace: (content, count) => content.replace(/(\d+) 个 skill、/, `${count} 个 skill、`) },

package/scripts/lib/cmd-config.mjs

@@ -1,7 +1,7 @@
 // tf config — display or modify configuration
-import { readFileSync, writeFileSync, existsSync } from 'node:fs';
-import { join } from 'node:path';
-import { loadConfig, getDefaults, resolveModelProfile } from './config-loader.mjs';
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { loadConfig, getDefaults, resolveModelProfile, resolveConfigWritePath } from './config-loader.mjs';
 
 export async function run(args) {
   const config = loadConfig(process.cwd());
@@ -60,8 +60,10 @@ export async function run(args) {
     else if (/^\d+$/.test(rawValue)) value = parseInt(rawValue, 10);
     else value = rawValue;
 
-    // Load existing config file or start from empty
-    const configPath = join(process.cwd(), 'team-flow.config.json');
+    // v0.62.0（G5）：写入路径改为与读取对齐（原固定写 `<cwd>/team-flow.config.json`，
+    // 而读取首选 `.team-flow/team-flow.config.json` 且首个命中即返回 → 静默无效）。
+    // 现在写 `findConfigFile()` 命中的文件；未命中则新建 `.team-flow/team-flow.config.json`。
+    const configPath = resolveConfigWritePath(process.cwd());
     let fileConfig = {};
     if (existsSync(configPath)) {
       fileConfig = JSON.parse(readFileSync(configPath, 'utf-8'));
@@ -78,8 +80,10 @@ export async function run(args) {
     }
     target[parts[parts.length - 1]] = value;
 
+    mkdirSync(dirname(configPath), { recursive: true });
     writeFileSync(configPath, JSON.stringify(fileConfig, null, 2) + '\n');
     console.log(`Set ${path} = ${JSON.stringify(value)}`);
+    console.log(`Written to: ${configPath}`);
     return;
   }
 

package/scripts/lib/cmd-prd.mjs

@@ -0,0 +1,225 @@
+// scripts/lib/cmd-prd.mjs — tf prd <sub>：PRD 模板一致性确认门（v0.62.0 · G6 / G1 / G2）
+//
+// 子命令分发照 `cmd-arch.mjs` / `cmd-runtime.mjs` 既有惯例。
+//
+// **为何需要原子命令（G6 的由来）**：
+//   ack 是「一组 hash + mode + 批准人/时间」的**复合状态**。用 `tf config --set` 逐字段写
+//   既无原子性（中途失败即半写），也无法表达「一组 hash 对应一次批准」的语义；
+//   且 `--set` 的值解析只认 bool/int/string，**不支持对象**（cmd-config.mjs:54-61）。
+//
+// **落点统一**：ack 一律写 `resolveConfigWritePath()` 命中的文件（= findConfigFile() 的读取结果），
+// 消除 v1.5 的「落点三方不一」（G2 写 .team-flow/、G5 写命中文件、check-project-config 只读 .team-flow/）。
+//
+// 另提供 `tf prd check`：用共享模块 `template-hash.mjs` 比对 hash 与 ack，
+// 供主会话 Phase 0.0 的阻塞提问（G1）取判据——**判据不在 skill 散文里另写一套**。
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { parseArgs } from 'node:util';
+import { loadConfig, resolveConfigWritePath } from './config-loader.mjs';
+import {
+  hashTemplateFile,
+  hashTemplatePair,
+  compareAgainstAck,
+  shortHash,
+} from './template-hash.mjs';
+
+const VALID_MODES = ['adopt_latest', 'keep_legacy'];
+
+export async function run(args) {
+  const { positionals, values } = parseArgs({
+    args,
+    options: {
+      json: { type: 'string' },
+      mode: { type: 'string' },
+      'in-use-hash': { type: 'string' },
+      'plugin-hash': { type: 'string' },
+      'spec-hash': { type: 'string' },
+      'plugin-version': { type: 'string' },
+      'diff-digest': { type: 'string' },
+      by: { type: 'string' },
+      'plugin-root': { type: 'string' },
+      'template-path': { type: 'string' },
+      'spec-path': { type: 'string' },
+    },
+    allowPositionals: true,
+  });
+
+  const sub = positionals[0];
+  if (sub === 'ack') return ack(positionals.slice(1), values);
+  if (sub === 'check') return check(values);
+  usage();
+}
+
+function usage() {
+  console.error(
+    'Usage:\n' +
+      '  tf prd ack set --json \'<ack object>\'      # 原子写入完整 ack 对象\n' +
+      '  tf prd ack set --mode adopt_latest --in-use-hash … [--plugin-hash …] [--spec-hash …]\n' +
+      '  tf prd ack show                            # 查看当前 ack\n' +
+      '  tf prd ack clear                           # 清除 ack（下次将重新提问）\n' +
+      '  tf prd check [--template-path <p>] [--plugin-root <p>]   # 比对 hash 与 ack，输出 STATUS'
+  );
+  process.exit(2);
+}
+
+/** 读原始配置文件（未与 DEFAULTS 合并），用于区分「用户显式配置」与「默认值」。 */
+function readRawConfig() {
+  const p = resolveConfigWritePath(process.cwd());
+  if (!p || !fs.existsSync(p)) return {};
+  try {
+    return JSON.parse(fs.readFileSync(p, 'utf-8'));
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * 解析「实际使用的模板」路径。
+ *
+ * F2 语义：未配置 `prd.template` → 插件内置；已配置 → 用户路径（相对则按项目根解析）。
+ * 因此必须读原始配置区分二者，不能用合并后的 loadConfig 结果判断。
+ */
+function resolveInUseTemplatePath(pluginRoot, explicit) {
+  if (explicit) {
+    return path.isAbsolute(explicit) ? explicit : path.join(process.cwd(), explicit);
+  }
+  const raw = readRawConfig();
+  const configured = raw?.prd?.template;
+  if (configured) {
+    return path.isAbsolute(configured) ? configured : path.join(process.cwd(), configured);
+  }
+  // 默认 = 插件内置
+  return pluginRoot ? path.join(pluginRoot, 'templates', 'prd.md') : null;
+}
+
+function resolvePluginRoot(values) {
+  return values['plugin-root'] || process.env.CLAUDE_PLUGIN_ROOT || null;
+}
+
+function ack(subArgs, values) {
+  const verb = subArgs[0];
+
+  if (verb === 'show') {
+    const cfg = loadConfig(process.cwd());
+    console.log(JSON.stringify(cfg.prd?.template_ack ?? {}, null, 2));
+    return;
+  }
+
+  if (verb === 'clear') {
+    const configPath = resolveConfigWritePath(process.cwd());
+    let fileConfig = {};
+    if (fs.existsSync(configPath)) fileConfig = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+    if (fileConfig.prd) fileConfig.prd.template_ack = {};
+    fs.mkdirSync(path.dirname(configPath), { recursive: true });
+    fs.writeFileSync(configPath, JSON.stringify(fileConfig, null, 2) + '\n');
+    console.log('ack cleared');
+    console.log(`Written to: ${configPath}`);
+    return;
+  }
+
+  if (verb !== 'set') usage();
+
+  // 组装 ack 对象：--json 优先（整体替换），否则逐字段
+  let patch = {};
+  if (values.json) {
+    try {
+      patch = JSON.parse(values.json);
+    } catch {
+      console.error('Invalid --json: not valid JSON');
+      process.exit(2);
+    }
+    if (!patch || typeof patch !== 'object' || Array.isArray(patch)) {
+      console.error('Invalid --json: expected an object');
+      process.exit(2);
+    }
+  } else {
+    if (values.mode) patch.mode = values.mode;
+    if (values['in-use-hash']) patch.in_use_hash = values['in-use-hash'];
+    if (values['plugin-hash']) patch.plugin_hash = values['plugin-hash'];
+    if (values['spec-hash']) patch.spec_hash = values['spec-hash'];
+    if (values['plugin-version']) patch.plugin_version = values['plugin-version'];
+    if (values['diff-digest']) patch.diff_digest = values['diff-digest'];
+  }
+
+  if (patch.mode && !VALID_MODES.includes(patch.mode)) {
+    console.error(`Invalid mode: ${patch.mode} (expected one of ${VALID_MODES.join(' | ')})`);
+    process.exit(2);
+  }
+  if (!values.json && !patch.mode) {
+    console.error('Missing --mode (required for field-wise set)');
+    process.exit(2);
+  }
+
+  // 补充留痕字段（谁 / 何时）
+  if (!patch.acknowledged_at) patch.acknowledged_at = new Date().toISOString();
+  if (!patch.acknowledged_by) patch.acknowledged_by = values.by || null;
+
+  // 原子写入：整块替换 prd.template_ack，一次 writeFileSync
+  const configPath = resolveConfigWritePath(process.cwd());
+  let fileConfig = {};
+  if (fs.existsSync(configPath)) fileConfig = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+  fileConfig.prd = fileConfig.prd || {};
+  fileConfig.prd.template_ack = patch;
+
+  fs.mkdirSync(path.dirname(configPath), { recursive: true });
+  fs.writeFileSync(configPath, JSON.stringify(fileConfig, null, 2) + '\n');
+  console.log('ack written');
+  console.log(`Written to: ${configPath}`);
+  return;
+}
+
+/**
+ * `tf prd check`：比对「实际使用模板 / 插件内置模板 / 规范文件」三个 hash 与 ack。
+ *
+ * 输出末行固定为 `STATUS: MATCH | MISMATCH | NO_ACK | UNRESOLVED`，供主会话 G1 取判据。
+ * **exit code 恒为 0**——本命令是判据工具，不是门禁；是否阻塞由主会话决定（G1）。
+ */
+function check(values) {
+  const pluginRoot = resolvePluginRoot(values);
+  const pluginTemplate = pluginRoot
+    ? path.join(pluginRoot, 'templates', 'prd.md')
+    : null;
+  const specPath =
+    values['spec-path'] ||
+    (pluginRoot
+      ? path.join(pluginRoot, 'skills', 'ce-brainstorm', 'references', 'prd-84-authoring-spec.md')
+      : null);
+
+  const inUsePath = resolveInUseTemplatePath(pluginRoot, values['template-path']);
+
+  const current = {
+    template_hash: hashTemplateFile(inUsePath),
+    spec_hash: hashTemplateFile(specPath),
+    plugin_hash: hashTemplateFile(pluginTemplate),
+  };
+
+  const cfg = loadConfig(process.cwd());
+  const ackObj = cfg.prd?.template_ack || {};
+
+  console.log('in_use      :', inUsePath ?? '(unresolved)');
+  console.log('            :', shortHash(current.template_hash));
+  console.log('plugin      :', pluginTemplate ?? '(unresolved)');
+  console.log('            :', shortHash(current.plugin_hash));
+  console.log('spec        :', specPath ?? '(unresolved)');
+  console.log('            :', shortHash(current.spec_hash));
+  console.log('ack         :', JSON.stringify({
+    in_use_hash: ackObj.in_use_hash ? shortHash(ackObj.in_use_hash) : null,
+    plugin_hash: ackObj.plugin_hash ? shortHash(ackObj.plugin_hash) : null,
+    spec_hash: ackObj.spec_hash ? shortHash(ackObj.spec_hash) : null,
+    mode: ackObj.mode ?? null,
+  }));
+
+  if (!inUsePath && !pluginTemplate) {
+    console.log('STATUS: UNRESOLVED');
+    return;
+  }
+  if (!ackObj.in_use_hash && !ackObj.plugin_hash && !ackObj.spec_hash) {
+    console.log('STATUS: NO_ACK');
+    return;
+  }
+
+  const { matched, changed } = compareAgainstAck(current, ackObj);
+  console.log('changed     :', changed.length ? changed.join(', ') : '(none)');
+  console.log(`STATUS: ${matched ? 'MATCH' : 'MISMATCH'}`);
+}

package/scripts/lib/cmd-version.mjs

@@ -34,7 +34,9 @@ const TEXT_FILES = [
   // v0.60.0：补 usage-guide 的**同步面**——v0.59.0 只把它纳入检出（check-version-consistency.mjs），
   // 漏了本列表，导致升版时「package.json 已改但 usage-guide 未同步 → 检出失败 → npm version 非 0 退出」
   // 的脏状态。检出与同步现已同源（两处 pattern 对应同一锚点）。
-  { file: 'docs/usage-guide.md',    pattern: /(版本锚点：v)\d+\.\d+\.\d+/g,                     replacement: '$1%MAJOR%.%MINOR%.%PATCH%' },
+  // v0.62.0：文件名同步——文档已更名为「team-flow 使用说明（研发团队版）.md」，
+  // check-version-consistency.mjs 已改指新名，本处漏改导致升版时该文件被 skip（版本锚点留在旧值 → 复检失败）。
+  { file: 'docs/team-flow 使用说明（研发团队版）.md', pattern: /(版本锚点：v)\d+\.\d+\.\d+/g, replacement: '$1%MAJOR%.%MINOR%.%PATCH%' },
   { file: 'skills/workflow-start/SKILL.md', pattern: /(npx --yes --package @xulthekl\/team-flow@)\d+\.\d+\.\d+( tf)/g, replacement: '$1%MAJOR%.%MINOR%.%PATCH%$2' },
   { file: 'skills/need-explorer/SKILL.md', pattern: /(npx --yes --package @xulthekl\/team-flow@)\d+\.\d+\.\d+( tf)/g, replacement: '$1%MAJOR%.%MINOR%.%PATCH%$2' },
   { file: 'skills/spec-writer/SKILL.md', pattern: /(npx --yes --package @xulthekl\/team-flow@)\d+\.\d+\.\d+( tf)/g, replacement: '$1%MAJOR%.%MINOR%.%PATCH%$2' },

package/scripts/lib/config-loader.mjs

@@ -21,7 +21,25 @@ const DEFAULTS = {
     language: 'auto',
   },
   prd: {
+    // 模板路径。默认值为 **插件内置** 相对路径 —— 一律以**插件根**为基准解析，
+    // 项目根下的同名路径不构成回退目标（v0.62.0 F2，消除默认值基准歧义）。
     template: 'templates/prd.md',
+    // §8.4 撰写规范文件（v0.62.0 F1）。规范与体例解耦后，权威物是它而非模板骨架。
+    // 路径相对于插件根解析。
+    spec: 'skills/ce-brainstorm/references/prd-84-authoring-spec.md',
+    // 模板一致性确认记忆（v0.62.0 G2）。
+    // 由 `tf prd ack set` 原子写入（G6），落点 = resolveConfigWritePath() 命中的文件。
+    // 判据：三个 hash 全等 → 静默按 mode 执行；任一变化 → 重新提问（上一选择作默认项）。
+    template_ack: {
+      in_use_hash: null,   // 实际使用的模板骨架 hash
+      plugin_hash: null,   // 插件内置模板骨架 hash
+      spec_hash: null,     // 规范文件 hash —— v0.62.0 新增：规范升级须触发重问
+      plugin_version: null,
+      mode: null,          // 'adopt_latest' | 'keep_legacy'
+      diff_digest: null,   // 批准时所见差异摘要的摘要值 —— 否则事后无法复现"批了什么"
+      acknowledged_at: null,
+      acknowledged_by: null,
+    },
   },
   conventions: {
     // 项目级规范文件路径映射（v0.11 §33）
@@ -129,6 +147,27 @@ function findConfigFile(startDir) {
   return null;
 }
 
+/**
+ * v0.62.0（G5）：**写入路径与读取路径对齐**。
+ *
+ * 缺陷：`tf config --set` 原固定写 `<cwd>/team-flow.config.json`（legacy 第 2 顺位），
+ * 而读取走 `findConfigFile`，其**首选** `<cwd>/.team-flow/team-flow.config.json`
+ * 且**首个命中即返回、不合并** → 在已有 `.team-flow/` 配置的项目里 `--set`
+ * **静默无效**（写进一个没人读的文件），并在项目根留下误导性配置。
+ *
+ * 改法：写入一律落到 `findConfigFile()` 命中的那个文件；未命中则新建
+ * `.team-flow/team-flow.config.json`（与读取首选一致）。G6 的 ack 写入复用同一函数。
+ *
+ * @param {string} startDir
+ * @returns {string} 应写入的配置文件绝对路径
+ */
+export function resolveConfigWritePath(startDir) {
+  const hit = findConfigFile(startDir);
+  if (hit) return hit;
+  // 未命中 → 用读取的首选位置新建，避免"写了但读不到"
+  return join(startDir, '.team-flow', 'team-flow.config.json');
+}
+
 export function loadConfig(projectRoot) {
   const configPath = findConfigFile(projectRoot || process.cwd());
   if (!configPath) return { ...DEFAULTS };

package/scripts/lib/template-hash.mjs

@@ -0,0 +1,95 @@
+// scripts/lib/template-hash.mjs — 模板 / 规范文件的稳定 hash（v0.62.0，F5）
+//
+// 存在理由：改造前 **F3（Node 侧机械脚本）与 G1（skill 散文侧人工比对）各有一套
+// hash 判据**。同一文件在两处算出不同结果（换行、尾空白、编码差异）会导致
+// 「门失效」（该拦的没拦）或「误报落后」（不该问的乱问）。本模块把判据收敛为
+// **唯一实现**，两侧一律调用，不另立第二套。
+//
+// 判据定义（v1.7 §5.7 F5）：
+//   ① 算法 sha256，前缀 `sha256:`（与 `hash.mjs` 既有惯例一致）
+//   ② 颗粒度 = 整文件字节；**先做换行归一化（CRLF→LF）与首尾空白裁剪**
+//   ③ 输出：全长用于比对，`shortHash()`（前 8 位）仅用于展示
+
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+
+/**
+ * 归一化：CRLF → LF，并裁剪首尾空白。
+ *
+ * 只做这两件事，不做更激进的归一化（不折叠空行、不统一缩进）——
+ * 内容级差异应当反映到 hash 上，否则"改了却没变 hash"，门就形同虚设。
+ *
+ * @param {string} content
+ * @returns {string}
+ */
+export function normalizeForHash(content) {
+  return (content ?? '').replace(/\r\n/g, '\n').trim();
+}
+
+/**
+ * 对内容取稳定 hash。空内容返回 null（不是空串 hash）——
+ * 「文件为空/不存在」是独立状态，不应与「内容为空串」混淆。
+ *
+ * @param {string} content
+ * @returns {string|null} `sha256:<hex>` 或 null
+ */
+export function hashContent(content) {
+  const normalized = normalizeForHash(content);
+  if (normalized.length === 0) return null;
+  return `sha256:${crypto.createHash('sha256').update(normalized, 'utf-8').digest('hex')}`;
+}
+
+/**
+ * 对文件取稳定 hash（文件不存在返回 null）。
+ *
+ * @param {string} filePath
+ * @returns {string|null}
+ */
+export function hashTemplateFile(filePath) {
+  if (!filePath || !fs.existsSync(filePath)) return null;
+  return hashContent(fs.readFileSync(filePath, 'utf-8'));
+}
+
+/**
+ * 展示用短标识（默认前 8 位，去掉 `sha256:` 前缀）。
+ *
+ * @param {string|null} hash
+ * @param {number} [len=8]
+ * @returns {string}
+ */
+export function shortHash(hash, len = 8) {
+  if (!hash) return '—';
+  const hex = hash.startsWith('sha256:') ? hash.slice(7) : hash;
+  return hex.slice(0, len);
+}
+
+/**
+ * 一次算出「模板骨架 + 规范文件」两个 hash（G1 判据对象，v1.7 DEC-16）。
+ *
+ * F 类-F1 之后，**权威物是规范文件而非模板骨架**，故判据必须含 spec_hash；
+ * 只比骨架会导致「规范升级不触发重问」——正是红队批评的「门管错了对象」。
+ *
+ * @param {{ templatePath?: string, specPath?: string }} paths
+ * @returns {{ template_hash: string|null, spec_hash: string|null }}
+ */
+export function hashTemplatePair(paths = {}) {
+  return {
+    template_hash: hashTemplateFile(paths.templatePath),
+    spec_hash: hashTemplateFile(paths.specPath),
+  };
+}
+
+/**
+ * 比对两组 hash（G2 ack 失效判定）。
+ *
+ * @param {{ template_hash?: string|null, spec_hash?: string|null }} current
+ * @param {{ in_use_hash?: string, spec_hash?: string, plugin_hash?: string }} ack
+ * @returns {{ matched: boolean, changed: string[] }}
+ */
+export function compareAgainstAck(current, ack = {}) {
+  const changed = [];
+  // ack 字段名沿用 config schema：in_use_hash 记录的是"项目侧实际使用"的骨架 hash
+  if ((current.template_hash ?? null) !== (ack.in_use_hash ?? null)) changed.push('in_use_hash');
+  if ((current.spec_hash ?? null) !== (ack.spec_hash ?? null)) changed.push('spec_hash');
+  return { matched: changed.length === 0, changed };
+}

package/scripts/team-flow.mjs

@@ -11,6 +11,7 @@ const COMMANDS = {
   version:        () => import('./lib/cmd-version.mjs'),
   sync:           () => import('./lib/cmd-sync.mjs'),
   config:         () => import('./lib/cmd-config.mjs'),
+  prd:            () => import('./lib/cmd-prd.mjs'),
   state:          () => import('./lib/cmd-state.mjs'),
   inject:         () => import('./lib/cmd-inject.mjs'),
   audit:          () => import('./lib/cmd-audit.mjs'),

package/skills/bug-investigator/SKILL.md

@@ -92,6 +92,14 @@ Write the investigation report with this structure:
 - **Mechanism:** [How the bug works, step by step]
 - **Evidence:** [What proves this is the cause]
 
+## 源 Change 关联（v0.61.0 新增，设计依据 v0.26 §203）
+
+- **是否匹配到源 change**：是 / 否
+- **源 change 目录**：`<changes/<name>/>`（若匹配到；否则填「独立缺陷 / 新文件，无源 change」）
+- **匹配方式**：`git blame` 受影响文件/符号 → 引入 commit → 经 `change_dag` / `change-brief` / `learnings.md` 反查；或全局 `specs/` 按 capability 检索
+- **复用约束**：修复时复用源 change 的 `design.md` / `specs/` / `tests` 作为已知设计约束，避免偏离原设计意图；若源 change 已 closing，仅在本 bugfix change 内复用上下文，**不重开**源 change
+- **用户确认**：匹配结果须由用户确认；失准时本段填「匹配失败，按独立缺陷处理」
+
 ## Recommended Fix
 [Suggested approach — describe what to change and why, but do NOT implement it]
 - **Fix location:** [where to change]