@dommaker/harness 1.7.0 → 1.8.0

package/src/context/knowledge-injector.ts

@@ -5,7 +5,7 @@
  * 支持按阶段预算、类型过滤、去重
  */
 
-import { KnowledgeQuery } from '../knowledge/query';
+import { KnowledgeQuery, EXTERNAL_SOURCE_MARKER } from '../knowledge/query';
 import { TokenEstimator } from './token-budget';
 import type { KnowledgeEntry, KnowledgeSubsystem } from '../knowledge/types';
 import type { ContextSource } from './types';
@@ -81,7 +81,7 @@ export class KnowledgeInjector {
               id: `knowledge-summary-${entry.id}`,
               content: summary,
               priority: 3,
-              metadata: { entryId: entry.id, isSummary: true },
+              metadata: { entryId: entry.id, isSummary: true, origin: entry.origin },
             });
             tokensUsed += summaryTokens;
             entriesSummarized++;
@@ -101,7 +101,7 @@ export class KnowledgeInjector {
           id: `knowledge-${entry.id}`,
           content: formatted,
           priority: 3,
-          metadata: { entryId: entry.id, maturity: entry.maturity },
+          metadata: { entryId: entry.id, maturity: entry.maturity, origin: entry.origin },
         });
         tokensUsed += entryTokens;
         entriesIncluded++;
@@ -116,7 +116,7 @@ export class KnowledgeInjector {
             id: `knowledge-summary-${entry.id}`,
             content: summary,
             priority: 3,
-            metadata: { entryId: entry.id, isSummary: true },
+            metadata: { entryId: entry.id, isSummary: true, origin: entry.origin },
           });
           tokensUsed += summaryTokens;
           entriesSummarized++;
