@dommaker/harness 1.5.0 → 1.6.0

package/src/context/__tests__/token-budget.test.ts

@@ -2,7 +2,7 @@
  * TokenBudget 和 TokenEstimator 测试
  */
 
-import { TokenBudget, TokenEstimator, AdaptiveTokenBudget } from '../token-budget';
+import { TokenBudget, TokenEstimator } from '../token-budget';
 
 describe('TokenEstimator', () => {
   describe('estimateText()', () => {
@@ -256,83 +256,3 @@ describe('TokenBudget', () => {
     });
   });
 });
-
-describe('AdaptiveTokenBudget', () => {
-  describe('recordActualUsage()', () => {
-    it('should record usage history', () => {
-      const budget = new AdaptiveTokenBudget(1000);
-      budget.recordActualUsage(500);
-      budget.recordActualUsage(600);
-      expect(budget.getAverageUsage()).toBe(550);
-    });
-
-    it('should trim history when exceeding max size', () => {
-      const budget = new AdaptiveTokenBudget(1000);
-      for (let i = 0; i < 15; i++) {
-        budget.recordActualUsage(100 + i);
-      }
-      expect(budget.getAverageUsage()).toBeGreaterThan(0);
-    });
-  });
-
-  describe('getAverageUsage()', () => {
-    it('should return 0 when no history', () => {
-      const budget = new AdaptiveTokenBudget(1000);
-      expect(budget.getAverageUsage()).toBe(0);
-    });
-  });
-
-  describe('predictNeed()', () => {
-    it('should return total when no history', () => {
-      const budget = new AdaptiveTokenBudget(1000);
-      expect(budget.predictNeed()).toBe(1000);
-    });
-
-    it('should predict based on history', () => {
-      const budget = new AdaptiveTokenBudget(1000);
-      budget.recordActualUsage(400);
-      budget.recordActualUsage(500);
-      budget.recordActualUsage(600);
-      const predicted = budget.predictNeed(0.9);
-      expect(predicted).toBeGreaterThan(0);
-    });
-  });
-
-  describe('suggestBudgetAdjustment()', () => {
-    it('should suggest increase when ratio > 0.9', () => {
-      const budget = new AdaptiveTokenBudget(1000);
-      for (let i = 0; i < 5; i++) {
-        budget.recordActualUsage(950);
-      }
-      const suggestion = budget.suggestBudgetAdjustment();
-      expect(suggestion.action).toBe('increase');
-      expect(suggestion.suggestedBudget).toBeGreaterThan(1000);
-    });
-
-    it('should suggest decrease when ratio < 0.5 and history >= 5', () => {
-      const budget = new AdaptiveTokenBudget(1000);
-      for (let i = 0; i < 5; i++) {
-        budget.recordActualUsage(100);
-      }
-      const suggestion = budget.suggestBudgetAdjustment();
-      expect(suggestion.action).toBe('decrease');
-    });
-
-    it('should maintain when ratio is moderate', () => {
-      const budget = new AdaptiveTokenBudget(1000);
-      for (let i = 0; i < 5; i++) {
-        budget.recordActualUsage(600);
-      }
-      const suggestion = budget.suggestBudgetAdjustment();
-      expect(suggestion.action).toBe('maintain');
-    });
-
-    it('should maintain when history < 5 even if low usage', () => {
-      const budget = new AdaptiveTokenBudget(1000);
-      budget.recordActualUsage(100);
-      budget.recordActualUsage(100);
-      const suggestion = budget.suggestBudgetAdjustment();
-      expect(suggestion.action).toBe('maintain');
-    });
-  });
-});

package/src/context/index.ts

@@ -1,7 +1,7 @@
 /**
  * 上下文管理模块（ADR-0003：显式清单，禁 export *）
  *
- * Token 预算 + 会话压缩 + 知识注入
+ * Token 预算 + 会话管理 + 知识注入
  */
 
 // 类型
@@ -17,14 +17,9 @@ export type {
   SessionHandle,
   SessionMessage,
 } from './types';
-export { DEFAULT_COMPACTION_CONFIG } from './types';
 
 // Token 预算
-export { AdaptiveTokenBudget, TokenBudget, TokenEstimator } from './token-budget';
-
-// 会话压缩
-export { SessionCompaction } from './compaction';
-export type { CompactionResult } from './compaction';
+export { TokenBudget, TokenEstimator } from './token-budget';
 
 // 会话管理
 export { SessionManager } from './session-manager';

