@dommaker/harness 1.1.1 → 1.2.0

package/src/knowledge/query.ts

@@ -86,6 +86,34 @@ export class KnowledgeQuery {
     return result;
   }
 
+  /**
+   * Full-text search over the entire corpus.
+   *
+   * Unlike query(), this is NOT budget-constrained: text matching runs on the
+   * full (filtered) corpus first, then results are sorted by
+   * maturity desc → lastReferenced desc and capped at `limit`.
+   * Token budgets only make sense for prompt injection (query()); interactive
+   * search must see every entry or low-ranked entries become unfindable.
+   *
+   * No caching and no recordReference side effect — searching is not citing.
+   */
+  search(query: string, options?: { limit?: number; filter?: QueryFilter }): KnowledgeEntry[] {
+    const limit = options?.limit ?? 20;
+    const candidates = this.store.list({
+      excludeArchived: true,
+      ...options?.filter,
+    });
+
+    const q = query.toLowerCase();
+    const matched = candidates.filter(e =>
+      e.title.toLowerCase().includes(q) ||
+      e.content.toLowerCase().includes(q) ||
+      e.tags.some(t => t.toLowerCase().includes(q))
+    );
+
+    return this.sortEntries(matched).slice(0, limit);
+  }
+
   /**
    * Estimate token count for a piece of text.
    * Rule of thumb: 1 CJK char ≈ 2 tokens, 1 ASCII char ≈ 0.25 tokens.

package/src/monitoring/CONTEXT.md

@@ -1,28 +1,22 @@
 # monitoring/
 
 ## 职责
-运行时监控：Execution Trace(收集/分析/诊断)、Performance Trace(收集/分析)、知识进化、上下文追踪。
+运行时监控：Execution Trace（收集/分析）+ 上下文使用追踪。
 
 ## 核心导出
-- `TraceCollector` — 执行追踪收集(append-only JSONL，`.harness/logs/traces.log`)
-- `TraceAnalyzer` — 追踪统计分析 + 异常检测
-- `ConstraintDoctor` — 约束诊断接口(Agent 消费)
-- `PerformanceCollector` — 性能日志收集
-- `PerformanceAnalyzer` — 性能统计分析
-- `ContextTracker` — 上下文追踪
-- `KnowledgeDoctor` — 知识健康诊断
-- `KnowledgeEvolver` — 知识进化引擎
+- `TraceCollector` — 执行追踪收集（append-only JSONL，`.harness/logs/traces.log`）
+- `TraceAnalyzer` — 追踪统计分析 + 异常检测（共用 analyzer-base 纯函数）
+- `ContextTracker` — LLM 调用上下文使用快照记录
 
 ## 依赖关系
-- 依赖 `src/core/constraints/` 约束定义
 - 依赖 `src/types/trace` ExecutionTrace 类型
-- 被 `src/cli/` 命令消费
+- 被 `src/core/constraints/checker`（惰性接线 getTraceCollector，ADR-0003）与 `src/cli/` 命令消费
 
 ## 约定
-- Trace 文件存储在 .harness/ 目录(不提交)
+- Trace 文件存储在 .harness/ 目录（不提交）
 - 追加写入，单行 JSON，自动滚动
 - 零 Token 成本：不调用 LLM
 
 ## 注意事项
 - 追踪数据供 `harness constraints report` 统计与退役候选诊断消费（观测用途，不做自动降级）
-- PerformanceCollector 和 TraceCollector 独立运作
+- ADR-0003 起移除 recordBypass 链（绕过观测后续单独立项）与断链的诊断/性能/知识医生文件

package/src/monitoring/__tests__/traces.test.ts

@@ -79,16 +79,6 @@ describe('TraceCollector', () => {
     });
   });
 
-  describe('recordBypass()', () => {
-    it('should record bypass trace', () => {
-      collector.recordBypass('test', 'guideline', 'Emergency');
-      const call = mockFs.appendFileSync.mock.calls[0];
-      const content = JSON.parse(call[1] as string);
-      expect(content.result).toBe('bypassed');
-      expect(content.bypassReason).toBe('Emergency');
-    });
-  });
-
   describe('read()', () => {
     it('should return empty array if file not exists', () => {
       mockFs.existsSync.mockReturnValueOnce(true);

package/src/monitoring/analyzer-base.ts

@@ -35,28 +35,6 @@ export function timeRangeOf(timestamps: number[]): { start: number; end: number
   };
 }
 
-/**
- * 找出出现次数最多的元素
- */
-export function findMostCommon(items: string[]): string | undefined {
-  if (items.length === 0) return undefined;
-
-  const counts = new Map<string, number>();
-  for (const item of items) {
-    counts.set(item, (counts.get(item) || 0) + 1);
-  }
-
-  let maxCount = 0;
-  let mostCommon: string | undefined;
-  for (const [item, count] of counts) {
-    if (count > maxCount) {
-      maxCount = count;
-      mostCommon = item;
-    }
-  }
-  return mostCommon;
-}
-
 /**
  * 平均值
  */

