@dommaker/harness 1.7.0 → 1.8.0

package/src/hooks/__tests__/pipeline.test.ts

@@ -4,16 +4,26 @@
  * block/warn 行为是 studio safeCallHook 语义在管线侧的无损承载面：
  * - 'block'：hook 失败 → passed=false、blockedBy 记名、停止执行后续 hook
  * - 'warn'：hook 失败 → 记录警告、继续执行后续 hook、passed 不受影响
- * - 'ignore'/未声明：静默跳过（历史行为保留）
+ *
+ * #159 起 `enabled` / `errorStrategy` 的唯一声明点是 HookConfig：
+ * HookDefinition 不再携带这两个字段，有效值在注册环节由配置表填充。
  */
 
 import { HookPipeline } from '../pipeline';
 import { HookRegistry } from '../registry';
-import type { HookDefinition } from '../types';
+import type { HookConfig, HookDefinition } from '../types';
+
+function makeConfig(name: string, overrides: Partial<HookConfig> = {}): HookConfig {
+  return { name, enabled: true, errorStrategy: 'warn', ...overrides };
+}
 
-function makeRegistry(hooks: HookDefinition[]): { registry: HookRegistry; pipeline: HookPipeline } {
+function makeRegistry(
+  entries: Array<{ hook: HookDefinition; config?: Partial<HookConfig> }>
+): { registry: HookRegistry; pipeline: HookPipeline } {
   const registry = new HookRegistry();
-  registry.registerAll(hooks);
+  for (const { hook, config } of entries) {
+    registry.register(hook, makeConfig(hook.name, config));
+  }
   return { registry, pipeline: new HookPipeline(registry) };
 }
 
@@ -21,8 +31,8 @@ describe('HookPipeline errorStrategy 语义', () => {
   it('block：失败阻断管线（passed=false、blockedBy 记名、停止后续 hook）', async () => {
     const second = jest.fn().mockResolvedValue({ passed: true });
     const { pipeline } = makeRegistry([
-      { name: 'first', phase: 'before', errorStrategy: 'block', execute: async () => ({ passed: false, error: 'boom' }) },
-      { name: 'second', phase: 'before', execute: second },
+      { hook: { name: 'first', phase: 'before', execute: async () => ({ passed: false, error: 'boom' }) }, config: { errorStrategy: 'block' } },
+      { hook: { name: 'second', phase: 'before', execute: second } },
     ]);
 
     const result = await pipeline.run('before', {});
@@ -35,8 +45,8 @@ describe('HookPipeline errorStrategy 语义', () => {
   it('warn：失败记录警告并继续（passed 不受影响、后续 hook 照常执行）', async () => {
     const second = jest.fn().mockResolvedValue({ passed: true });
     const { pipeline } = makeRegistry([
-      { name: 'first', phase: 'before', errorStrategy: 'warn', execute: async () => ({ passed: false, error: 'soft' }) },
-      { name: 'second', phase: 'before', execute: second },
+      { hook: { name: 'first', phase: 'before', execute: async () => ({ passed: false, error: 'soft' }) }, config: { errorStrategy: 'warn' } },
+      { hook: { name: 'second', phase: 'before', execute: second } },
     ]);
 
     const result = await pipeline.run('before', {});
@@ -50,8 +60,8 @@ describe('HookPipeline errorStrategy 语义', () => {
   it('block 失败停在当前 phase，不改变其它 phase 的 hook', async () => {
     const afterHook = jest.fn().mockResolvedValue({ passed: true });
     const { pipeline } = makeRegistry([
-      { name: 'blocker', phase: 'before', errorStrategy: 'block', execute: async () => ({ passed: false }) },
-      { name: 'afterHook', phase: 'after', execute: afterHook },
+      { hook: { name: 'blocker', phase: 'before', execute: async () => ({ passed: false }) }, config: { errorStrategy: 'block' } },
+      { hook: { name: 'afterHook', phase: 'after', execute: afterHook } },
     ]);
 
     const before = await pipeline.run('before', {});
@@ -62,18 +72,19 @@ describe('HookPipeline errorStrategy 语义', () => {
     expect(afterHook).toHaveBeenCalled();
   });
 
-  it('未声明 errorStrategy：静默跳过（历史行为保留）', async () => {
-    const second = jest.fn().mockResolvedValue({ passed: true });
+  it('配置 enabled:false 的 hook 不进入管线执行（配置表是唯一声明点）', async () => {
+    const disabledHook = jest.fn().mockResolvedValue({ passed: true });
+    const enabledHook = jest.fn().mockResolvedValue({ passed: true });
     const { pipeline } = makeRegistry([
-      { name: 'first', phase: 'before', execute: async () => ({ passed: false }) },
-      { name: 'second', phase: 'before', execute: second },
+      { hook: { name: 'disabled', phase: 'before', execute: disabledHook }, config: { enabled: false } },
+      { hook: { name: 'enabled', phase: 'before', execute: enabledHook } },
     ]);
 
     const result = await pipeline.run('before', {});
 
     expect(result.passed).toBe(true);
-    expect(result.blockedBy).toEqual([]);
-    expect(result.warnings).toEqual([]);
-    expect(second).toHaveBeenCalled();
+    expect(disabledHook).not.toHaveBeenCalled();
+    expect(enabledHook).toHaveBeenCalled();
+    expect(result.records.map(r => r.hookName)).toEqual(['enabled']);
   });
 });

package/src/hooks/__tests__/registry.test.ts

@@ -2,6 +2,10 @@
  * Hook 注册表闭环双向校验测试（H5，复制 checker 闭环模式）
  *
  * 两个失败方向 + 重复声明/注册都必须抛错；闭环通过时不抛错。
+ *
+ * #159 起注册即配对：`register(hook, config)` 以 HookConfig 填充有效
+ * `enabled` / `errorStrategy`——配置表是这两个语义的唯一声明点，
+ * HookDefinition 类型上不再存在同名字段（矛盾在构造上不可能出现）。
  */
 
 import { assertHookRegistryClosed, HookRegistry } from '../registry';
@@ -15,8 +19,8 @@ function makeHook(name: string): HookDefinition {
   };
 }
 
-function makeConfig(name: string): HookConfig {
-  return { name, enabled: true, errorStrategy: 'block' };
+function makeConfig(name: string, overrides: Partial<HookConfig> = {}): HookConfig {
+  return { name, enabled: true, errorStrategy: 'block', ...overrides };
 }
 
 describe('assertHookRegistryClosed', () => {
@@ -60,8 +64,52 @@ describe('assertHookRegistryClosed', () => {
 
   it('与 HookRegistry.listAll 组合可用（consumer 注册点用法）', () => {
     const registry = new HookRegistry();
-    registry.registerAll([makeHook('beforeAgentExecute')]);
+    registry.registerAll([makeHook('beforeAgentExecute')], [makeConfig('beforeAgentExecute')]);
     expect(() => assertHookRegistryClosed([makeConfig('beforeAgentExecute')], registry.listAll()))
       .not.toThrow();
   });
 });
+
+describe('HookRegistry 注册即配对（#159 配置表唯一化）', () => {
+  it('register 以 HookConfig 填充有效 enabled / errorStrategy', () => {
+    const registry = new HookRegistry();
+    registry.register(makeHook('a'), makeConfig('a', { enabled: false, errorStrategy: 'block' }));
+
+    const effective = registry.get('a');
+    expect(effective?.enabled).toBe(false);
+    expect(effective?.errorStrategy).toBe('block');
+    // 配置 enabled:false → 不进 enabled 列表
+    expect(registry.getEnabled('before')).toEqual([]);
+  });
+
+  it('register 定义与配置名称不一致 → 抛错', () => {
+    const registry = new HookRegistry();
+    expect(() => registry.register(makeHook('a'), makeConfig('b'))).toThrow(/名称不一致/);
+  });
+
+  it('registerAll 有实现缺配置声明 → 抛错', () => {
+    const registry = new HookRegistry();
+    expect(() =>
+      registry.registerAll([makeHook('a'), makeHook('orphan')], [makeConfig('a')])
+    ).toThrow(/hook "orphan" 没有对应的 HookConfig 声明/);
+  });
+
+  it('HookDefinition 类型上不再存在 enabled / errorStrategy（编译期钉）', () => {
+    const withStrategy: HookDefinition = {
+      name: 'x',
+      phase: 'before',
+      // @ts-expect-error HookDefinition 不再存在 errorStrategy 字段（#159）
+      errorStrategy: 'block',
+      execute: async () => ({ passed: true }),
+    };
+    const withEnabled: HookDefinition = {
+      name: 'y',
+      phase: 'before',
+      // @ts-expect-error HookDefinition 不再存在 enabled 字段（#159）
+      enabled: false,
+      execute: async () => ({ passed: true }),
+    };
+    expect(withStrategy.name).toBe('x');
+    expect(withEnabled.name).toBe('y');
+  });
+});

package/src/hooks/bootstrap.ts

@@ -11,17 +11,18 @@
  * // harness.checker, harness.config, harness.hooks, harness.sessions
  * ```
  *
- * checker 的 trace 记录器在此接线（harness#88：core 不上行依赖 monitoring）。
+ * checker 的 trace 记录器在此接线（harness#88：core 不上行依赖 monitoring），
+ * 且锚在本函数收到的 projectPath 上（#139：落点跟根走，不落调用方 cwd）。
  */
 
 import { ConstraintChecker } from '../core/constraints/checker';
 import { SessionManager } from '../context/session-manager';
 import { ProjectConfigLoader } from '../core/project-config-loader';
-import { getTraceCollector } from '../monitoring/traces';
+import { TraceCollector } from '../monitoring/traces';
 import { HookRegistry } from './registry';
 import { HookPipeline } from './pipeline';
 import type { MergedConstraintsConfig } from '../types/project-config';
-import type { HookDefinition } from './types';
+import type { HookConfig, HookDefinition } from './types';
 
 /**
  * 异步加载项目配置（S9：异步 I/O）
@@ -30,8 +31,8 @@ async function loadConfigAsync(projectPath: string): Promise<{
   config: ReturnType<ProjectConfigLoader['getConfig']>;
   mergedConstraints: MergedConstraintsConfig;
 }> {
-  // config.yml 解析经 loadRawProjectConfig 进程级 memoize（工单 16），
-  // 此处不再重复读取文件
+  // config.yml 的读取只有 loadRawProjectConfig 这一条路（ADR-0023 决策 2 撤销进程级
+  // 缓存后，每次调用读当下内容），此处不重复读文件
   const loader = new ProjectConfigLoader(projectPath);
   loader.load();
 
@@ -59,15 +60,36 @@ export interface HarnessBootstrap {
   mergedConstraints: MergedConstraintsConfig;
 }
 
+/**
+ * 注册初始 hook（定义必须配对配置声明表——#159 起 HookConfig 是
+ * enabled / errorStrategy 的唯一声明点，缺表即抛错）
+ */
+function registerInitialHooks(
+  hooks: HookRegistry,
+  hookDefinitions: HookDefinition[] | undefined,
+  hookConfigs: HookConfig[] | undefined
+): void {
+  if (!hookDefinitions || hookDefinitions.length === 0) return;
+  if (!hookConfigs) {
+    throw new Error(
+      '[harness] bootstrap 失败：注册 hook 定义必须同时提供 HookConfig 声明表' +
+      '（enabled / errorStrategy 的唯一声明点）。'
+    );
+  }
+  hooks.registerAll(hookDefinitions, hookConfigs);
+}
+
 /**
  * 初始化 harness 运行环境（异步，不阻塞事件循环）
  *
  * @param projectPath 项目根路径
  * @param hookDefinitions 可选，初始化时注册的 hook
+ * @param hookConfigs 可选，与 hookDefinitions 配对的配置声明表（注册定义时必填）
  */
 export async function bootstrapHarness(
   projectPath?: string,
-  hookDefinitions?: HookDefinition[]
+  hookDefinitions?: HookDefinition[],
+  hookConfigs?: HookConfig[]
 ): Promise<HarnessBootstrap> {
   const resolvedPath = projectPath || process.cwd();
 
@@ -75,16 +97,15 @@ export async function bootstrapHarness(
   const { mergedConstraints } = await loadConfigAsync(resolvedPath);
 
   // 2. 初始化核心组件
-  const checker = new ConstraintChecker(getTraceCollector());
+  // trace 记录器锚根构造（#139）：本函数本就收 projectPath，落点必须跟着根走
+  const checker = new ConstraintChecker(new TraceCollector({ projectPath: resolvedPath }));
 
   const sessions = new SessionManager(resolvedPath);
   const hooks = new HookRegistry();
   const pipeline = new HookPipeline(hooks);
 
   // 3. 注册初始 hook
-  if (hookDefinitions) {
-    hooks.registerAll(hookDefinitions);
-  }
+  registerInitialHooks(hooks, hookDefinitions, hookConfigs);
 
   return {
     checker,
@@ -103,7 +124,8 @@ export async function bootstrapHarness(
  */
 export function bootstrapHarnessSync(
   projectPath?: string,
-  hookDefinitions?: HookDefinition[]
+  hookDefinitions?: HookDefinition[],
+  hookConfigs?: HookConfig[]
 ): HarnessBootstrap {
   const resolvedPath = projectPath || process.cwd();
 
@@ -111,15 +133,13 @@ export function bootstrapHarnessSync(
   loader.load();
   const mergedConstraints = loader.mergeConstraints();
 
-  const checker = new ConstraintChecker(getTraceCollector());
+  const checker = new ConstraintChecker(new TraceCollector({ projectPath: resolvedPath }));
 
   const sessions = new SessionManager(resolvedPath);
   const hooks = new HookRegistry();
   const pipeline = new HookPipeline(hooks);
 
-  if (hookDefinitions) {
-    hooks.registerAll(hookDefinitions);
-  }
+  registerInitialHooks(hooks, hookDefinitions, hookConfigs);
 
   return {
     checker,

package/src/hooks/config.ts

@@ -2,7 +2,7 @@
  * Hook 配置归一（G7）
  *
  * studio 侧 per-hook 运行时配置（`blocking: boolean`）与 harness 侧
- * `HookDefinition.errorStrategy` 双轨归一：以 errorStrategy 为唯一真相，
+ * `HookConfig.errorStrategy` 双轨归一：以 errorStrategy 为唯一真相，
  * `blocking` → errorStrategy 为无损映射。
  *
  * 映射语义（确认于 H5）：
@@ -12,6 +12,10 @@
  *   （管线结果 warnings 记名，passed 不受影响）——对应 studio safeCallHook
  *   console.warn 继续
  *
+ * #159 起 `HookConfig` 是 `enabled` / `errorStrategy` 的唯一声明点：
+ * HookDefinition 不再携带这两个字段，注册环节以配置表填充有效值，
+ * 有效策略集合收敛为 'block' | 'warn'（原 'ignore' 退出有效面）。
+ *
  * studio 侧随动（studio #150 A4）：hooks/config.ts 删 DEFAULTS/safeCallHook，
  * blocking→errorStrategy 无损映射进 toHookDef；HARNESS_HOOK_DISABLE 保留 studio。
  */
@@ -24,6 +28,6 @@ import type { HookErrorStrategy } from './types';
  * @param blocking studio 侧「失败是否阻断」语义
  * @returns 'block'（阻断）| 'warn'（警告继续）
  */
-export function toErrorStrategy(blocking: boolean): Extract<HookErrorStrategy, 'block' | 'warn'> {
+export function toErrorStrategy(blocking: boolean): HookErrorStrategy {
   return blocking ? 'block' : 'warn';
 }

package/src/hooks/index.ts

@@ -5,7 +5,16 @@
  * 无业务逻辑，consumer 自行定义 hook 名称和语义。
  */
 
-export * from './types';
+export type {
+  HookPhase,
+  HookErrorStrategy,
+  HookConfig,
+  HookDefinition,
+  EffectiveHook,
+  HookResult,
+  HookExecutionRecord,
+  PipelineResult,
+} from './types';
 export { HookRegistry, assertHookRegistryClosed } from './registry';
 export { HookPipeline } from './pipeline';
 export { toErrorStrategy } from './config';

package/src/hooks/pipeline.ts

@@ -6,7 +6,7 @@
  */
 
 import type {
-  HookDefinition,
+  EffectiveHook,
   HookPhase,
   HookExecutionRecord,
   PipelineResult,
@@ -47,10 +47,8 @@ export class HookPipeline<C = unknown> {
           blockedBy.push(hook.name);
           break; // blocking hook 失败，停止执行后续 hook
         }
-        if (hook.errorStrategy === 'warn') {
-          warnings.push(hook.name);
-        }
-        // 'ignore' 策略静默跳过
+        // 'warn'：记录警告继续（有效集合仅 block/warn，策略由 HookConfig 必填声明）
+        warnings.push(hook.name);
       }
     }
 
@@ -111,7 +109,7 @@ export class HookPipeline<C = unknown> {
    * 执行单个 hook（带采样和错误隔离）
    */
   private async executeOne(
-    hook: HookDefinition<C, unknown>,
+    hook: EffectiveHook<C, unknown>,
     context: C
   ): Promise<HookExecutionRecord> {
     const startedAt = Date.now();

package/src/hooks/registry.ts

@@ -4,7 +4,7 @@
  * 纯簿记，无执行逻辑。线程不安全（Node.js 单线程）。
  */
 
-import type { HookConfig, HookDefinition, HookPhase } from './types';
+import type { EffectiveHook, HookConfig, HookDefinition, HookPhase } from './types';
 
 /**
  * 注册表闭环双向校验（H5，复制 checker 闭环模式）
@@ -66,21 +66,40 @@ export function assertHookRegistryClosed<C = unknown, R = unknown>(
 }
 
 export class HookRegistry<C = unknown, R = unknown> {
-  private hooks: Map<string, HookDefinition<C, R>> = new Map();
+  private hooks: Map<string, EffectiveHook<C, R>> = new Map();
 
   /**
    * 注册 hook（同名覆盖）
+   *
+   * 有效 `enabled` / `errorStrategy` 由 HookConfig 填充——配置表是这两个
+   * 语义的唯一声明点（#159），定义与配置名称不一致即抛错。
    */
-  register(hook: HookDefinition<C, R>): void {
-    this.hooks.set(hook.name, { ...hook });
+  register(hook: HookDefinition<C, R>, config: HookConfig): void {
+    if (hook.name !== config.name) {
+      throw new Error(
+        `[harness] hook 注册失败：定义 "${hook.name}" 与配置 "${config.name}" 名称不一致。`
+      );
+    }
+    this.hooks.set(hook.name, {
+      ...hook,
+      enabled: config.enabled,
+      errorStrategy: config.errorStrategy,
+    });
   }
 
   /**
-   * 批量注册
+   * 批量注册（按 name 配对配置；有实现缺配置声明即抛错）
    */
-  registerAll(hooks: HookDefinition<C, R>[]): void {
+  registerAll(hooks: HookDefinition<C, R>[], configs: readonly HookConfig[]): void {
+    const configByName = new Map(configs.map(c => [c.name, c]));
     for (const hook of hooks) {
-      this.register(hook);
+      const config = configByName.get(hook.name);
+      if (!config) {
+        throw new Error(
+          `[harness] hook 注册失败：hook "${hook.name}" 没有对应的 HookConfig 声明。`
+        );
+      }
+      this.register(hook, config);
     }
   }
 
@@ -92,18 +111,18 @@ export class HookRegistry<C = unknown, R = unknown> {
   }
 
   /**
-   * 获取单个 hook
+   * 获取单个 hook（含有效 enabled / errorStrategy）
    */
-  get(name: string): HookDefinition<C, R> | undefined {
+  get(name: string): EffectiveHook<C, R> | undefined {
     return this.hooks.get(name);
   }
 
   /**
    * 获取指定时机、已启用的 hook，按优先级排序
    */
-  getEnabled(phase: HookPhase): HookDefinition<C, R>[] {
+  getEnabled(phase: HookPhase): EffectiveHook<C, R>[] {
     return Array.from(this.hooks.values())
-      .filter(h => h.phase === phase && h.enabled !== false)
+      .filter(h => h.phase === phase && h.enabled)
       .sort((a, b) => (a.priority ?? 100) - (b.priority ?? 100));
   }
 
@@ -117,7 +136,7 @@ export class HookRegistry<C = unknown, R = unknown> {
   /**
    * 列出所有 hook（含禁用）
    */
-  listAll(): HookDefinition<C, R>[] {
+  listAll(): EffectiveHook<C, R>[] {
     return Array.from(this.hooks.values());
   }
 

package/src/hooks/types.ts

@@ -11,9 +11,12 @@
 export type HookPhase = 'before' | 'after' | 'around';
 
 /**
- * Hook 错误处理策略
+ * Hook 错误处理策略（有效集合：'block' | 'warn'）
+ *
+ * #159 起原 'ignore' 退出有效面：策略的唯一声明点是 HookConfig（必填），
+ * 不存在「未声明 strategy」的运行时形态。
  */
-export type HookErrorStrategy = 'block' | 'warn' | 'ignore';
+export type HookErrorStrategy = 'block' | 'warn';
 
 /**
  * Hook 配置（G7 归一后形状：consumer 侧的 per-hook 声明表）
@@ -22,6 +25,10 @@ export type HookErrorStrategy = 'block' | 'warn' | 'ignore';
  * - 声明（HookConfig）是「定义」侧：引用未注册实现 → 抛错
  * - 注册（HookDefinition）是「实现」侧：注册无对应声明 → 抛错
  *
+ * #159 起本表是 `enabled` / `errorStrategy` 的**唯一声明点**：
+ * HookDefinition 不再携带这两个字段，有效值在注册环节由本表填充
+ * （见 EffectiveHook），声明与实现两处值矛盾在构造上不可能出现。
+ *
  * 对应 studio 侧 per-hook 运行时配置（hooks/config.ts 的 DEFAULTS）语义：
  * blocking:true ↔ errorStrategy 'block'（失败阻断管线），
  * blocking:false ↔ errorStrategy 'warn'（记录警告继续）——无损映射见
@@ -33,13 +40,14 @@ export interface HookConfig {
   /** 是否启用（false 时不进入管线） */
   enabled: boolean;
   /** 错误策略：block=失败阻断管线，warn=记录警告继续 */
-  errorStrategy: 'block' | 'warn';
+  errorStrategy: HookErrorStrategy;
 }
 
 /**
  * Hook 定义
  *
  * Consumer 自行选择 name（如 'beforeAgentExecute'），harness 只提供管线。
+ * `enabled` / `errorStrategy` 不在此处声明——唯一声明点是 HookConfig（#159）。
  */
 export interface HookDefinition<C = unknown, R = unknown> {
   /** Hook 唯一名称（consumer 定义语义） */
@@ -48,16 +56,25 @@ export interface HookDefinition<C = unknown, R = unknown> {
   phase: HookPhase;
   /** 优先级（越小越先执行，默认 100） */
   priority?: number;
-  /** 错误策略：block=阻断管线, warn=记录警告继续, ignore=静默跳过 */
-  errorStrategy?: HookErrorStrategy;
   /** 采样率 0-1（1=100% 执行，0.1=10% 采样） */
   sampleRate?: number;
-  /** 是否启用 */
-  enabled?: boolean;
   /** Hook 执行函数 */
   execute: (context: C) => Promise<HookResult<R>>;
 }
 
+/**
+ * 有效 hook = HookDefinition + 注册环节由 HookConfig 填充的有效值
+ *
+ * 管线与注册表的判定（启用过滤、block/warn 分派）只读本类型，
+ * 值来源单一（HookConfig），不存在第二声明点。
+ */
+export interface EffectiveHook<C = unknown, R = unknown> extends HookDefinition<C, R> {
+  /** 是否启用（来自 HookConfig.enabled） */
+  enabled: boolean;
+  /** 错误策略（来自 HookConfig.errorStrategy） */
+  errorStrategy: HookErrorStrategy;
+}
+
 /**
  * Hook 执行结果
  */

package/src/index.ts

@@ -152,7 +152,6 @@ export {
   registeredGateCount,
   assertGateRegistryClosed,
   runGates,
-  getEffectiveGates,
   createCheckerGate,
 } from './gates';
 export type {
@@ -163,7 +162,6 @@ export type {
   GateDecisionStatus,
   GateDefinition,
   GateRunResult,
-  GatesConfig,
   PerformanceThresholds,
   ReviewGateConfig,
   SecurityGateConfig,
@@ -357,6 +355,7 @@ export {
 export type {
   HookDefinition,
   HookConfig,
+  EffectiveHook,
   HookErrorStrategy,
   HookExecutionRecord,
   HookPhase,

package/src/knowledge/CONTEXT.md

@@ -17,13 +17,16 @@
 - 所有模式支持 `decayAt` 硬过期
 
 ## 核心导出
-- `KnowledgeStore` — 知识条目 CRUD + 结构化存储；`saveAll()` 批量写入（循环内只更新内存索引、结束一次 writeIndex，harness#107）
+- `KnowledgeStore`（类型面）/ `FileKnowledgeStore`（`store.ts`，barrel 与包根交出的**值**符号——store 的文件系统实现，构造收 `{ baseDir }`；仓内构造点两处：`cli/commands/knowledge-view.ts` 的 `openKnowledgeStore()`（knowledge 各子命令的取数口）与 `cli/commands/constraints-retire.ts` 的退役沉淀写入）— 知识条目 CRUD + 结构化存储；`saveAll()` 全量批量写入（循环内只更新内存索引、结束一次 writeIndex，harness#107）、`applyAll()` 按 id 部分更新的批量出口（`update(id, partial)` 的批量形，语义含未知 id 逐条跳过与空批零读写，harness#134）、`getConsumptionStats()` 读 `.consumption-stats.json` 的当日消费计数（打分核心唯一的消费统计取数口，harness#134）
 - `KnowledgeQuery` — 语义搜索 + 类型/标签过滤 + `queryByMode()` + `consume(taskContext)`；`query()` 是 budget 截断管线（仅用于 prompt 注入），`search()` 是全语料文本搜索（先匹配→排序→limit，交互搜索专用，勿用 query() 代替）
-- `KnowledgeLifecycle` — per-mode 生命周期管理
+- `KnowledgeLifecycle` — per-mode 生命周期管理；缺省阈值常量 `DEFAULT_DECAY_CONFIG`（`provenDecayMonths: 12` / `verifiedDecayMonths: 6` / `draftDecayMonths: 3` / `autoPromoteSources: []`，正本 `types.ts`）经构造器 `{...DEFAULT_DECAY_CONFIG, ...config}` 合并，barrel 与包根一并交出
+- `extractCodeStructure(dir)`（`primitives/code-structure.ts`，配 `CodeStructure`/`DeclarationInfo`/`ImportInfo` 三类型对外）— 目录代码结构提取；仓内零调用方，是留给下游的公开面
 - `KnowledgeIngest` — 知识摄取引擎（含 ingest gate 质量门）+ `ingestExternal()` 外部内容摄入
 - `sanitizeExternalContent` — 外部内容安全清洗（过滤注入模式 + 长度限制）
-- `migrateKnowledgeEntries` — AS-021 迁移工具（为现有条目添加 consumptionMode/origin）
-- `KnowledgeAudit` — 7 维度质量审计引擎。per-entry 规则记录带 `scope: 'active' | 'all'`（active = 不判定 archived 条目）；人口过滤由 `ruleDetail()` 统一执行，规则内禁止再写 `entry.maturity === 'archived'` 早返回。规则中文 label 正本在规则定义的 `label` 字段（harness#109，ADR-0002 定义即注册），`AUDIT_RULE_LABELS` 派生导出、与 `AuditRuleName` 编译期闭环，CLI 展示层直接消费、禁止另建 label 表
+- `migrateKnowledgeEntries` — AS-021 迁移工具（为现有条目添加 consumptionMode/origin）；条目人口按 `tree-walker` 口径判定，`_index.md` 等树生成物不计入 `total`/`errors`（harness#134 修此前假阳性）
+- `KnowledgeAudit` — 7 维度质量审计**引擎**：构造收 `KnowledgeStore`（与 lint / doctor / query / lifecycle / ingest 同形，harness#134——此前收目录并自建 store，致使打分判定无法脱离文件系统测试）+ 可选阈值形参（三个数值槽显式传 NaN/±Infinity/负数时构造期抛 `TypeError`（message 含槽名与实参），不放行到打分层静默关掉 short-content/stale-entry/promotion-blocked 三条判定；未传/显式 `undefined` 走缺省、显式 `0` 合法按 0 生效，harness#163）。职责只剩装配：取条目、经 store 取环境数据、把整批修复动作交 `store.applyAll()`。per-entry 规则记录带 `scope: 'active' | 'all'`（active = 不判定 archived 条目）；人口过滤由 `ruleDetail()` 统一执行，规则内禁止再写 `entry.maturity === 'archived'` 早返回。规则中文 label 正本在规则定义的 `label` 字段（harness#109，ADR-0002 定义即注册），`AUDIT_RULE_LABELS` 派生导出、与 `AuditRuleName` 编译期闭环，CLI 展示层直接消费、禁止另建 label 表
+- `audit-scoring`（**值面**不进导出面；类型面是例外——`AuditRuleName`/`AuditAction`/`AuditIssue`/`AuditReport`/`AuditOptions` 经 `index.ts` 再导出并上包根，ADR-0003 显式清单）— D1–D7 打分**纯模块**（harness#134）：规则表、`scanEntries()` / `summarizeIssues()` / `computeDimensions()` / `calculateHealthScore()`，零 fs——环境数据（消费统计、快照存活）由调用方经 store 取好喂入。审计判定的唯一正本在此，可脱离合建目录测试
+- `tree-walker`（包内，不进导出面）— 知识树排除口径单点（harness#134）：`isEntryFile()` / `isInfraDir()` / `INDEX_MD_FILE` / `SNAPSHOTS_DIR`，由 store 顶层扫描、migration 顶层扫描、index-generator 递归扫描三处共同消费
 - `flywheel-metrics`（包内，不进导出面）— 知识飞轮指标唯一实现：`evaluateFlywheel(env)` 出 canonical 比例、`genuineRefs()` 出 synthetic 过滤口径，audit D6 / `knowledge stats` / `knowledge health` 三处共消费（ADR-0013）
 - `ReferenceTracker` — 知识引用关系图谱
 - `KnowledgeLinter` — 知识质量检查(完整性/一致性/时效性)
@@ -31,19 +34,22 @@
 - `KnowledgeHealthScorer` — 知识健康评分（doctor.ts）
 
 ## 依赖关系
-- 依赖 `src/types/` 知识相关类型
+- 知识类型正本在**本模块** `src/knowledge/types.ts`（`KnowledgeEntry`/`MaturityLevel`/`ConsumptionMode`/`KnowledgeOrigin`/`DecayConfig`…）；本目录对 `src/types/` **零 import**——旧条目「依赖 `src/types/` 知识相关类型」不实（harness#142 逐条核对）
 - 依赖 `src/utils/frontmatter` — markdown frontmatter 解析/序列化的唯一正本（harness#89：store、migration、index-generator、ingest 共用同一套语法判定，不再各写正则）
 - 不依赖 `src/context/`（原 `lifecycle-hooks.ts` 是唯一 import `context/types` 的文件，已随 ADR-0022 删除），也不依赖 monitoring——知识健康评分由本目录 doctor.ts 的 KnowledgeHealthScorer 承载
 - 被 `src/cli/commands/knowledge.ts` CLI 消费（含 `migrate` 子命令）
 
 ## 约定
-- 知识条目文件的 frontmatter 语法只由 `src/utils/frontmatter` 定义（harness#89）：缺头/空 meta = `absent`（合法输入，按非条目静默处理）；未闭合/YAML 非法 = `malformed`（必须显式上报后按消费方语义恢复——migration 落 `errors`、store 与 index-generator 打一行 stderr 后跳过或走 best-effort），禁止静默丢条目；canonical 字段序是 `store.toFrontmatter` 的私有策略，`join` 只管包裹格式
+- 知识条目文件的 frontmatter 语法只由 `src/utils/frontmatter` 定义（harness#89）：缺头/空 meta = `absent`（合法输入，按非条目静默处理、不上报——migration 对 `absent` 不计 `errors`、不迁移，只计 `skipped` 保证 `total` 计数闭环，harness#161 对齐 #89 裁决 2）；未闭合/YAML 非法 = `malformed`（必须显式上报后按消费方语义恢复——migration 落 `errors`、store 与 index-generator 打一行 stderr 后跳过或走 best-effort），禁止静默丢条目；canonical 字段序是 `store.toFrontmatter` 的私有策略，`join` 只管包裹格式
+- **知识树的排除口径只有一个正本 `tree-walker`**（harness#134）：`_index.md`（索引生成物）、`.snapshots`、`.archive` / `archived`、`resolutions` 是树基建、不是条目人口。store 与 migration 的顶层扫描、index-generator 的递归扫描三处都走它；新增 walker 禁止另立排除清单。统一的是**排除口径**不是遍历深度（store/migration 顶层、index-generator 递归）。例外须原地记名理由：`import.ts` 的 docs 扫描吃的是**项目文档树**，本口径在它那里没有对应物
+- **循环内禁止逐条 `store.update()`**（harness#134）：`update()` 的形状是 get→save、`save()` 每次全量重写 index.json，N 条修复 = N 次全量重写。批量形是 `applyAll(id → partial)`；一次 `audit --fix`、一轮 `runDecayCycle()`、一次 `updateReferencedBy()` 各只重写一次索引，计数闸见 `audit-write-count.test.ts` 与 `lifecycle.test.ts` / `reference-tracker.test.ts` 的 stringify 计数项
+- **审计判定脱离文件系统可测**（harness#134）：规则表与 D1–D7 打分住 `audit-scoring.ts`，零 fs（源形状闸钉在 `audit-scoring.test.ts`）；引擎 `audit.ts` 只做 store 装配，环境数据经 `store.getConsumptionStats()` / `getSurvivalRate()` 取好喂入
 - 知识条目有明确的生命周期状态（按 consumptionMode 分化）
 - 约束退役（`harness constraints retire`，人确认）时写入 KnowledgeStore：规则原文 + 退役原因 + 历史统计
 - Linter 检查完整性/一致性/时效性三个维度
 - Audit 7 维度评分：D1结构 D2内容 D3去重 D4成熟度 D5新鲜度 D6飞轮 D7增量存活
 - Ingest gate: ingestEntry() 先经 audit.validate() 检查，reject 不入库
-- 外部内容三层防御：ingest sanitization + retrieval marking + prompt constraint
+- 外部内容三层防御：ingest sanitization + retrieval marking + prompt constraint。第二层 marking 已接线（harness#161）：标记正本是 `knowledge/query.ts` 的 `EXTERNAL_SOURCE_MARKER` 常量（`[External Source — verify before acting]`），`KnowledgeQuery.formatForPrompt()` 与注入路径 `context/knowledge-injector.ts` 的 `formatEntry()`/`formatEntrySummary()` 共用同一常量——`origin === 'external'` 条目注入 prompt 时带来源前缀，注入 source 的 metadata 带 `origin`。第三层（prompt constraint）在本仓不可核（属 studio/agent 侧提示词），未核不改
 - 消费饱和度替代固定 TTL 用于 signal 过期判断
 - **飞轮指标只有一个实现**（ADR-0013）：`refCoverage` / `avgRefs` / `consumptionHitRate` 一律出自 `flywheel-metrics.evaluateFlywheel()`，canonical 分子 = `genuineRefs()` 过滤后的真实消费引用（`search|test-agent|prompt-inject|monitor|analyst|...:<date>` 自动化按天记账键不算消费，`unknown:` 注入键算消费）。audit D6 / `knowledge stats` / `knowledge health` 只在展示层做单位与字段名映射（百分比取整、一位小数、`avgRefs`→`avgRefCount`），人口筛选留在各调用方。新增消费方禁止自行数 `referencedBy.length`。
 
@@ -53,3 +59,4 @@
 - `MaturityLevel` 包含 6 个值: draft/verified/proven/archived/active/deprecated
 - `excludeArchived` 同时排除 archived 和 deprecated
 - 仍有两处按**原始** `referencedBy.length` 判定，不属飞轮指标、ADR-0013 明确列为范围外：`lifecycle.ts` 的 signal 饱和 / reference 激活（退役阈值调整另票）、`knowledge health` 的 D1「verified 零引用」线索提示（逐条 issue 线索，非聚合分子）
+- #134 收口后仍在的逐条写点（同型问题，本票裁决点名的循环之外，需要时另票）：`lint.ts` 的三处 autoFix `store.update()`、`lifecycle.recordReference()`（逐事件调用，返回更新后条目并触发回调，批量化会改它的契约）、`ingest.mergeEntries()`；`store.list()` 每条一次 `findFile()` 线性扫索引的 O(N²) 按 #134 裁决**未动**，待把知识树实际规模重新量一次再判是否单开票

package/src/knowledge/__tests__/audit-labels.test.ts

@@ -1,15 +1,18 @@
 /**
  * 审计规则 label 闭环测试（架构评审 A6，#109）
  *
- * label 正本在 audit.ts 规则定义上（定义即注册），AUDIT_RULE_LABELS 派生自规则表。
- * 新增规则无 label → 编译期/本测试期即失败，CLI 不再静默回落英文键名。
+ * label 正本在规则定义上（定义即注册，#134 后随规则表住在 audit-scoring.ts），
+ * AUDIT_RULE_LABELS 派生自规则表。新增规则无 label → 编译期/本测试期即失败，
+ * CLI 不再静默回落英文键名。
  */
 
 import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
-import { KnowledgeAudit, AUDIT_RULE_LABELS } from '../audit';
-import type { AuditRuleName } from '../audit';
+import { KnowledgeAudit } from '../audit';
+import { AUDIT_RULE_LABELS } from '../audit-scoring';
+import type { AuditRuleName } from '../audit-scoring';
+import { FileKnowledgeStore } from '../store';
 
 function makeTmpDir(): string {
   return fs.mkdtempSync(path.join(os.tmpdir(), 'audit-labels-test-'));
@@ -27,7 +30,7 @@ describe('AUDIT_RULE_LABELS', () => {
   });
 
   it('应与运行期 summary 的规则键集完全一致（双向闭环）', () => {
-    const report = new KnowledgeAudit({ baseDir: tmpDir }).run();
+    const report = new KnowledgeAudit(new FileKnowledgeStore({ baseDir: tmpDir })).run();
     const summaryKeys = Object.keys(report.summary).sort();
     const labelKeys = (Object.keys(AUDIT_RULE_LABELS) as AuditRuleName[]).sort();
     expect(labelKeys).toEqual(summaryKeys);