package/src/context/token-budget.ts

@@ -220,76 +220,3 @@ export class TokenBudget {
     };
   }
 }
-
-/**
- * 自适应预算管理器
- * 
- * 根据历史使用情况动态调整预算
- */
-export class AdaptiveTokenBudget extends TokenBudget {
-  private history: number[] = [];
-  private maxHistorySize: number = 10;
-
-  /**
-   * 记录实际使用情况
-   */
-  recordActualUsage(actualTokens: number): void {
-    this.history.push(actualTokens);
-    if (this.history.length > this.maxHistorySize) {
-      this.history.shift();
-    }
-  }
-
-  /**
-   * 获取平均使用量
-   */
-  getAverageUsage(): number {
-    if (this.history.length === 0) return 0;
-    return this.history.reduce((a, b) => a + b, 0) / this.history.length;
-  }
-
-  /**
-   * 预测未来需求
-   */
-  predictNeed(confidence: number = 0.9): number {
-    if (this.history.length === 0) return this.total;
-    
-    const avg = this.getAverageUsage();
-    const max = Math.max(...this.history);
-    
-    // 简单预测：平均值 + 一定比例的最大值
-    return Math.ceil(avg + (max - avg) * confidence);
-  }
-
-  /**
-   * 建议预算调整
-   */
-  suggestBudgetAdjustment(): {
-    action: 'increase' | 'decrease' | 'maintain';
-    suggestedBudget: number;
-    reason: string;
-  } {
-    const avg = this.getAverageUsage();
-    const ratio = avg / this.total;
-
-    if (ratio > 0.9) {
-      return {
-        action: 'increase',
-        suggestedBudget: Math.ceil(avg * 1.2),
-        reason: '平均使用量接近预算上限，建议增加 20%'
-      };
-    } else if (ratio < 0.5 && this.history.length >= 5) {
-      return {
-        action: 'decrease',
-        suggestedBudget: Math.ceil(avg * 1.2),
-        reason: '平均使用量远低于预算，可减少预算'
-      };
-    }
-
-    return {
-      action: 'maintain',
-      suggestedBudget: this.total,
-      reason: '预算使用合理'
-    };
-  }
-}

package/src/context/types.ts

@@ -19,15 +19,6 @@ export interface CompactionConfig {
   fallbackStrategy: 'truncate-middle' | 'head-drop' | 'retry-with-clamp';
 }
 
