@dommaker/harness 0.13.0 → 0.13.2

package/src/types/checkpoint.ts

@@ -0,0 +1,174 @@
+/**
+ * 检查点类型定义
+ */
+
+/**
+ * 检查类型
+ */
+export type CheckType =
+  | 'file_exists'
+  | 'file_not_empty'
+  | 'file_contains'
+  | 'file_not_contains'
+  | 'command_success'
+  | 'command_output'
+  | 'output_contains'
+  | 'output_not_contains'
+  | 'output_matches'
+  | 'json_path'
+  | 'http_status'
+  | 'http_body'
+  | 'custom';
+
+/**
+ * 检查配置
+ */
+export interface CheckConfig {
+  /** 文件路径（用于文件检查） */
+  path?: string;
+  
+  /** 预期值（用于 contains 检查） */
+  expected?: string | number | boolean | object;
+  
+  /** 内容（用于 file_contains 检查） */
+  content?: string;
+  
+  /** 正则表达式（用于 matches 检查） */
+  pattern?: string;
+  
+  /** JSON 路径（用于 json_path 检查） */
+  jsonPath?: string;
+  
+  /** HTTP URL（用于 http 检查） */
+  url?: string;
+  
+  /** HTTP 方法 */
+  method?: 'GET' | 'POST' | 'PUT' | 'DELETE';
+  
+  /** HTTP 请求体 */
+  body?: any;
+  
+  /** HTTP 请求头 */
+  headers?: Record<string, string>;
+  
+  /** 预期 HTTP 状态码 */
+  expectedStatus?: number;
+  
+  /** 命令（用于 command 检查） */
+  command?: string;
+  
+  /** 工作目录 */
+  workdir?: string;
+  
+  /** 环境变量 */
+  env?: Record<string, string>;
+  
+  /** 超时时间（毫秒） */
+  timeout?: number;
+  
+  /** 自定义检查函数名 */
+  customFunction?: string;
+}
+
+/**
+ * 检查项定义
+ */
+export interface CheckpointCheck {
+  /** 检查 ID */
+  id: string;
+  
+  /** 检查类型 */
+  type: CheckType;
+  
+  /** 检查配置 */
+  config: CheckConfig;
+  
+  /** 错误消息 */
+  message?: string;
+  
+  /** 是否必须通过 */
+  required?: boolean;
+}
+
+/**
+ * 检查点定义
+ */
+export interface Checkpoint {
+  /** 检查点 ID */
+  id: string;
+  
+  /** 检查点名称 */
+  name?: string;
+  
+  /** 描述 */
+  description?: string;
+  
+  /** 检查列表 */
+  checks: CheckpointCheck[];
+  
+  /** 是否必须全部通过 */
+  requireAll?: boolean;
+}
+
+/**
+ * 单项检查结果
+ */
+export interface CheckResult {
+  /** 检查 ID */
+  checkId: string;
+  
+  /** 是否通过 */
+  passed: boolean;
+  
+  /** 消息 */
+  message?: string;
+  
+  /** 错误详情 */
+  error?: string;
+  
+  /** 实际值 */
+  actual?: any;
+  
+  /** 预期值 */
+  expected?: any;
+}
+
+/**
+ * 检查点验证结果
+ */
+export interface CheckpointResult {
+  /** 检查点 ID */
+  checkpointId: string;
+  
+  /** 是否全部通过 */
+  passed: boolean;
+  
+  /** 各项检查结果 */
+  checks: CheckResult[];
+  
+  /** 消息 */
+  message?: string;
+  
+  /** 验证时间 */
+  validatedAt: Date;
+}
+
+/**
+ * 检查点验证上下文
+ */
+export interface CheckpointContext {
+  /** 项目路径 */
+  projectPath: string;
+  
+  /** 工作目录 */
+  workdir: string;
+  
+  /** 环境变量 */
+  env?: Record<string, string>;
+  
+  /** 步骤输出（用于 output_* 检查） */
+  output?: any;
+  
+  /** 自定义检查处理器 */
+  customHandlers?: Map<string, (config: CheckConfig) => Promise<CheckResult>>;
+}

