@xulthekl/team-flow 0.61.0 → 0.63.0

package/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "team-flow",
-  "version": "0.61.0",
+  "version": "0.63.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/guard/checks/contract-fresh.mjs

@@ -1,17 +1,61 @@
 // scripts/guard/checks/contract-fresh.mjs — check contract staleness via hash comparison
+//
+// v0.63.0（workflow-feedback 20260923-013114 S3）：本维度新增挂载到 executing:closing。
+// 动机：S3「DP-3 后 planning 制品冻结」的反查锚——原本 closing 侧反查依赖
+// execution-plan-ready（validatePlan 比对 plan 内嵌的 artifacts_hash/contract_hash），
+// 而该比对可被 `tf execution refresh-hash` 一键刷平（它只改 plan JSON）→ 把 gate-affecting
+// 变更伪记为陈述性勘误后，closing 全维 PASS、wave receipt 亦不失效（wave_fingerprint
+// 不含 artifacts_hash）→ **伪绿静默通过**。本维度直接比对 state.artifacts_hash 与制品实算值，
+// refresh-hash 无法清屏（它不碰 state），故为独立锚。
+//
+// 注意（卡死面）：本维度**无 legacy 豁免**（与既有挂载点一致）——存量 change 在 closing
+// 若状态文件缺 artifacts_hash 会被拦。故失败信息必须给出可执行出路（tf state rebuild），
+// 不得让门禁成为无出口的闭门（参照 arch_merge_skipped 的设计原则）。
+import fs from 'node:fs';
+import path from 'node:path';
 import { isContractFresh } from '../../lib/hash.mjs';
+import { readState } from '../../lib/state-loader.mjs';
+
+// v0.63.0（P4 评审 L3）：裸 rebuild 会重算并覆盖 state.artifacts_hash——若发生在 DP-3 冻结之后，
+// 它就成了与 refresh-hash 并列的「清屏」通道，且不留任何 errata 痕迹。故提示按时间点分流：
+// 冻结前的改动可裸 rebuild；冻结后的改动必须走勘误登记/例外 2，不得用 rebuild 把差异抹平。
+const REBUILD_HINT =
+  'If the planning change predates DP-3 approval, re-capture the hash: `tf state rebuild <dir>`. '
+  + 'If it happened AFTER DP-3, the artifacts are FROZEN: record it in the contract `## Errata Register` '
+  + 'under the applicable exception (doc-only corrections), or take the gate-affecting path rebuild->revise '
+  + '(exception 2). Do NOT rebuild past a frozen change — that erases the diff without any errata trace.';
 
 /**
  * Compare stored artifacts_hash in .team-flow.yaml against current artifact hashes.
  * Returns { pass, failures[] }.
  */
 export function checkContractFresh(changeDir) {
-  const fresh = isContractFresh(changeDir);
-  if (fresh) {
+  if (isContractFresh(changeDir)) {
     return { pass: true, failures: [] };
   }
+
+  // 区分两类失败，给出各自的出路（否则关闭期死锁无指示）。
+  let stored = null;
+  try {
+    const state = readState(changeDir);
+    stored = state?.artifacts_hash ?? null;
+  } catch {
+    stored = null;
+  }
+  if (!stored || stored === 'null') {
+    return {
+      pass: false,
+      failures: [
+        'execution-contract.md freshness cannot be judged: the state file carries no artifacts_hash '
+        + '(hand-written or truncated .team-flow.yaml). Re-capture it: `tf state rebuild <dir>`.',
+      ],
+    };
+  }
+
   return {
     pass: false,
-    failures: ['execution-contract.md is stale: artifacts hash mismatch. Re-run contract-builder to regenerate.'],
+    failures: [
+      `execution-contract.md is stale: artifacts hash mismatch. ${REBUILD_HINT}`,
+    ],
   };
-}
+}

package/scripts/guard/checks/gates-probed.mjs