package/src/monitoring/index.ts

@@ -4,18 +4,12 @@
  * Execution Trace 系统：
  * - TraceCollector：轻量收集，零 Token
  * - TraceAnalyzer：统计汇总，异常检测
- * - ConstraintDoctor：Agent 诊断接口
  *
- * Performance Trace 系统：
- * - PerformanceCollector：性能日志收集，零 Token
- * - PerformanceAnalyzer：统计汇总，异常检测
+ * 上下文使用追踪：
+ * - ContextTracker：LLM 调用上下文快照记录
  */
 
-export * from './traces';
-export * from './trace-analyzer';
-export * from './constraint-doctor';
-export * from './performance-collector';
-export * from './performance-analyzer';
-export * from './context-tracker';
-export { KnowledgeDoctor } from './knowledge-doctor';
-export { KnowledgeEvolver } from './knowledge-evolver';
+export { TraceCollector, getTraceCollector, configureTraceCollector, DEFAULT_TRACE_FILE } from './traces';
+export { TraceAnalyzer, createAnalyzer } from './trace-analyzer';
+export { ContextTracker } from './context-tracker';
+export type { ContextAverages } from './context-tracker';

package/src/monitoring/trace-analyzer.ts

@@ -19,7 +19,6 @@ import { TraceCollector } from './traces';
 import {
   groupByKey,
   timeRangeOf,
-  findMostCommon,
   splitByTime,
   writeSummaryJson,
   readSummaryJson,
@@ -33,9 +32,7 @@ const DEFAULT_CONFIG: TraceAnalyzerConfig = {
   summaryFile: '.harness/logs/traces-summary.json',
   periodMs: 3600 * 1000, // 1 小时
   thresholds: {
-    bypassRate: 0.3,      // 绕过率 > 30% 视为异常
     failRate: 0.5,        // 失败率 > 50% 视为异常
-    exceptionRate: 0.4,   // 例外率 > 40% 视为滥用
   },
 };
 
@@ -76,13 +73,12 @@ export class TraceAnalyzer {
       // 计算时间范围
       const timeRange = timeRangeOf(group.map(t => t.timestamp));
 
-      // 单次遍历计算核心统计（skip 单独计数，不计入 pass/fail/bypass 率分母，ADR-0001）
+      // 单次遍历计算核心统计（skip 单独计数，不计入 pass/fail 率分母，ADR-0001）
       const totalChecks = group.length;
-      let passCount = 0, failCount = 0, bypassCount = 0, ignoreCount = 0, skipCount = 0;
+      let passCount = 0, failCount = 0, ignoreCount = 0, skipCount = 0;
       for (const t of group) {
         if (t.result === 'pass') passCount++;
         else if (t.result === 'fail') failCount++;
-        else if (t.result === 'bypassed') bypassCount++;
         else if (t.result === 'skip') skipCount++;
         if (t.userAction === 'ignore') ignoreCount++;
       }
@@ -91,13 +87,6 @@ export class TraceAnalyzer {
       const evaluatedChecks = totalChecks - skipCount;
       const passRate = evaluatedChecks > 0 ? passCount / evaluatedChecks : 0;
       const failRate = evaluatedChecks > 0 ? failCount / evaluatedChecks : 0;
-      const bypassRate = evaluatedChecks > 0 ? bypassCount / evaluatedChecks : 0;
-
-      // 计算例外统计
-      const exceptionTraces = group.filter(t => t.exceptionApplied);
-      const exceptionCount = exceptionTraces.length;
-      const exceptionTypes = exceptionTraces.map(t => t.exceptionApplied!);
-      const mostCommonException = findMostCommon(exceptionTypes);
 
       // 计算趋势
       const recentTrend = this.calculateTrend(group);
@@ -109,15 +98,11 @@ export class TraceAnalyzer {
         totalChecks,
         passCount,
         failCount,
-        bypassCount,
         skipCount,
         ignoreCount,
         passRate,
         failRate,
-        bypassRate,
         recentTrend,
-        exceptionCount,
-        mostCommonException,
       });
     }
 
@@ -150,23 +135,6 @@ export class TraceAnalyzer {
     const thresholds = this.config.thresholds!;
 
     for (const summary of summaries) {
-      // 检测高绕过率
-      if (summary.bypassRate > thresholds.bypassRate!) {
-        anomalies.push({
-          type: 'high_bypass_rate',
-          constraintId: summary.constraintId,
-          level: summary.level,
-          message: `约束 ${summary.constraintId} 绕过率 ${Math.round(summary.bypassRate * 100)}%，超过阈值 ${thresholds.bypassRate! * 100}%`,
-          data: {
-            currentRate: summary.bypassRate,
-            threshold: thresholds.bypassRate!,
-            trend: summary.recentTrend,
-          },
-          detectedAt: Date.now(),
-          suggestedAction: 'diagnose',
-        });
-      }
-
       // 检测失败率上升
       if (summary.failRate > thresholds.failRate! && summary.recentTrend === 'rising') {
         anomalies.push({
@@ -184,23 +152,6 @@ export class TraceAnalyzer {
         });
       }
 
-      // 检测绕过率上升
-      if (summary.bypassRate > 0.1 && summary.recentTrend === 'rising') {
-        anomalies.push({
-          type: 'rising_bypass_rate',
-          constraintId: summary.constraintId,
-          level: summary.level,
-          message: `约束 ${summary.constraintId} 绕过率 ${Math.round(summary.bypassRate * 100)}% 且趋势上升`,
-          data: {
-            currentRate: summary.bypassRate,
-            threshold: 0.1,
-            trend: 'rising',
-          },
-          detectedAt: Date.now(),
-          suggestedAction: 'diagnose',
-        });
-      }
-
       // 检测低通过率
       if (summary.passRate < 0.3) {
         anomalies.push({
@@ -217,26 +168,6 @@ export class TraceAnalyzer {
           suggestedAction: 'adjust_threshold',
         });
       }
-
-      // 检测例外滥用
-      const exceptionRate = summary.totalChecks > 0
-        ? summary.exceptionCount / summary.totalChecks
-        : 0;
-
-      if (exceptionRate > thresholds.exceptionRate!) {
-        anomalies.push({
-          type: 'exception_overuse',
-          constraintId: summary.constraintId,
-          level: summary.level,
-          message: `约束 ${summary.constraintId} 例外使用率 ${Math.round(exceptionRate * 100)}%，可能过度依赖例外`,
-          data: {
-            currentRate: exceptionRate,
-            threshold: thresholds.exceptionRate!,
-          },
-          detectedAt: Date.now(),
-          suggestedAction: 'add_exception',
-        });
-      }
     }
 
     return anomalies;
@@ -262,7 +193,6 @@ export class TraceAnalyzer {
         summary.changeFromLastPeriod = {
           passRateDelta: summary.passRate - prev.passRate,
           failRateDelta: summary.failRate - prev.failRate,
-          bypassRateDelta: summary.bypassRate - prev.bypassRate,
         };
       }
 
@@ -386,7 +316,6 @@ export class TraceAnalyzer {
       lines.push(`  - Checks: ${summary.totalChecks}`);
       lines.push(`  - Pass: ${Math.round(summary.passRate * 100)}%`);
       lines.push(`  - Fail: ${Math.round(summary.failRate * 100)}%`);
-      lines.push(`  - Bypass: ${Math.round(summary.bypassRate * 100)}%`);
       lines.push(`  - Trend: ${summary.recentTrend}`);
       lines.push('');
     }

package/src/monitoring/traces.ts

@@ -117,26 +117,6 @@ export class TraceCollector {
     });
   }
 
-  /**
-   * 快捷方法：记录绕过
-   */
-  recordBypass(
-    constraintId: string,
-    level: 'iron_law' | 'guideline',
-    bypassReason?: string,
-    options?: Partial<ExecutionTrace>
-  ): void {
-    this.record({
-      constraintId,
-      level,
-      timestamp: Date.now(),
-      result: 'bypassed',
-      userAction: 'bypass',
-      bypassReason,
-      ...options,
-    });
-  }
-
   /**
    * 批量读取 traces
    *

package/src/presets/__tests__/standard.test.ts

@@ -1,89 +1,68 @@
 /**
- * Tests for standard.ts — applyPreset, getPreset
+ * presets 纯数据测试
  *
- * Pure logic, no I/O — tests preset selection and constraint filtering.
+ * 预设只保留数据（ADR-0001：筛选逻辑统一在 mergeConstraints），
+ * 这里锁定数据形状与 strict→standard 别名语义。
  */
 
-import { applyPreset, getPreset } from '../standard';
+import {
+  STRICT_PRESET,
+  STANDARD_PRESET,
+  RELAXED_PRESET,
+  PRESETS_BY_NAME,
+} from '../standard';
 
-describe('getPreset', () => {
-  it('returns strict preset', () => {
-    const preset = getPreset('strict');
-    expect(preset.name).toBe('strict');
-    expect(preset.ironLaws).toBeNull();
-    expect(preset.guidelines).toBeNull();
-    expect(preset.prompts).toBeNull();
-  });
-
-  it('returns standard preset', () => {
-    const preset = getPreset('standard');
-    expect(preset.name).toBe('standard');
+describe('预设数据', () => {
+  describe('STRICT_PRESET', () => {
+    it('应该启用所有约束', () => {
+      expect(STRICT_PRESET.name).toBe('strict');
+      expect(STRICT_PRESET.ironLaws).toBeNull();
+      expect(STRICT_PRESET.guidelines).toBeNull();
+      expect(STRICT_PRESET.prompts).toBeNull();
+    });
   });
 
-  it('returns relaxed preset', () => {
-    const preset = getPreset('relaxed');
-    expect(preset.name).toBe('relaxed');
-    expect(preset.ironLaws).toHaveLength(3);
-    expect(preset.guidelines).toHaveLength(2);
-    expect(preset.prompts).toEqual([]);
+  describe('STANDARD_PRESET', () => {
+    it('应该启用所有约束', () => {
+      expect(STANDARD_PRESET.name).toBe('standard');
+      expect(STANDARD_PRESET.ironLaws).toBeNull();
+      expect(STANDARD_PRESET.guidelines).toBeNull();
+      expect(STANDARD_PRESET.prompts).toBeNull();
+    });
   });
 
-  it('defaults to standard for unknown preset name', () => {
-    const preset = getPreset('unknown' as any);
-    expect(preset.name).toBe('standard');
-  });
-});
+  describe('RELAXED_PRESET', () => {
+    it('应该只启用核心约束', () => {
+      expect(RELAXED_PRESET.name).toBe('relaxed');
+      expect(RELAXED_PRESET.ironLaws).toHaveLength(3);
+      expect(RELAXED_PRESET.guidelines).toHaveLength(2);
+      expect(RELAXED_PRESET.prompts).toEqual([]);
+    });
 
-describe('applyPreset with string preset names', () => {
-  it('strict enables all iron laws and guidelines', () => {
-    const config = applyPreset('strict');
-    expect(config.ironLaws).toBeDefined();
-    expect(Object.keys(config.ironLaws).length).toBeGreaterThan(0);
-    expect(config.guidelines).toBeDefined();
-    expect(Object.keys(config.guidelines).length).toBeGreaterThan(0);
-    expect(config.disabled).toEqual([]);
-  });
+    it('应该包含 no_completion_without_verification', () => {
+      expect(RELAXED_PRESET.ironLaws).toContain('no_completion_without_verification');
+    });
 
-  it('relaxed enables only specific constraints', () => {
-    const config = applyPreset('relaxed');
-    expect(config.ironLaws).toBeDefined();
-    expect(config.ironLaws.no_completion_without_verification).toBeDefined();
-    expect(Object.keys(config.prompts ?? {}).length).toBe(0);
-    expect(config.disabled.length).toBeGreaterThan(0);
+    it('应该包含 no_bypass_checkpoint', () => {
+      expect(RELAXED_PRESET.guidelines).toContain('no_bypass_checkpoint');
+    });
   });
-});
 
-describe('applyPreset with PresetConfig object', () => {
-  it('filters iron laws when ids are provided', () => {
-    const config = applyPreset({
-      name: 'custom',
-      ironLaws: ['no_completion_without_verification', 'incremental_progress'],
-      guidelines: null,
-      prompts: null,
+  describe('PRESETS_BY_NAME', () => {
+    it('strict 是 standard 的别名（同为全部启用）', () => {
+      expect(PRESETS_BY_NAME['strict']?.ironLaws).toBeNull();
+      expect(PRESETS_BY_NAME['strict']?.guidelines).toBeNull();
+      expect(PRESETS_BY_NAME['strict']?.prompts).toBeNull();
     });
-    expect(Object.keys(config.ironLaws)).toHaveLength(2);
-    expect(config.ironLaws.no_completion_without_verification).toBeDefined();
-    expect(config.ironLaws.no_implementation_without_requirement).toBeUndefined();
-  });
 
-  it('includes all guidelines when null', () => {
-    const config = applyPreset({
-      name: 'custom',
-      ironLaws: null,
-      guidelines: null,
-      prompts: [],
+    it('三个预设名均可解析', () => {
+      expect(PRESETS_BY_NAME['strict']).toBe(STRICT_PRESET);
+      expect(PRESETS_BY_NAME['standard']).toBe(STANDARD_PRESET);
+      expect(PRESETS_BY_NAME['relaxed']).toBe(RELAXED_PRESET);
     });
-    expect(Object.keys(config.guidelines).length).toBeGreaterThan(0);
-    expect(Object.keys(config.prompts ?? {}).length).toBe(0);
-  });
 
-  it('creates disabled list for omitted constraints', () => {
-    const config = applyPreset({
-      name: 'custom',
-      ironLaws: [],
-      guidelines: [],
-      prompts: [],
+    it('未知预设名不在表中（由 mergeConstraints 回落 standard）', () => {
+      expect(PRESETS_BY_NAME['unknown']).toBeUndefined();
     });
-    expect(config.disabled.length).toBeGreaterThan(0);
   });
 });

package/src/presets/index.ts

@@ -1,14 +1,12 @@
 /**
- * 预设模块入口
+ * 预设模块入口（纯数据，ADR-0001：筛选逻辑统一在 mergeConstraints）
  */
 
 export {
   STRICT_PRESET,
   STANDARD_PRESET,
   RELAXED_PRESET,
-  getPreset,
-  applyPreset,
-
+  PRESETS_BY_NAME,
 } from './standard';
 
-export type { PresetConfig } from './standard';
+export type { PresetConfig } from './standard';

package/src/presets/standard.ts

@@ -1,15 +1,13 @@
 /**
- * 约束预设
+ * 约束预设（纯数据）
  *
- * 预设定义哪些约束被启用
+ * 预设定义哪些内置约束被启用。筛选与合并逻辑统一在
+ * core/project-config-loader.ts 的 mergeConstraints（ADR-0001 生效集链路），
+ * 本文件只保留预设数据，不再含函数。
  *
  * ADR-0001：kind 二元（check + prompt 纯注入层）。
  */
 
-import type { Constraint } from '../types/constraint';
-import type { MergedConstraintsConfig } from '../types/project-config';
-import { IRON_LAWS, GUIDELINES, PROMPTS } from '../core/constraints/definitions';
-
 /**
  * 预设配置
  */
@@ -27,69 +25,10 @@ export interface PresetConfig {
   prompts: string[] | null;
 }
 
-/**
- * 应用预设，生成 MergedConstraintsConfig（S12）
- *
- * 将 PresetConfig 转换为 ConstraintChecker.checkConstraints() 所需的 customConfig。
- * 支持 per-request 预设切换，不再局限于 CLI。
- *
- * @param preset 预设名称（'strict' | 'standard' | 'relaxed'）或 PresetConfig 对象
- * @returns 可直接传入 checkConstraints() 的 merged config
- *
- * 用法：
- * ```typescript
- * const config = applyPreset('relaxed');
- * await checker.checkConstraints(ctx, config);
- * ```
- */
-export function applyPreset(
-  preset: string | PresetConfig
-): MergedConstraintsConfig {
-  const cfg = typeof preset === 'string' ? getPreset(preset) : preset;
-
-  const filterByIds = (
-    source: Record<string, Constraint>,
-    ids: string[] | null,
-  ): Record<string, Constraint> => {
-    if (ids === null) return { ...source };
-    const filtered: Record<string, Constraint> = {};
-    for (const id of ids) {
-      if (source[id]) filtered[id] = source[id];
-    }
-    return filtered;
-  };
-
-  const disabled: string[] = [];
-  if (cfg.ironLaws !== null) {
-    for (const id of Object.keys(IRON_LAWS)) {
-      if (!cfg.ironLaws.includes(id)) disabled.push(id);
-    }
-  }
-  if (cfg.guidelines !== null) {
-    for (const id of Object.keys(GUIDELINES)) {
-      if (!cfg.guidelines.includes(id)) disabled.push(id);
-    }
-  }
-  if (cfg.prompts !== null) {
-    for (const id of Object.keys(PROMPTS)) {
-      if (!cfg.prompts.includes(id)) disabled.push(id);
-    }
-  }
-
-  return {
-    ironLaws: filterByIds(IRON_LAWS, cfg.ironLaws),
-    guidelines: filterByIds(GUIDELINES, cfg.guidelines),
-    prompts: filterByIds(PROMPTS, cfg.prompts),
-    disabled,
-    custom: [],
-    unknownIds: [],
-  };
-}
-
 /**
  * 严格预设
  *
- * 所有约束全部启用
+ * 所有约束全部启用（与 standard 同集，保留别名兼容历史配置）
  */
 export const STRICT_PRESET: PresetConfig = {
   name: 'strict',
@@ -130,17 +69,13 @@ export const RELAXED_PRESET: PresetConfig = {
 };
 
 /**
- * 获取预设
+ * 预设名 → 预设数据
+ *
+ * strict 是 standard 的别名（两者同为全部启用）。未知名不在此表，
+ * 由 mergeConstraints 回落 standard + stderr 警告。
  */
-export function getPreset(name: string): PresetConfig {
-  switch (name) {
-    case 'strict':
-      return STRICT_PRESET;
-    case 'standard':
-      return STANDARD_PRESET;
-    case 'relaxed':
-      return RELAXED_PRESET;
-    default:
-      return STANDARD_PRESET;
-  }
-}
+export const PRESETS_BY_NAME: Record<string, PresetConfig> = {
+  strict: STRICT_PRESET,
+  standard: STANDARD_PRESET,
+  relaxed: RELAXED_PRESET,
+};

package/src/spec/CONTEXT.md

@@ -1,19 +1,11 @@
 # spec/
 
 ## 职责
-代码注释规范检查：验证代码中的 @spec 注释是否符合规范。
+（空目录）原 @spec 注释规范检查（annotation-checker）已随 ADR-0003 删除。
 
-## 核心导出
-- `annotation-checker.ts` — AnnotationChecker: 检查 @spec 注释规范(有效/无效/警告)
-
-## 依赖关系
-- 依赖 `fs` / `path` 文件系统操作
-- 被 `src/cli/commands/spec.ts` CLI 命令消费
-
-## 约定
-- Spec 注释格式由 @spec 标签定义
-- 检查结果包含 valid: boolean + errors + warnings
+## 已接线的 spec 故事
+- `src/core/spec/validator.ts` — SpecValidator：spec 文档结构/内容验证（CLI `harness spec` 消费）
+- `src/gates/acceptance.ts` — SpecAcceptanceGate：验收标准门禁
 
 ## 注意事项
-- 无 index.ts 统一导出，独立模块导入
-- 扫描指定目录下所有 TS 文件的 @spec 注释
+- @spec 注释检查若需恢复，应迁移为 ConstraintCheck 注册进闭环注册表（ADR-0003 后续立项），不在本目录重建独立子系统