package/src/types/constraint.ts

@@ -0,0 +1,335 @@
+/**
+ * 约束类型定义
+ * 
+ * 三层约束体系：
+ * - Iron Laws：绝对禁止，无例外，违背即阻止执行
+ * - Guidelines：优先建议，有例外，违背发警告但不阻止
+ * - Tips：信息性提示，可忽略
+ */
+
+/**
+ * 约束 ID
+ */
+export type ConstraintId = string;
+
+/**
+ * 约束层级
+ */
+export type ConstraintLevel = 'iron_law' | 'guideline' | 'tip';
+
+/**
+ * 约束触发条件
+ */
+/**
+ * 约束触发器（开放扩展）
+ *
+ * 从硬编码 union type 改为 string，consumer 可传入任意 trigger。
+ * 无需修改 harness 即可添加领域特定 trigger。
+ *
+ * 以下为推荐的抽象 trigger 常量。领域概念（如 deploy、
+ * config_update 等）由 consumer 自行管理。
+ */
+
+export const CODE_IMPLEMENTATION = 'code_implementation' as const;
+export const FILE_MODIFICATION = 'file_modification' as const;
+export const FILE_CREATION = 'file_creation' as const;
+export const FILE_DELETION = 'file_deletion' as const;
+export const MODULE_CREATION = 'module_creation' as const;
+export const MODULE_MODIFICATION = 'module_modification' as const;
+export const MODULE_DELETION = 'module_deletion' as const;
+export const MODULE_EXTENSION = 'module_extension' as const;
+export const API_CHANGE = 'api_change' as const;
+export const EXPORT_CHANGE = 'export_change' as const;
+export const TEST_CREATION = 'test_creation' as const;
+export const COMMIT = 'commit' as const;
+export const PUSH = 'push' as const;
+export const MERGE = 'merge' as const;
+export const DESIGN_REQUEST = 'design_request' as const;
+export const ARCHITECTURE_CHANGE = 'architecture_change' as const;
+
+export type ConstraintTrigger = string;
+
+/**
+ * 约束定义
+ */
+export interface Constraint {
+  /** 约束 ID */
+  id: ConstraintId;
+  
+  /** 约束规则（英文） */
+  rule: string;
+  
+  /** 约束消息（中文） */
+  message: string;
+  
+  /** 约束层级 */
+  level: ConstraintLevel;
+  
+  /** 触发条件（支持多个 trigger） */
+  trigger: ConstraintTrigger | ConstraintTrigger[];
+  
+  /** 强制执行的技能/步骤 */
+  enforcement: string;
+  
+  /** 约束描述 */
+  description?: string;
+
+  /** 软约束 prompt 注入（引导 Agent 行为的提示文本） */
+  promptInjection?: string;
+
+  /** 是否注入 Agent prompt（默认 iron_law=true, guideline=false） */
+  injectPrompt?: boolean;
+
+  /** 是否启用 */
+  enabled?: boolean;
+
+  /** 例外条件（仅 Guidelines 有效） */
+  exceptions?: string[];
+}
+
+// ========================================
+// 向后兼容的类型别名
+// ========================================
+
+/**
+ * @deprecated 使用 ConstraintId 代替
+ */
+export type IronLawId = ConstraintId;
+
+/**
+ * @deprecated 使用 ConstraintLevel 代替
+ */
+export type IronLawSeverity = 'error' | 'warning' | 'info';
+
+/**
+ * @deprecated 使用 ConstraintTrigger 代替
+ */
+export type IronLawTrigger = ConstraintTrigger;
+
+/**
+ * @deprecated 使用 Constraint 代替
+ */
+export interface IronLaw extends Constraint {
+  /** @deprecated 使用 level 代替 */
+  severity?: IronLawSeverity;
+}
+
+/**
+ * 约束检查结果
+ */
+export interface ConstraintResult {
+  /** 约束 ID */
+  id: ConstraintId;
+  
+  /** 约束层级 */
+  level: ConstraintLevel;
+  
+  /** 是否满足 */
+  satisfied: boolean;
+  
+  /** 约束定义 */
+  constraint?: Constraint;
+  
+  /** 消息 */
+  message?: string;
+  
+  /** 建议操作 */
+  requiredAction?: string;
+  
+  /** 检查时间 */
+  checkedAt: Date;
+}
+
+/**
+ * @deprecated 使用 ConstraintResult 代替
+ */
+export interface IronLawResult extends ConstraintResult {
+  /** @deprecated */
+  law?: Constraint;
+}
+
+/**
+ * 约束检查上下文
+ */
+export interface ConstraintContext {
+  /** 当前操作类型 */
+  operation: ConstraintTrigger;
+  
+  /** 工作流 ID */
+  workflowId?: string;
+  
+  /** 步骤 ID */
+  stepId?: string;
+  
+  /** 任务描述 */
+  taskDescription?: string;
+  
+  /** 项目路径 */
+  projectPath?: string;
+  
+  /** 会话 ID（用于追踪同一会话的多次检查） */
+  sessionId?: string;
+  
+  /** 变更的文件列表 */
+  changedFiles?: string[];
+  
+  /** 提交信息 */
+  commitMessage?: string;
+  
+  /** 分支名称 */
+  branch?: string;
+  
+  // ========================================
+  // 前置条件检查
+  // ========================================
+  
+  /** 是否有根本原因调查 */
+  hasRootCauseInvestigation?: boolean;
+
+  /** 是否已通过诊断→修复闸门（设计方案已确认） */
+  hasPlanApproval?: boolean;
+
+  /** 是否有验证证据 */
+  hasVerificationEvidence?: boolean;
+  
+  /** 是否有测试 */
+  hasTest?: boolean;
+  
+  /** 是否有失败的测试 */
+  hasFailingTest?: boolean;
+  
+  /** 是否已进行复用检查 */
+  hasReuseCheck?: boolean;
+  
+  /** 复用检查结果 */
+  reuseCheckResult?: {
+    existingCapabilities: string[];
+    canReuse: boolean;
+    reuseRecommendation: string;
+  };
+  
+  /** 是否只处理单个任务（用于 incremental_progress） */
+  hasSingleTask?: boolean;
+  
+  /** 是否已验证外部能力（用于 verify_external_capability） */
+  hasExternalCapabilityVerification?: boolean;
+
+  /** 是否已对比需求验证（用于 no_implementation_without_requirement_review） */
+  hasRequirementReview?: boolean;
+
+  /** 是否有需求文档（用于 no_implementation_without_requirement） */
+  hasRequirement?: boolean;
+
+  /** 是否在 worktree 中执行（用于 must_use_worktree） */
+  hasWorktree?: boolean;
+
+  /** worktree 路径（用于 worktree 相关检查） */
+  worktreePath?: string;
+
+  /** 完成声明文本（用于 fuzzy/excuse 检查） */
+  completionClaimText?: string;
+
+  /** 是否完成两阶段审查（用于 two_stage_review_required） */
+  hasTwoStageReview?: boolean;
+  
+  // ========================================
+  // 例外条件（用于 Guidelines）
+  // ========================================
+  
+  // simplest_solution_first 例外
+  scalabilityRequired?: boolean;
+  securityRequired?: boolean;
+  performanceRequired?: boolean;
+  reliabilityRequired?: boolean;
+  
+  // no_fix_without_root_cause 例外
+  isSimpleTypo?: boolean;
+  isConfigValueError?: boolean;
+  isMissingConfig?: boolean;
+  
+  // no_code_without_test 例外
+  isConfigFile?: boolean;
+  isTypeDefinition?: boolean;
+  isSimpleAccessor?: boolean;
+  isPureDisplayComponent?: boolean;
+  
+  // no_any_type 例外
+  isJsonParseResult?: boolean;
+  isThirdPartyNoTypes?: boolean;
+  isLegacyMigration?: boolean;
+  
+  // capability_sync 例外
+  isInternalRefactor?: boolean;
+  isBugFixOnly?: boolean;
+  isPerformanceOptimization?: boolean;
+  
+  // no_simplification_without_approval 例外
+  isRedundantCodeCleanup?: boolean;
+  isSameEffectRefactor?: boolean;
+  isUnusedCodeRemoval?: boolean;
+
+  // 设计决策例外
+  isExplicitInstruction?: boolean;
+  isEmergencyFix?: boolean;
+  isExistingDesign?: boolean;
+
+  // 外部依赖相关
+  isExternalDependency?: boolean;
+  
+  /** 例外理由说明 */
+  exceptionReason?: string;
+  
+  /** 执行上下文 */
+  executionContext?: any;
+}
+
+/**
+ * @deprecated 使用 ConstraintContext 代替
+ */
+export type IronLawContext = ConstraintContext;
+
+/**
+ * 约束违规错误
+ */
+export class ConstraintViolationError extends Error {
+  public readonly result: ConstraintResult;
+
+  constructor(result: ConstraintResult) {
+    super(result.message || 'Constraint violation');
+    this.name = 'ConstraintViolationError';
+    this.result = result;
+  }
+}
+
+/**
+ * @deprecated 使用 ConstraintViolationError 代替
+ */
+export class IronLawViolationError extends ConstraintViolationError {
+  constructor(result: ConstraintResult) {
+    super(result);
+    this.name = 'IronLawViolationError';
+  }
+}
+
+/**
+ * 三层约束检查结果
+ */
+export interface ConstraintCheckResult {
+  /** 铁律检查结果（必须全部通过） */
+  ironLaws: ConstraintResult[];
+  
+  /** 指导原则检查结果（警告，不阻止） */
+  guidelines: ConstraintResult[];
+  
+  /** 提示检查结果（仅提示） */
+  tips: ConstraintResult[];
+  
+  /** 是否通过（铁律全部通过） */
+  passed: boolean;
+  
+  /** 警告数量 */
+  warningCount: number;
+  
+  /** 提示数量 */
+  tipCount: number;
+}

