@dommaker/harness 0.18.0 → 1.0.0

package/src/core/constraints/check-cache.ts

@@ -4,10 +4,19 @@
  * 缓存 git diff 和 src/ 递归扫描结果，减少重复 I/O。
  * 同一请求内多次 checkConstraints 调用共享缓存。
  *
+ * 计数采样（H6/G5，收编 studio runtime/cache.ts）：
+ * get/getSync 可传声明式采样配置，对每个 (namespace, key) 独立计数，
+ * 第 1 次调用必执行，此后每 N 次执行 1 次完整检查，其余 N-1 次复用缓存；
+ * 非采样轮缓存未命中（无缓存或已过期）时返回 defaultValueOnMiss，不执行 fn。
+ * invalidate 同时重置对应计数，保证失效后下一次调用恢复为完整检查。
+ *
  * 用法：
  * ```typescript
  * const cache = new CheckCache({ ttlMs: 5000 });
+ * // 普通 TTL 缓存
  * const diff = await cache.get('git_diff', projectPath, () => runCommand('git diff --cached', projectPath));
+ * // 计数采样：每 3 次调用执行 1 次完整检查
+ * const ok = await cache.get('goal_check', key, check, { sampleRate: 3, defaultValueOnMiss: true });
  * ```
  */
 
@@ -16,13 +25,41 @@ interface CacheEntry {
   expiresAt: number;
 }
 
+/**
+ * CheckCache 构造配置
+ */
 export interface CheckCacheConfig {
   /** 缓存 TTL（毫秒），默认 5000 */
   ttlMs: number;
 }
 
