@dommaker/harness 1.0.0 → 1.1.1

package/src/index.ts

@@ -66,6 +66,13 @@ export * from './safety';
 // ========================================
 export * from './verification';
 
+// ========================================
+// Completion Checkers 导出（T7-E1，studio#160）
+// WU 收尾软观测三纯判定函数：tdd-chain / phase-format / contract-presence。
+// 纯函数直接 export，不进 ConstraintCheck 闭环注册表。
+// ========================================
+export * from './completion-checkers';
+
 // ========================================
 // Dashboard 数据导出
 // ========================================
@@ -106,6 +113,7 @@ export type { RenderConstraintsByTriggerOptions } from './core/constraints/agent
 import { constraintChecker } from './core/constraints/checker';
 import { getTraceCollector } from './monitoring/traces';
 import type { ConstraintContext, ConstraintCheckResult, ConstraintTrigger } from './types/constraint';
+import type { MergedConstraintsConfig } from './types/project-config';
 import { constraintInterceptor } from './core/constraints/interceptor';
 import type { EnforcementExecutor, EnforcementId, InterceptionResult } from './types/enforcement';
 
@@ -119,13 +127,15 @@ export const interceptor = constraintInterceptor;
  * 拦截操作 — 在操作执行前检查约束
  * @param trigger - 触发条件
  * @param context - 约束上下文