package/src/types/cso.ts

@@ -0,0 +1,37 @@
+/**
+ * CSO (Concise Skill Optimization) 类型定义
+ */
+
+/**
+ * Workflow 元数据
+ */
+export interface WorkflowMeta {
+  /** 工作流名称 */
+  name: string;
+  /** 工作流描述 */
+  description: string;
+  /** 工作流步骤 */
+  steps?: StepMeta[];
+}
+
+/**
+ * Step 元数据
+ */
+export interface StepMeta {
+  /** 步骤名称 */
+  name: string;
+  /** 步骤描述 */
+  description: string;
+  /** 步骤工具 */
+  tools?: ToolMeta[];
+}
+
+/**
+ * Tool 元数据
+ */
+export interface ToolMeta {
+  /** 工具名称 */
+  name: string;
+  /** 工具描述 */
+  description: string;
+}

package/src/types/enforcement.ts

@@ -0,0 +1,48 @@
+/**
+ * Enforcement 执行器类型定义
+ */
+
+import type { Constraint, ConstraintContext } from './constraint';
+
+export type EnforcementId = string;
+
+export interface EnforcementContext extends ConstraintContext {
+  enforcementId: EnforcementId;
+  constraint: Constraint;
+  params?: Record<string, any>;
+}
+
+export interface EnforcementResult {
+  passed: boolean;
+  evidence?: string;
+  message?: string;
+  error?: string;
+  duration?: number;
+  validatedAt?: Date;
+}
+
+export interface EnforcementExecutor {
+  execute(context: EnforcementContext): Promise<EnforcementResult>;
+  description?: string;
+  supportedParams?: string[];
+}
+
+export interface EnforcementRegistration {
+  id: EnforcementId;
+  executor: EnforcementExecutor;
+  registeredAt: Date;
+  source?: string;
+}
+
+export interface InterceptionResult {
+  passed: boolean;
+  constraints: {
+    constraint: Constraint;
+    enforcementResult?: EnforcementResult;
+    skipped?: boolean;
+    skipReason?: string;
+  }[];
+  violations: Constraint[];
+  message?: string;
+  interceptedAt: Date;
+}