@@ -134,11 +134,17 @@ export class KnowledgeInjector {
   }
 
   /**
-   * 将知识条目格式化为上下文内容
+   * 将知识条目格式化为上下文内容。
+   * 外部来源条目带 EXTERNAL_SOURCE_MARKER 前缀（harness#161：
+   * 三层防御第二层 retrieval marking 的正本接线，标记唯一来源是 knowledge/query）。
    */
   formatEntry(entry: KnowledgeEntry): string {
     const parts: string[] = [];
 
+    if (entry.origin === 'external') {
+      parts.push(EXTERNAL_SOURCE_MARKER);
+    }
+
     parts.push(`## [${entry.type.toUpperCase()}] ${entry.title}`);
     parts.push(`ID: ${entry.id} | 成熟度: ${entry.maturity} | 层级: ${entry.layer}`);
 
@@ -153,10 +159,11 @@ export class KnowledgeInjector {
   }
 
   /**
-   * 将知识条目格式化为摘要（一行）
+   * 将知识条目格式化为摘要（一行）；外部来源条目同样带来源标记前缀
    */
   formatEntrySummary(entry: KnowledgeEntry): string {
-    return `[${entry.id}] ${entry.title} (${entry.maturity}) — ${entry.content.slice(0, 100)}${entry.content.length > 100 ? '...' : ''}`;
+    const prefix = entry.origin === 'external' ? `${EXTERNAL_SOURCE_MARKER} ` : '';
+    return `${prefix}[${entry.id}] ${entry.title} (${entry.maturity}) — ${entry.content.slice(0, 100)}${entry.content.length > 100 ? '...' : ''}`;
   }
 
   /**

package/src/core/CONTEXT.md

@@ -4,20 +4,23 @@
 约束引擎核心：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，异常文案是其证据唯一外溢面）；检查引擎双出口——`checkConstraints`（block：首个铁律违规即抛，throw 契约不动）与 `collectConstraints`（collect：共享检查体、不抛、全量收集，report 的不抛出口，架构评审候选1）
+- `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；其 trigger 归一与匹配谓词单点在 `constraints/triggers.ts`——harness#105 定语义，harness#137 自 `utils/exec.ts` 归位，约束域谓词不住 utils 层)/漂移校验(injection-drift：纯检测只读，路由消费 injection-writer；期望段可吃调用方传入的本 run 生效集，缺省自取)/使用统计(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；一次 check run 内该判定只算一次并由 `RunEnv.capabilities()` 供给两 checker，ADR-0023 决策 4——增量那一维由 capability_sync 用导出的唯一覆盖规则 `isCoveredByEntries` 自算，代码实况清单的唯一取法是 `collectPopulationFiles`)；CheckEnv 生产侧唯一构造点 `buildCheckEnv(context, providers|'none', runEnv?)`（checkers/types.ts：CheckEnv `extends RunEnv`，runEnv 注入即与 context-builder 共用同一份上行数据读取、不传则自造一枚；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）
+- `constraints/context-reconcile.ts` — CONTEXT.md「核心导出」节与目录导出面的**幽灵/未登记**判定唯一实现（harness#142 / ADR-0025，与 `capabilities-reconcile` 同一套覆盖/幽灵语义，不另造第二套对照逻辑）：`reconcileContext({ contextMdContent, exportSurface, barrelExports? })` → `{ declaredSymbols, ghosts, unlistedBarrelExports, hasCoreExportsSection }`；配套两个口径正本也是纯函数——`parseDeclaredExportSymbols`（只认 bullet 行首反引号标识符，`/` 连接视为多声明，形参与 `（type）`注解剥掉，非标识符的模块名 bullet 整条跳过）与 `parseExportStatements`（声明形 / `export { a, b as c }` / 逐项与块级 `type` / `export default` / `export *` 的待解析 spec）。零 fs IO：文件遍历与 `export *` 目标解析在调用方（`cli/commands/sync-docs/context-syncer.ts` 的 `collectContextExportSurface`）；覆盖方向只判 barrel 的**值**符号（类型面豁免），mtime 判定就此降级为本地提示。本层 checker 暂无消费方
 - `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）；PassesGate 公开面 = `check()` + `runTests()` 两个真实消费点，`setPasses`/`getTestResult`/`checkTestFileChanges` 三方法与死数据 `PROTECTED_TEST_PATTERNS`、私有 `testResults` 缓存已随 ADR-0022（双仓零消费者）删除，历史 AC-007「保留 setPasses 向后兼容」同案推翻；`runTest` 的 `_task` 形参与其类型 `DynamicTask` 是同批漏收的第三处死面（二次复审 B1）——setPasses 删除后只剩这个从不读取的私有形参在供养它，而包根 `DynamicTask` 取自 `./types/passes-gate`，故它是**公开的**死类型；随 A1/A2 同判据删除，`runTest` 签名收为 `(workDir, command?)`，类型面钉子同 `PassesGateResult` 手法（`src/__tests__/public-exports.test.ts`）；包内模块，不进 `src/index.ts` 导出面
+- `constraints/context-builder.ts` — 只装配不取证：`buildConstraintContext(options.evidence?, options.runEnv?)` 与 `detectTrigger(…, options.runEnv?)` 经 GitEvidence 取 git 事实（不传 = 自建真 adapter），本模块无 child_process import；上行数据（源码根、trace 记录）经 `RunEnv` 取（ADR-0023），其余证据标志（ROOT_CAUSE/reuse/需求文档标记）仍为本地探测；`detectFailingTest`/`detectVerificationEvidence` 是模块私有的布尔投影（除本模块外零消费者，收私依 ADR-0022 同判据）
+- `constraints/run-env.ts` — 一次 check 的运行级观察面（ADR-0023）：`createRunEnv(projectPath)` 返回 `RunEnv{projectPath, traceTail(limit), sourceRoots(), rawConfig(), customConstraints(fileName), capabilities(populationFiles)}`，懒建 + run 内 memo，同一份文件一次运行至多读一次。与 git-evidence 同一形状：一次 run 一份、沿调用链显式传递（CLI check 入口 → 生效集 / buildConstraintContext / checkConstraints / 漂移检测），不做模块级全局。为何是两个类型而不是一个：`CheckEnv` 含 `context`，而 `context` 正是本对象读文件算出来的产物——同一对象不能既是构造者的输入又是其产物；故这里只放「不需要 context 就能造」的那半，`CheckEnv` 以 `extends RunEnv` 从它派生（`buildCheckEnv(context, evidence, runEnv?)` 第三参注入，不传 = 自造一枚一次性观察面）。配置两口的口径：`rawConfig()` 缺失 → undefined、空文件 → `{}`、YAML 解析失败**照抛**（兜与否属消费方判定）；`customConstraints(file)` 取 `custom_constraints` 段、缺失 → `{}`，「哪个文件名算数」仍由 ProjectConfigLoader 决定，读面不掺判定。`capabilities(population)` 一次读文档 + 一次 `reconcileCapabilities`（带存在性 oracle；不收 git 增量，`verdict.uncoveredChanges` 在此恒空），**memo 只记第一次传入的清单**——两消费方一律经 `collectPopulationFiles` 取数以由构造保证同形；源根 memo 与它共用。`traceTail(limit)` 底层是 `jsonl.readJsonlWindow`（一次分块读尾部行文本、按不同 limit 反复截窗），**先截行文本再 parse** 才与「各读一遍」逐字同口径（坏行占槽位不占 records 名额）；请求超出窗口上限直接抛，不静默少给。`RunTarget = RunEnv | 项目根路径` 与 `resolveRunEnv()` 是这套入参形状的归一点：传路径 = 一次性读取语义（每次调用读当下内容）
+- `effective-constraints.ts` — `getEffectiveConstraints(target, {preset?})`：全仓唯一生效集来源（内置 → preset → config.yml 禁用（内置与 custom 同效）→ custom 追加（禁用/已退役的不追加）→ scenes 过滤）；`constraintsFromMerged(merged)`：从已算好的合并配置取清单（推导单点，`getEffectiveConstraints` 也走它）；`getMergedConstraintsConfig(target, {preset?})`：同链路的完整 MergedConstraintsConfig 形状（含 disabled/custom/unknownIds），内置工单 23 优先级规则（**只有显式传 preset 才覆盖 config.yml**，CLI 不给缺省值，ADR-0023 步骤 4.5），check 命令经此入口并把算好的一份清单转交漂移检测 → 一次运行只算一遍；三个入口的 `target` = `RunTarget`（传 RunEnv 即与 checker、漂移检测共用同一份配置读取，ADR-0023 决策 2）；`lintEffectiveConfig` 配置诊断
+- `effective-set.ts` — `filterEnabledEntries(knownIds, entries)`：config 条目筛选器唯一实现，语义单一——未知 id 静默忽略并收集进 `unknownIds` 供诊断（历史配置可能残留已移除条目的禁用键，故不抛错）。唯一生产调用方是约束侧 `mergeConstraints`；曾按语义分 `'collect'`/`'throw'` 两模式，throw 侧唯一调用方 `getEffectiveGates` 随 ADR-0002「后续变更」收缩后，该模式按 ADR-0022 判据删除（harness#141）
+- `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 向后兼容」同案推翻；`runTest` 的 `_task` 形参与其类型 `DynamicTask` 是同批漏收的第三处死面（二次复审 B1）——setPasses 删除后只剩这个从不读取的私有形参在供养它，而包根 `DynamicTask` 取自 `./types/passes-gate`，故它是**公开的**死类型；随 A1/A2 同判据删除，`runTest` 签名收为 `(workDir, command?)`，类型面钉子同 `PassesGateResult` 手法（`src/__tests__/public-exports.test.ts`）；包内模块，不进 `src/index.ts` 导出面；`check-handlers/` 各族处理器统一签名 `(check, context)`，context 即既有注入车辆（`customHandlers` 同形）——`http_*` 族的重试退避等待经 `CheckpointContext.sleep` 注入（工单 #136），缺省 = 真定时器且退避公式与重试次数逐字不变，测试据此断言尝试次数与退避序列而不必真等；新增等待类副作用按同形收进 context，不再内联进处理器
 - `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/扫描类工具流调用方
+- `project-config-loader` — 项目配置解读 + 约束合并（mergeConstraints 内含 preset 裁剪：presets/ 纯数据 + 未知名回落 standard，禁用到未知 id 经 effective-set 共享筛选器收集（未知 id 不抛错、进 `unknownIds` 供诊断））；**退役判定单点 `isConstraintRetired(customDef, disabled)`**（harness#137）= 「禁用 或 custom 条目带 `retired` 元数据」（studio#82 D6 两个落点合成一条规则），`mergeConstraints` 的 custom 追加跳过与 `cli/commands/constraints-retire` 的 already_retired 共用它——后者此前是这条规则的手写复印；`disabled` 由调用方给（merge 侧含 preset 裁剪，retire 侧只看 config.yml），`retired` 按 truthiness 判；同批删掉 `isConstraintEnabled()`/`getConstraintSource()` 两个平行复印（双仓零消费者，生效集判定唯一来源是 mergeConstraints → getEffectiveConstraints）；**本模块不碰文件系统**：config.yml 与自定义约束文件的读取在 `constraints/run-env.ts`（ADR-0023 决策 2 撤销了工单 16 的进程级 `rawConfigCache` + mtime 指纹，改为一次运行一份快照）；访问器族（`loadRawProjectConfig`/`getGovernanceConfig`/`resolveContextFiles`/`getCapabilitiesMode`）与 `ProjectConfigLoader` 构造器的入参形状 = `RunTarget`（传项目根路径 = 一次性读取，传 RunEnv = 与本 run 其余消费方共用同一份）；`getGovernanceConfig` 是全仓唯一允许手写钻取 `config.governance` 的点（工单 84），消费方一律经它或经 `resolveContextFiles`（三态：unconfigured / enabled-empty / enabled，dirs 元素类型在此收口）取数据，不得再自己 cast `Record<string, unknown>`；checker 对前两态一律 skip，自动探测回落只属于 init/扫描类工具流调用方
+- `index.ts` barrel 公开面（子路径 `@dommaker/harness/core`，ADR-0003 显式清单、禁 `export *`）——定义取数 `getAllConstraints()` / `getConstraint(id)` / `findConstraintsByTrigger(trigger)`（正本 `constraints/definitions.ts`）；判定出口 `checkConstraints()` / `checkConstraint()` / `checkBeforeExecution()` 与未接线默认实例 `constraintChecker`（= `ConstraintChecker.getInstance()`，不写 trace，正本 `constraints/checker.ts`）；治理注入段标记常量 `CONSTRAINTS_START_MARKER` / `CONSTRAINTS_END_MARKER` 与 `renderConstraintsSection(constraints, version)`（正本 `constraints/injection-renderer.ts`）、按 trigger 分组渲染 `renderConstraintsByTrigger()`（正本 `constraints/agent-prompt-renderer.ts`）；验证器 `CheckpointValidator` / `CSOValidator`（两者私有构造 + `static getInstance()` 单例出口）与 `PassesGate` + 工厂 `createPassesGate(config?)`（`Partial<PassesGateConfig>`，正本 `validators/`）
 
 ## 依赖关系
 - 被所有模块依赖（基础层，无上层依赖）
 - 依赖 `src/types/` 类型定义
 - 依赖 `src/utils/` 工具函数
-- 对 `cli/`、`gates/`、`monitoring/` **零值导入**（type-only 允许）：方向由 eslint.config.mjs 的 `@typescript-eslint/no-restricted-imports`（error 级）锁死，守卫测试见 `src/__tests__/layering.test.ts`（harness#88）
+- 对 `cli/`、`gates/`、`monitoring/` **零值导入**（type-only 允许）：方向由 eslint.config.mjs 的 `@typescript-eslint/no-restricted-imports`（error 级）锁死，守卫测试见 `src/__tests__/layering.test.ts`（harness#88；harness#137 起该守卫已参数化成「每个顶层单元声明允许的下行集合」，core 的这条边只是其中一个条目）
 
 ## 约定
 - 约束定义在 `constraints/definitions/{iron-laws,guidelines,prompts}.ts`，不在运行时代码中定义

package/src/core/__tests__/effective-set.test.ts

@@ -1,7 +1,7 @@
 /**
  * effective-set 共享筛选器测试
  *
- * 覆盖约束侧（collect）与门禁侧（throw）两种 onUnknownId 模式。
+ * 筛选语义单一（未知 id 静默忽略并收集进 unknownIds）；「新形状钉」一组钉住 throw 模式已删除。
  */
 
 import { filterEnabledEntries } from '../effective-set';
@@ -9,72 +9,48 @@ import { filterEnabledEntries } from '../effective-set';
 const KNOWN = new Set(['a', 'b', 'c']);
 
 describe('filterEnabledEntries', () => {
-  describe('onUnknownId: collect（约束侧）', () => {
-    it('已知 id 全部通过，enabled:false 收进 disabledIds', () => {
-      const result = filterEnabledEntries(
-        KNOWN,
-        { a: { enabled: false }, b: { enabled: true }, c: {} },
-        { onUnknownId: 'collect' }
-      );
-      expect(result.disabledIds).toEqual(['a']);
-      expect(result.unknownIds).toEqual([]);
+  it('已知 id 全部通过，enabled:false 收进 disabledIds', () => {
+    const result = filterEnabledEntries(KNOWN, {
+      a: { enabled: false },
+      b: { enabled: true },
+      c: {},
     });
+    expect(result.disabledIds).toEqual(['a']);
+    expect(result.unknownIds).toEqual([]);
+  });
 
-    it('未知 id 静默忽略并收集进 unknownIds', () => {
-      const result = filterEnabledEntries(
-        KNOWN,
-        { a: {}, ghost: { enabled: false } },
-        { onUnknownId: 'collect' }
-      );
-      expect(result.unknownIds).toEqual(['ghost']);
-      // 未知 id 带 enabled:false 同样计入 disabledIds（历史行为：delete 空桶为 no-op）
-      expect(result.disabledIds).toEqual(['ghost']);
-    });
+  it('未知 id 静默忽略并收集进 unknownIds', () => {
+    const result = filterEnabledEntries(KNOWN, { a: {}, ghost: { enabled: false } });
+    expect(result.unknownIds).toEqual(['ghost']);
+    // 未知 id 带 enabled:false 同样计入 disabledIds（历史行为：delete 空桶为 no-op）
+    expect(result.disabledIds).toEqual(['ghost']);
+  });
 
-    it('未知 id 无 enabled 标记时只收集不进 disabledIds', () => {
-      const result = filterEnabledEntries(
-        KNOWN,
-        { ghost: {} },
-        { onUnknownId: 'collect' }
-      );
-      expect(result.unknownIds).toEqual(['ghost']);
-      expect(result.disabledIds).toEqual([]);
-    });
+  it('未知 id 无 enabled 标记时只收集不进 disabledIds', () => {
+    const result = filterEnabledEntries(KNOWN, { ghost: {} });
+    expect(result.unknownIds).toEqual(['ghost']);
+    expect(result.disabledIds).toEqual([]);
+  });
 
-    it('空 entries → 空结果', () => {
-      const result = filterEnabledEntries(KNOWN, {}, { onUnknownId: 'collect' });
-      expect(result).toEqual({ disabledIds: [], unknownIds: [] });
-    });
+  it('空 entries → 空结果', () => {
+    const result = filterEnabledEntries(KNOWN, {});
+    expect(result).toEqual({ disabledIds: [], unknownIds: [] });
   });
+});
 
-  describe('onUnknownId: throw（门禁侧）', () => {
-    it('未知 id 抛错（默认消息）', () => {
-      expect(() =>
-        filterEnabledEntries(KNOWN, { nope: { enabled: false } }, { onUnknownId: 'throw' })
-      ).toThrow(/未注册的 id "nope"/);
-    });
+describe('新形状钉（throw 模式已按 ADR-0022 判据删除，harness#141）', () => {
+  it('形参只有 knownIds/entries 两个（运行期钉）', () => {
+    expect(filterEnabledEntries.length).toBe(2);
+  });
 
-    it('未知 id 抛错（unknownIdError 定制消息）', () => {
-      expect(() =>
-        filterEnabledEntries(
-          KNOWN,
-          { nope: {} },
-          {
-            onUnknownId: 'throw',
-            unknownIdError: id => `gates.${id} 引用了未注册的门禁。可用门禁: a, b, c。`,
-          }
-        )
-      ).toThrow(/gates\.nope 引用了未注册的门禁/);
-    });
+  it('选项参数不再是合法入参（编译期钉）', () => {
+    // @ts-expect-error onUnknownId/unknownIdError 随 throw 模式一并删除，调用面不接收第三参数
+    filterEnabledEntries(KNOWN, { nope: {} }, { onUnknownId: 'throw' });
+  });
 
-    it('已知 id 的 enabled:false 正常收集，不抛错', () => {
-      const result = filterEnabledEntries(
-        KNOWN,
-        { a: { enabled: false }, b: { enabled: true } },
-        { onUnknownId: 'throw' }
-      );
-      expect(result.disabledIds).toEqual(['a']);
-      expect(result.unknownIds).toEqual([]);
-    });
+  it('FilterEnabledEntriesOptions 不再是可导入类型（编译期钉）', () => {
+    // @ts-expect-error 选项类型随其唯一成员（onUnknownId）一并消失
+    const removed: import('../effective-set').FilterEnabledEntriesOptions | undefined = undefined;
+    expect(removed).toBeUndefined();
   });
 });

package/src/core/constraints/__tests__/context-reconcile.test.ts

@@ -0,0 +1,246 @@
+/**
+ * context-reconcile 纯判定测试（harness#142 / ADR-0025）
+ *
+ * interface 即测试面（对位 ADR-0009）：喂 CONTEXT.md 正文 + 目录导出面清单，
+ * 断言双向判定；零 fs fixture。夹具取仓内真实写法（hooks 的 `/` 连接多符号、
+ * release 的节首散文 + 带参反引号、knowledge 的模块名 bullet、monitoring 的行首单符号）。
+ */
+
+import {
+  reconcileContext,
+  parseExportStatements,
+  parseDeclaredExportSymbols,
+} from '../context-reconcile';
+
+const SECTION_HEAD = '## 核心导出\n';
+
+function contextDoc(sectionBody: string, tailSection = '## 约定\n- 随便写点别的\n'): string {
+  return `# 模块\n\n${SECTION_HEAD}${sectionBody}\n${tailSection}`;
+}
+
+describe('parseDeclaredExportSymbols — 「核心导出」节声明解析', () => {
+  it('行首反引号标识符是声明；节外（其它 ## 节 / 节首散文）不算', () => {
+    const doc = contextDoc(
+      [
+        '下列符号都由 `integrity.ts` 就地导出；散文段落里的 `NotADeclaration` 不参与。',
+        '- `getCriticalArtifacts` — 公开 API',
+        '- `EXTRA_CRITICAL_ARTIFACTS`——常量',
+      ].join('\n')
+    );
+    expect(parseDeclaredExportSymbols(doc)).toEqual(['getCriticalArtifacts', 'EXTRA_CRITICAL_ARTIFACTS']);
+  });
+
+  it('`/` 连接的行首多符号逐个取（hooks 写法），并跳过括号形参（release 写法）', () => {
+    const doc = contextDoc(
+      [
+        '- `bootstrapHarness` / `bootstrapHarnessSync` — 启动引导',
+        '- `deriveCriticalArtifacts(manifest)`（`integrity.ts`）——纯函数',
+        '- `getCriticalArtifacts(pkgRoot?)` / `verifyReleaseArtifacts(pkgRoot?)`——公开 API',
+      ].join('\n')
+    );
+    expect(parseDeclaredExportSymbols(doc)).toEqual([
+      'bootstrapHarness',
+      'bootstrapHarnessSync',
+      'deriveCriticalArtifacts',
+      'getCriticalArtifacts',
+      'verifyReleaseArtifacts',
+    ]);
+  });
+
+  it('类型注解与模块名 bullet：`HookConfig`（type）取符号，`types.ts`/`audit-scoring`/`constraints/` 整条跳过', () => {
+    const doc = contextDoc(
+      [
+        '- `HookConfig`（type）— per-hook 配置声明',
+        '- `type HarnessBootstrap` — 把关键字写进反引号里的另一种类型注解形',
+        '- `types.ts` — 类型定义文件',
+        '- `audit-scoring`（包内，不进导出面）— 打分纯模块',
+        '- `constraints/` — 子目录条目',
+      ].join('\n')
+    );
+    expect(parseDeclaredExportSymbols(doc)).toEqual(['HookConfig', 'HarnessBootstrap']);
+  });
+
+  it('bullet 行首不是反引号（gates 的「统一协议：`Gate{…}`」形）不取声明；bullet 中段反引号不取', () => {
+    const doc = contextDoc(
+      [
+        '- 统一协议：`Gate{id, order}` → `GateDecision{status}`（`types.ts`）',
+        '- `TraceCollector` — 读入口 `readReport(filter?)` 与 `read()` 兼容包装',
+      ].join('\n')
+    );
+    expect(parseDeclaredExportSymbols(doc)).toEqual(['TraceCollector']);
+  });
+
+  it('无「核心导出」节 → 空清单（散文式 CONTEXT.md 不参与内容判定）', () => {
+    expect(parseDeclaredExportSymbols('# 模块\n\n## 职责\n- `Whatever`\n')).toEqual([]);
+  });
+});
+
+describe('parseExportStatements — 源码导出面解析口径', () => {
+  it('声明形：function/async function/const/class/interface/type/enum 各取符号并分型', () => {
+    const src = [
+      'export function f() {}',
+      'export async function g() {}',
+      'export const A = 1;',
+      'export let B = 2;',
+      'export class C {}',
+      'export abstract class D {}',
+      'export interface I {}',
+      'export type T = string;',
+      'export enum E {}',
+      'const notExported = 0;',
+    ].join('\n');
+    const { symbols } = parseExportStatements(src);
+    const asMap = Object.fromEntries(symbols.map((entry) => [entry.name, entry.typeOnly]));
+    expect(asMap).toEqual({
+      f: false,
+      g: false,
+      A: false,
+      B: false,
+      C: false,
+      D: false,
+      I: true,
+      T: true,
+      E: false,
+    });
+    expect(symbols.map((s) => s.name)).not.toContain('notExported');
+  });
+
+  it('`export { a, b as c }` 取导出名（别名后名），块级与逐项 `type` 标记都判为类型', () => {
+    const src = [
+      "export { Alpha, Beta as Gamma } from './alpha';",
+      "export type { Delta } from './alpha';",
+      "export { Epsilon, type Zeta } from './epsilon';",
+    ].join('\n');
+    const { symbols } = parseExportStatements(src);
+    expect(symbols).toEqual([
+      { name: 'Alpha', localName: 'Alpha', typeOnly: false, from: './alpha' },
+      { name: 'Gamma', localName: 'Beta', typeOnly: false, from: './alpha' },
+      { name: 'Delta', localName: 'Delta', typeOnly: true, from: './alpha' },
+      { name: 'Epsilon', localName: 'Epsilon', typeOnly: false, from: './epsilon' },
+      { name: 'Zeta', localName: 'Zeta', typeOnly: true, from: './epsilon' },
+    ]);
+  });
+
+  it('列表里的空项与裸 `default` 说明符不成符号（尾逗号与整体默认导出不混为一谈）', () => {
+    const src = ["export { Alpha, , default } from './x';", "export { Beta as default } from './y';"].join('\n');
+    const { symbols } = parseExportStatements(src);
+    expect(symbols).toEqual([
+      { name: 'Alpha', localName: 'Alpha', typeOnly: false, from: './x' },
+      { name: 'default', localName: 'Beta', typeOnly: false, from: './y' },
+    ]);
+  });
+
+  it('`export *` 只报待解析的相对 spec；非相对 spec 由调用方跳过', () => {
+    const src = ["export * from './types';", "export * as ns from './other';", "export * from 'chalk';"].join('\n');
+    expect(parseExportStatements(src).starFrom).toEqual(['./types', './other', 'chalk']);
+  });
+
+  it('export default 记为 `default`；注释内的伪 export 不取', () => {
+    const src = ['export default 42;', '// export const commented = 1;', '/* export const blocked = 2; */'].join('\n');
+    const names = parseExportStatements(src).symbols.map((s) => s.name);
+    expect(names).toEqual(['default']);
+  });
+});
+
+describe('reconcileContext — 幽灵方向（文档→代码）', () => {
+  const doc = contextDoc(['- `TraceCollector` — 收集', '- `ContextTracker` — 快照'].join('\n'));
+
+  it('声明的符号在导出面中不存在 → 报幽灵并指名符号', () => {
+    const v = reconcileContext({
+      contextMdContent: doc,
+      exportSurface: ['TraceCollector'],
+    });
+    expect(v.declaredSymbols).toEqual(['TraceCollector', 'ContextTracker']);
+    expect(v.ghosts).toEqual(['ContextTracker']);
+  });
+
+  it('导出面含同名符号（含类型符号）→ 零幽灵', () => {
+    expect(
+      reconcileContext({
+        contextMdContent: doc,
+        exportSurface: ['TraceCollector', 'ContextTracker'],
+      }).ghosts
+    ).toEqual([]);
+  });
+
+  it('无「核心导出」节的文档不产幽灵，也不把 barrel 全量判成未登记', () => {
+    const v = reconcileContext({
+      contextMdContent: '# 模块\n\n只有散文\n',
+      exportSurface: [],
+      barrelExports: ['Anything'],
+    });
+    expect(v.hasCoreExportsSection).toBe(false);
+    expect(v.ghosts).toEqual([]);
+    expect(v.unlistedBarrelExports).toEqual([]);
+  });
+});
+
+describe('reconcileContext — 覆盖方向（代码→文档，barrel 值符号）', () => {
+  const doc = contextDoc(
+    [
+      '- `TraceCollector` — 执行追踪收集（`readReport(filter?)`）',
+      '- `TraceAnalyzer` — 统计分析，另有 `createAnalyzer` 工厂',
+    ].join('\n')
+  );
+
+  it('barrel 再导出的值符号未出现在「核心导出」节 → 未登记；inline 提及即算登记', () => {
+    const v = reconcileContext({
+      contextMdContent: doc,
+      exportSurface: ['TraceCollector', 'TraceAnalyzer', 'createAnalyzer', 'configureTraceCollector'],
+      barrelExports: ['TraceCollector', 'TraceAnalyzer', 'createAnalyzer', 'configureTraceCollector'],
+    });
+    expect(v.unlistedBarrelExports).toEqual(['configureTraceCollector']);
+  });
+
+  it('无 barrel 的目录（barrelExports 不传/空）跳过覆盖方向', () => {
+    const v = reconcileContext({
+      contextMdContent: contextDoc('- `COMMAND_DEFINITIONS` — 定义表'),
+      exportSurface: ['COMMAND_DEFINITIONS', 'syncDocs'],
+      barrelExports: [],
+    });
+    expect(v.unlistedBarrelExports).toEqual([]);
+  });
+
+  it('名称匹配按标识符边界：`Gate` 不因文档里有 `GateResult` 而算登记', () => {
+    const v = reconcileContext({
+      contextMdContent: contextDoc('- `GateResult` — 报告结构'),
+      exportSurface: ['GateResult', 'Gate'],
+      barrelExports: ['Gate', 'GateResult'],
+    });
+    expect(v.unlistedBarrelExports).toEqual(['Gate']);
+  });
+
+  it('节外正文（其它 ## 节）里的同名句子不救 barrel 未登记', () => {
+    const v = reconcileContext({
+      contextMdContent: contextDoc('- `TraceCollector` — 收集', '## 约定\n- `configureTraceCollector` 只在组合根用\n'),
+      exportSurface: ['TraceCollector', 'configureTraceCollector'],
+      barrelExports: ['TraceCollector', 'configureTraceCollector'],
+    });
+    expect(v.unlistedBarrelExports).toEqual(['configureTraceCollector']);
+  });
+});
+
+describe('reconcileContext — 两方向同输入对撞', () => {
+  it('改符号名（代码改名不回灌文档）同时撞出幽灵与未登记', () => {
+    const doc = contextDoc('- `TraceCollector` — 收集\n');
+    const v = reconcileContext({
+      contextMdContent: doc,
+      exportSurface: ['TraceSink', 'configureTraceCollector'],
+      barrelExports: ['TraceSink'],
+    });
+    expect(v.ghosts).toEqual(['TraceCollector']);
+    expect(v.unlistedBarrelExports).toEqual(['TraceSink']);
+  });
+
+  it('两侧一致 → 干净（判定不制造存量噪音）', () => {
+    const doc = contextDoc('- `TraceCollector` — 收集\n- `configureTraceCollector` — 单例装配\n');
+    const v = reconcileContext({
+      contextMdContent: doc,
+      exportSurface: ['TraceCollector', 'configureTraceCollector'],
+      barrelExports: ['TraceCollector', 'configureTraceCollector'],
+    });
+    expect(v.ghosts).toEqual([]);
+    expect(v.unlistedBarrelExports).toEqual([]);
+    expect(v.hasCoreExportsSection).toBe(true);
+  });
+});