sillyspec 3.28.7 → 3.28.9

package/src/progress.js

@@ -12,7 +12,7 @@
 
 import { existsSync, mkdirSync, readFileSync, writeFileSync, renameSync, unlinkSync, appendFileSync, copyFileSync, readdirSync, statSync, realpathSync } from 'fs';
 import { join, basename, dirname, resolve, sep } from 'path';
-import { tmpdir } from 'os';
+import { tmpdir, hostname } from 'os';
 import { writeAtomicSync } from './fs-atomic.js';
 import { DB } from './db.js';
 import { checkExecuteCodeEvidence } from './stage-contract.js';
@@ -81,6 +81,61 @@ export class PlatformManagedError extends PointerUnreachableError {
   }
 }
 
+// ── 会话标识三级解析（2026-09-14-change-ownership-guards task-02，FR-01 / D-001@v1）──
+// 优先级：--session flag > env SILLYSPEC_SESSION_ID > quick 场景 changeName（quick-<8hex>，
+// 既有 sessionId 机制——guard 按 change 名落盘天然跨进程）> anon@<hostname> 机器级降级。
+// 降级时打一次性教学 warning：指引 export SILLYSPEC_SESSION_ID=<唯一标识> 或 --session，
+// 明示无标识时同机并行不设防（R-01 明示局限，防线=显式标识铁律+归档收口+--takeover 摩擦）。
+// 「一次性」双层降频：进程内 memo（同进程多次解析只报一次）+ 跨进程 marker 文件窗口
+// （warnSelfRefPointerOnce 同款模式；CLI 每次调用即新进程，纯进程 memo 会退化成每命令必报）。
+const ANON_SESSION_WARN_MARKER = 'anon-session-warn.json';
+const ANON_SESSION_WARN_WINDOW_MS = 24 * 60 * 60 * 1000; // 教学指引 24h 窗口（非告警，不设短窗）
+const QUICK_SID_PATTERN_FOR_IDENTITY = /^quick-[0-9a-f]{8}$/;
+let _anonSessionWarnedThisProcess = false;
+
+/**
+ * 解析本会话的所有权标识（纯函数 + 降级侧的一次性教学 warn）。
+ * @param {{ flagSession?: string|null, quickChangeName?: string|null, cwd?: string|null, warn?: boolean }} [opts]
+ *   - flagSession：--session flag 值（最高优先级；空串/空白视为未提供）
+ *   - quickChangeName：quick 场景的 changeName（匹配 quick-<8hex> 才启用第三级）
+ *   - cwd：教学 warning marker 落盘根（不提供则跳过跨进程降频，仅进程内 memo）
+ *   - warn：false 关闭教学 warning（机器消费路径）
+ * @returns {{session: string, source: 'flag'|'env'|'quick-session'|'anon-host'}}
+ */
+export function resolveSessionIdentity({ flagSession = null, quickChangeName = null, cwd = null, warn = true } = {}) {
+  const flag = typeof flagSession === 'string' ? flagSession.trim() : '';
+  if (flag) return { session: flag, source: 'flag' };
+  const env = typeof process.env.SILLYSPEC_SESSION_ID === 'string' ? process.env.SILLYSPEC_SESSION_ID.trim() : '';
+  if (env) return { session: env, source: 'env' };
+  if (quickChangeName && QUICK_SID_PATTERN_FOR_IDENTITY.test(quickChangeName)) {
+    return { session: quickChangeName, source: 'quick-session' };
+  }
+  const session = `anon@${hostname()}`;
+  if (warn && !_anonSessionWarnedThisProcess) {
+    let suppressed = false;
+    if (cwd) {
+      try {
+        const markerDir = join(cwd, SPEC_DIR_NAME, RUNTIME_SUBDIR);
+        mkdirSync(markerDir, { recursive: true });
+        const markerPath = join(markerDir, ANON_SESSION_WARN_MARKER);
+        const now = Date.now();
+        try {
+          const m = JSON.parse(readFileSync(markerPath, 'utf8'));
+          if (m && Number.isFinite(m.at) && now - m.at < ANON_SESSION_WARN_WINDOW_MS) suppressed = true;
+        } catch { /* 无 marker / 损坏 → 首报 */ }
+        if (!suppressed) writeFileSync(markerPath, JSON.stringify({ at: now }) + '\n');
+      } catch { /* marker 落盘失败 → 照常 warn（降频是优化不是语义） */ }
+    }
+    if (!suppressed) {
+      _anonSessionWarnedThisProcess = true;
+      console.warn(`⚠️ 未显式配置会话标识，所有权护栏已降级为机器级标识 ${session}（只拦他机，同机并行会话不设防）`);
+      console.warn(`   指引：会话启动时 export SILLYSPEC_SESSION_ID=<唯一标识>（如 agent 名+任务名），或在接管类命令上带 --session <唯一标识>（三级解析最高优先级）`);
+      console.warn(`   （24 小时内不重复提示）`);
+    }
+  }
+  return { session, source: 'anon-host' };
+}
+
 /**
  * 平台感知的 specDir 解析（fail-closed，所有 CLI 子命令统一入口）。
  *
@@ -435,7 +490,7 @@ export class ProgressManager {
     }
 
     const result = {
-      _version: 5,
+      _version: 6,
       project: projectName,
       currentChange: cName,
       currentStage: currentStage || '',
@@ -460,7 +515,9 @@ export class ProgressManager {
    * 输出契约（字段名 = DB 列名 snake_case，import 直接对列写回，round-trip 无映射损耗）：
    *   project        { name, schema_version }                                        —— 全局单行稳定字段（id/created_at/updated_at 本地元数据不同步）
    *   changes        [{ name, current_stage, status, last_active,
-   *                      last_synced_platform_ts, last_local_modified_ts }]           —— 只投影流程进度列；
+   *                      last_synced_platform_ts, last_local_modified_ts, owner_session }] —— 只投影流程进度列
+   *                     + 所有权列 owner_session（v6，2026-09-14-change-ownership-guards D-005@v1；
+   *                     NULL=无主随 payload 带出，平台消费端不强制）；
    *                     排除 isolation_* 系列 与 platform_* 系列（platform_change_id/workspace_id/last_sync/sync_enabled）
    *                     以及 created_at（本地强相关，不同步，B2）
    *   stages         [{ change_name, stage, status, started_at, completed_at,
@@ -490,9 +547,9 @@ export class ProgressManager {
     const db = this._ensureDB(cwd);
     const sqlDb = db.getDb();
 
-    // 1. changes 行（投影流程进度列 + name 标识）
+    // 1. changes 行（投影流程进度列 + name 标识 + 所有权列 owner_session）
     const changeRow = sqlDb.prepare(
-      `SELECT id, name, current_stage, status, last_active, last_synced_platform_ts, last_local_modified_ts
+      `SELECT id, name, current_stage, status, last_active, last_synced_platform_ts, last_local_modified_ts, owner_session
        FROM changes WHERE name = ?`
     ).get(changeName);
     if (changeRow === undefined) return null;
@@ -504,6 +561,7 @@ export class ProgressManager {
       last_active: changeRow.last_active,
       last_synced_platform_ts: changeRow.last_synced_platform_ts ?? null,
       last_local_modified_ts: changeRow.last_local_modified_ts ?? null,
+      owner_session: changeRow.owner_session ?? null,
     };
 
     // 2. project 全局单行（只投影稳定字段 name/schema_version；created_at/updated_at 是本地库元数据，
@@ -600,7 +658,8 @@ export class ProgressManager {
    *
    * 语义：
    * - 单个 DB.transaction() 包裹，原子重建 stages/steps/batch_progress/approvals 四表（任一失败整体回滚）
-   * - changes 行用 UPDATE 选择投影列（current_stage/status/last_active/last_synced_platform_ts/last_local_modified_ts），
+   * - changes 行用 UPDATE 选择投影列（current_stage/status/last_active/last_synced_platform_ts/last_local_modified_ts
+   *   + owner_session 容错回写——payload 含该列才写），
    *   保留 isolation_* / platform_* / created_at（本地强相关状态不被覆盖，B2；change 不存在时 INSERT 兜底平台新增）
    * - import 后 last_synced_platform_ts 与 last_local_modified_ts 均置为 progressObj.pushed_at（D-013 例外：
    *   不更新 now()——否则 now()>base_ts 下次 pull 误判冲突；pushed_at 由 sync.js pull() 从响应 header attach）
@@ -673,6 +732,12 @@ export class ProgressManager {
           ch && ch.last_active != null ? ch.last_active : now,
           pushedAt, pushedAt, cn
         );
+        // owner_session 回写容错（v6，2026-09-14-change-ownership-guards task-01）：payload 含
+        // 该列（非 null）才写——他端旧版本快照无此列 → 跳过不报错，且本地已有 owner 不被置空
+        // （平台权威态随 payload 往返；serializeForSync↔import 互逆在非 null 值上成立）。
+        if (ch && ch.owner_session != null) {
+          sqlDb.prepare('UPDATE changes SET owner_session = ? WHERE name = ?').run(ch.owner_session, cn);
+        }
         const changeRow = sqlDb.prepare('SELECT id FROM changes WHERE name = ?').get(cn);
         const changeId = changeRow.id;
 
@@ -806,6 +871,22 @@ export class ProgressManager {
    *   3. 单进程内调用串行（design §9），事务窗口短（毫秒级），全量写正确性远高于 diff 的边际收益。
    * 结论：全量 UPSERT 的简单正确性 > 持锁窗口优化的边际收益，不强行改 diff。
    */