package/src/types/index.ts

@@ -0,0 +1,59 @@
+/**
+ * 类型导出
+ */
+
+// 约束类型（三层体系）
+export * from './constraint';
+
+export * from './checkpoint';
+export * from './passes-gate';
+export * from './cso';
+
+// Trace 类型（Execution Trace 系统）
+export * from './trace';
+
+// Performance 类型（Performance Trace 系统）
+export * from './performance';
+
+// 诊断和提案类型（从 monitoring 导入）
+export type { Diagnosis } from '../monitoring/constraint-doctor';
+export type {
+  ConstraintProposal,
+  ProposalReviewResult,
+} from '../monitoring/constraint-evolver';
+
+// Session 类型（排除与 passes-gate 冲突的类型）
+export {
+  StartupCheckpoints,
+  StartupCheckpointType,
+  StartupCheckpointResult,
+  CleanStateConfig,
+  CleanStateResult,
+  DetectedBug,
+  TaskListJson,
+  TaskStepStatus,
+  SessionInfo,
+} from './session';
+
+// 从 session 导入 DynamicTask，扩展 passes-gate 的定义
+export { DynamicTask as ExtendedDynamicTask, TaskTestResult as ExtendedTaskTestResult } from './session';
+
+// 项目配置类型
+export * from './project-config';
+
+// Enforcement 类型
+export * from './enforcement';
+
+// Spec 验证类型
+export * from './spec';
+
+// Failure 类型（从 failure 模块导入）
+export {
+  ErrorType,
+  FailureLevel,
+  ErrorClassificationRule,
+  FailureRecord,
+  ClassificationResult,
+  DEFAULT_CLASSIFICATION_RULES,
+  DEFAULT_LEVEL_MAPPING,
+} from '../failure/types';

