@xulthekl/team-flow 0.64.0 → 0.67.0

package/scripts/lib/cmd-prd.mjs

@@ -14,7 +14,9 @@
 // 供主会话 Phase 0.0 的阻塞提问（G1）取判据——**判据不在 skill 散文里另写一套**。
 
 import fs from 'node:fs';
+import { existsSync, mkdirSync } from 'node:fs';
 import path from 'node:path';
+import { createHash } from 'node:crypto';
 import { parseArgs } from 'node:util';
 import { loadConfig, resolveConfigWritePath } from './config-loader.mjs';
 import {
@@ -23,6 +25,7 @@ import {
   compareAgainstAck,
   shortHash,
 } from './template-hash.mjs';
+import { checkPrdClarity } from '../guard/checks/prd-clarity.mjs';
 
 const VALID_MODES = ['adopt_latest', 'keep_legacy'];
 
@@ -48,6 +51,7 @@ export async function run(args) {
   const sub = positionals[0];
   if (sub === 'ack') return ack(positionals.slice(1), values);
   if (sub === 'check') return check(values);
+  if (sub === 'check-clarity') return checkClarity(positionals.slice(1));
   usage();
 }
 
@@ -58,11 +62,90 @@ function usage() {
       '  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'
+      '  tf prd check [--template-path <p>] [--plugin-root <p>]   # 比对 hash 与 ack，输出 STATUS\n' +
+      '  tf prd check-clarity <dir|prd.md>                        # 清晰度机械门（弱词/段/§8.4 漂移），末行 STATUS: PASS | FAIL，FAIL exit 1'
   );
   process.exit(2);
 }
 
