@dommaker/harness 0.16.9 → 0.17.1

package/src/dashboard/types.ts

@@ -5,7 +5,24 @@
  */
 
 import type { KnowledgeType } from '../knowledge/types';
-import type { ConstraintLayer, DeprecationStatus } from '../constraints/types';
+
+// ── 约束分层（原 src/constraints/types，约束分层子系统删除后归位 dashboard）──
+
+/** 约束分层 */
+export type ConstraintLayer = 'safety' | 'quality';
+
+/** 退化状态（生命周期机制已删除，保留字段供消费方兼容，恒为 active） */
+export type DeprecationStatus = 'active' | 'scheduled' | 'deprecated' | 'removed';
+
+/** 约束拦截统计（generate/getConstraintHeatmap 的输入） */
+export interface ConstraintStats {
+  constraintId: string;
+  triggerCount: number;
+  passCount: number;
+  interceptCount: number;
+  interceptRate: number;
+  lastTriggered?: string;
+}
 
 // ── 知识库全景 ───────────────────────────────────────────
 

package/src/index.ts

@@ -73,13 +73,6 @@ export * from './safety';
 // ========================================
 export * from './verification';
 
-// ========================================
-// 约束分层导出
-// ========================================
-export * from './constraints/types';
-export { ConstraintRegistry } from './constraints/registry';
-export { ConstraintLifecycleRunner } from './constraints/lifecycle-runner';
-
 // ========================================
 // Dashboard 数据导出
 // ========================================
@@ -114,11 +107,6 @@ export * from './agents';
 // ========================================
 export * from './presets';
 
-// ========================================
-// 约束进化导出
-// ========================================
-export * from './evolution';
-
 // ========================================
 // 便捷 API
 // ========================================

package/src/knowledge/CONTEXT.md

@@ -37,7 +37,7 @@
 
 ## 约定
 - 知识条目有明确的生命周期状态（按 consumptionMode 分化）
-- 约束退化时自动写入 KnowledgeStore
+- 约束退役（`harness constraints retire`，人确认）时写入 KnowledgeStore：规则原文 + 退役原因 + 历史统计
 - Linter 检查完整性/一致性/时效性三个维度
 - Audit 6 维度评分：D1结构 D2内容 D3去重 D4成熟度 D5新鲜度 D6飞轮
 - Ingest gate: ingestEntry() 先经 audit.validate() 检查，reject 不入库
@@ -46,6 +46,6 @@
 
 ## 注意事项
 - Phase 1+4 实现的知识引擎核心
-- 约束"退化不删除"——降级时保留规则原文 + 退化原因 + 历史数据
+- 约束"退役不删除"——retire 落盘 config.yml `enabled: false` + retired 元数据，保留规则原文 + 退役原因 + 历史统计（可回滚）
 - `MaturityLevel` 包含 6 个值: draft/verified/proven/archived/active/deprecated
 - `excludeArchived` 同时排除 archived 和 deprecated

package/src/monitoring/CONTEXT.md

@@ -1,13 +1,12 @@
 # monitoring/
 
 ## 职责
-运行时监控：Execution Trace(收集/分析/诊断)、Performance Trace(收集/分析)、约束进化提案、知识进化、上下文追踪。
+运行时监控：Execution Trace(收集/分析/诊断)、Performance Trace(收集/分析)、知识进化、上下文追踪。
 
 ## 核心导出
-- `TraceCollector` — 执行追踪收集(append-only JSONL)
+- `TraceCollector` — 执行追踪收集(append-only JSONL，`.harness/logs/traces.log`)
 - `TraceAnalyzer` — 追踪统计分析 + 异常检测
 - `ConstraintDoctor` — 约束诊断接口(Agent 消费)
-- `ConstraintEvolver` — 约束进化提案流程
 - `PerformanceCollector` — 性能日志收集
 - `PerformanceAnalyzer` — 性能统计分析
 - `ContextTracker` — 上下文追踪