+ * @param customConfig - 可选，per-request 自定义约束配置；不传则用内置约束集
  * @returns 拦截结果（是否通过、违规列表）
  */
 export async function interceptOperation(
   trigger: ConstraintTrigger,
-  context: ConstraintContext
+  context: ConstraintContext,
+  customConfig?: MergedConstraintsConfig | null
 ): Promise<InterceptionResult> {
-  return constraintInterceptor.intercept(trigger, context);
+  return constraintInterceptor.intercept(trigger, context, customConfig);
 }
 
 /**
@@ -159,12 +169,16 @@ export function registerExecutor(
  *
  * @param context - 约束上下文
  * @param options.onTrace - 每条约束检查后的回调（用于记录 trace 到外部存储）
+ * @param options.customConfig - 可选，per-request 自定义约束配置；不传则用内置约束集
  */
 export async function checkConstraints(
   context: ConstraintContext,
-  options?: { onTrace?: (result: import('./types/constraint').ConstraintResult) => void }
+  options?: {
+    onTrace?: (result: import('./types/constraint').ConstraintResult) => void;
+    customConfig?: MergedConstraintsConfig | null;
+  }
 ): Promise<ConstraintCheckResult> {
-  const result = await constraintChecker.checkConstraints(context);
+  const result = await constraintChecker.checkConstraints(context, options?.customConfig ?? null);
   if (options?.onTrace) {
     for (const r of result.ironLaws) options.onTrace(r);
     for (const r of result.guidelines) options.onTrace(r);
@@ -174,9 +188,13 @@ export async function checkConstraints(
 
 /**
  * 执行前检查（仅 Iron Laws）
+ *
+ * @param context - 约束上下文
+ * @param customConfig - 可选，per-request 自定义约束配置；不传则用内置约束集
  */
 export async function checkBeforeExecution(
-  context: ConstraintContext
+  context: ConstraintContext,
+  customConfig?: MergedConstraintsConfig | null
 ): Promise<void> {
-  return constraintChecker.beforeExecution(context);
+  return constraintChecker.beforeExecution(context, customConfig);
 }

package/src/monitoring/constraint-doctor.ts

@@ -19,17 +19,8 @@ export type { Diagnosis };
  * 诊断配置
  */
 export interface ConstraintDoctorConfig {
-  /** 是否启用 Agent 诊断（默认 false，需要显式启用） */
-  enabled?: boolean;
-
-  /** Agent 类型（预留，后续对接） */
-  agentType?: 'claude-code' | 'codex' | 'openai';
-
-  /** 最大 traces 数量（用于构造 prompt） */
-  maxTracesInPrompt?: number;
-
-  /** 是否自动生成提案 */
-  autoGenerateProposal?: boolean;
+  /** 最大 traces 数量（用于构造诊断证据） */
+  maxTraces?: number;
 }
 
 /**
@@ -51,9 +42,7 @@ export class ConstraintDoctor {
 
   constructor(config?: ConstraintDoctorConfig) {
     this.config = {
-      enabled: false,
-      maxTracesInPrompt: 20,
-      autoGenerateProposal: false,
+      maxTraces: 20,
       ...config,
     };
     this.traces = [];
@@ -95,7 +84,7 @@ export class ConstraintDoctor {
       rootCause: {
         primary: '',
         secondary: [],
-        evidence: traces.slice(0, this.config.maxTracesInPrompt!),
+        evidence: traces.slice(0, this.config.maxTraces!),
       },
       impact: {
         severity: 'medium',

package/src/monitoring/traces.ts

@@ -88,7 +88,7 @@ export class TraceCollector {
    */
   recordPass(
     constraintId: string,
-    level: 'iron_law' | 'guideline' | 'tip',
+    level: 'iron_law' | 'guideline',
     options?: Partial<ExecutionTrace>
   ): void {
     this.record({
@@ -105,7 +105,7 @@ export class TraceCollector {
    */
   recordFail(
     constraintId: string,
-    level: 'iron_law' | 'guideline' | 'tip',
+    level: 'iron_law' | 'guideline',
     options?: Partial<ExecutionTrace>
   ): void {
     this.record({
@@ -122,7 +122,7 @@ export class TraceCollector {
    */
   recordBypass(
     constraintId: string,
-    level: 'iron_law' | 'guideline' | 'tip',
+    level: 'iron_law' | 'guideline',
     bypassReason?: string,
     options?: Partial<ExecutionTrace>
   ): void {

package/src/pretool-use-hook.ts

@@ -0,0 +1,68 @@
+/**
+ * PreToolUse 执法脚本 — command-gate hook 固化版（studio#153）
+ *
+ * 内容 = studio-agent provider-hooks.buildHookScriptContent 生成脚本（#147）的固化版，
+ * 归属归位：谁的东西谁发货——CommandGate 是 harness 的，hook 脚本随 harness 包出厂。
+ * 编译产物 = 包内 dist/pretool-use-hook.js，provider hook 配置（codex hooks.json /
+ * kimi config.toml）直接指向 require.resolve('@dommaker/harness') 同目录的该文件，
+ * 不再由 studio-agent 按 worktree 生成、不再内嵌绝对路径。
+ *
+ * 语义（与生成版一致）：
+ * - stdin 收 provider PreToolUse JSON（tool_input.command）；
+ * - CommandGate.isAllowed 判定 block 级黑名单，命中 → stderr 写原因 + exit 2
+ *   （codex/kimi 阻断语义：exit 2 + stderr 阻断，其余 exit code fail-open）；
+ * - fail-open：stdin 非 JSON / 缺字段 / CommandGate 异常一律放行——宁可漏拦
+ *   也不全体 Bash 秒断，拦截层只是纵深防御的一道；
+ * - warn/audit 级命中同样放行（isAllowed 只看 block 级），与生成版行为一致。
+ */
+import { CommandGate } from './gates/command';
+
+/** hook 标识：与 studio-agent 生成版同一 marker（配置幂等检测共用口径） */
+export const HOOK_MARKER = 'harness-command-gate';
+
+interface PreToolUseInput {
+  tool_input?: { command?: string };
+}
+
+/**
+ * 判定一次 PreToolUse 是否放行。
+ * block 级命中 → allowed=false；warn/audit/干净命令/坏输入一律 allowed=true。
+ */
+export function decidePreToolUse(rawStdin: string): { allowed: boolean; command: string } {
+  let input: PreToolUseInput = {};
+  try {
+    input = JSON.parse(rawStdin || '{}') as PreToolUseInput;
+  } catch {
+    // 非 JSON stdin：放行
+  }
+  const command = (input.tool_input && input.tool_input.command) || '';
+  try {
+    const gate = new CommandGate();
+    return { allowed: gate.isAllowed(command), command };
+  } catch {
+    // CommandGate 加载/判定异常：fail-open
+    return { allowed: true, command };
+  }
+}
+
+/**
+ * 执行一次 hook：返回进程 exit code（2 = 阻断，0 = 放行）。
+ * 阻断时原因写 stderr（provider 把 stderr 作为阻断原因回填模型）。
+ */
+export function runPreToolUseHook(rawStdin: string): number {
+  const { allowed, command } = decidePreToolUse(rawStdin);
+  if (!allowed) {
+    console.error(`[${HOOK_MARKER}] blocked: ${command}`);
+    return 2;
+  }
+  return 0;
+}
+
+/* istanbul ignore next -- 进程入口仅做 stdin 收集 + exit，逻辑由 runPreToolUseHook 单测覆盖 */
+if (require.main === module) {
+  let raw = '';
+  process.stdin.on('data', (c) => { raw += c; });
+  process.stdin.on('end', () => {
+    process.exit(runPreToolUseHook(raw));
+  });
+}

package/src/types/trace.ts

@@ -29,7 +29,7 @@ export interface ExecutionTrace {
   constraintId: string;
 
   /** 约束层级 */
-  level: 'iron_law' | 'guideline' | 'prompt' | 'tip';
+  level: 'iron_law' | 'guideline' | 'prompt';
 
   /** 检查时间（Unix timestamp） */
   timestamp: number;
@@ -77,7 +77,7 @@ export interface TraceSummary {
   constraintId: string;
 
   /** 约束层级 */
-  level: 'iron_law' | 'guideline' | 'prompt' | 'tip';
+  level: 'iron_law' | 'guideline' | 'prompt';
 
   /** 统计时间范围 */
   timeRange: {
@@ -161,7 +161,7 @@ export interface TraceAnomaly {
   constraintId: string;
 
   /** 约束层级 */
-  level: 'iron_law' | 'guideline' | 'prompt' | 'tip';
+  level: 'iron_law' | 'guideline' | 'prompt';
 
   /** 异常描述 */
   message: string;
@@ -188,7 +188,7 @@ export interface TraceFilter {
   constraintId?: string;
 
   /** 约束层级（可选） */
-  level?: 'iron_law' | 'guideline' | 'prompt' | 'tip';
+  level?: 'iron_law' | 'guideline' | 'prompt';
 
   /** 结果类型（可选） */
   result?: 'pass' | 'fail' | 'bypassed' | 'skip';