@@ -0,0 +1,175 @@
+// scripts/guard/checks/gates-probed.mjs — bridging dry-run evidence gate
+//
+// v0.63.0（workflow-feedback 20260923-013114 S2）：
+// full workflow 的 bridging→approved-for-build 新增本维度——契约产出的 G 类闸门
+// 必须已在**主工作区当前态**跑过 dry-run（预期 FAIL = RED 基线），原始输出留档。
+// 动机：`design.md` R-7「闸门命令已实测可跑」长期只是**文字自证**；实测中 G1 格式约束、
+// grep shim、dist 误入扫描、desc 文案 vs G2 互斥均在施工中才暴露。
+//
+// **存在性强制（Critical 处置，不得退回内容型豁免）**：
+// 契约缺 `## Gate Registry` 段 / 表解析失败 → **FAIL**，不得落入 N/A 放行。
+// 依据：v0.13 RC-1 已删除「以 contract 内容为键」的豁免——test-gate-exemptions.mjs
+// :7-10 明文记载「无法区分真存量与漏生成，导致零测试通过全部门禁」；既有先例
+// `contractDeclaresTestMatrix` 走的是段存在性硬要求。本 check 复刻该先例。
+//
+// 与 test-matrix-ready（:49 入口门禁）同构：legacy 豁免 + 显式 skip 附理由。
+import fs from 'node:fs';
+import path from 'node:path';
+import { readState } from '../../lib/state-loader.mjs';
+import { computeContractHash } from '../../lib/hash.mjs';
+import { isLegacyChange } from './test-gate-exemptions.mjs';
+
+export const EVIDENCE_REL = path.join('.superpowers', 'test-evidence', 'bridging-gates-red.txt');
+const REGISTRY_HEADING = '## Gate Registry';
+const RED_BASELINE_LINE = 'EXPECTED: FAIL (RED baseline)';
+const SKIP_REASON_HINT =
+  'gates_probed_skipped=true requires gates_probed_skip_reason — record it: '
+  + "tf state set <dir> gates_probed_skip_reason '<why this change has no gate dry-run>'";
+
+/** 提取 '## Gate Registry' 段正文（到下一个同级标题或文件尾）。 */
+export function extractRegistrySection(contractText) {
+  const lines = contractText.split(/\r?\n/);
+  const start = lines.findIndex((l) => l.trim() === REGISTRY_HEADING);
+  if (start === -1) return null;
+  const body = [];
+  for (let i = start + 1; i < lines.length; i += 1) {
+    if (/^##\s/.test(lines[i])) break;
+    body.push(lines[i]);
+  }
+  return body.join('\n');
+}
+
+/**
+ * 解析 Gate Registry 表格的 id 列。
+ * 表头固定 `| id | phase | command | expected |`；id 形如 G-1。
+ * @returns {string[]} id 列表（去重，出现顺序）
+ */
+export function parseGateIds(sectionBody) {
+  const ids = [];
+  for (const line of sectionBody.split(/\r?\n/)) {
+    if (!line.trim().startsWith('|')) continue;
+    const cells = line.split('|').map((c) => c.trim());
+    // cells[0] === ''（前导竖线），故首列在 index 1
+    const first = cells[1] || '';
+    if (!first || /^-+$/.test(first) || first.toLowerCase() === 'id') continue;
+    if (!ids.includes(first)) ids.push(first);
+  }
+  return ids;
+}
+
+/** 段内显式声明零闸门 + 理由（形如 `N/A: <理由>`）。 */
+export function declaredNotApplicable(sectionBody) {
+  const m = sectionBody.match(/(?:^|\n)\s*(?:N\/A|NA)\s*[:：]\s*(.+)/i);
+  return m ? m[1].trim() : null;
+}
+
+/**
+ * Returns { pass, failures[], reason? }.
+ */
+export function checkGatesProbed(changeDir) {
+  const state = readState(changeDir);
+
+  // Exemption 1：legacy change（v0.32.0 之前初始化，无 schema_version 打戳）。
+  if (isLegacyChange(state)) {
+    return { pass: true, failures: [], reason: 'legacy change — initialized before v0.32.0' };
+  }
+
+  // Exemption 2：显式 skip（必须附理由）。
+  if (state.gates_probed_skipped === 'true') {
+    const reason = state.gates_probed_skip_reason;
+    if (typeof reason !== 'string' || reason.trim().length === 0) {
+      return { pass: false, failures: [SKIP_REASON_HINT] };
+    }
+    return { pass: true, failures: [], reason: `explicitly skipped: ${reason}` };
+  }
+
+  // 段存在性硬要求（fail-closed）：缺段 / 解析失败一律 FAIL，不得落 N/A。
+  const contractPath = path.join(changeDir, 'execution-contract.md');
+  if (!fs.existsSync(contractPath)) {
+    return { pass: false, failures: ['execution-contract.md is missing — run contract-builder first'] };
+  }
+  const contractText = fs.readFileSync(contractPath, 'utf-8');
+  const section = extractRegistrySection(contractText);
+  if (section === null) {
+    return {
+      pass: false,
+      failures: [
+        `contract does not declare ${REGISTRY_HEADING} — return to bridging so contract-builder generates it.`,
+        'A missing section is NOT a "no gates" declaration: absence of the registry cannot be distinguished '
+        + 'from an omitted registry (v0.13 RC-1 content-key exemption was removed for exactly this reason).',
+        'If this change genuinely has no gates, write the section with an explicit "N/A: <reason>" line.',
+      ],
+    };
+  }
+  const gateIds = parseGateIds(section);
+
+  // N/A：段存在 + 显式声明零闸门 + 理由（state 键为备用通道）。
+  if (gateIds.length === 0) {
+    const naReason = declaredNotApplicable(section);
+    if (naReason) {
+      return { pass: true, failures: [], reason: `not applicable — ${naReason}` };
+    }
+    if (state.gates_probed_na === 'true') {
+      return { pass: true, failures: [], reason: 'not applicable — gates_probed_na set in state' };
+    }
+    return {
+      pass: false,
+      failures: [
+        `${REGISTRY_HEADING} present but declares no gate id and no "N/A: <reason>" line.`,
+        'Either list the gates (| id | phase | command | expected |) or state "N/A: <reason>".',
+      ],
+    };
+  }
+
+  // 正常路径：evidence 文件 + 首行 RED 基线 + hash 值新鲜 + id 全覆盖。
+  const evidencePath = path.join(changeDir, EVIDENCE_REL);
+  if (!fs.existsSync(evidencePath)) {
+    return {
+      pass: false,
+      failures: [
+        `${EVIDENCE_REL} is missing — run the bridging gate dry-run (expect FAIL = RED baseline) `
+        + 'and persist the raw output there.',
+        'Required first line: ' + RED_BASELINE_LINE,
+      ],
+    };
+  }
+  const evidence = fs.readFileSync(evidencePath, 'utf-8');
+  const failures = [];
+  const evidenceLines = evidence.split(/\r?\n/);
+  const firstNonEmpty = evidenceLines.find((l) => l.trim().length > 0) || '';
+  if (firstNonEmpty.trim() !== RED_BASELINE_LINE) {
+    failures.push(
+      `evidence first line must be exactly "${RED_BASELINE_LINE}", got: "${firstNonEmpty.trim().slice(0, 80)}". `
+      + 'A gate that already PASSES means the baseline was not RED — record the expected-FAIL run instead.',
+    );
+  }
+
+  // 新鲜度 = hash 值比对（非 mtime）：
+  // refresh-hash / state rebuild 均不重写契约文件，故 mtime 判据只会在「契约字节等价重生成」
+  // 或 git 恢复场景下误报；hash 值比对天然免疫。
+  const contractHash = computeContractHash(changeDir);
+  const hashMatch = evidence.match(/CONTRACT_HASH:\s*(sha256:[0-9a-f]{64})/);
+  if (!hashMatch) {
+    failures.push(
+      'evidence must carry a "CONTRACT_HASH: sha256:<64 hex>" line so freshness is judged by content, not mtime.',
+    );
+  } else if (contractHash && hashMatch[1] !== contractHash) {
+    failures.push(
+      `evidence is stale: CONTRACT_HASH ${hashMatch[1].slice(0, 20)}… does not match current contract `
+      + `${String(contractHash).slice(0, 20)}… — re-run the dry-run against the current contract.`,
+    );
+  }
+
+  const missingIds = gateIds.filter((id) => {
+    const esc = id.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    return !new RegExp(`(^|[^\\w-])${esc}([^\\w-]|$)`).test(evidence);
+  });
+  if (missingIds.length > 0) {
+    failures.push(
+      `evidence does not cover declared gate id(s): ${missingIds.join(', ')} — every id in ${REGISTRY_HEADING} needs a dry-run record.`,
+    );
+  }
+
+  if (failures.length > 0) return { pass: false, failures };
+  return { pass: true, failures: [] };
+}

package/scripts/guard/guard.mjs

@@ -16,6 +16,7 @@ import { checkExecutionReviewsPassed } from './checks/execution-reviews-passed.m
 import { checkCompoundCaptured } from './checks/compound-captured.mjs';
 import { checkTestMatrixComplete } from './checks/test-matrix-complete.mjs';
 import { checkTestMatrixReady } from './checks/test-matrix-ready.mjs';
+import { checkGatesProbed } from './checks/gates-probed.mjs';
 import { checkArchReadiness } from './checks/arch-readiness.mjs';
 import { checkArchSnapshot } from './checks/arch-snapshot.mjs';
 import { checkArchMerged } from './checks/arch-merged.mjs';
@@ -39,7 +40,12 @@ const TRANSITION_CHECKS = {
   // 任何能写 dp_3_result 的主体（含夜间替身的 HOLD 落盘）都能让 change 呈现"已批准"假象，
   // 从而在无真实批准的前提下跨过 DP-3 硬门。本维度要求取值以 "approved" 开头
   // （判据实现见 checks/dp3-approved.mjs）。
-  'bridging:approved-for-build':    ['artifacts-exist', 'schema-valid', 'contract-fresh', 'dp-gate-passed', 'dp3-approved'],
+  // v0.63.0（workflow-feedback 20260923-013114 S2）：**gates-probed 新增**——契约的 G 类闸门
+  // 必须在 bridging 期跑过 dry-run（预期 FAIL = RED 基线）并留档，把 design.md R-7 长期存在的
+  // 「闸门已实测可跑」文字自证物化为机械证据。检查五件：evidence 存在 / 首行 RED 基线 /
+  // CONTRACT_HASH 值新鲜 / 契约 Gate Registry 的 id 逐 id 覆盖 / **段缺失即 FAIL（fail-closed）**。
+  // hotfix 走 WORKFLOW_TRANSITION_CHECKS 自有覆盖（下方），tweak 由 skip 回退阀放行。
+  'bridging:approved-for-build':    ['artifacts-exist', 'schema-valid', 'contract-fresh', 'dp-gate-passed', 'dp3-approved', 'gates-probed'],
   // v0.13 §49：test-matrix-ready 门禁前移——full 模式进入 executing 前强制测试准备度
   //（矩阵存在非空 OR 显式 skip 附理由；legacy 豁免）。hotfix/tweak 沿用 §45.3 豁免，不挂。
   'approved-for-build:executing':   ['artifacts-exist', 'contract-fresh', 'dp-gate-passed', 'execution-plan-ready', 'test-matrix-ready'],
@@ -51,7 +57,15 @@ const TRANSITION_CHECKS = {
   // 且 arch-merge 在状态机上无任何锚点（VALID_STATES 无 closed、closing→closed 不存在）。
   // B' 把 arch-merge 前移到本转换**之前**，本维度即其前置条件。
   // hotfix/tweak 沿用既有豁免口径（WORKFLOW_TRANSITION_CHECKS 各自列维度，天然不挂）。
-  'executing:closing':              ['tasks-complete', 'tests-passing', 'specs-merged', 'execution-plan-ready', 'execution-reviews-passed', 'compound-captured', 'test-matrix-complete', 'arch-snapshot', 'delegation-status', 'arch-merged'],
+  // v0.63.0（feedback 20260923-013114 S3）：**contract-fresh 新增**——S3「DP-3 后规划制品冻结」
+  // 的反查锚。原状 closing 无 contract-fresh，反查实际依赖 execution-plan-ready（validatePlan
+  // 比对 plan 内嵌的 artifacts_hash/contract_hash），而该比对可被 `tf execution refresh-hash`
+  // 一键刷平（refreshPlanHash 直接改写 plan JSON、revision 不升）→ 把 gate-affecting 变更
+  // 伪记为陈述性勘误后，closing 全维 PASS、wave receipt 亦不失效（wave_fingerprint 不含
+  // artifacts_hash）→ **伪绿静默通过**。本维度直接比对 state.artifacts_hash 与制品实算值，
+  // refresh-hash 无法清屏（它只改 plan JSON，不碰 state）——故为 refresh-hash 之外的独立锚。
+  // hotfix/tweak 不挂：二者跳过 spec-writer、无 planning 四件，冻结机制本身 N/A（设计 §3.9）。
+  'executing:closing':              ['contract-fresh', 'tasks-complete', 'tests-passing', 'specs-merged', 'execution-plan-ready', 'execution-reviews-passed', 'compound-captured', 'test-matrix-complete', 'arch-snapshot', 'delegation-status', 'arch-merged'],
 
   // Debugging side-path
   'executing:debugging':            [],
@@ -200,6 +214,7 @@ async function main() {
     'compound-captured': (dir) => checkCompoundCaptured(dir),
     'test-matrix-complete': (dir) => checkTestMatrixComplete(dir),
     'test-matrix-ready': (dir) => checkTestMatrixReady(dir),
+    'gates-probed': (dir) => checkGatesProbed(dir),
     'arch-readiness': (dir) => checkArchReadiness(dir),
     'arch-snapshot': (dir) => checkArchSnapshot(dir),
     'arch-merged': (dir) => checkArchMerged(dir),

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-state.mjs

@@ -45,6 +45,10 @@ const SETTABLE_FIELDS = [
   'tasks_skipped', 'tasks_skip_reason',
   // Arch merge gate (v0.53.0 §110.2：arch-merged guard 维度的显式跳过键，须附理由)
   'arch_merge_skipped', 'arch_merge_skip_reason',
+  // Bridging gates dry-run gate (v0.63.0；feedback 20260923-013114 S2)
+  // 三键必须与 state-loader BUILTIN_DEFAULTS + writeState 序列化分支同步注册，
+  // 缺任一环即「回显成功却零写入」（v0.59.0 同型教训，见本文件 :20-24 注释）。
+  'gates_probed_skipped', 'gates_probed_skip_reason', 'gates_probed_na',
 ];
 
 export async function run(args) {

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' },