+  /** .bak 快照节流间隔（坑2②）：5 分钟——损坏回退最坏丢 5 分钟进度，换取每次写零额外负担 */
+  static SNAPSHOT_INTERVAL_MS = 5 * 60_000;
+
+  _maybeSnapshotBak(cwd) {
+    try {
+      const dbPath = this._runtimePath(cwd, 'sillyspec.db');
+      const bakPath = dbPath + '.bak';
+      const st = existsSync(bakPath) ? statSync(bakPath) : null;
+      if (st && Date.now() - st.mtimeMs < ProgressManager.SNAPSHOT_INTERVAL_MS) return;
+      const tmpPath = bakPath + '.tmp';
+      try { unlinkSync(tmpPath) } catch { /* 不存在即无事 */ }
+      this._ensureDB(cwd).getDb().exec(`VACUUM INTO '${tmpPath.replace(/'/g, "''")}'`);
+      renameSync(tmpPath, bakPath);
+    } catch { /* best-effort：快照失败只损失恢复源新鲜度，不影响写入主流程 */ }
+  }
+
   _write(cwd, data, changeName = null) {
     const cn = changeName || data.currentChange;
     if (!cn) {
@@ -813,6 +894,13 @@ export class ProgressManager {
       return;
     }
 
+    // 坑 platform-sync-progress-rollback-and-db-corruption 坑2②（2026-09-08 实证）：并发写
+    // 把主库打成 0 字节时 .bak 全空——fail-loud 有其设计正当性但无恢复出路，只能删库重放。
+    // 定期 .bak 快照（5 分钟龄控）让 db.js _openWithFallback 的既有回退链获得新鲜恢复源：
+    // 损坏最坏回退到 ≤5min 前的进度，而不是从零重放。VACUUM INTO 产出一致性快照（对 WAL
+    // 并发写安全；比裸 copyFileSync 正确），best-effort 失败不影响写入主流程。
+    this._maybeSnapshotBak(cwd);
+
     const db = this._ensureDB(cwd);
     db.transaction(() => {
       const sqlDb = db.getDb();
@@ -915,7 +1003,7 @@ export class ProgressManager {
   // 或 verify 两窗口，锚「完成时刻」会把 execute 期间产的证据判旧（时序两难）；无行 null 走 completed_at → R-05
   getStageStartedAt(cwd, changeName, stage) { return this._changeRegistry.getStageStartedAt(cwd, changeName, stage); }
 
-  registerChange(cwd, changeName) { return this._changeRegistry.registerChange(cwd, changeName); }
+  registerChange(cwd, changeName, opts) { return this._changeRegistry.registerChange(cwd, changeName, opts); }
 
   updateChangeIsolation(cwd, changeName, isolation) { return this._changeRegistry.updateChangeIsolation(cwd, changeName, isolation); }
 
@@ -949,6 +1037,28 @@ export class ProgressManager {
   // quick --done 兜底复用启动 ql-ID（坑 platform-takeover-phantom-progress-db 同日变体）
   getQuicklogId(cwd, changeName) { return this._changeRegistry.getQuicklogId(cwd, changeName); }
 
+  // ── change 所有权读写 API（2026-09-14-change-ownership-guards task-01 数据载体，D-001/D-005@v1）──
+  // 只铺数据读写；所有权判定/心跳窗口/接管语义（assertChangeOwnership）归 task-02 接线。
+
+  /** 读变更所有者会话标识；无行/未登记/无主 → null */
+  getChangeOwner(cwd, changeName) { return this._changeRegistry.getChangeOwner(cwd, changeName); }
+
+  /** 认领所有权：首建写 own、已有值不覆盖；返回实际 owner（string|null） */
+  claimChangeOwner(cwd, changeName, session) { return this._changeRegistry.claimChangeOwner(cwd, changeName, session); }
+
+  // task-02 接线（FR-01 / D-001@v1）：判定/接管/心跳窗——会话标识三级解析见模块级
+  // resolveSessionIdentity；接线点=index.js apply/cleanup/assess 自动 apply（锁内、实际动作前）。
+
+  /**
+   * 所有权判定（纯读不写库，详见 change-registry.assertChangeOwnership）：
+   * 四分支 self/no-owner/takeover-stale/takeover-forced 放行；他人且活跃窗内 →
+   * { allowed:false, action:'blocked-active-owner' }（owner+lastActive+heartbeatMs 供结构化错误）。
+   */
+  assertChangeOwnership(cwd, changeName, opts) { return this._changeRegistry.assertChangeOwnership(cwd, changeName, opts); }
+
+  /** 强制重写所有者+心跳起算（接管放行后的写库侧；claimChangeOwner 是「已有值不覆盖」守卫版） */
+  setChangeOwner(cwd, changeName, session) { return this._changeRegistry.setChangeOwner(cwd, changeName, session); }
+
   // ── CLI 命令 ──
 
   init(cwd) {
@@ -995,10 +1105,15 @@ export class ProgressManager {
     }
     // quick 会话 id（quick-<uuid8>，见 run.js QUICK_SID_RE）只作 progress 的跨进程 session key，
     // 进度存 SQL 不需要实体 change 目录——跳过避免 changes/quick-<uuid>/ 空目录残留。
+    // default 兜底 key 同款待遇（坑 default-empty-dir-materialized，2026-09-14 用户反馈）：
+    // default 行是辅助阶段（explore 等）无实体产物的进度容器，物化 changes/default/ 空目录
+    // 纯污染——next.js 会报「变更目录为空→清理该空目录」误导、resolveChangeNameAuto 的目录
+    // 计数被搅动、spec 树上行空目录（本仓实证 changes/default/ 建于 09-11 零文件）。进度真相
+    // 在 DB 行；辅助阶段续跑锚定改由 run/command.js 的 default 行阶段亲和解析承担。
     // 注：日期前缀门禁（assertDatedChangeName）只在 CLI 边界强制（run --change / change-rename，
     // 见 run/command.js + index.js）——initChange 是库函数，测试/平台工具合法用任意名建 fixture，
     // 不在此设门（2026-09-11 决策，避免 ~30 处测试 fixture 非日期名被拦）。
-    if (!/^quick-[0-9a-f]{8}$/.test(changeName)) {
+    if (!/^quick-[0-9a-f]{8}$/.test(changeName) && changeName !== 'default') {
       this._ensureChangeDir(cwd, changeName);
     }
 

package/src/quick-gate-profile.js

@@ -0,0 +1,251 @@
+/**
+ * quick-gate-profile.js — quick 出口分级门禁画像（信号层，纯函数零 IO）
+ *
+ * quick --done 分级门禁的信号单一来源（2026-09-14-quick-exit-tiered-gates task-01 / FR-02）：
+ * 输入 CLI 审计链的 git 事实 changedFiles（非 --files 自声明）+ 调用方传入的 moduleIndex
+ * （_module-map.yaml 解析结果），输出 L0/L1/L2 画像与检查项，供 Wave 2 接线消费
+ * （run/shared.js 挂 review.gateProfile → complete-handlers 落账 / quick-audit 打印 /
+ * scope-audit 表格与 --json 双出口）。本模块零 IO、零子进程：moduleIndex、风险表、阈值
+ * 全部由参数或默认值提供（D-007 独立纯函数模块；R-04 画像=纯字符串运算）。
+ *
+ * 判级（阈值只引用 THRESHOLDS 常量，不散落字面量）：
+ *   正常态（moduleIndex 可用）：L2 = 跨 ≥L2_SPAN 模块 或 风险命中；L1 = 跨 ≥L1_SPAN 模块
+ *     或 ≥L1_FILES 文件；否则 L0。
+ *   降级态（moduleIndex 为 null/undefined/空，如未 scan / 无 module-map 的存量项目）：
+ *     span 退出判级，L2 = ≥L2_FILES_DEGRADED 文件 或 风险命中；L1 = ≥L1_FILES 文件。
+ *   全部 advisory（D-003：升 blocking 是另立变更的显式决策），不抛错不阻断。
+ *
+ * 计数口径（design 接口定义，勿自创字段）：
+ *   fileCount     = 全部变更文件数（判级用的「文件数」信号与之一致——与旧「≤3 文件」规则
+ *                   及 sillyhub 校准统计同基）；
+ *   testFileCount = 非文档文件中：路径含 __tests__/、/tests/ 目录段、basename test_ 前缀
+ *                   （python 风格）或 .test./_test./.spec. 命名（对齐仓内既有测试判定先例）；
+ *   codeFileCount = 其余非文档文件。文档口径沿用 docSyncHint 的 isDoc（run/shared.js
+ *                   auditQuickCompletion 内 isDocFile 同款：.md/.yaml/.yml 扩展或 docs/、
+ *                   .sillyspec/docs/ 前缀——模块卡与 changelog sidecar 均 .md 天然覆盖），
+ *                   文档文件不计入 testFileCount/codeFileCount，也不参与模块归属与风险命中。
+ */
+import { QUICK_RISK_PATH_PATTERNS } from './change-risk-profile.js'
+
+/** 代码内默认阈值（task-05 真实图谱校准定稿，缺省行为的单一事实源；local.yaml quick-gate 段可覆写，D-009）。
+ *  定稿依据（2026-09-14，sillyhub 919 条 quicklog × 5 份真实 _module-map.yaml 重算交叉表，
+ *  证据全文见主仓 changes/2026-09-14-quick-exit-tiered-gates/design.md「阈值校准记录」）：
+ *  L1_SPAN=2 落在文档同步率断崖上（≤3 文件档 span1 33.3% → span2-3 5.9%，近期口径）；
+ *  L2_SPAN=4 边界内格子全档最差（近期 span4+×4-10 文件 0-14.3%）；L1_FILES=4 维持旧规则
+ *  「≤3 文件」边界连续性（文件维度无同步率断崖——量错维度的实证本身）；L2_FILES_DEGRADED=8
+ *  覆盖降级档最差文件桶 7-10（32.9-35.3%）。四值与 brainstorm 初值一致，维持不调。 */
+export const THRESHOLDS = {
+  L1_SPAN: 2,            // 跨 ≥2 模块 → L1
+  L1_FILES: 4,           // 或 ≥4 文件 → L1
+  L2_SPAN: 4,            // 跨 ≥4 模块 → L2
+  L2_FILES_DEGRADED: 8,  // module-map 缺失降级档：≥8 文件 → L2
+}
+
+/** local.yaml quick-gate 键 → THRESHOLDS 常量键（覆写面与代码默认值的单一对照）。 */
+const GATE_KEY_TO_THRESHOLD = {
+  l1_span: 'L1_SPAN',
+  l1_files: 'L1_FILES',
+  l2_span: 'L2_SPAN',
+  l2_files_degraded: 'L2_FILES_DEGRADED',
+}
+
+/** 阈值合法性：≥1 的有限整数（0/负数会让一切改动升 L1、浮点/字符串无意义）。 */
+function isValidThreshold(v) {
+  return typeof v === 'number' && Number.isInteger(v) && v >= 1
+}
+
+/**
+ * 合并 local.yaml quick-gate 段覆写与代码默认值（D-009）。
+ * @param {object} config local.yaml 解析结果（无 quick-gate 段 → 全默认；键非法回退默认并 warn）
+ * @returns {{ l1_span: number, l1_files: number, l2_span: number, l2_files_degraded: number }}
+ */
+export function resolveGateThresholds(config) {
+  const merged = {
+    l1_span: THRESHOLDS.L1_SPAN,
+    l1_files: THRESHOLDS.L1_FILES,
+    l2_span: THRESHOLDS.L2_SPAN,
+    l2_files_degraded: THRESHOLDS.L2_FILES_DEGRADED,
+  }
+  const section = config == null ? undefined : config['quick-gate']
+  if (section == null) return merged
+  if (typeof section !== 'object' || Array.isArray(section)) {
+    console.warn('[quick-gate] local.yaml quick-gate 段须为键值对象，已忽略（使用默认阈值）')
+    return merged
+  }
+  for (const [key, constName] of Object.entries(GATE_KEY_TO_THRESHOLD)) {
+    if (!(key in section)) continue
+    const v = section[key]
+    if (isValidThreshold(v)) merged[key] = v
+    else console.warn(`[quick-gate] local.yaml 配置键 quick-gate.${key}=${JSON.stringify(v)} 非法（须为 ≥1 整数），回退默认 ${THRESHOLDS[constName]}`)
+  }
+  return merged
+}
+
+// ── 计数口径判定（文档/测试/代码三分；口径见文件头注释） ──
+
+/** 文档文件口径：沿用 docSyncHint 的 isDoc（run/shared.js auditQuickCompletion 内 isDocFile 逐款同源）。 */
+function isDocPath(p) {
+  return p.endsWith('.md') || p.endsWith('.yaml') || p.endsWith('.yml') ||
+    p.startsWith('docs/') || p.startsWith('.sillyspec/docs/')
+}
+
+/** __tests__/ 或 tests/ 目录段（/test_ 前缀与命名判定在 isTestPath 内）。 */
+const TEST_DIR_RE = /(^|\/)(__tests__|tests)\//i
+
+/** 测试文件判定：目录段、basename test_ 前缀、.test./_test./.spec. 命名三信号任一命中。 */
+function isTestPath(p) {
+  if (TEST_DIR_RE.test(p)) return true
+  const base = p.slice(p.lastIndexOf('/') + 1)
+  if (/^test_/i.test(base)) return true
+  return /[._](test|spec)\.[^.]+$/i.test(base)
+}
+
+/** moduleIndex 兼容两种形态：parseModuleMapSimple 扁平 { id: {...} } 或 { modules: {...} } 包装；空 → null（degraded）。 */
+function resolveModulesObject(moduleIndex) {
+  if (moduleIndex == null || typeof moduleIndex !== 'object') return null
+  const wrapped = moduleIndex.modules
+  const obj = wrapped && typeof wrapped === 'object' && !Array.isArray(wrapped) ? wrapped : moduleIndex
+  return Object.keys(obj).length > 0 ? obj : null
+}
+
+/** 一级归属：paths/core_files 字面量或目录前缀命中（与 docs-debt matchFilesToModules 一级口径同款，纯内存零 IO）。 */
+function matchModuleForFile(posix, modulesObj) {
+  for (const [id, m] of Object.entries(modulesObj)) {
+    if (m == null || typeof m !== 'object') continue
+    const prefixes = [...(Array.isArray(m.paths) ? m.paths : []), ...(Array.isArray(m.core_files) ? m.core_files : [])]
+    for (const raw of prefixes) {
+      const p = String(raw).replace(/\\/g, '/').replace(/\/+$/, '')
+      if (!p) continue
+      if (posix === p || posix.startsWith(p + '/')) return id
+    }
+  }
+  return null
+}
+
+/** 卡片认领判定：模块 doc 字段（如 modules/core-engine.md）对应卡片文件在 changedFiles 内。
+ *  changedFiles 为仓库根相对路径（如 .sillyspec/docs/<project>/modules/core-engine.md），
+ *  本函数无 cwd/project 入参，按字面量或后缀对齐。 */
+function cardInFiles(doc, fileSet) {
+  const d = doc.replace(/\\/g, '/').replace(/^\.\//, '')
+  for (const f of fileSet) {
+    if (f === d || f.endsWith('/' + d)) return true
+  }
+  return false
+}
+
+/**
+ * quick 出口门禁画像（纯函数：无 IO、无子进程，moduleIndex/风险表/阈值全由参数或默认值）。
+ * @param {string[]} changedFiles 变更文件（CLI 审计链 git 事实；反斜杠自动归一 POSIX）
+ * @param {object|null} moduleIndex _module-map.yaml 解析结果（null/undefined/空 → degraded）
+ * @param {object} [opts]
+ * @param {Array<{pattern: string, re: RegExp}>} [opts.riskTable] 路径模式风险表（默认 QUICK_RISK_PATH_PATTERNS）
+ * @param {object} [opts.thresholds] 已合并阈值（resolveGateThresholds 产物；缺省用 THRESHOLDS，D-009）
+ * @param {Array<{path: string}>} [opts.fileNotes] --file-notes 解析结果（perFileNotes 覆盖率判定）
+ * @param {boolean} [opts.noDocs] --no-docs 显式豁免（docClaim → exempt-no-docs）
+ * @returns 画像对象（字段与判级规则见 design.md 接口定义）
+ */
+export function computeGateProfile(changedFiles, moduleIndex, opts = {}) {
+  const riskTable = Array.isArray(opts.riskTable) ? opts.riskTable : QUICK_RISK_PATH_PATTERNS
+
+  // 阈值：opts.thresholds 逐键取合法值，否则回 THRESHOLDS 默认（warn 责任在 resolveGateThresholds）
+  const th = {}
+  for (const [key, constName] of Object.entries(GATE_KEY_TO_THRESHOLD)) {
+    const v = opts.thresholds ? opts.thresholds[key] : undefined
+    th[key] = isValidThreshold(v) ? v : THRESHOLDS[constName]
+  }
+
+  const files = (Array.isArray(changedFiles) ? changedFiles : [])
+    .map((f) => String(f).replace(/\\/g, '/'))
+    .filter(Boolean)
+
+  const notedPaths = new Set(
+    (Array.isArray(opts.fileNotes) ? opts.fileNotes : [])
+      .filter((n) => n != null && typeof n.path === 'string' && typeof n.note === 'string' && n.note.trim() !== '')
+      .map((n) => n.path.replace(/\\/g, '/')),
+  )
+
+  const codeFiles = []
+  const testFiles = []
+  for (const f of files) {
+    if (isDocPath(f)) continue // 文档文件不计入两者、不参与归属与风险命中（口径见文件头）
+    if (isTestPath(f)) testFiles.push(f)
+    else codeFiles.push(f)
+  }
+
+  const modulesObj = resolveModulesObject(moduleIndex)
+  const degraded = modulesObj === null
+
+  // 模块归属（非文档文件 × paths/core_files 前缀聚类）；degraded 时不算，modules=[]、unmappedFiles=[]
+  const modules = []
+  const unmappedFiles = []
+  if (!degraded) {
+    const byModule = new Map()
+    for (const f of [...codeFiles, ...testFiles]) {
+      const id = matchModuleForFile(f, modulesObj)
+      if (id == null) { unmappedFiles.push(f); continue }
+      const entry = byModule.get(id)
+      if (entry) entry.files.push(f)
+      else byModule.set(id, { id, files: [f] })
+    }
+    modules.push(...byModule.values())
+  }
+  const moduleSpan = degraded ? null : modules.length
+
+  // 风险命中：非文档文件 × 路径模式表（v1 仅路径模式，无 diff 关键词维度；元素只含 pattern/file）
+  const riskHits = []
+  for (const f of [...codeFiles, ...testFiles]) {
+    for (const entry of riskTable) {
+      const re = entry == null ? null : entry.re
+      if (!(re instanceof RegExp)) continue
+      if (re.global) re.lastIndex = 0 // 防调用方传入 /g 正则跨文件携带 lastIndex 状态
+      if (re.test(f)) riskHits.push({ pattern: entry.pattern, file: f })
+    }
+  }
+
+  // 判级：正常态 span 参与；degraded 态 span 退出（L1=≥l1_files、L2=≥l2_files_degraded 或风险命中）
+  let level = 'L0'
+  if (degraded) {
+    if (files.length >= th.l2_files_degraded || riskHits.length > 0) level = 'L2'
+    else if (files.length >= th.l1_files) level = 'L1'
+  } else if (moduleSpan >= th.l2_span || riskHits.length > 0) level = 'L2'
+  else if (moduleSpan >= th.l1_span || files.length >= th.l1_files) level = 'L1'
+
+  // L1：--file-notes 覆盖率（changedFiles 全集均有非空注记 → true；`path::` 空括注不算——防形式化绕过；
+  // 空集空真 true——L0 不消费）
+  const perFileNotes = files.every((f) => notedPaths.has(f))
+
+  // L1 机械规则：codeFileCount ≥2 且 testFileCount===0 → missing；codeFileCount ≤1 → na；其余 ok
+  let testDelta
+  if (codeFiles.length <= 1) testDelta = 'na'
+  else if (testFiles.length === 0) testDelta = 'missing'
+  else testDelta = 'ok'
+
+  // L2：模块文档认领（触及模块中带 doc 卡片的模块，其卡片文件全在 changedFiles → claimed；
+  // 无带卡片的触及模块（含 degraded）→ 无可认领，空真 claimed 不出假 advisory；--no-docs 优先豁免）
+  let docClaim
+  if (opts.noDocs) docClaim = 'exempt-no-docs'
+  else {
+    const fileSet = new Set(files)
+    const claimable = modules.filter((e) => {
+      const m = modulesObj == null ? null : modulesObj[e.id]
+      return m != null && typeof m === 'object' && typeof m.doc === 'string' && m.doc.trim() !== ''
+    })
+    docClaim = claimable.every((e) => cardInFiles(modulesObj[e.id].doc, fileSet)) ? 'claimed' : 'missing'
+  }
+
+  // L2 风险命中：运行时证据要求（advisory 提示，不引入 quick 没有的 wait 机制）
+  const runtimeEvidence = riskHits.length > 0 ? 'required' : 'na'
+
+  return {
+    fileCount: files.length,
+    codeFileCount: codeFiles.length,
+    testFileCount: testFiles.length,
+    moduleSpan,
+    modules,
+    unmappedFiles,
+    riskHits,
+    level,
+    degraded,
+    checks: { perFileNotes, testDelta, docClaim, runtimeEvidence },
+  }
+}