+/**
+ * `tf prd check-clarity`：产品级 PRD 清晰度机械门（agent-governance P0-1，DEC-8a）。
+ *
+ * 入参 = 目录（自动定位 requirement/vN/prd.md，多个 vN 取最大）或 prd.md 文件路径。
+ * 输出末行固定 `STATUS: PASS | FAIL`；**FAIL 时 exit 1**（fail-closed——本命令是门，
+ * 不同于 `tf prd check` 的判据工具语义；SKILL 冻结步骤 MUST 读 STATUS 且不得忽略非零退出码）。
+ * 判定细节见 scripts/guard/checks/prd-clarity.mjs 头注（规则源 / 豁免边界 / 校准纪律）。
+ */
+function checkClarity(positionalArgs) {
+  const target = positionalArgs[0];
+  if (!target) usage();
+
+  let prdPath = target;
+  if (fs.existsSync(target) && fs.statSync(target).isDirectory()) {
+    prdPath = resolvePrdInDir(target);
+    if (!prdPath) {
+      console.error(`no requirement/vN/prd.md found under: ${target}`);
+      console.log('STATUS: FAIL');
+      process.exit(1);
+    }
+  }
+  if (!fs.existsSync(prdPath)) {
+    console.error(`PRD file not found: ${prdPath}`);
+    console.log('STATUS: FAIL');
+    process.exit(1);
+  }
+
+  const { pass, failures, stats } = checkPrdClarity(prdPath);
+  console.log('prd         :', prdPath);
+  console.log('weak_hits   :', stats.weakHits, '| drift_cells:', stats.driftCells,
+    '| missing_sections:', stats.sectionsMissing.length ? stats.sectionsMissing.join(',') : '(none)');
+  for (const f of failures) console.log(f);
+  console.log(`STATUS: ${pass ? 'PASS' : 'FAIL'}`);
+  recordClarityResult(pass, prdPath); // P1-1 跨层管道：落产品级记录供 tf state init 拷贝
+  if (!pass) process.exit(1);
+}
+
+/**
+ * P1-1 clarity 跨层管道的写侧：落 `<cwd>/.team-flow/prd-clarity.json`。
+ * 消费链 = `tf state init` 拷入 change state（prd_clarity_result/prd_clarity_hash）
+ * → guard 维度 `prd-clarity`（checks/prd-clarity-state.mjs）在接活前转换消费。
+ * PASS/FAIL 都落盘（fail 记录让绕过 S2 的 direct change 也在变更级被拦——双保险）。
+ */
+function recordClarityResult(pass, prdPath) {
+  try {
+    const dir = path.join(process.cwd(), '.team-flow');
+    if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+    const content = fs.readFileSync(prdPath, 'utf-8');
+    const sha = createHash('sha256').update(content).digest('hex');
+    fs.writeFileSync(path.join(dir, 'prd-clarity.json'), `${JSON.stringify({
+      status: pass ? 'pass' : 'fail',
+      prd: prdPath,
+      prd_hash: `sha256:${sha}`,
+      checked_at: new Date().toISOString(),
+    }, null, 2)}\n`);
+  } catch {
+    // 落盘失败不吞主判定——STATUS 已输出；管道缺失 = 变更级维度走中性，fail-closed 不受影响
+  }
+}
+
+/**
+ * 目录内定位 prd.md：<dir>/prd.md、requirement/ 下最大 vN、或老布局 prd/ 下最大 vN
+ * （存量项目用 `prd/vN/prd.md`——2026-09-25 存量校准时实测补上，防新门卡死老布局）。
+ */
+function resolvePrdInDir(dir) {
+  const direct = path.join(dir, 'prd.md');
+  if (fs.existsSync(direct)) return direct;
+  for (const base of ['requirement', 'prd']) {
+    const reqDir = path.join(dir, base);
+    if (!fs.existsSync(reqDir)) continue;
+    const versions = fs.readdirSync(reqDir)
+      .filter((n) => fs.existsSync(path.join(reqDir, n, 'prd.md')))
+      .sort((a, b) => parseInt(a.replace(/\D/g, ''), 10) - parseInt(b.replace(/\D/g, ''), 10)); // 数值序：v10 > v9（字典序会取错）
+    if (versions.length > 0) return path.join(reqDir, versions[versions.length - 1], 'prd.md');
+  }
+  return null;
+}
+
 /** 读原始配置文件（未与 DEFAULTS 合并），用于区分「用户显式配置」与「默认值」。 */
 function readRawConfig() {
   const p = resolveConfigWritePath(process.cwd());

package/scripts/lib/cmd-solutions.mjs

@@ -21,6 +21,8 @@ export async function run(args) {
       severity: { type: 'string' },
       summary: { type: 'string' },
       source: { type: 'string' },
+      // agent-governance P2-1：纠错条目的来源事件锚（HOLD 的 msg_id / 决策日志行）
+      'source-event': { type: 'string' },
       // v0.57.0 §4.1：inject 的展示条数控制与 backfill 的预演
       limit: { type: 'string' },
       all: { type: 'boolean' },
@@ -52,6 +54,7 @@ export async function run(args) {
       severity: values.severity,
       summary: values.summary,
       source: values.source,
+      source_event: values['source-event'],
       dir: values.dir,
     });
     return;

package/scripts/lib/cmd-state.mjs

@@ -1,7 +1,7 @@
 // scripts/lib/cmd-state.mjs — tf state subcommand handler
 import { parseArgs } from 'node:util';
 import { spawnSync } from 'node:child_process';
-import { existsSync, mkdirSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync } from 'node:fs';
 import path, { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 // VALID_STATES 统一从 state-loader.mjs 引入(状态机合法值唯一真相源),不再本地硬编码。
@@ -11,6 +11,26 @@ import { computeArtifactsHash, computeContractHash, computeTestMatrixHash } from
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
+/**
+ * P1-1：自 changeDir 向上（限 6 层）找 `<root>/.team-flow/prd-clarity.json` 并解析。
+ * 找不到 / 解析失败 → null（= 中性，init 不打字段）。
+ */
+function findProductClarityRecord(changeDir) {
+  let dir = path.resolve(changeDir);
+  for (let i = 0; i < 6; i += 1) {
+    const rec = path.join(dir, '.team-flow', 'prd-clarity.json');
+    if (existsSync(rec)) {
+      const parsed = JSON.parse(readFileSync(rec, 'utf-8'));
+      if (parsed && (parsed.status === 'pass' || parsed.status === 'fail')) return parsed;
+      return null;
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null;
+}
+
 // v0.13 §50（BUG-A 政策修正）：test_result 移出可手工设置字段——测试证据必须经
 // tf test record 程序化记录，手工自述值不再被 tests-passing 门禁接受。
 // v0.13 §48.2：test_matrix_skip_reason 可设置（显式 skip 的理由留痕）。
@@ -121,6 +141,16 @@ export async function run(args) {
       const state = readState(changeDir);
       if (!stateFileExisted) {
         state.schema_version = 1;
+        // P1-1 clarity 跨层管道：拷贝产品级记录（唯一写入路径——state 字段不在
+        // SETTABLE_FIELDS，防自助放行）。find 向上找 <root>/.team-flow/prd-clarity.json。
+        // 记录 fail 也拷：绕过 S2 冻结的 direct change 在变更级被 guard 拦下（双保险）。
+        try {
+          const rec = findProductClarityRecord(changeDir);
+          if (rec) {
+            state.prd_clarity_result = rec.status === 'fail' ? 'fail' : 'pass';
+            state.prd_clarity_hash = rec.prd_hash ?? null;
+          }
+        } catch { /* 无记录 = 中性，不阻断 init */ }
         // v0.64.0 P0（§4 扫描基线）：init 打戳 base_sha（架构 surface 扫描的 git 基线）。
         // 非 git 环境 / 尚无提交 → 保持 null，扫描时按 §4 退化参照（origin → FAIL）。
         try {

package/scripts/lib/config-loader.mjs

@@ -47,6 +47,26 @@ const DEFAULTS = {
     // 各 skill 上下文加载时按 phase 过滤注入
     // 示例: { database: ".team-flow/conventions/db-design.md", ... }
   },
+  arch: {
+    // C4 代码注解扫描配置（ddd-purity-and-arch-merge-design v1.4 §5.4-4b）。
+    // C4 是本机制**唯一**「A 级 · 真独立」锚：锚点 = 代码本体，不经 arch-merge 写路径。
+    scan: {
+      // 持久化注解名（默认 MyBatis-Plus）。非该框架的项目改此值。
+      annotation: 'TableName',
+      // 自定义正则源（优先于 annotation）。约定 capture group(1) 为表名。
+      pattern: null,
+      // 扫描的目标文件扩展名。
+      extensions: ['.java'],
+      // 多仓场景：扫描根（相对项目根）；为空则扫项目根。
+      // emp-auth 恰把两仓放在同一工作树，故单根可跑；两仓分属不同 git 仓库时须配置。
+      repos: [],
+      // 排除目录（按 basename 匹配，任意层级生效）。
+      // ★ 必配：emp-auth 根下有 4 个 .worktrees/ 副本，不排除会把同一批注解重复计入。
+      // ★ 真相源说明（P3 MIN-4）：**强制底线以 `arch-scan-code.mjs` 的 `DEFAULT_EXCLUDE_DIRS`
+      //   为准**（并集语义恒生效，配置只能追加）——此处仅是文档性默认值，漂移不影响强制性。
+      exclude: ['.worktrees', '.git', 'node_modules', 'target', 'build', 'dist'],
+    },
+  },
   glaf4_dev: {
     // glaf4-dev 运行时探测结果（v2.1 §4 接口①）
     // contract-builder 产出 execution-contract 时实时探测写入；delegation_mode 由用户/编排开关

package/scripts/lib/solutions-capture.mjs

@@ -42,6 +42,10 @@ export function run(args = {}) {
   const severity = args.severity || 'medium';
   const summary = args.summary || '(no summary)';
   const source = args.source || '';
+  // agent-governance P2-1：来源事件锚——correction 条目的毕业条件消费它
+  //（P2-2「锚未标撤销」判定；无锚条目按未毕业处理）。HOLD 场景 = escalation msg_id
+  // 或决策日志行；非空才写入 frontmatter。
+  const sourceEvent = args.source_event || '';
   const dir = args.dir || 'docs/solutions';
 
   // 注：process.exit 后补 return——真实 CLI 下 exit 即终止；测试环境 mock exit 时
@@ -79,6 +83,7 @@ type: ${type}
 severity: ${severity}
 date: ${date}
 source: ${source}
+${sourceEvent ? `source_event: ${sourceEvent}` : ''}
 title: ${title}
 ---
 

package/scripts/lib/solutions-index-gen.mjs

@@ -41,6 +41,34 @@ import { parseFrontmatter, listSolutionEntries } from './solutions-entry.mjs';
 /** INDEX 保留的最大**条目数**（非行数——文件还含 4 行头部） */
 export const MAX_INDEX_ENTRIES = 150;
 
+/**
+ * agent-governance P2-2（earned automation 见习）：毕业阈值。
+ * `flags` 列派生规则（**纯派生、随重建重算**——INDEX 是投影）：
+ * - 条目有 `source_event` 锚（P2-1 起的 correction 条目）：confirmations ≥ 本阈值 → `auto-ok`，
+ *   否则 → `probation`（见习：不进自动注入上下文）。
+ *   「锚被标撤销」的毕业否决暂无实现（撤销动作未建，如实声明——source_event 锚已就位，
+ *   撤销标记是其消费侧的未来项）。
+ * - 无锚存量条目 → `auto-ok`（**grandfather**：它们已在注入通道，见习化 = 行为回退，不采纳；
+ *   与 schema_version 存量豁免同构）。
+ * - 红区硬排除不在此处：红区判定是**消费侧**职责（inject 按 summary/domain 关键词排除），
+ *   flags 表示毕业状态、不表示区域。
+ */
+export const GRADUATED_MIN_CONFIRMATIONS = 3;
+
+/** 解析 frontmatter confirmations 计数（宽松：仅计数，promote 的严格解析不在此复用）。 */
+function countConfirmations(fm) {
+  const raw = fm?.confirmations;
+  if (raw == null || raw === '') return 0;
+  return String(raw).replace(/[[\]]/g, '').split(',').map((s) => s.trim()).filter(Boolean).length;
+}
+
+/** 派生 flags（见上注释的规则表）。 */
+export function deriveFlags(fm) {
+  const hasAnchor = Boolean(fm?.source_event && String(fm.source_event).trim());
+  if (!hasAnchor) return 'auto-ok';
+  return countConfirmations(fm) >= GRADUATED_MIN_CONFIRMATIONS ? 'auto-ok' : 'probation';
+}
+
 /**
  * 解析条目文件的 frontmatter（扁平键值）——**收敛到共享层**（v0.57.0 P4 二轮）。
  *
@@ -111,6 +139,8 @@ export function refreshIndex(dir, { phases = SOLUTION_PHASES, maxEntries = MAX_I
         file: `${phase}/${file}`,
         // v0.57.0 P4：source 进 INDEX 供 inject 做同源聚类（此前只存在于条目文件，消费方读不到）
         source: fm.source || '',
+        // P2-2：见习/毕业派生状态（规则见 GRADUATED_MIN_CONFIRMATIONS 注释）
+        flags: deriveFlags(fm),
       });
     }
   }
@@ -133,10 +163,10 @@ export function refreshIndex(dir, { phases = SOLUTION_PHASES, maxEntries = MAX_I
   // "只读 INDEX、不读条目文件"，故聚类键必须进索引。消费方对 7/8 列都容错（见 solutions-inject）。
   let index = '# Solutions Index\n';
   index += `<!-- 每条一行，排序 severity 降序 → date 降序 → file 兜底，≤${maxEntries} 条上限；summary/source 内的 | 转义为 \\| -->\n`;
-  index += '| date | phase | domain | type | severity | summary | file | source |\n';
-  index += '|------|-------|--------|------|----------|---------|------|--------|\n';
+  index += '| date | phase | domain | type | severity | summary | file | source | flags |\n';
+  index += '|------|-------|--------|------|----------|---------|------|--------|-------|\n';
   for (const e of kept) {
-    index += `| ${escapeCell(e.date)} | ${escapeCell(e.phase)} | ${escapeCell(e.domain)} | ${escapeCell(e.type)} | ${escapeCell(e.severity)} | ${escapeCell(e.summary)} | ${escapeCell(e.file)} | ${escapeCell(e.source)} |\n`;
+    index += `| ${escapeCell(e.date)} | ${escapeCell(e.phase)} | ${escapeCell(e.domain)} | ${escapeCell(e.type)} | ${escapeCell(e.severity)} | ${escapeCell(e.summary)} | ${escapeCell(e.file)} | ${escapeCell(e.source)} | ${escapeCell(e.flags)} |\n`;
   }
 
   writeFileSync(join(dir, 'INDEX.md'), index, 'utf-8');

package/scripts/lib/solutions-inject.mjs

@@ -37,16 +37,31 @@ import { severityRank } from './severity.mjs';
 import { parseTableRow } from './md-normalize.mjs';
 
 /**
- * INDEX 表列数范围（date | phase | domain | type | severity | summary | file [| source]）。
- * v0.57.0 P4：`source` 列是本版新增 ⇒ 7（存量 INDEX）与 8（本版重建）都要接受。
+ * INDEX 表列数范围（date | phase | domain | type | severity | summary | file | source | flags）。
+ * v0.57.0 P4：`source` 列新增 ⇒ 7/8 都要接受；
+ * agent-governance P2-2：`flags` 列（见习/毕业）新增 ⇒ 8（上版重建）与 9（本版）都要接受，
+ * **7 列最旧存量同样接受**（flags 缺失 = 无锚存量 = grandfather auto-ok，见 index-gen deriveFlags）。
  */
 const INDEX_COLUMNS_MIN = 7;
-const INDEX_COLUMNS_MAX = 8;
+const INDEX_COLUMNS_MAX = 9;
 /** `file` 列的形状（`<phase>/<name>.md`）——语义校验，见下方列解析注释 */
 const ENTRY_FILE_RE = /^[a-z][a-z-]*\/.+\.md$/;
 /** 默认展示条数 */
 const DEFAULT_LIMIT = 5;
 
+/**
+ * P2-2 红区硬排除：DP-A / Code Landing / publish 相关的复利建议**永不自动注入**
+ * （memo §2.4 红区护栏——红区永久人工，连"建议"也不自动进上下文，防复利通道
+ * 变相给红区动作背书）。宁可少注入（安全方向）不误放。
+ */
+const RED_ZONE_RE = /\bDP-A\b|Code Landing|\bpublish\b|发布闸|代码落地/i;
+
+/** P2-2 见习判定：flags 列非 auto-ok（probation 或未知新值）即不自动注入。 */
+function isProbation(flags) {
+  const f = String(flags || '').toLowerCase();
+  return f !== '' && f !== 'auto-ok';
+}
+
 export function run(args = {}) {
   const phase = args.phase || 'cross-phase';
   const domain = args.domain || '';
@@ -63,6 +78,8 @@ export function run(args = {}) {
 
   const content = readFileSync(indexPath, 'utf-8');
   const entries = [];
+  // P2-2 门控计数（可观察性：跳过多少 = 门在工作的证据）
+  const excluded = { probation: 0, redZone: 0 };
 
   for (const line of content.split('\n')) {
     if (!line.startsWith('|') || line.startsWith('| date') || line.startsWith('|--')) continue;
@@ -70,7 +87,7 @@ export function run(args = {}) {
     const cells = parseTableRow(line);
     // 上下界同时校验：只查下界无法发现"summary 含 `|` 导致列数变多、file 列错位"（v0.38.0 test-merge 同型缺陷）
     if (cells.length < INDEX_COLUMNS_MIN || cells.length > INDEX_COLUMNS_MAX) continue;
-    const [date, ePhase, eDomain, type, severity, summary, file, source = ''] = cells;
+    const [date, ePhase, eDomain, type, severity, summary, file, source = '', flags = ''] = cells;
     // file 列语义校验（v0.57.0 P4）：列数在界内仍可能错位——例如 summary 含**未转义**的 `|`
     // 时列数恰好落进 7/8 区间，摘要后半段会顶到 file 位。形状不符即丢弃，避免注入错位的路径。
     if (!ENTRY_FILE_RE.test(file)) continue;
@@ -79,7 +96,10 @@ export function run(args = {}) {
     const domainMatch = !domain || !eDomain || eDomain === 'general' || eDomain === domain;
 
     if (phaseMatch && domainMatch) {
-      entries.push({ date, phase: ePhase, domain: eDomain, type, severity, summary, file, source, isNative: ePhase === phase });
+      // P2-2 两道消费侧门控（跳过 = 不注入，落 excluded 计数可观察）
+      if (isProbation(flags)) { excluded.probation += 1; continue; }
+      if (RED_ZONE_RE.test(`${summary} ${eDomain}`)) { excluded.redZone += 1; continue; }
+      entries.push({ date, phase: ePhase, domain: eDomain, type, severity, summary, file, source, flags, isNative: ePhase === phase });
     }
   }
 
@@ -119,12 +139,17 @@ export function run(args = {}) {
   const shown = all ? clustered : clustered.slice(0, limit);
 
   if (shown.length === 0) {
-    console.log(`<!-- No matching solutions found (phase=${phase}, domain=${domain || 'any'}) -->`);
-    return { entries: [] };
+    // P2-2：「被门控排除成空」与「本来无匹配」语义不同——前者必须可见，否则门 = 隐形
+    const excl = (excluded.probation + excluded.redZone) > 0
+      ? `（P2-2 门控排除 ${excluded.probation} 条见习 + ${excluded.redZone} 条红区）` : '';
+    console.log(`<!-- No matching solutions found (phase=${phase}, domain=${domain || 'any'})${excl} -->`);
+    return { entries: [], excluded };
   }
 
   const foldedNote = foldedCount > 0 ? `, ${foldedCount} 条同源已折叠` : '';
-  console.log(`## Solutions Context (phase=${phase}, domain=${domain || 'any'}, showing ${shown.length}/${clustered.length}${foldedNote})`);
+  const excludedNote = (excluded.probation + excluded.redZone) > 0
+    ? `, P2-2 门控排除 ${excluded.probation} 条见习 + ${excluded.redZone} 条红区` : '';
+  console.log(`## Solutions Context (phase=${phase}, domain=${domain || 'any'}, showing ${shown.length}/${clustered.length}${foldedNote}${excludedNote})`);
   console.log('');
   for (const e of shown) {
     console.log(`- [${e.severity}] ${e.summary} (${e.phase}/${e.domain}, ${e.date}) → ${e.file}`);
@@ -140,7 +165,7 @@ export function run(args = {}) {
     console.log('');
   }
 
-  return { entries: shown, total: clustered.length, folded: foldedCount, hidden };
+  return { entries: shown, total: clustered.length, folded: foldedCount, hidden, excluded };
 }
 
 if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {

package/scripts/lib/state-loader.mjs

@@ -89,6 +89,11 @@ const BUILTIN_DEFAULTS = {
   test_matrix_skip_reason: null,
   // Test evidence (v0.13 §50：tf test record 落盘的 runner 输出证据路径)
   test_evidence_path: null,
+  // Product-level PRD clarity record（agent-governance P1-1 跨层管道）：
+  // 唯一写入路径 = tf state init 从 <root>/.team-flow/prd-clarity.json 拷贝；
+  // **有意不在 cmd-state SETTABLE_FIELDS**——可 set 就是自助放行通道（gate-hint-is-a-bypass）。
+  prd_clarity_result: null,
+  prd_clarity_hash: null,
   // Tasks gate (v0.22 §85：hotfix/tweak 跳过 spec-writer 时显式跳过 tasks.md)
   tasks_skipped: null,
   tasks_skip_reason: null,
@@ -184,6 +189,14 @@ export function writeState(changeDir, state) {
   lines.push('# === Hashes (fast staleness detection) ===');
   lines.push(`artifacts_hash: ${state.artifacts_hash ?? 'null'}`);
   lines.push(`contract_hash: ${state.contract_hash ?? 'null'}`);
+  // P1-1 clarity 管道：条件序列化（同 schema_version 模式）——存量 change 无记录不追加，
+  // readState 缺失回退 BUILTIN_DEFAULTS 的 null（= 变更级维度中性）。
+  if (state.prd_clarity_result != null) {
+    lines.push(`prd_clarity_result: ${state.prd_clarity_result}`);
+  }
+  if (state.prd_clarity_hash != null) {
+    lines.push(`prd_clarity_hash: ${state.prd_clarity_hash}`);
+  }
   lines.push('');
   lines.push('# === Execution progress ===');
   lines.push(`execution_mode: ${state.execution_mode ?? 'null'}`);

package/scripts/team-flow.mjs

@@ -71,6 +71,9 @@ Commands:
   arch scaffold         Scaffold global docs/architecture/ ledger in generator format (v0.53.0 §102)
   arch precheck <change-dir> [--json]
                         Emit deterministic architecture-gate evidence (v0.22 §88; evidence only, exit 0)
+  arch scan-code [--root <path>|--project-root <path>] [--repos <a,b>] [--annotation <name>] [--exclude <a,b>] [--json]
+                        Scan code for persistence annotations (C4 anchor; v1.4 §5.4-4b;
+                        read-only, zero-dep, evidence only, exit 0; status=na N/A, status=partial partial coverage — neither is PASS)
   arch-merge <change-dir> [--project-root <path>] [--dry-run] [--light]
                         Merge architecture delta into global docs/architecture/
   test-merge <change-dir> [--project-root <path>] [--dry-run] [--light]

package/skills/architecture-design/SKILL.md

@@ -22,7 +22,7 @@ description: 基于 4A 企业架构 + DDD 领域驱动设计的架构/API/DB 设
 实体(唯一标识)+值对象(无标识)+聚合根(唯一入口)+事务边界(聚合内一事务)。聚合仅存于业务服务；数据服务/技术服务无聚合。
 
 ### F5 · 限界上下文(Context Map)
-语义边界=L3 应用服务；同术语异义须显式映射(Shared Kernel / Anti-Corruption Layer / Open Host Service)。
+语义边界=L3 应用服务；同术语异义须显式映射——**经典 8 模式**（Shared Kernel / Customer-Supplier / Conformist / Anti-Corruption Layer / Open Host Service / Separate Ways / Partnership / Published Language），选型走决策流（`references/context-map-8.md`，含 Mermaid；CML NO-GO）。
 
 ### F6 · CQRS 写读模型
 事务型对象→写模型(聚合，Command/Read 操作)；分析型对象→读模型(查询模型，Query 派生，无事务)。Command/Read→写模型；Query 经阻断测试分流。
@@ -37,7 +37,7 @@ description: 基于 4A 企业架构 + DDD 领域驱动设计的架构/API/DB 设
 - ch01-4a-domains — 4A 四域定义与分叉依赖
 - ch02-change-cascade — 变更级联与跨域一致性门禁
 - ch03-architecture-outputs — 架构产出三层 + 治理三支柱
-- ch04-entity-to-aggregate — 业务实体→聚合→限界上下文
+- ch04-entity-to-aggregate — 业务实体→聚合→子域→限界上下文
 - ch05-cqrs — 写/读模型、指令分流、三维判定
 - ch06-integration — 与 team-flow / compound-engineering 的集成
 
@@ -54,6 +54,11 @@ description: 基于 4A 企业架构 + DDD 领域驱动设计的架构/API/DB 设
 - Command / Read / Query → ch05
 - 阻断测试 / 三维判定 → ch05
 - 增量设计 / As-Is 冻结 / 复利回写 / 全局锚点 → ch06
+- 子域 / 问题空间·解空间 / 统一语言索引 → ch04, 产品级模板 §0/§1.1（O2/O3）
+- Context Map 8 模式 / 决策流 / Mermaid → references/context-map-8.md（O7）
+- 事件 schema 版本策略 / 领域事件表 → 产品级模板 §3.2 门禁段 + 变更级模板 §2.5（O4）
+- Saga 补偿矩阵 / Projection 重建 / ADR 模板 → references/ddd-evented-playbook.md, references/adr-templates.md（O5/O6）
+- DDD 深度 advisory / ddd_depth（lightweight≠skipped）→ 「DDD 深度 advisory」段 + 结构化输出契约（O1）
 
 ## Workflow Integration: 判断+执行一体化（v0.9 §26）
 
@@ -67,10 +72,19 @@ description: 基于 4A 企业架构 + DDD 领域驱动设计的架构/API/DB 设
 
 - `change-brief.md`（scope / AC / 技术方向）
 - `requirement/vN/plan.md` 高阶技术设计段（模块边界/技术选型/数据流/关键聚合划分）
-- `docs/architecture/iterations/vN/architecture.md`（产品级架构快照，**主输入**，v0.35.0）——BC 边界/聚合所有权/全局契约的唯一事实源；**Fast Path 下不读**（见 `### Fast Path`）
+- `docs/architecture/iterations/vN/architecture.md`（产品级架构快照，**设计期主输入**，v0.35.0）——BC 边界/聚合所有权/全局契约的设计输入（★ O8：**落地态权威 = 全局 ARCHITECTURE.md**（registry 渲染），快照 = grounding + seed 源 + 体检基准，不称唯一事实源）；**Fast Path 下不读**（见 `### Fast Path`）
 - 全局 `docs/architecture/`（As-Is 实际态基线，已落地部分）
 - 现有 `specs/`（若有）
 
+### DDD 深度 advisory（O1 · 在五项检查**之前**执行）
+
+按**领域复杂度**输出 DDD 深度旗标（advisory，**绝不替代 `decision`**）：
+
+- **三判据**（禁「4 选 2」硬阈值，防 LLM 套用偏差放大）：① 是否有丰富行为/不变量 ② 是否存在模型冲突（同词异义/多义） ③ 是否存在值得深建模的 Core Domain。
+- 输出 `ddd_depth: full | lightweight`。吸收「3 Questions + 反模式红牌」（微服务过早 / CQRS / 事件溯源 / DDD / Repository 可能过度工程）。
+- **★ 头号红牌：`lightweight ≠ skipped`**——lightweight 分支**仍须走完五项检查，且第 4/5 项（API / DB schema）不得短路**；只是战术建模从简（可省略部分 DDD 战术制品），判定与 API/DB 设计照做。
+- **诚实边界**：LLM 是否把 lightweight 误当"可跳过"**无法机械观测**——由契约正交 lint 与步骤表静态检查收敛路径，行为层保留人审（§10 风险如实登记）。
+
 ### 五项检查（架构变更判定）
 
 依次检查以下五项，**全部为否** → `decision: skipped`；**任一为是** → `decision: required`：
@@ -111,25 +125,23 @@ description: 基于 4A 企业架构 + DDD 领域驱动设计的架构/API/DB 设
 **流程**（不硬阻断，显式确认 + 登记 deviation）：
 1. **呈现变更摘要**：涉及的产品级决策 + 影响范围（引用快照章节）
 2. **用户确认**（阻塞问题工具）：接受 → 执行变更；拒绝 → 保持产品级定义，change 内走增量
-3. **登记 deviation**：确认后写入 `orchestrator.yaml` 的 `replan_log`（`seq/trigger: arch-deviation/before/after/approved_by`）+ 在 `iterations/vN/architecture.md` 演进日志追加修订记录（迭代收尾 S3.5 确认晋升）
+3. **登记 deviation**：确认后写入 `orchestrator.yaml` 的 `replan_log`（`seq/trigger: arch-deviation/before/after/approved_by`——**可机读唯一落点**）；**Rationale/Consequences 按 `references/adr-templates.md` 选型**（五模板；仅「难逆转 ∧ 无上下文会困惑 ∧ 真实权衡」三条件全满足才写完整 ADR，否则 replan_log 一行即可，防泛滥；**不另起 `docs/adr/`**，防双轨漂移）+ 在 `iterations/vN/architecture.md` 演进日志追加修订记录（迭代收尾 S3.5 确认晋升）
 4. **`new` 聚合 flag**：在 `iterations/vN/architecture.md` 聚合注册表标注 `[pending-promotion]`，待下一迭代产品级晋升
 
 ### 执行流程
 
 ```
 1. 读取输入（brief + plan + specs + 全局 ARCHITECTURE.md）——**Fast Path 裁剪为「brief + precheck 输出」**
-2. 执行五项检查
-3. 全部为否：
-   → decision: skipped
-   → reason: 简述不涉及架构变更的理由
-   → 返回结构化输出
+1.5 DDD 深度 advisory（领域复杂度三判据 → ddd_depth: full | lightweight；advisory，不影响 decision）
+2. 执行五项检查（ddd_depth: lightweight 分支**同样执行全部五项**，第 4/5 项不得短路）
+3. 全部为否 → decision: skipped + reason（不涉及架构变更）→ 返回结构化输出（含 ddd_depth）
 4. 任一为是：
    → decision: required
    → reason: 简述涉及的架构变更项
-   → 执行完整 4A+DDD 增量设计（F1-F8）
+   → 执行 4A+DDD 增量设计（F1-F8；ddd_depth: lightweight 时战术制品从简，API/DB 产出不减）
    → 产出 architecture/architecture.md + database.md + api.md
    → artifacts: 产出路径列表
-   → 返回结构化输出
+   → 返回结构化输出（含 ddd_depth）
 ```
 
 ### 结构化输出契约
@@ -137,6 +149,8 @@ description: 基于 4A 企业架构 + DDD 领域驱动设计的架构/API/DB 设
 返回给 workflow-start 的结果**必须**包含以下字段：
 
 ```yaml
+ddd_depth: full | lightweight    # O1 advisory：与 decision **正交**——任意组合合法；
+                                 # 禁止从 lightweight 推导/默认出 skipped（契约正交 lint 锁定）
 decision: required | skipped
 reason: "..."                    # skipped 时：不涉及架构变更的理由
                                  # required 时：涉及的变更项摘要
@@ -146,6 +160,10 @@ artifacts:                       # required 时必填，skipped 时为空
   - architecture/api.md
 ```
 
+> **schema 正交（O1 判据①，规则文本 lint）**：`ddd_depth ∈ {full, lightweight}` 与 `decision ∈ {required, skipped}`
+> 同时存在、取值域独立、**任意组合合法**（lightweight+required / lightweight+skipped / full+required / full+skipped 全允许）——
+> schema 层**不得**出现 `lightweight → skipped` 的推导或默认值。该 lint 校验的是**我们写下的规则文本自洽**，不校验 LLM 实际判定（诚实边界见 advisory 段）。
+
 **职责边界**：architecture-design 负责**判断+产出**（五项检查判断是否涉及架构变更，涉及则产出架构设计文档），workflow-start 负责**reasonableness check + 状态写入**（确认判断合理性后写入 yaml）。
 
 ### 产出目录

package/skills/architecture-design/chapters/ch04-entity-to-aggregate.md

@@ -1,4 +1,4 @@
-# ch04 · 业务实体→聚合→限界上下文
+# ch04 · 业务实体→聚合→子域→限界上下文
 
 ## 业务实体（识别起点）
 - 定义：BA 流程中的**表证单书**（订单/合同/工单/客户档案/库存记录），是业务概念而非数据库表。
@@ -15,12 +15,23 @@
 - 事务边界：聚合内所有操作须在一个事务完成（如创建订单同时建头/行项目/算总价）。
 - **硬规则**：聚合仅存在于业务服务；数据服务（跨聚合查询分析）、技术服务（消息队列）**无聚合**。
 
-## 限界上下文 / Context Map（核心框架 F5）
-- 限界上下文=语义边界，对应 L3 应用服务；相关聚合组成上下文。
-- 同术语异义须显式映射（映射类型）：
-  - **Shared Kernel（共享内核）**：两上下文共享部分模型。
-  - **Anti-Corruption Layer（防腐层）**：下游翻译上游模型，防止概念泄漏。
-  - **Open Host Service（开放主机）**：上游暴露标准协议供多下游消费。
+## 子域（问题空间 · 投资分级）
+- **子域(Subdomain)**：业务问题空间的分区（Vernon《IDDD》），先于解空间存在；子域 → 限界上下文是**多对多映射**（一个 BC 常服务多个子域），不是 1:1。
+- **三分类**：**Core**（核心竞争力，深建模）/ **Supporting**（保障性，最小定制）/ **Generic**（通用能力，买或复用）——**分类驱动 BC 投资**。
+- **纪律**：子域描述只写**业务问题**，不列 service / 包名 / 类名（问题空间 ≠ 解空间；按实现载体划子域/BC 是已知失效模式，须人审）。
+
+## 限界上下文 / Context Map（核心框架 F5 · 经典 8 模式，O7）
+- 限界上下文=语义边界，对应 L3 应用服务；相关聚合组成上下文（**解空间，≠ 子域**）。
+- 同术语异义须显式映射——**8 模式全集**（与产品级模板 §1.2 同步，教 = 用）：
+  - **Separate Ways**：不集成（先问要不要集成再选型）。
+  - **Partnership**：对等团队共同演进、双向承诺。
+  - **Customer-Supplier**：供需协商契约。
+  - **Conformist**：下游全盘接受上游模型。
+  - **Open Host Service**：上游开放标准协议供多下游消费。
+  - **Anti-Corruption Layer**：下游翻译上游模型，防止概念泄漏。
+  - **Shared Kernel**：两上下文共享部分模型，变更须协商。
+  - **Published Language**：标准化语义词汇（与 OHS 天然配对）。
+- **决策流与 Mermaid 生成**：见 `references/context-map-8.md`（选型顺序 Separate Ways → Partnership → Customer-Supplier → Conformist → OHS+PL → ACL → Shared Kernel；CML DSL 导出 = NO-GO）。
 
 ## 应用提示
 - 每变更设计先画"涉及实体的活动对象矩阵"；再定聚合根与事务边界；最后落到全局 Context Map。

package/skills/architecture-design/chapters/ch06-integration.md

@@ -6,8 +6,9 @@
 ```
 项目根/
 ├── STRATEGY.md              # 产品/BA 锚点（compound，不动）
-├── CONCEPTS.md              # 领域词汇（追加 DDD 术语，复利累积）
 ├── docs/architecture/       # 【技术锚点层，独立于 STRATEGY.md】
+│   ├── CONCEPTS.md          # ★ 业务统一语言唯一内容写入点（per-BC 业务术语定义）+ DDD 方法术语，复利累积
+│   │                        #   快照 §0 只是其 per-BC 索引（术语→锚点，不含定义）——零双写，见 O2
 │   ├── ARCHITECTURE.md      # 全局架构（瘦锚点：Context Map+聚合清单+关键决策）
 │   └── DATABASE.md          # 全局 DB（实体+读写模型+OLTP/OLAP）
 
@@ -28,13 +29,21 @@ changes/<name>/              # change 容器
 
 > **语义分离**：架构产出独立 `architecture/` 目录，不混入 `specs/`（行为规格）。目录存在 = 有架构产出，目录不存在 = 判定为不需要。下游消费方（spec-writer / release-archivist）显式读取此目录。
 
+## CONCEPTS.md 维护（O2 · 业务统一语言）
+
+- **两段拆分**：`docs/architecture/CONCEPTS.md` 内容组织分「**技术层角色词汇**」与「**per-BC 业务统一语言**」两段——技术分层角色（infra / agg / adapter / bff 等）**不是领域词**，不得混入业务段（消 emp-auth 审计 B6/B7 技术 jargon 污染）。
+- **主动纪律（活的语言，非静态表）**：① **挑战术语**——业务术语首现即问"业务方听得懂吗"；② **锐化模糊语**——歧义词当场拆义项，不带病累积；③ **场景压测**——拿真实业务场景验证术语覆盖度；④ **对照代码**——术语与代码标识符互查漂移（LLM 生成的 UL **必须人审**，防幻觉领域概念）。
+- 快照 §0 只维护索引（per-BC 术语 → 锚点）；本文件的更新触发时机靠流程纪律（**无机械门禁**，方案 CQ-12 已登记），由迭代收尾人审把关。
+
 ## 每变更增量设计（SOP 步骤，v0.35.0 更新：产品级快照为输入）
-1. (LLM) 读全局 ARCHITECTURE.md **+ 产品级快照 `iterations/vN/architecture.md`**（v0.35.0，BC 边界/聚合注册表唯一事实源）作 grounding；识别本 change 触及的 BC → 按 `references/s3.5-loading-protocol.md` 三段式装载对应域；用活动对象矩阵识别限界上下文/聚合（变更级只引用产品级注册表，不重定义）。
+1. (LLM) 读全局 ARCHITECTURE.md **+ 产品级快照 `iterations/vN/architecture.md`**（v0.35.0 作 grounding；★ O8 修正：**落地态权威 = 全局 ARCHITECTURE.md marker 区**（registry 渲染、source 列归因），快照承担 grounding + 首次 seed + 差异体检基准三角色——**不再称"唯一事实源"**，forward-designed 快照是预测态）；识别本 change 触及的 BC → 按 `references/s3.5-loading-protocol.md` 三段式装载对应域；用活动对象矩阵识别限界上下文/聚合（变更级只引用产品级注册表，不重定义）。
 2. (LLM) 出 To-Be：**本 change 增量**（extend/new/refactor 三类动作）——新增/调整聚合、Context Map 关系、CQRS 读写模型、4A 跨域对齐；触及产品级决策走架构修订决策门。
 3. **As-Is 冻结**（核心修正）：复制产品级快照/全局相关章节**当前原文** + 记版本锚点（`iterations/vN/architecture.md@<change_id>#<章节>`），变更内不可变——杜绝活引用漂移。
 4. (脚本) 填 frontmatter 并校验：`cap_id/date/change_type/bounded_contexts/aggregates_affected/cqrs`。
 5. (LLM) 写 ADR 理由；API 标 Command/Read/Query + 阻断测试归属。
-6. (脚本) 回写全局 + 生成 API 索引。
+6. (LLM→脚本) **O8 两段式回写**：先（LLM 语义段）从本 change 制品产 `architecture/.arch-delta.json`
+   （new/extend/refactor/retire + evidence，见 release-archivist ①-pre）；再（CLI 确定段）`tf arch-merge`
+   消费该制品合并进 `docs/architecture/.registry/registry.json` 并生成全局产物（确定段零 LLM，可重放）。
 
 ## 复利回写（借鉴 ce-compound，已正名）
 - **one change per run**：一次回写一个变更 delta，可追溯、不混杂。

package/skills/architecture-design/glossary.md

@@ -1,6 +1,10 @@
 # Glossary · 架构设计术语表
 
+> **本表是方法论术语表**（4A / DDD 概念），**不是业务域统一语言**——per-BC 业务术语的唯一内容写入点是 **`docs/architecture/CONCEPTS.md`**（根位置自 v0.23.0 已弃用），快照 §0 只是其索引（O2）。
+
 - **BA / IA / AA / TA**：业务/信息(数据)/应用(功能)/技术 架构四域。仅 TA 是技术架构。
+- **子域(Subdomain)**：业务**问题空间**的分区，先于解空间存在；Core/Supporting/Generic 三分类驱动投资。
+- **问题空间 / 解空间**：问题空间 = 业务问题与子域（做什么）；解空间 = 限界上下文与聚合（怎么做）。子域 → BC 多对多映射，**不是 1:1**；按实现载体（service/包）划子域是已知失效模式。
 - **分叉依赖**：`BA→(IA∥AA)→TA`，BA 先行、IA/AA 并行双向对齐、TA 最后。
 - **跨域一致性（双对齐）**：AA 功能≥1 IA 实体支撑，IA 实体≥1 AA 功能消费；结构+语义双对齐。
 - **架构产出三层**：元素(积木)/制品(图纸)/交付件(成品)。
@@ -9,7 +13,7 @@
 - **聚合(Aggregate)**：实体+值对象+聚合根+事务边界；仅存业务服务。
 - **聚合根(Aggregate Root)**：聚合外部唯一入口。
 - **值对象(Value Object)**：无独立标识，属性变即另一对象。
-- **限界上下文(Bounded Context)**：语义边界，对应 L3 应用服务。
+- **限界上下文(Bounded Context)**：语义边界，对应 L3 应用服务；属**解空间**，不等于子域。
 - **Context Map**：限界上下文间关系图；映射类型 Shared Kernel / Anti-Corruption Layer / Open Host Service。
 - **CQRS**：写模型(事务型,聚合)与读模型(分析型,查询模型)分离建模。
 - **写模型(Write Model)**：事务型对象在 AA 的表达，有聚合根/事务边界，Command/Read 操作。