-export const DEFAULT_COMPACTION_CONFIG: CompactionConfig = {
-  triggerRatio: 0.8,
-  level: 'eviction',
-  preserveToolCallPairs: true,
-  structuredSummary: true,
-  maxSummaryTokens: 2000,
-  fallbackStrategy: 'truncate-middle',
-};
-
 export interface SessionMessage {
   role: 'user' | 'assistant' | 'tool';
   content: string;

package/src/core/CONTEXT.md

@@ -1,16 +1,15 @@
 # core/
 
 ## 职责
-约束引擎核心：check/prompt 二元约束系统（ADR-0001）、生效集合并（effective-constraints）、检查点验证器(CSO/passes-gate)、会话管理、Spec 验证器、项目配置加载。
+约束引擎核心：check/prompt 二元约束系统（ADR-0001）、生效集合并（effective-constraints）、检查点验证器(CSO/passes-gate)、Spec 验证器、项目配置加载。
 
 ## 核心导出
-- `constraints/` — 约束定义(IRON_LAWS/GUIDELINES/PROMPTS) + 检查引擎(ConstraintChecker，拦截统一由 checkBeforeExecution 承担，ADR-0004) + 缓存(CheckCache：TTL 缓存 + 计数采样，H6/G5 起公开导出) + 注入渲染(injection-renderer) + 落点写入器(injection-writer：「声明→对照→幂等替换」中 marker-range 替换的唯一 writer——replaceStandaloneRange/replaceEnclosedRange/cutMarkerBlock + 半标记守护；落点路由读写两侧同住此模块 resolveInjectionTarget(CLAUDE.md 有标记段优先、否则 AGENTS.md PRESERVE:governance，studio #307)/resolveGovernanceLanding(init 写侧，含旧版无标记 Governance Rules 块豁免)，ADR-0011) + Agent prompt 渲染(agent-prompt-renderer：trigger 参数化分组渲染，role 路由留 studio，H6/G6)/漂移校验(injection-drift：纯检测只读，路由消费 injection-writer)/使用统计(usage-report：constraints report·retire 的只读数据层，读 trace 两个入口——`readProjectTracesReport()` 带 `skippedLines`、`readProjectTraces()` 兼容包装丢计数；报告模型 `ConstraintsUsageReport` 的降级位 = `traceFileExists` + `skippedLines`，harness#100)/清单对照(capabilities-reconcile：CAPABILITIES.md 与代码实况的覆盖/幽灵判定唯一实现，capability_sync·docs_freshness·sync-docs 共消费，ADR-0009)；CheckEnv 生产侧唯一构造点 `buildCheckEnv(context, providers|'none')`（checkers/types.ts：providers = 证据接线，git 两项绑 GitEvidence 实例，'none' = 显式不接 → evidence flag checker 按契约 skip）；判定接缝 `CheckOutcome = boolean | 'skip' | CheckDetail{pass, evidence}`（harness#119/ADR-0016）——编排层与 `gates/checker-gate` 一律经唯一归一点 `normalizeCheckOutcome()` 取三态 + 证据，不各自 `=== false`（对新形状会误判）；证据行由 checker 自行措辞（自描述、不带缩进），组装与截断策略单点在 `formatEvidence()`/`MAX_EVIDENCE_ITEMS`（同住 checkers/types.ts）；证据四出口 = `ConstraintResult.evidence` → CLI 结论块/提示块、`ExecutionTrace.evidence`、铁律 `ConstraintViolationError.message`（铁律违规直接 throw，异常文案是其证据唯一外溢面）
-- `git-evidence.ts` — 全仓唯一 git 取证点（#87）：`createGitEvidence(projectPath, run?)` 返回 `GitEvidence{stagedDiff, changedFileNames(staged), headDirs}`，seam 上两个真 adapter（缺省 `realGitCommandRunner` 走真 git / 注入 runner 供计数与替身）。命令级 memo 落在此实例（含失败结果），实例生命周期 = 一次 check run，故 context-builder 与 ConstraintChecker 传同一实例即共用证据；判定语义与迁移前一致（diff 取证失败 → 空串，`git ls-tree` 失败 → null = 所有目录视为新）；`parseHeadDirs`/`splitFileNames` 是配套纯函数
+- `constraints/` — 约束定义(IRON_LAWS/GUIDELINES/PROMPTS) + 检查引擎(ConstraintChecker，拦截统一由 checkBeforeExecution 承担，ADR-0004) + 缓存(CheckCache：TTL 缓存 + 计数采样，H6/G5 起公开导出) + 注入渲染(injection-renderer) + 落点写入器(injection-writer：「声明→对照→幂等替换」中 marker-range 替换的唯一 writer——replaceStandaloneRange/replaceEnclosedRange/cutMarkerBlock + 半标记守护；落点路由读写两侧同住此模块 resolveInjectionTarget(CLAUDE.md 有标记段优先、否则 AGENTS.md PRESERVE:governance，studio #307)/resolveGovernanceLanding(init 写侧，含旧版无标记 Governance Rules 块豁免)，ADR-0011) + Agent prompt 渲染(agent-prompt-renderer：trigger 参数化分组渲染，role 路由留 studio，H6/G6)/漂移校验(injection-drift：纯检测只读，路由消费 injection-writer)/使用统计(usage-report：constraints report·retire 的只读数据层，读 trace 两个入口——`readProjectTracesReport()` 带 `skippedLines`、`readProjectTraces()` 兼容包装丢计数；报告模型 `ConstraintsUsageReport` 的降级位 = `traceFileExists` + `skippedLines`，harness#100)/清单对照(capabilities-reconcile：CAPABILITIES.md 与代码实况的覆盖/幽灵判定唯一实现，capability_sync·docs_freshness·sync-docs 共消费，ADR-0009)；CheckEnv 生产侧唯一构造点 `buildCheckEnv(context, providers|'none')`（checkers/types.ts：providers = 证据接线，git 两项绑 GitEvidence 实例，'none' = 显式不接 → evidence flag checker 按契约 skip）；判定接缝 `CheckOutcome = boolean | 'skip' | CheckDetail{pass, evidence}`（harness#119/ADR-0016）——编排层与 `gates/checker-gate` 一律经唯一归一点 `normalizeCheckOutcome()` 取三态 + 证据，不各自 `=== false`（对新形状会误判）；证据行由 checker 自行措辞（自描述、不带缩进），组装与截断策略单点在 `formatEvidence()`/`MAX_EVIDENCE_ITEMS`（同住 checkers/types.ts）；证据四出口 = `ConstraintResult.evidence` → CLI 结论块/提示块、`ExecutionTrace.evidence`、铁律 `ConstraintViolationError.message`（铁律违规直接 throw，异常文案是其证据唯一外溢面）；检查引擎双出口——`checkConstraints`（block：首个铁律违规即抛，throw 契约不动）与 `collectConstraints`（collect：共享检查体、不抛、全量收集，report 的不抛出口，架构评审候选1）
+- `git-evidence.ts` — check 链路的 git 取证唯一接缝（#87，范围按 ADR-0021 收窄；`spec/validator` 的 staged 列表同型复用）：`createGitEvidence(projectPath, run?)` 返回 `GitEvidence{stagedDiff, changedFileNames(staged), headDirs}`，seam 上两个真 adapter（缺省 `realGitCommandRunner` 走真 git / 注入 runner 供计数与替身）。命令级 memo 落在此实例（含失败结果），实例生命周期 = 一次 check run，故 context-builder 与 ConstraintChecker 传同一实例即共用证据；判定语义与迁移前一致（diff 取证失败 → 空串，`git ls-tree` 失败 → null = 所有目录视为新）；`parseHeadDirs`/`splitFileNames` 是配套纯函数
 - `constraints/context-builder.ts` — 只装配不取证：`buildConstraintContext(options.evidence?)` 与 `detectTrigger(options.evidence?)` 经 GitEvidence 取 git 事实（不传 = 自建真 adapter），本模块无 child_process import；其余证据标志（traces/文档标记）仍为本地探测
 - `effective-constraints.ts` — `getEffectiveConstraints(projectRoot, {preset?})`：全仓唯一生效集来源（内置 → preset → config.yml 禁用（内置与 custom 同效）→ custom 追加（禁用/已退役的不追加）→ scenes 过滤）；`getMergedConstraintsConfig(projectRoot, {preset?})`：同链路的完整 MergedConstraintsConfig 形状（含 disabled/custom/unknownIds），内置工单 23 优先级规则（--preset 仅在无项目自定义配置时生效），check 命令经此入口；`lintEffectiveConfig` 配置诊断
 - `effective-set.ts` — `filterEnabledEntries(knownIds, entries, {onUnknownId})`：约束侧（collect）与门禁侧（throw）共用的 config 条目筛选器
-- `validators/` — checkpoints、passes-gate、CSO 验证器；`test-output.ts` —「测试产物解读」唯一实现：`extractFailures` 提取函数 + `judgeTestRun` 判定入口（退出码为主 + 行首锚定的文本失败信号交叉否决；文本救不回非零退出，`allowPartialPass` 只作用于文本否决那一维），passes-gate 与 `gates/acceptance` 的结论一律从它取、各自体内不写判定 `if`（解析收口 ADR-0012，判定依据 ADR-0014）；**不读覆盖率**——harness 核心判定对覆盖率不取数不执法，判覆盖率的两处（CLI `passes-gate --coverage`、`gates/performance`）各自读 json-summary，`extractCoverage` 与 `TaskTestResult.coverage` 已随 ADR-0015 删除；`PassesGate.runTests(workDir)` 的执行与证据落盘根是**必传形参**，本层不再取 cwd（harness#95，约定正本见 `src/cli/commands/CONTEXT.md`）；`detectTestCommand` 是测试命令探测唯一正本（模块级导出：test:ci → test 排 echo 占位 → test:e2e → test:coverage → Python 标记 pyproject.toml/pytest.ini → go.mod，探不到返回 undefined，兜底归调用方——CLI 映射 skip、PassesGate 内部 fail-closed，不再兜底 'npm test'；CLI 本地版已删，架构评审 A2）；PassesGate 扩展注册表（registerExtension/unregisterExtension/getExtensionNames/runAllTests/checkAllPasses + PassesGateExtension/ExtensionTestResult 两类型与包根导出）已整段删除——零 adapter 假想 seam 且扩展结果本就不参与 allowed 判定，需要扩展测试类型时按 ADR-0014 判例在 `judgeTestRun` 层加，不恢复旧 seam（harness#104，架构评审 B1）；包内模块，不进 `src/index.ts` 导出面
-- `session/` — 会话管理
+- `validators/` — checkpoints、passes-gate、CSO 验证器；`test-output.ts` —「测试产物解读」唯一实现：`extractFailures` 提取函数 + `judgeTestRun` 判定入口（退出码为主 + 行首锚定的文本失败信号交叉否决；文本救不回非零退出，`allowPartialPass` 只作用于文本否决那一维），passes-gate 与 `gates/acceptance` 的结论一律从它取、各自体内不写判定 `if`（解析收口 ADR-0012，判定依据 ADR-0014）；**不读覆盖率**——harness 核心判定对覆盖率不取数不执法，判覆盖率的两处（CLI `passes-gate --coverage`、`gates/performance`）各自读 json-summary，`extractCoverage` 与 `TaskTestResult.coverage` 已随 ADR-0015 删除；`PassesGate.runTests(workDir)` 的执行与证据落盘根是**必传形参**，本层不再取 cwd（harness#95，约定正本见 `src/cli/commands/CONTEXT.md`）；`detectTestCommand` 是测试命令探测唯一正本（模块级导出：test:ci → test 排 echo 占位 → test:e2e → test:coverage → Python 标记 pyproject.toml/pytest.ini → go.mod，探不到返回 undefined，兜底归调用方——CLI 映射 skip、PassesGate 内部 fail-closed，不再兜底 'npm test'；CLI 本地版已删，架构评审 A2）；PassesGate 扩展注册表（registerExtension/unregisterExtension/getExtensionNames/runAllTests/checkAllPasses + PassesGateExtension/ExtensionTestResult 两类型与包根导出）已整段删除——零 adapter 假想 seam 且扩展结果本就不参与 allowed 判定，需要扩展测试类型时按 ADR-0014 判例在 `judgeTestRun` 层加，不恢复旧 seam（harness#104，架构评审 B1）；PassesGate 公开面 = `check()` + `runTests()` 两个真实消费点，`setPasses`/`getTestResult`/`checkTestFileChanges` 三方法与死数据 `PROTECTED_TEST_PATTERNS`、私有 `testResults` 缓存已随 ADR-0022（双仓零消费者）删除，历史 AC-007「保留 setPasses 向后兼容」同案推翻；包内模块，不进 `src/index.ts` 导出面
 - `spec/validator` — SpecValidator
 - `project-config-loader` — 项目配置加载 + 约束合并（mergeConstraints 内含 preset 裁剪：presets/ 纯数据 + 未知名回落 standard，禁用到未知 id 经 effective-set 共享筛选器 collect 模式）；`getGovernanceConfig` 是全仓唯一允许手写钻取 `config.governance` 的点（工单 84），消费方一律经它或经 `resolveContextFiles`（三态：unconfigured / enabled-empty / enabled，dirs 元素类型在此收口）取数据，不得再自己 cast `Record<string, unknown>`；checker 对前两态一律 skip，自动探测回落只属于 init/扫描类工具流调用方
 
@@ -25,7 +24,7 @@
 - check 层必须带真实 checker（注册表闭环，引用未注册 checker 构建报错）
 - Iron Law 违规必须 throw ConstraintViolationError
 - 上行数据一律注入，不在 core 内 require 上层（harness#88）：trace 记录器经 `ConstraintChecker` 构造参数注入（缺省 no-op，`getInstance()`/`constraintChecker` 即未接线的默认实例，只评估不写 trace），真实收集器由组合根接线（CLI check/report、`bootstrapHarness`）；CAPABILITIES.md 能力清单计数经 `capabilities-parser` 的 `CapabilityDefinitionSource` 由 cli 侧注入定义表
-- git 事实只能经 `constraints/git-evidence.ts` 的 adapter 取（#87）：core/cli 内不得出现 `execSync('git …')`；一次 run 一份实例、沿调用链显式传递（CLI check → buildConstraintContext → checkConstraints），memo 既不做成模块级全局也不做成单例字段
+- git **取证**（读判定证据）在 check 链路内只能经 `constraints/git-evidence.ts` 的 adapter 取（#87，适用范围按 ADR-0021 收窄为「check 链路唯一」，不再声称全仓唯一）：`context-builder` / `checker` / `CheckEnv` / `validators` 这条判定链内不得出现 `execSync`/`execAsync`/`execFileAsync` 跑 git；`spec/validator` 的 staged 文件列表与 `changedFileNames(staged:true)` 同型，已收口（就地 `createGitEvidence(cwd)`，测试注入 runner）；一次 run 一份实例、沿调用链显式传递（CLI check → buildConstraintContext → checkConstraints），memo 既不做成模块级全局也不做成单例字段。**链外站点记名豁免**（语义异质：不要 memo、不要 once 语义、失败处理各异，硬并入会造出宽 interface）——`cli/commands/release.ts`（发布流程编排，非判定证据）、`gates/review.ts` 与 `cli/commands/review.ts`（PR 审查流，gh/日志语义）、`knowledge/import.ts`（导入启发式，失败记 ImportError 降级）。豁免清单外新增 git 站点先回答「在不在判定链内」；`validators/passes-gate.ts` 的 `git diff --name-only` 站点已随 ADR-0022 删 `checkTestFileChanges` 消失，判定链内当下无站外 git 调用点
 
 ## 注意事项
 - 零 Token 成本：所有分析纯文件操作，无 LLM 调用

package/src/core/constraints/__tests__/collect-constraints.test.ts

@@ -0,0 +1,66 @@
+/**
+ * collectConstraints — 收集模式（架构评审候选1）
+ *
+ * 与 checkConstraints 共享检查体，唯一差别是不 throw：
+ * 铁律违规不抛、全量收进 ironLaws、guidelines 照常、passed 如实。
+ * block 模式的 throw 契约由 checker-extra / iron-laws 既有用例钉住，这里只测 collect 侧。
+ */
+
+import { describe, it, expect } from '@jest/globals';
+import { ConstraintChecker } from '../checker';
+import type { ConstraintContext, ConstraintResult } from '../../../types/constraint';
+
+// 缺省 no-op trace 记录器：本套件不验 trace 面（trace 面由 trace-injection 套件钉住）
+const checker = new ConstraintChecker();
+
+/** 只违 no_completion_without_verification，其余铁律满足（flag 口径同 checker-extra） */
+const VIOLATING: ConstraintContext = {
+  operation: 'code_implementation',
+  hasTest: false,
+  hasVerificationEvidence: false,
+  hasRequirement: true,
+  hasSingleTask: true,
+  taskDescription: 'single focused change',
+};
+
+const CLEAN: ConstraintContext = {
+  operation: 'code_implementation',
+  hasTest: true,
+  hasVerificationEvidence: true,
+  hasRequirement: true,
+  hasSingleTask: true,
+  taskDescription: 'single focused change',
+};
+
+describe('collectConstraints（收集模式，不抛）', () => {
+  it('铁律违规不抛 —— resolves 而非 rejects', async () => {
+    await expect(checker.collectConstraints(VIOLATING)).resolves.toBeDefined();
+  });
+
+  it('违规铁律如实进 ironLaws：satisfied=false 且 passed=false', async () => {
+    const result = await checker.collectConstraints(VIOLATING);
+    const violated = result.ironLaws.find((r: ConstraintResult) => r.id === 'no_completion_without_verification');
+    expect(violated).toBeDefined();
+    expect(violated!.satisfied).toBe(false);
+    expect(result.passed).toBe(false);
+  });
+
+  it('首个违规不截断：触发域内后续铁律照常评估', async () => {
+    const result = await checker.collectConstraints(VIOLATING);
+    const ids = result.ironLaws.map((r: ConstraintResult) => r.id);
+    expect(ids).toContain('incremental_progress');
+    expect(ids).toContain('no_implementation_without_requirement');
+  });
+
+  it('guidelines 照常执行，warningCount 与不满意条目同口径', async () => {
+    const result = await checker.collectConstraints(VIOLATING);
+    expect(result.guidelines.length).toBeGreaterThan(0);
+    expect(result.warningCount).toBe(result.guidelines.filter((g: ConstraintResult) => !g.satisfied).length);
+  });
+
+  it('干净上下文对照：passed=true、ironLaws 全满意', async () => {
+    const result = await checker.collectConstraints(CLEAN);
+    expect(result.passed).toBe(true);
+    expect(result.ironLaws.every((r: ConstraintResult) => r.satisfied)).toBe(true);
+  });
+});

package/src/core/constraints/checker.ts

@@ -263,6 +263,35 @@ export class ConstraintChecker {
     context: ConstraintContext,
     customConfig?: MergedConstraintsConfig | null,
     evidence?: GitEvidence
+  ): Promise<ConstraintCheckResult> {
+    return this.runAllConstraints(context, customConfig, evidence, 'block');
+  }
+
+  /**
+   * 收集模式执行约束检查（harness report 的不抛出口，架构评审候选1）
+   *
+   * 与 checkConstraints 共享同一检查体，唯一差别是不 throw：
+   * 铁律违规照进 result.ironLaws、passed=false，后续铁律与 guidelines 照常执行，
+   * trace 逐条照记。报告类消费者拿全量视图；阻断语义只属于 checkConstraints
+   * （throw 契约是 #119 判定证据的外溢面，逐字不动）。
+   */
+  async collectConstraints(
+    context: ConstraintContext,
+    customConfig?: MergedConstraintsConfig | null,
+    evidence?: GitEvidence
+  ): Promise<ConstraintCheckResult> {
+    return this.runAllConstraints(context, customConfig, evidence, 'collect');
+  }
+
+  /**
+   * checkConstraints / collectConstraints 的共享检查体；
+   * mode='block' 首个铁律违规即抛，mode='collect' 全量跑完不抛
+   */
+  private async runAllConstraints(
+    context: ConstraintContext,
+    customConfig: MergedConstraintsConfig | null | undefined,
+    evidence: GitEvidence | undefined,
+    mode: 'block' | 'collect'
   ): Promise<ConstraintCheckResult> {
     // run 起始：重置 src 扫描缓存（S7）；git 证据 = 本 run 独占的 adapter 实例（工单 18 → #87）
     this.cache.invalidate();
@@ -279,7 +308,7 @@ export class ConstraintChecker {
     // context.operation 为主触发条件，extraTriggers 为次级推断（ADR-0001），任一命中即匹配
     const operations = [context.operation, ...(context.extraTriggers ?? [])];
 
-    // 1. Iron Laws: 必须全部通过
+    // 1. Iron Laws: block 模式首个违规即抛；collect 模式全量收集
     for (const constraint of Object.values(constraints.ironLaws)) {
       if (!matchesTrigger(constraint, operations)) continue;
 
@@ -289,7 +318,9 @@ export class ConstraintChecker {
 
       if (!checkResult.satisfied) {
         result.passed = false;
-        throw new ConstraintViolationError(checkResult);
+        if (mode === 'block') {
+          throw new ConstraintViolationError(checkResult);
+        }
       }
     }
 

package/src/core/constraints/git-evidence.ts

@@ -1,10 +1,13 @@
 /**
- * git 证据适配器（架构评审 #87）
+ * git 证据适配器（架构评审 #87，适用范围按 ADR-0021 收窄）
  *
- * 全仓唯一的 git 取证点：context-builder（触发推断）与 checker 层（CheckEnv 证据）
+ * check 链路的唯一 git 取证点：context-builder（触发推断）与 checker 层（CheckEnv 证据）
  * 共用同一实例 = 共用同一证据来源。此前两处各自抓真 git，一次 CLI check 里
  * `git diff --cached --name-only` 实跑两遍。
  *
+ * 链外站点（写操作 / 发布编排 / 审查流 / 降级容忍）不并入本 seam，记名豁免清单见
+ * `core/CONTEXT.md` 约定段；同型站点（spec/validator 的 staged 列表）经此取证据。
+ *
  * seam 上的两个真 adapter：
  * - 缺省 realGitCommandRunner：真 git 子进程
  * - 注入 runner：委托/计数/命令表（测试与定制场景）
@@ -77,7 +80,7 @@ export function parseHeadDirs(treeOutput: string): Set<string> {
 }
 
 /**
- * 构造 git 证据 adapter（生产侧唯一构造点）
+ * 构造 git 证据 adapter（GitEvidence 实例的唯一构造点：check 链路与 spec/validator 的 staged 取证都经此）
  *
  * @param projectPath 取证目录
  * @param run 命令执行器，缺省真 git；测试注入计数/替身执行器即可脱离子进程

package/src/core/index.ts

@@ -59,21 +59,10 @@ export type {
   CheckType,
   CheckConfig,
   PassesGateConfig,
-  PassesGateResult,
   TaskTestResult,
   DynamicTask,
 } from './validators';
 
-// 会话启动 / 净室状态
-export {
-  SessionStartup,
-  createSessionStartup,
-  DEFAULT_CODE_CHECKPOINTS,
-  MINIMAL_CHECKPOINTS,
-  CleanStateManager,
-  createCleanStateManager,
-} from './session';
-
 // Spec 验证器
 export { SpecValidator } from './spec/validator';
 export type {

package/src/core/spec/__tests__/validator.test.ts

@@ -3,6 +3,7 @@
  */
 
 import { SpecValidator, validateSpec, validateAllSpecs } from '../validator';
+import type { GitCommandRunner } from '../../constraints/git-evidence';
 import * as fs from 'fs/promises';
 
 // Mock fs
@@ -263,6 +264,29 @@ describe('SpecValidator', () => {
       expect(result).toBeDefined();
       expect(result.total).toBeGreaterThanOrEqual(0);
     });
+
+    it('staged 取证经 GitEvidence adapter（注入 runner，不落 child_process）', async () => {
+      const calls: Array<{ command: string; cwd: string }> = [];
+      const runner: GitCommandRunner = (command, cwd) => {
+        calls.push({ command, cwd });
+        return 'specs/test.yml\nARCHITECTURE.md\nsrc/utils/helper.ts';
+      };
+
+      const files: string[] = await (validator as any).getStagedFiles('/repo', runner);
+
+      expect(calls).toEqual([{ command: 'git diff --cached --name-only', cwd: '/repo' }]);
+      expect(files).toEqual(['/repo/specs/test.yml', '/repo/ARCHITECTURE.md']);
+    });
+
+    it('runner 抛错 → 空列表（取证失败降级语义与迁移前一致）', async () => {
+      const runner: GitCommandRunner = () => {
+        throw new Error('not a git repository');
+      };
+
+      const files: string[] = await (validator as any).getStagedFiles('/repo', runner);
+
+      expect(files).toEqual([]);
+    });
   });
 
   describe('validate with custom schema', () => {

package/src/core/spec/validator.ts

@@ -12,7 +12,7 @@
 import * as fs from 'fs/promises';
 import * as path from 'path';
 import * as glob from 'fast-glob';
-import { execAsync } from '../../utils/exec';
+import { createGitEvidence, splitFileNames, type GitCommandRunner } from '../constraints/git-evidence';
 import type {
   SpecValidatorConfig,
   SpecValidationResult,
@@ -243,7 +243,7 @@ export class SpecValidator {
     let files: string[];
 
     if (staged) {
-      files = await this.getStagedFiles();
+      files = await this.getStagedFiles(cwd);
     } else {
       files = await this.getSpecFiles(cwd);
     }
@@ -291,15 +291,14 @@ export class SpecValidator {
 
   /**
    * 获取暂存的 Spec 文件
+   *
+   * git 事实经 GitEvidence adapter（ADR-0021）；`run` 缺省真 git，测试注入替身。
    */
-  private async getStagedFiles(): Promise<string[]> {
-    try {
-      const { stdout } = await execAsync('git diff --cached --name-only');
-      const allFiles = stdout.trim().split('\n').filter(Boolean);
-      return allFiles.filter(f => this.isSpecFile(f));
-    } catch {
-      return [];
-    }
+  private async getStagedFiles(cwd: string, run?: GitCommandRunner): Promise<string[]> {
+    const evidence = createGitEvidence(cwd, run);
+    return splitFileNames(evidence.changedFileNames(true))
+      .filter(f => this.isSpecFile(f))
+      .map(f => path.resolve(cwd, f));
   }
 
   /**

package/src/core/validators/__tests__/passes-gate.test.ts

@@ -2,7 +2,7 @@
  * Tests for passes-gate.ts
  *
  * Priority: test pure logic methods (check)
- * Skip methods that do real file I/O / exec (setPasses, runTests, runTest, detectTestCommand, etc.)
+ * Skip methods that do real file I/O / exec (runTests, runTest, detectTestCommand, etc.)
  * 测试产物解析判定不在此面：见 test-output.test.ts（ADR-0012）
  */
 
@@ -16,7 +16,7 @@ describe('PassesGate', () => {
     });
 
     it('creates a PassesGate instance with custom config', () => {
-      const gate = createPassesGate({ enabled: false, maxRetries: 5 });
+      const gate = createPassesGate({ enabled: false, allowPartialPass: true });
       expect(gate).toBeInstanceOf(PassesGate);
     });
   });
@@ -67,11 +67,4 @@ describe('PassesGate', () => {
       expect(result.testResult).toEqual(testResult);
     });
   });
-
-  describe('getTestResult', () => {
-    it('returns undefined for unknown task', () => {
-      const gate = createPassesGate();
-      expect(gate.getTestResult('unknown')).toBeUndefined();
-    });
-  });
 });

package/src/core/validators/index.ts

@@ -19,7 +19,6 @@ export type {
 
 export type {
   PassesGateConfig,
-  PassesGateResult,
   TaskTestResult,
   DynamicTask,
 } from '../../types/passes-gate';