+/**
+ * 计数采样配置（声明式）
+ *
+ * 传此配置后，对应 (namespace, key) 启用计数采样：
+ * - 第 1 次调用必执行 fn（采样轮），结果以正常 TTL 写入缓存；
+ * - 其后每 N 次调用执行 1 次（计数独立于普通缓存读写）；
+ * - 非采样轮：缓存命中（未过期）返回缓存值；未命中或已过期
+ *   返回 {@link defaultValueOnMiss}，不执行 fn、不刷新 TTL。
+ */
+export interface CheckSamplingConfig<T> {
+  /** 采样率：每 N 次调用执行 1 次完整检查；N <= 1 视为不采样（回退为普通 TTL 缓存语义） */
+  sampleRate: number;
+  /** 非采样轮且缓存未命中（无缓存或已过期）时的默认返回值 */
+  defaultValueOnMiss: T;
+}
+
+/**
+ * 约束检查缓存：TTL 缓存 + 可选计数采样
+ *
+ * 普通 get/getSync 为 TTL 缓存；传入 sampling 配置后对应 (namespace, key)
+ * 启用计数采样（每 N 次执行 1 次完整检查，其余轮次复用缓存或返回
+ * defaultValueOnMiss）。语义详见 {@link CheckSamplingConfig}。
+ */
 export class CheckCache {
   private store = new Map<string, CacheEntry>();
+  /** 采样计数器（仅启用采样的 key 有计数） */
+  private sampleCounters = new Map<string, number>();
   private ttlMs: number;
 
   constructor(config?: CheckCacheConfig) {
@@ -35,19 +72,28 @@ export class CheckCache {
    * @param namespace 命名空间（如 'git_diff', 'src_scan'）
    * @param key 缓存键（如 projectPath）
    * @param fn miss 时的计算函数
+   * @param sampling 计数采样配置（可选；不传时每次 miss 都执行 fn）
    */
   async get<T>(
     namespace: string,
     key: string,
     fn: () => Promise<T>,
+    sampling?: CheckSamplingConfig<T>,
   ): Promise<T> {
     const cacheKey = `${namespace}:${key}`;
     const entry = this.store.get(cacheKey);
+    const rate = sampling ? Math.max(1, Math.floor(sampling.sampleRate)) : 1;
+    // 采样轮优先于缓存命中：每 N 次调用必执行一次完整检查（第 1 次必执行）
+    const sampleTurn = rate > 1 && this.isSampleTurn(cacheKey, rate);
 
-    if (entry && Date.now() < entry.expiresAt) {
+    if (!sampleTurn && entry && Date.now() < entry.expiresAt) {
       return entry.value as T;
     }
 
+    if (sampling && rate > 1 && !sampleTurn) {
+      return sampling.defaultValueOnMiss;
+    }
+
     const value = await fn();
     this.store.set(cacheKey, {
       value,
@@ -58,19 +104,28 @@ export class CheckCache {
 
   /**
    * 同步版本（用于 readdirSync 等同步操作）
+   *
+   * @param sampling 计数采样配置（语义同 {@link get}）
    */
   getSync<T>(
     namespace: string,
     key: string,
     fn: () => T,
+    sampling?: CheckSamplingConfig<T>,
   ): T {
     const cacheKey = `${namespace}:${key}`;
     const entry = this.store.get(cacheKey);
+    const rate = sampling ? Math.max(1, Math.floor(sampling.sampleRate)) : 1;
+    const sampleTurn = rate > 1 && this.isSampleTurn(cacheKey, rate);
 
-    if (entry && Date.now() < entry.expiresAt) {
+    if (!sampleTurn && entry && Date.now() < entry.expiresAt) {
       return entry.value as T;
     }
 
+    if (sampling && rate > 1 && !sampleTurn) {
+      return sampling.defaultValueOnMiss;
+    }
+
     const value = fn();
     this.store.set(cacheKey, {
       value,
@@ -80,7 +135,8 @@ export class CheckCache {
   }
 
   /**
-   * 使指定命名空间缓存失效
+   * 使指定命名空间缓存失效（同时重置该命名空间的采样计数器，
+   * 保证失效后的下一次调用恢复为采样轮/完整检查）
    */
   invalidate(namespace?: string): void {
     if (namespace) {
@@ -89,8 +145,24 @@ export class CheckCache {
           this.store.delete(key);
         }
       }
+      for (const key of this.sampleCounters.keys()) {
+        if (key.startsWith(`${namespace}:`)) {
+          this.sampleCounters.delete(key);
+        }
+      }
     } else {
       this.store.clear();
+      this.sampleCounters.clear();
     }
   }
+
+  /**
+   * 计数采样判定：计数 +1 后返回是否采样轮（第 1 次必采样，每 N 次 1 次）。
+   * 仅在采样启用（rate > 1）时调用。
+   */
+  private isSampleTurn(cacheKey: string, rate: number): boolean {
+    const count = (this.sampleCounters.get(cacheKey) ?? 0) + 1;
+    this.sampleCounters.set(cacheKey, count);
+    return count % rate === 1;
+  }
 }

package/src/core/constraints/checker.ts

@@ -17,7 +17,7 @@ import {
   ConstraintViolationError,
 } from '../../types/constraint';
 import type { ExecutionTrace } from '../../types/trace';
-import { IRON_LAWS, GUIDELINES, TIPS, PROMPTS } from './definitions';
+import { IRON_LAWS, GUIDELINES, PROMPTS } from './definitions';
 import type { MergedConstraintsConfig } from '../../types/project-config';
 import { normalizeTriggers } from '../../utils/exec';
 import { runCommand } from '../../utils/exec';
@@ -74,9 +74,6 @@ const NOOP_TRACE_RECORDER: TraceRecorder = { record: () => undefined };
 export class ConstraintChecker {
   private static instance: ConstraintChecker;
 
-  /** 自定义约束配置（项目级） */
-  private customConfig: MergedConstraintsConfig | null = null;
-
   /** 检查结果缓存（S7：src 扫描等重复 I/O，TTL=1s 防跨测试污染） */
   private cache: CheckCache = new CheckCache({ ttlMs: 1000 });
 
@@ -139,31 +136,20 @@ export class ConstraintChecker {
     this.traceRecorder = recorder;
   }
 
-  /**
-   * 设置项目级约束配置
-   *
-   * @deprecated 修改单例状态，多项目并发时存在污染风险。
-   * 请改用 checkConstraints() / beforeExecution() 的 customConfig 参数实现 per-request 隔离。
-   */
-  setCustomConfig(config: MergedConstraintsConfig): void {
-    this.customConfig = config;
-  }
-
   /**
    * 获取当前的约束集合（内置 + 自定义）
    *
-   * @param customConfig 可选，per-request 自定义配置（优先级高于 setCustomConfig 的单例状态）
+   * @param customConfig 可选，per-request 自定义配置；不传则返回内置约束集
    */
   getConstraints(customConfig?: MergedConstraintsConfig | null): {
     ironLaws: Record<string, Constraint & { check: (ctx: ConstraintContext) => Promise<ConstraintResult> }>;
     guidelines: Record<string, Constraint & { check: (ctx: ConstraintContext) => Promise<ConstraintResult> }>;
-    tips: Record<string, Constraint & { check: (ctx: ConstraintContext) => Promise<ConstraintResult> }>;
     prompts: Record<string, Constraint & { check: (ctx: ConstraintContext) => Promise<ConstraintResult> }>;
   } {
-    const config = customConfig ?? this.customConfig;
+    const config = customConfig;
     const source = config
-      ? { ironLaws: config.ironLaws, guidelines: config.guidelines, tips: config.tips, prompts: config.prompts ?? PROMPTS }
-      : { ironLaws: IRON_LAWS, guidelines: GUIDELINES, tips: TIPS, prompts: PROMPTS };
+      ? { ironLaws: config.ironLaws, guidelines: config.guidelines, prompts: config.prompts ?? PROMPTS }
+      : { ironLaws: IRON_LAWS, guidelines: GUIDELINES, prompts: PROMPTS };
 
     // Wire unified check() method on every constraint
     const wire = (constraints: Record<string, Constraint>) => {
@@ -175,7 +161,6 @@ export class ConstraintChecker {
     return {
       ironLaws: wire(source.ironLaws),
       guidelines: wire(source.guidelines),
-      tips: wire(source.tips),
       prompts: wire(source.prompts),
     };
   }
@@ -260,7 +245,6 @@ export class ConstraintChecker {
       case 'guideline':
         return 'warning';
       case 'prompt':
-      case 'tip':
         return 'info';
       default:
         return 'warning';
@@ -350,7 +334,6 @@ export class ConstraintChecker {
   ): {
     ironLaws: Constraint[];
     guidelines: Constraint[];
-    tips: Constraint[];
     prompts: Constraint[];
   } {
     const operations = [context.operation, ...(context.extraTriggers ?? [])];
@@ -368,17 +351,15 @@ export class ConstraintChecker {
     return {
       ironLaws: filterByTrigger(constraints.ironLaws),
       guidelines: filterByTrigger(constraints.guidelines),
-      tips: filterByTrigger(constraints.tips),
       prompts: filterByTrigger(constraints.prompts),
     };
   }
 
   /**
-   * 执行三层约束检查
+   * 执行约束检查
    *
    * - Iron Laws：检查失败立即抛出异常
    * - Guidelines：检查失败记录警告
-   * - Tips：检查失败记录提示
    *
    * @param context 约束上下文
    * @param customConfig 可选，per-request 自定义配置（避免多请求间的单例状态污染）
@@ -395,10 +376,8 @@ export class ConstraintChecker {
       const result: ConstraintCheckResult = {
         ironLaws: [],
         guidelines: [],
-        tips: [],
         passed: true,
         warningCount: 0,
-        tipCount: 0,
       };
 
       const traceCollector = this.traceRecorder;
@@ -431,19 +410,6 @@ export class ConstraintChecker {
         }
       }
 
-      // 3. Tips: 仅记录
-      for (const constraint of Object.values(constraints.tips)) {
-        if (!this.matchesTrigger(constraint, context)) continue;
-
-        const checkResult = await this.check(constraint, context);
-        result.tips.push(checkResult);
-        this.recordTrace(traceCollector, constraint, checkResult, context);
-
-        if (!checkResult.satisfied) {
-          result.tipCount++;
-        }
-      }
-
       return result;
     } finally {
       this.runCache = null;
@@ -451,7 +417,7 @@ export class ConstraintChecker {
   }
 
   /**
-   * S11: 安全全量检查 — 全部三层约束检查，不抛异常
+   * S11: 安全全量检查 — 全部约束检查，不抛异常
    *
    * 区别 checkConstraints(): Iron Law 违规收集在结果中而不是抛异常。
    * 调用方通过 result.passed + result.warningCount 判断状态。
@@ -468,10 +434,8 @@ export class ConstraintChecker {
       const result: ConstraintCheckResult = {
         ironLaws: [],
         guidelines: [],
-        tips: [],
         passed: true,
         warningCount: 0,
-        tipCount: 0,
       };
 
       const traceCollector = this.traceRecorder;
@@ -493,14 +457,6 @@ export class ConstraintChecker {
         if (!checkResult.satisfied) result.warningCount++;
       }
 
-      for (const constraint of Object.values(constraints.tips)) {
-        if (!this.matchesTrigger(constraint, context)) continue;
-        const checkResult = await this.check(constraint, context);
-        result.tips.push(checkResult);
-        this.recordTrace(traceCollector, constraint, checkResult, context);
-        if (!checkResult.satisfied) result.tipCount++;
-      }
-
       return result;
     } finally {
       this.runCache = null;
@@ -549,13 +505,12 @@ export async function checkConstraint(
   const constraint =
     constraints.ironLaws[constraintId] ||
     constraints.guidelines[constraintId] ||
-    constraints.tips[constraintId] ||
     constraints.prompts[constraintId];
 
   if (!constraint) {
     return {
       id: constraintId,
-      level: 'tip',
+      level: 'guideline',
       satisfied: false,
       message: `未知的约束: ${constraintId}`,
       checkedAt: new Date(),

package/src/core/constraints/definitions.ts

@@ -4,8 +4,6 @@
  * kind 二元模型（ADR-0001）：
  * - IRON_LAWS / GUIDELINES：check 层，必须带真实 checker（注册表闭环）
  * - PROMPTS：prompt 层，纯文本注入，不占检查位
- * - TIPS：已退役，导出空表仅为在途消费者（capabilities-syncer）编译兼容，
- *   后续阶段随其改造一并删除
  *
  * 工单 20：字面量定义按层拆至 ./definitions/{iron-laws,guidelines,prompts}.ts；
  * 本文件保持原路径做薄聚合（studio rule-scanner 按此路径解析，P0 #8）。
@@ -16,12 +14,6 @@ import { IRON_LAWS } from './definitions/iron-laws';
 import { GUIDELINES } from './definitions/guidelines';
 import { PROMPTS } from './definitions/prompts';
 
-/**
- * @deprecated TIPS 已退役（ADR-0001），恒为空表。
- * 仅为在途 capabilities-syncer 编译兼容保留，后续阶段删除。
- */
-export const TIPS: Record<string, Constraint> = {};
-
 export { IRON_LAWS, GUIDELINES, PROMPTS };
 
 // ========================================

package/src/core/constraints/doc-freshness/runner.ts

@@ -44,7 +44,6 @@ interface RunContext {
   constraintCounts?: {
     ironLaws?: number;
     guidelines?: number;
-    tips?: number;
   };
 }
 
@@ -58,7 +57,7 @@ export class FreshnessRunner {
   runAll(
     config: DocFreshnessConfig,
     projectPath: string,
-    ctx?: { requiredDirs?: string[]; constraintCounts?: { ironLaws?: number; guidelines?: number; tips?: number } }
+    ctx?: { requiredDirs?: string[]; constraintCounts?: { ironLaws?: number; guidelines?: number } }
   ): FreshnessCheckResult[] {
     if (config.enabled === false) return [];
     if (!config.checks || config.checks.length === 0) return [];

package/src/core/constraints/index.ts

@@ -2,12 +2,11 @@
  * 约束模块入口
  */
 
-// 约束定义（kind 二元：check 层 + prompt 层；TIPS 已退役，空表仅为在途兼容保留）
+// 约束定义（kind 二元：check 层 + prompt 层）
 export {
   IRON_LAWS,
   GUIDELINES,
   PROMPTS,
-  TIPS,
   getAllConstraints,
   findConstraintsByTrigger,
   getConstraint,
@@ -29,6 +28,16 @@ export {
   renderConstraintsSection,
 } from './injection-renderer';
 
+// 约束检查缓存（H6/G5：TTL 缓存 + 计数采样，公开导出）
+export { CheckCache } from './check-cache';
+export type { CheckCacheConfig, CheckSamplingConfig } from './check-cache';
+
+// Agent prompt 约束段渲染（H6/G6：trigger 参数化分组渲染，role 路由留 studio）
+export {
+  renderConstraintsByTrigger,
+} from './agent-prompt-renderer';
+export type { RenderConstraintsByTriggerOptions } from './agent-prompt-renderer';
+
 // 类型导出
 export type {
   ConstraintId,

package/src/core/constraints/interceptor.ts

@@ -115,14 +115,13 @@ export class ConstraintInterceptor {
     const allConstraints = [
       ...Object.values(constraints.ironLaws),
       ...Object.values(constraints.guidelines),
-      ...Object.values(constraints.tips),
     ].filter(c => c.kind !== 'prompt');
 
     const applicableConstraints = allConstraints.filter(
       (c) => normalizeTriggers<ConstraintTrigger>(c.trigger).includes(trigger)
     );
 
-    const order: Record<ConstraintLevel, number> = { iron_law: 0, guideline: 1, prompt: 2, tip: 3 };
+    const order: Record<ConstraintLevel, number> = { iron_law: 0, guideline: 1, prompt: 2 };
     const ordered = applicableConstraints.sort((a, b) => order[a.level] - order[b.level]);
 
     for (const constraint of ordered) {
@@ -200,10 +199,6 @@ export class ConstraintInterceptor {
 
 export const constraintInterceptor = ConstraintInterceptor.getInstance();
 
-// 注册内置 executors
-import { registerDefaultExecutors } from './default-executors';
-registerDefaultExecutors();
-
 export async function interceptOperation(
   trigger: ConstraintTrigger,
   context: ConstraintContext

package/src/core/effective-constraints.ts

@@ -29,7 +29,6 @@ export function getEffectiveConstraints(projectRoot: string = process.cwd()): Co
   return [
     ...Object.values(merged.ironLaws),
     ...Object.values(merged.guidelines),
-    ...Object.values(merged.tips),
     ...Object.values(merged.prompts ?? {}),
   ];
 }

package/src/core/project-config-loader.ts

@@ -172,7 +172,6 @@ export class ProjectConfigLoader {
     const result: MergedConstraintsConfig = {
       ironLaws: presetMerged.ironLaws,
       guidelines: presetMerged.guidelines,
-      tips: {},
       prompts: presetMerged.prompts ?? {},
       disabled: [...presetMerged.disabled],
       custom: [],
@@ -196,7 +195,6 @@ export class ProjectConfigLoader {
           // 从对应层级中移除
           delete result.ironLaws[constraintId];
           delete result.guidelines[constraintId];
-          delete result.tips[constraintId];
           delete result.prompts![constraintId];
         }
       }
@@ -225,7 +223,6 @@ export class ProjectConfigLoader {
           ];
           if (result.ironLaws[id]) result.ironLaws[id] = constraint;
           if (result.guidelines[id]) result.guidelines[id] = constraint;
-          if (result.tips[id]) result.tips[id] = constraint;
           if (result.prompts![id]) result.prompts![id] = constraint;
           continue;
         }
@@ -255,9 +252,6 @@ export class ProjectConfigLoader {
         case 'prompt':
           result.prompts![id] = constraint;
           break;
-        case 'tip':
-          result.tips[id] = constraint;
-          break;
       }
     }
 
@@ -285,7 +279,7 @@ export class ProjectConfigLoader {
     id: string,
     merged: MergedConstraintsConfig
   ): Constraint | undefined {
-    return merged.ironLaws[id] || merged.guidelines[id] || merged.tips[id] || merged.prompts?.[id];
+    return merged.ironLaws[id] || merged.guidelines[id] || merged.prompts?.[id];
   }
 
   /**

package/src/dashboard/stats.ts

@@ -4,7 +4,7 @@
  * 纯函数，从原始数据计算统计指标
  */
 
-import type { KnowledgeEntry, KnowledgeType } from '../knowledge/types';
+import type { KnowledgeEntry, KnowledgeSubsystem } from '../knowledge/types';
 import type { KnowledgeOverview, KnowledgeFlow } from './types';
 
 /**
@@ -36,7 +36,7 @@ export function computeKnowledgeOverview(entries: KnowledgeEntry[]): KnowledgeOv
  * 按类型分组统计
  */
 function computeByType(entries: KnowledgeEntry[]): KnowledgeOverview['byType'] {
-  const typeMap = new Map<KnowledgeType, { total: number; proven: number; verified: number; draft: number }>();
+  const typeMap = new Map<KnowledgeSubsystem, { total: number; proven: number; verified: number; draft: number }>();
 
   for (const entry of entries) {
     const existing = typeMap.get(entry.type) || { total: 0, proven: 0, verified: 0, draft: 0 };

package/src/dashboard/types.ts

@@ -4,7 +4,7 @@
  * harness 提供数据，studio 负责渲染
  */
 
-import type { KnowledgeType } from '../knowledge/types';
+import type { KnowledgeSubsystem } from '../knowledge/types';
 
 // ── 约束分层（原 src/constraints/types，约束分层子系统删除后归位 dashboard）──
 
@@ -28,7 +28,7 @@ export interface ConstraintStats {
 
 export interface KnowledgeOverview {
   byType: Array<{
-    type: KnowledgeType;
+    type: KnowledgeSubsystem;
     total: number;
     proven: number;
     verified: number;

package/src/failure/constraint-handler.ts

@@ -108,10 +108,8 @@ export class ConstraintViolationHandler {
       const empty: ConstraintCheckResult = {
         ironLaws: [],
         guidelines: [],
-        tips: [],
         passed: false,
         warningCount: 0,
-        tipCount: 0,
       };
       return {
         strategy: 'COLLECT',

package/src/gates/CONTEXT.md

@@ -1,27 +1,30 @@
 # gates/
 
 ## 职责
-质量门禁系统：6 种门禁检查（验收/命令/契约/性能/审查/安全）。
+质量门禁系统：6 种门禁检查（验收/命令/契约/性能/审查/安全）。统一 Gate 三态协议 + 注册表闭环 + 声明式生效集（G1）。
 
 ## 核心导出
-- `ReviewGate` — 代码审查门禁
-- `SecurityGate` — 安全检查门禁
-- `PerformanceGate` — 性能门禁
-- `ContractGate` — 契约(OpenAPI)门禁
-- `SpecAcceptanceGate` — Spec 验收门禁
-- `CommandGate` — 命令黑名单门禁
-- `types.ts` — GateResult / GateContext 等公共类型
-- 便捷工厂函数：createReviewGate / createSecurityGate / createPerformanceGate / createContractGate / createSpecAcceptanceGate
+- 统一协议：`Gate{id, order, evaluate(ctx)}` → `GateDecision{status: deny|abstain|ask, result: GateResult}`（`types.ts`；`decisionFromResult` 报告→决策映射，浅冻结）
+- 注册表：`gateRegistry`（`registry.ts`）——定义即注册 + 构建期双向闭环（定义无实现/实现无定义/重复 id → 加载期抛错）；`getGate`（未注册抛错）/`listRegisteredGates`/`registeredGateCount`
+- 定义表：`GATE_DEFINITIONS`（`definitions.ts`）——id/description/默认 order/CLI 元数据；bin/harness.js 注册表驱动生成 6 门禁命令（纯数据模块，禁 import 实现，保 --help 懒加载；CLI 实现引用为 module+export，per-command 懒加载，H5）
+- 执行器：`runGates`（`runner.ts`）——按 order 升序；deny 单调（下游 abstain 不得改回 allow）+ ask 枚举预留 fail-closed = deny；决策浅冻结
+- 生效集：`getEffectiveGates(projectRoot)`（`effective-gates.ts`）——对齐 getEffectiveConstraints 裁剪模式：config.yml `gates.order` 重排 + `gates.<id>.enabled:false` 移除；引用未注册 id 抛错
+- checker-as-guard 接线点：`createCheckerGate(check)`（`checker-gate.ts`）——ConstraintCheck → Gate（studio #129 随动）；false→deny，true/'skip'→abstain
+- 门禁类：`ReviewGate` / `SecurityGate` / `PerformanceGate` / `ContractGate` / `SpecAcceptanceGate` / `CommandGate`（各自执行细节私有，保留 `check()`/`scan()` 报告方法）
+- `types.ts` — GateResult（报告结构，保留）/ GateContext / GateDecision 等公共类型
+- 便捷工厂函数：createReviewGate / createSecurityGate / createPerformanceGate / createContractGate / createSpecAcceptanceGate / createCommandGate
 
 ## 依赖关系
-- 依赖 `src/core/` 类型(GateResult)
+- 依赖 `src/core/`（effective-gates 读 project-config-loader；checker-gate 适配 checkers 注册表类型）
 - 依赖 `src/types/` 公共类型
 
 ## 约定
-- 所有门禁实现 GateResult 接口
-- 新门禁必须配 CLI 命令 + 测试文件
-- 工厂函数在 index.ts 中统一导出
+- 新门禁必须：① 在 `definitions.ts` 补 GateDefinition（含 CLI 元数据）② 在 `registry.ts` IMPLEMENTATIONS 注册实现（缺一 → 加载期抛错）③ 实现统一 Gate 接口（evaluate 产三态决策，报告走 GateResult）④ 配 CLI 命令（命令实现文件 + CLI 元数据的 module+export 引用，bin 由定义表驱动生成，不再手写块）+ 测试文件
+- deny 单调是接口契约：决策浅冻结，下游不得改写上游决策
+- ask 枚举预留：暂无实现，runGates fail-closed 按 deny 计
 
 ## 注意事项
 - 门禁系统不包含业务逻辑，只提供检查能力
+- 统一的是决策协议（id/order/三态），执行细节（gh pr view/正则黑名单/OpenAPI diff/benchmark）私有——不要把执行细节塞进 Gate 接口
+- config.yml gates 段为新增面：引用未注册 id 直接抛错（无历史残留配置需兼容）
 - CommandGate 为命令黑名单检查(SEC-006)

package/src/gates/__tests__/checker-gate.test.ts

@@ -0,0 +1,45 @@
+/**
+ * checker-as-guard 接线点测试（G1 / studio #129 随动）
+ */
+
+import { createCheckerGate } from '../checker-gate';
+import { contextFlag, contextEvidenceFlag } from '../../core/constraints/checkers/types';
+
+describe('createCheckerGate', () => {
+  const ctx = { projectId: 'p', projectPath: '/tmp/project' };
+
+  it('checker 通过（true）→ abstain', async () => {
+    const gate = createCheckerGate(contextFlag('flag-pass', () => true), 7);
+    expect(gate.id).toBe('flag-pass');
+    expect(gate.order).toBe(7);
+
+    const decision = await gate.evaluate(ctx);
+    expect(decision.status).toBe('abstain');
+    expect(decision.result.gate).toBe('flag-pass');
+    expect(decision.result.passed).toBe(true);
+    expect(decision.result.message).toContain('通过');
+  });
+
+  it('checker 违规（false）→ deny', async () => {
+    const gate = createCheckerGate(contextFlag('flag-fail', () => false));
+    const decision = await gate.evaluate(ctx);
+    expect(decision.status).toBe('deny');
+    expect(decision.result.passed).toBe(false);
+    expect(decision.result.message).toContain('判定违规');
+  });
+
+  it('证据未接线（skip）→ abstain（不阻断）', async () => {
+    const gate = createCheckerGate(
+      contextEvidenceFlag('flag-skip', () => undefined)
+    );
+    const decision = await gate.evaluate(ctx);
+    expect(decision.status).toBe('abstain');
+    expect(decision.result.message).toContain('跳过');
+  });
+
+  it('决策浅冻结（单调语义契约）', async () => {
+    const gate = createCheckerGate(contextFlag('flag-freeze', () => true));
+    const decision = await gate.evaluate(ctx);
+    expect(Object.isFrozen(decision)).toBe(true);
+  });
+});