package/src/types/iron-law.ts

@@ -0,0 +1,50 @@
+/**
+ * 铁律类型定义
+ * 
+ * @deprecated 请使用 './constraint' 代替
+ * 
+ * 此模块保留用于向后兼容。
+ * 新代码应使用三层约束类型：
+ * - Constraint
+ * - ConstraintLevel ('iron_law' | 'guideline' | 'tip')
+ */
+
+import type {
+  ConstraintId,
+  ConstraintLevel,
+  ConstraintTrigger,
+  Constraint,
+  ConstraintResult,
+  ConstraintContext,
+} from './constraint';
+
+import { ConstraintViolationError } from './constraint';
+
+// 重新导出新的约束类型
+export type {
+  ConstraintId as IronLawId,
+  ConstraintLevel,
+  ConstraintTrigger as IronLawTrigger,
+  Constraint as IronLaw,
+  ConstraintResult as IronLawResult,
+  ConstraintContext as IronLawContext,
+} from './constraint';
+
+export {
+  ConstraintViolationError as IronLawViolationError,
+} from './constraint';
+
+// 向后兼容的 severity 类型
+export type IronLawSeverity = 'error' | 'warning' | 'info';
+
+// 向后兼容的配置类型
+export interface IronLawConfig {
+  /** @deprecated */
+  ironLaws: Constraint[];
+  /** @deprecated */
+  preset?: 'strict' | 'standard' | 'relaxed';
+  /** @deprecated */
+  enabled?: boolean;
+  /** @deprecated */
+  configPath?: string;
+}