@@ -25,5 +24,5 @@
 - 零 Token 成本：不调用 LLM
 
 ## 注意事项
-- 追踪数据用于约束退化分析(拦截率 < 阈值 → 自动降级)
+- 追踪数据供 `harness constraints report` 统计与退役候选诊断消费（观测用途，不做自动降级）
 - PerformanceCollector 和 TraceCollector 独立运作

package/src/monitoring/index.ts

@@ -5,7 +5,6 @@
  * - TraceCollector：轻量收集，零 Token
  * - TraceAnalyzer：统计汇总，异常检测
  * - ConstraintDoctor：Agent 诊断接口
- * - ConstraintEvolver：约束提案流程
  *
  * Performance Trace 系统：
  * - PerformanceCollector：性能日志收集，零 Token
@@ -15,7 +14,6 @@
 export * from './traces';
 export * from './trace-analyzer';
 export * from './constraint-doctor';
-export * from './constraint-evolver';
 export * from './performance-collector';
 export * from './performance-analyzer';
 export * from './context-tracker';

package/src/monitoring/knowledge-evolver.ts

@@ -1,7 +1,7 @@
 /**
  * 知识成熟度进化器
  *
- * 从 ConstraintEvolver 转型，聚焦知识成熟度进化：
+ * 聚焦知识成熟度进化：
  * - 基于引用数据提议成熟度变更
  * - 自动审核（安全规则）
  * - 执行变更

package/src/monitoring/trace-analyzer.ts

@@ -76,20 +76,22 @@ export class TraceAnalyzer {
       // 计算时间范围
       const timeRange = timeRangeOf(group.map(t => t.timestamp));
 
-      // 单次遍历计算核心统计
+      // 单次遍历计算核心统计（skip 单独计数，不计入 pass/fail/bypass 率分母，ADR-0001）
       const totalChecks = group.length;
-      let passCount = 0, failCount = 0, bypassCount = 0, ignoreCount = 0;
+      let passCount = 0, failCount = 0, bypassCount = 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++;
       }
 
-      // 计算比率
-      const passRate = totalChecks > 0 ? passCount / totalChecks : 0;
-      const failRate = totalChecks > 0 ? failCount / totalChecks : 0;
-      const bypassRate = totalChecks > 0 ? bypassCount / totalChecks : 0;
+      // 计算比率（分母 = 实际评估次数，skip 未评估不计入）
+      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);
@@ -108,6 +110,7 @@ export class TraceAnalyzer {
         passCount,
         failCount,
         bypassCount,
+        skipCount,
         ignoreCount,
         passRate,
         failRate,
@@ -298,12 +301,13 @@ export class TraceAnalyzer {
   }
 
   /**
-   * 计算通过率
+   * 计算通过率（skip 未评估，不计入分母）
    */
   private calcPassRate(traces: ExecutionTrace[]): number {
-    if (traces.length === 0) return 0;
-    const passCount = traces.filter(t => t.result === 'pass').length;
-    return passCount / traces.length;
+    const evaluated = traces.filter(t => t.result !== 'skip');
+    if (evaluated.length === 0) return 0;
+    const passCount = evaluated.filter(t => t.result === 'pass').length;
+    return passCount / evaluated.length;
   }
 
   /**
@@ -374,6 +378,7 @@ export class TraceAnalyzer {
       const levelEmoji = {
         iron_law: '🔴',
         guideline: '🟡',
+        prompt: '🟣',
         tip: '🔵',
       }[summary.level];
 

package/src/monitoring/traces.ts

@@ -11,17 +11,21 @@
 
 import * as fs from 'fs';
 import * as path from 'path';
-import type {
-  ExecutionTrace,
-  TraceFilter,
-  TraceCollectorConfig,
+import {
+  DEFAULT_TRACE_FILE,
+  type ExecutionTrace,
+  type TraceFilter,
+  type TraceCollectorConfig,
 } from '../types/trace';
 
+// 路径常量再导出，保持既有从 monitoring/traces 导入的用法不破
+export { DEFAULT_TRACE_FILE };
+
 /**
  * 默认配置
  */
 const DEFAULT_CONFIG: TraceCollectorConfig = {
-  traceFile: '.harness/logs/traces.log',
+  traceFile: DEFAULT_TRACE_FILE,
   maxFileSize: 10 * 1024 * 1024, // 10MB
   enabled: true,
 };
@@ -260,7 +264,7 @@ export class TraceCollector {
     }
 
     const files = fs.readdirSync(dir);
-    const backupFiles = files.filter(f => f.endsWith('.log') && f !== 'execution.log');
+    const backupFiles = files.filter(f => f.endsWith('.log') && f !== path.basename(this.traceFile));
 
     const cutoffTime = Date.now() - maxAgeDays * 24 * 3600 * 1000;
     let deletedCount = 0;

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

@@ -12,7 +12,7 @@ describe('getPreset', () => {
     expect(preset.name).toBe('strict');
     expect(preset.ironLaws).toBeNull();
     expect(preset.guidelines).toBeNull();
-    expect(preset.tips).toBeNull();
+    expect(preset.prompts).toBeNull();
   });
 
   it('returns standard preset', () => {
@@ -25,7 +25,7 @@ describe('getPreset', () => {
     expect(preset.name).toBe('relaxed');
     expect(preset.ironLaws).toHaveLength(3);
     expect(preset.guidelines).toHaveLength(2);
-    expect(preset.tips).toEqual([]);
+    expect(preset.prompts).toEqual([]);
   });
 
   it('defaults to standard for unknown preset name', () => {
@@ -47,8 +47,9 @@ describe('applyPreset with string preset names', () => {
   it('relaxed enables only specific constraints', () => {
     const config = applyPreset('relaxed');
     expect(config.ironLaws).toBeDefined();
-    expect(config.ironLaws.no_self_approval).toBeDefined();
+    expect(config.ironLaws.no_completion_without_verification).toBeDefined();
     expect(Object.keys(config.tips).length).toBe(0);
+    expect(Object.keys(config.prompts ?? {}).length).toBe(0);
     expect(config.disabled.length).toBeGreaterThan(0);
   });
 });
@@ -57,13 +58,13 @@ describe('applyPreset with PresetConfig object', () => {
   it('filters iron laws when ids are provided', () => {
     const config = applyPreset({
       name: 'custom',
-      ironLaws: ['no_self_approval', 'no_completion_without_verification'],
+      ironLaws: ['no_completion_without_verification', 'incremental_progress'],
       guidelines: null,
-      tips: null,
+      prompts: null,
     });
     expect(Object.keys(config.ironLaws)).toHaveLength(2);
-    expect(config.ironLaws.no_self_approval).toBeDefined();
-    expect(config.ironLaws.no_fix_without_root_cause).toBeUndefined();
+    expect(config.ironLaws.no_completion_without_verification).toBeDefined();
+    expect(config.ironLaws.no_implementation_without_requirement).toBeUndefined();
   });
 
   it('includes all guidelines when null', () => {
@@ -71,10 +72,11 @@ describe('applyPreset with PresetConfig object', () => {
       name: 'custom',
       ironLaws: null,
       guidelines: null,
-      tips: [],
+      prompts: [],
     });
     expect(Object.keys(config.guidelines).length).toBeGreaterThan(0);
     expect(Object.keys(config.tips).length).toBe(0);
+    expect(Object.keys(config.prompts ?? {}).length).toBe(0);
   });
 
   it('creates disabled list for omitted constraints', () => {
@@ -82,7 +84,7 @@ describe('applyPreset with PresetConfig object', () => {
       name: 'custom',
       ironLaws: [],
       guidelines: [],
-      tips: [],
+      prompts: [],
     });
     expect(config.disabled.length).toBeGreaterThan(0);
   });

package/src/presets/standard.ts

@@ -1,12 +1,14 @@
 /**
  * 约束预设
- * 
+ *
  * 预设定义哪些约束被启用
+ *
+ * ADR-0001：tips 维度退役，替换为 prompts（纯注入层）。
  */
 
 import type { Constraint } from '../types/constraint';
 import type { MergedConstraintsConfig } from '../types/project-config';
-import { IRON_LAWS, GUIDELINES, TIPS } from '../core/constraints/definitions';
+import { IRON_LAWS, GUIDELINES, PROMPTS } from '../core/constraints/definitions';
 
 /**
  * 预设配置
@@ -22,7 +24,7 @@ export interface PresetConfig {
   guidelines: string[] | null;
 
   /** 启用的提示 ID 列表（null 表示全部启用） */
-  tips: string[] | null;
+  prompts: string[] | null;
 }
 
 /**
@@ -68,57 +70,64 @@ export function applyPreset(
       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),
-    tips: filterByIds(TIPS, cfg.tips),
+    tips: {},
+    prompts: filterByIds(PROMPTS, cfg.prompts),
     disabled,
     custom: [],
+    unknownIds: [],
   };
 }
 
 /**
  * 严格预设
- * 
+ *
  * 所有约束全部启用
  */
 export const STRICT_PRESET: PresetConfig = {
   name: 'strict',
   ironLaws: null,    // 全部启用
   guidelines: null,  // 全部启用
-  tips: null,        // 全部启用
+  prompts: null,     // 全部启用
 };
 
 /**
  * 标准预设
- * 
+ *
  * 铁律全部启用，指导原则和提示选择性启用
  */
 export const STANDARD_PRESET: PresetConfig = {
   name: 'standard',
   ironLaws: null,    // 全部启用
   guidelines: null,  // 全部启用
-  tips: null,        // 全部启用
+  prompts: null,     // 全部启用
 };
 
 /**
  * 宽松预设
- * 
+ *
  * 仅启用核心铁律，禁用提示
  */
 export const RELAXED_PRESET: PresetConfig = {
   name: 'relaxed',
   ironLaws: [
-    'no_bypass_checkpoint',
-    'no_self_approval',
     'no_completion_without_verification',
+    'incremental_progress',
+    'no_implementation_without_requirement',
   ],
   guidelines: [
-    'no_fix_without_root_cause',
-    'no_code_without_test',
+    'no_bypass_checkpoint',
+    'no_hardcoded_credentials',
   ],
-  tips: [],  // 禁用提示
+  prompts: [],  // 禁用提示
 };
 
 /**
@@ -135,4 +144,4 @@ export function getPreset(name: string): PresetConfig {
     default:
       return STANDARD_PRESET;
   }
-}
+}

package/src/types/constraint.ts

@@ -1,10 +1,14 @@
 /**
  * 约束类型定义
- * 
- * 三层约束体系：
- * - Iron Laws：绝对禁止，无例外，违背即阻止执行
- * - Guidelines：优先建议，有例外，违背发警告但不阻止
- * - Tips：信息性提示，可忽略
+ *
+ * kind 二元模型（ADR-0001）：
+ * - check：必须带真实 checker，参与运行时检查与 trace 统计
+ *   - iron_law：绝对禁止，无例外，违背即阻止执行
+ *   - guideline：优先建议，有例外，违背发警告但不阻止
+ * - prompt：纯文本提示，仅参与 prompt 注入，不占检查位、不产生 trace
+ *
+ * 'tip' 层级已随 TIPS 退役（ADR-0001），仅保留在类型上以兼容
+ * ConstraintCheckResult.tips 等历史结果形态，不再有新定义使用。
  */
 
 /**
@@ -12,10 +16,18 @@
  */
 export type ConstraintId = string;
 
+/**
+ * 约束类别：check = 可执行检查；prompt = 纯文本注入
+ */
+export type ConstraintKind = 'check' | 'prompt';
+
 /**
  * 约束层级
+ *
+ * check 层只使用 'iron_law' | 'guideline'；prompt 类统一为 'prompt'。
+ * 'tip' 已退役，仅为历史结果结构兼容保留。
  */
-export type ConstraintLevel = 'iron_law' | 'guideline' | 'tip';
+export type ConstraintLevel = 'iron_law' | 'guideline' | 'prompt' | 'tip';
 
 /**
  * 约束触发条件（开放扩展）
@@ -31,7 +43,14 @@ export type ConstraintTrigger = string;
 export interface Constraint {
   /** 约束 ID */
   id: ConstraintId;
-  
+
+  /**
+   * 约束类别（ADR-0001）：
+   * - check：必须带真实 checker，参与运行时检查
+   * - prompt：纯文本提示，仅参与注入，不执行 checker
+   */
+  kind: ConstraintKind;
+
   /** 约束规则（英文） */
   rule: string;
   
@@ -61,6 +80,12 @@ export interface Constraint {
 
   /** 例外条件（仅 Guidelines 有效） */
   exceptions?: string[];
+
+  /**
+   * 适用场景标签（prompt 类专用，如 'agent-skill'、'llm-app'）。
+   * 未标注表示通用场景。消费端（init 注入 / studio 路由）可按标签过滤。
+   */
+  appliesTo?: string[];
 }
 
 /**
@@ -75,6 +100,15 @@ export interface ConstraintResult {
   
   /** 是否满足 */
   satisfied: boolean;
+
+  /**
+   * 是否跳过评估（ADR-0001 三态语义）
+   *
+   * skip = 约定未采用（存在性探测未命中）或证据 flag 未接线（undefined）。
+   * skip 时 satisfied 恒为 true（fail-open，不阻断、不计警告），
+   * 但不计入 pass/fail 统计；trace 记录为 result: 'skip'。
+   */
+  skipped?: boolean;
   
   /** 约束定义 */
   constraint?: Constraint;
@@ -95,6 +129,14 @@ export interface ConstraintResult {
 export interface ConstraintContext {
   /** 当前操作类型 */
   operation: ConstraintTrigger;
+
+  /**
+   * 附加触发条件（ADR-0001：detectTrigger 的次级推断）
+   *
+   * pre-commit 变更包含代码文件时，operation 保持主推断（如 module_modification），
+   * code_implementation 记录在此；匹配约束时 operation 与 extraTriggers 一并参与。
+   */
+  extraTriggers?: ConstraintTrigger[];
   
   /** 工作流 ID */
   workflowId?: string;
@@ -152,25 +194,25 @@ export interface ConstraintContext {
   /** 是否只处理单个任务（用于 incremental_progress） */
   hasSingleTask?: boolean;
   
-  /** 是否已验证外部能力（用于 verify_external_capability） */
+  /** 是否已验证外部能力（对应约束已降级为 prompt，字段保留兼容） */
   hasExternalCapabilityVerification?: boolean;
 
-  /** 是否已对比需求验证（用于 no_implementation_without_requirement_review） */
+  /** 是否已对比需求验证（review 变体已并入主约束，字段保留兼容） */
   hasRequirementReview?: boolean;
 
   /** 是否有需求文档（用于 no_implementation_without_requirement） */
   hasRequirement?: boolean;
 
-  /** 是否在 worktree 中执行（用于 prefer_worktree） */
+  /** 是否在 worktree 中执行（对应约束已移出内置，字段保留兼容） */
   hasWorktree?: boolean;
 
   /** worktree 路径（用于 worktree 相关检查） */
   worktreePath?: string;
 
-  /** 完成声明文本（用于 fuzzy/excuse 检查） */
+  /** 完成声明文本（对应检查已并入 prompt 层，字段保留兼容） */
   completionClaimText?: string;
 
-  /** 是否完成两阶段审查（用于 two_stage_review_required） */
+  /** 是否完成两阶段审查（对应约束已移出内置，字段保留兼容） */
   hasTwoStageReview?: boolean;
   
   // ========================================
@@ -194,7 +236,7 @@ export interface ConstraintContext {
   isSimpleAccessor?: boolean;
   isPureDisplayComponent?: boolean;
   
-  // no_any_type 例外
+  // any 类型相关例外（对应约束已退役，字段保留兼容）
   isJsonParseResult?: boolean;
   isThirdPartyNoTypes?: boolean;
   isLegacyMigration?: boolean;
@@ -238,7 +280,10 @@ export class ConstraintViolationError extends Error {
 }
 
 /**
- * 三层约束检查结果
+ * 约束检查结果（check 层）
+ *
+ * tips/tipCount 已随 TIPS 退役（ADR-0001），保留字段以兼容历史调用方，
+ * 内置约束下恒为空数组 / 0。
  */
 export interface ConstraintCheckResult {
   /** 铁律检查结果（必须全部通过） */

package/src/types/index.ts

@@ -15,12 +15,10 @@ export * from './trace';
 // Performance 类型（Performance Trace 系统）
 export * from './performance';
 
-// 诊断和提案类型（定义已归位 types/monitoring-types.ts，monitoring 改从 types 导入）
+// 诊断类型（定义已归位 types/monitoring-types.ts，monitoring 改从 types 导入）
 // 显式再导出（不用 export *）：根入口同时星导出 ./monitoring，星-星歧义会静默丢符号
 export type {
   Diagnosis,
-  ConstraintProposal,
-  ProposalReviewResult,
 } from './monitoring-types';
 
 // Session 类型（排除与 passes-gate 冲突的类型）

package/src/types/monitoring-types.ts

@@ -1,7 +1,7 @@
 /**
- * 监控域类型（诊断 / 提案）
+ * 监控域类型（诊断）
  *
- * 原定义位于 monitoring/constraint-doctor.ts 与 monitoring/constraint-evolver.ts，
+ * 原定义位于 monitoring/constraint-doctor.ts，
  * 但被 types/index.ts 反向再导出（类型层依赖业务模块，分层倒挂）。
  * 工单 14 将类型定义归位到 types 层，monitoring 改从 types 导入。
  */
@@ -66,85 +66,3 @@ export interface Diagnosis {
   /** 紧急程度 */
   urgency: 'low' | 'medium' | 'high';
 }
-
-/**
- * 约束提案
- */
-export interface ConstraintProposal {
-  /** 提案 ID */
-  id: string;
-
-  /** 提案时间 */
-  proposedAt: number;
-
-  /** 来源诊断 */
-  diagnosisId: string;
-
-  /** 约束 ID */
-  constraintId: string;
-
-  /** 提案类型 */
-  type: 'add_exception' | 'remove_exception' | 'adjust_trigger' | 'change_level' | 'modify_message' | 'new_constraint';
-
-  /** 提案内容 */
-  content: {
-    /** 当前值（如果有） */
-    current?: any;
-
-    /** 建议值 */
-    proposed: any;
-
-    /** 变更描述 */
-    description: string;
-  };
-
-  /** 理由 */
-  reasoning: string;
-
-  /** 预期效果 */
-  expectedOutcome: string;
-
-  /** 风险评估 */
-  risk: {
-    /** 风险等级 */
-    level: 'low' | 'medium' | 'high';
-
-    /** 风险描述 */
-    description: string;
-
-    /** 回滚方案 */
-    rollbackPlan?: string;
-  };
-
-  /** 实施信息 */
-  implementation: {
-    /** 改动文件 */
-    files: string[];
-
-    /** 改动量估计 */
-    linesChanged: number;
-
-    /** 测试要求 */
-    testsRequired: boolean;
-  };
-
-  /** 状态 */
-  status: 'proposed' | 'reviewing' | 'accepted' | 'rejected' | 'implemented';
-
-  /** 审核意见 */
-  reviewComment?: string;
-}
-
-/**
- * 提案审核结果
- */
-export interface ProposalReviewResult {
-  /** 是否接受 */
-  accepted: boolean;
-
-  /** 审核意见 */
-  comment: string;
-
-  /** 修改建议（如果拒绝） */
-  modifications?: Partial<ConstraintProposal>;
-}