@dommaker/harness 1.9.0 → 1.11.0

package/src/__tests__/project-config-loader-extra.test.ts

@@ -1,9 +1,12 @@
 /**
  * ProjectConfigLoader 补充测试
+ *
+ * ADR-0029：custom 纯文本约束面（custom_constraints / getCustomConstraints /
+ * isConstraintRetired 的 custom 落点）已随文本注入层关停一并退役，相关用例移除。
  */
 
 import { describe, it, expect, beforeAll, afterAll, jest } from '@jest/globals';
-import { ProjectConfigLoader, isConstraintRetired } from '../core/project-config-loader';
+import { ProjectConfigLoader } from '../core/project-config-loader';
 import * as fs from 'fs';
 import * as path from 'path';
 import * as os from 'os';
@@ -27,7 +30,7 @@ describe('ProjectConfigLoader - 补充覆盖', () => {
   });
 
   describe('禁用约束', () => {
-    it('应该禁用指定约束', () => {
+    it('未知 id 的禁用配置静默忽略（生效集不变）', () => {
       fs.writeFileSync(
         path.join(harnessDir, 'config.yml'),
         `
@@ -43,69 +46,18 @@ constraints:
       loader.load();
       const merged = loader.mergeConstraints();
 
-      expect(merged.disabled).toContain('legacy_disabled_a');
-      expect(merged.disabled).toContain('legacy_disabled_b');
+      // 未知 id 进 unknownIds 供诊断（filterEnabledEntries 历史口径：未知但 enabled:false 的 id 同时也进 disabled）
+      expect(merged.unknownIds).toContain('legacy_disabled_a');
+      expect(merged.unknownIds).toContain('legacy_disabled_b');
     });
-  });
-
-  describe('自定义约束层级', () => {
-    it('应该正确分类 iron_law 级别约束', () => {
-      fs.writeFileSync(
-        path.join(harnessDir, 'config.yml'),
-        `
-custom_constraints:
-  my_iron_law:
-    rule: MY IRON LAW
-    message: Iron law message
-    level: iron_law
-    trigger: commit
-`
-      );
-
-      const loader = new ProjectConfigLoader(tempDir);
-      loader.load();
-      const merged = loader.mergeConstraints();
-
-      expect(merged.ironLaws['my_iron_law']).toBeDefined();
-    });
-
-    it('默认应该分类为 guideline', () => {
-      fs.writeFileSync(
-        path.join(harnessDir, 'config.yml'),
-        `
-custom_constraints:
-  my_guideline:
-    rule: MY GUIDELINE
-    message: Guideline message
-    trigger: commit
-`
-      );
-
-      const loader = new ProjectConfigLoader(tempDir);
-      loader.load();
-      const merged = loader.mergeConstraints();
-
-      expect(merged.guidelines['my_guideline']).toBeDefined();
-    });
-  });
 
-  describe('自定义约束 promptInjection', () => {
-    it('应该透传 promptInjection 并进入注入段渲染', async () => {
+    it('内置 id 的禁用配置从生效集移除并进 disabled', () => {
       fs.writeFileSync(
         path.join(harnessDir, 'config.yml'),
         `
-custom_constraints:
-  my_prompt_rule:
-    rule: MY PROMPT RULE
-    message: Prompt rule message
-    level: guideline
-    trigger: commit
-    promptInjection: 我的自定义注入文本
-  my_silent_rule:
-    rule: MY SILENT RULE
-    message: No injection text
-    level: guideline
-    trigger: commit
+constraints:
+  capability_sync:
+    enabled: false
 `
       );
 
@@ -113,16 +65,8 @@ custom_constraints:
       loader.load();
       const merged = loader.mergeConstraints();
 
-      // 字段透传
-      expect(merged.guidelines['my_prompt_rule']?.promptInjection).toBe('我的自定义注入文本');
-      // 未定义 promptInjection 的自定义约束保持不注入（与内置无注入文本条目一致）
-      expect(merged.guidelines['my_silent_rule']?.promptInjection).toBeUndefined();
-
-      // 端到端：进入 CLAUDE.md 注入段渲染
-      const { renderConstraintsSection } = await import('../core/constraints/injection-renderer');
-      const section = renderConstraintsSection(Object.values(merged.guidelines), '0.0.0-test');
-      expect(section).toContain('- **my_prompt_rule**: 我的自定义注入文本');
-      expect(section).not.toContain('my_silent_rule');
+      expect(merged.disabled).toContain('capability_sync');
+      expect(merged.constraints['capability_sync']).toBeUndefined();
     });
   });
 
@@ -130,7 +74,7 @@ custom_constraints:
     /**
      * `isConstraintEnabled` / `getConstraintSource` 属 ADR-0022 型漏收：
      * 除本文件与自身测试外双仓零消费者，生效集判定唯一来源是
-     * `mergeConstraints` → `getEffectiveConstraints`（ADR-0001），这两个查询函数是它的平行复印。
+     * `mergeConstraints` → `getEffectiveConstraints`，这两个查询函数是它的平行复印。
      */
     it('isConstraintEnabled / getConstraintSource 已从类面删除', () => {
       const loader = new ProjectConfigLoader(tempDir);
@@ -145,26 +89,6 @@ custom_constraints:
     });
   });
 
-  describe('isConstraintRetired（退役判定单点，harness#137）', () => {
-    it('config.yml enabled:false 即已退役，与 custom 条目无关', () => {
-      expect(isConstraintRetired(undefined, true)).toBe(true);
-    });
-
-    it('custom 条目带 retired 元数据即已退役（studio#82 D6 落点在条目自身）', () => {
-      expect(isConstraintRetired({ retired: { at: '2026-08-08T12:00:00.000Z' } }, false)).toBe(true);
-    });
-
-    it('两个落点都没命中 → 未退役', () => {
-      expect(isConstraintRetired(undefined, false)).toBe(false);
-      expect(isConstraintRetired({ retired: undefined }, false)).toBe(false);
-    });
-
-    it('retired 段的假值（null / 空串）不算退役——mergeConstraints 用的是 truthiness', () => {
-      expect(isConstraintRetired({ retired: null }, false)).toBe(false);
-      expect(isConstraintRetired({ retired: '' }, false)).toBe(false);
-    });
-  });
-
   describe('hasCustomConfig', () => {
     it('无自定义配置应该返回 false', () => {
       // 清空配置
@@ -179,15 +103,13 @@ custom_constraints:
       expect(loader.hasCustomConfig()).toBe(false);
     });
 
-    it('有自定义约束应该返回 true', () => {
+    it('有 constraints 段应该返回 true', () => {
       fs.writeFileSync(
         path.join(harnessDir, 'config.yml'),
         `
-custom_constraints:
-  custom_for_has:
-    rule: CUSTOM
-    message: Custom
-    trigger: commit
+constraints:
+  capability_sync:
+    enabled: false
 `
       );
 
@@ -220,10 +142,8 @@ custom_constraints:
       loader.load();
       const merged = loader.mergeConstraints({ preset: 'relaxed' });
 
-      // relaxed 仅启用 3 条铁律 + 2 条指导原则，禁用提示
-      expect(Object.keys(merged.ironLaws)).toHaveLength(3);
-      expect(Object.keys(merged.guidelines)).toHaveLength(2);
-      expect(Object.keys(merged.prompts ?? {})).toHaveLength(0);
+      // relaxed 仅启用 1 条 error 级 + 1 条 warning 级
+      expect(Object.keys(merged.constraints)).toHaveLength(2);
       expect(merged.disabled.length).toBeGreaterThan(0);
     });
 
@@ -249,25 +169,4 @@ custom_constraints:
       }
     });
   });
-
-  describe('getCustomConstraints', () => {
-    it('应该返回自定义约束', () => {
-      fs.writeFileSync(
-        path.join(harnessDir, 'config.yml'),
-        `
-custom_constraints:
-  get_custom_test:
-    rule: TEST
-    message: Test
-    trigger: commit
-`
-      );
-
-      const loader = new ProjectConfigLoader(tempDir);
-      loader.load();
-
-      const customs = loader.getCustomConstraints();
-      expect(customs['get_custom_test']).toBeDefined();
-    });
-  });
-});
+});

package/src/__tests__/project-config-loader.test.ts

@@ -32,23 +32,18 @@ describe('ProjectConfigLoader', () => {
       const config = loader.load();
 
       expect(config.preset).toBe('standard');
-      expect(config.custom_constraints_file).toBeDefined();
     });
 
     it('应该加载 config.yml', () => {
       fs.writeFileSync(
         path.join(harnessDir, 'config.yml'),
-        `
-preset: custom
-custom_constraints_file: my-constraints.yml
-`
+        `preset: custom`
       );
 
       const loader = new ProjectConfigLoader(tempDir);
       const config = loader.load();
 
       expect(config.preset).toBe('custom');
-      expect(config.custom_constraints_file).toBe('my-constraints.yml');
     });
   });
 
@@ -59,29 +54,8 @@ custom_constraints_file: my-constraints.yml
 
       const merged = loader.mergeConstraints();
 
-      expect(merged.ironLaws).toBeDefined();
-      expect(merged.guidelines).toBeDefined();
-      expect(Object.keys(merged.ironLaws).length).toBeGreaterThan(0);
-    });
-
-    it('应该加载自定义约束', () => {
-      fs.writeFileSync(
-        path.join(harnessDir, 'custom-constraints.yml'),
-        `
-custom_rules:
-  my_rule:
-    rule: MY CUSTOM RULE
-    message: Custom message
-    level: guideline
-    trigger: commit
-`
-      );
-
-      const loader = new ProjectConfigLoader(tempDir);
-      loader.load();
-
-      const merged = loader.mergeConstraints();
-      expect(merged.custom).toBeDefined();
+      expect(merged.constraints).toBeDefined();
+      expect(Object.keys(merged.constraints).length).toBeGreaterThan(0);
     });
   });
 
@@ -96,8 +70,6 @@ custom_rules:
       const config = loader.load();
 
       expect(config.preset).toBe('minimal');
-      // 默认值应该保留
-      expect(config.custom_constraints_file).toBe('custom-constraints.yml');
     });
   });
 
@@ -113,10 +85,10 @@ custom_rules:
       expect(() => loader.load()).toThrow();
     });
 
-    it('自定义约束文件不存在应该不崩溃', () => {
+    it('config.yml 只有无关键时 mergeConstraints 不崩溃', () => {
       fs.writeFileSync(
         path.join(harnessDir, 'config.yml'),
-        `custom_constraints_file: nonexistent.yml`
+        `preset: standard`
       );
 
       const loader = new ProjectConfigLoader(tempDir);

package/src/__tests__/public-exports.test.ts

@@ -19,8 +19,8 @@ import * as path from 'path';
 
 const EXPECTED_RUNTIME_EXPORTS = [
   'AgentLifecycle',
-  'CONSTRAINTS_END_MARKER',
-  'CONSTRAINTS_START_MARKER',
+  'CANDIDATE_KIND_LABEL',
+  'CONSTRAINTS',
   'CSOValidator',
   'CheckCache',
   'CheckpointValidator',
@@ -32,6 +32,7 @@ const EXPECTED_RUNTIME_EXPORTS = [
   'DEFAULT_CLASSIFICATION_RULES',
   'DEFAULT_COMMAND_BLACKLIST',
   'DEFAULT_DECAY_CONFIG',
+  'DEFAULT_DIAGNOSE_THRESHOLDS',
   'DEFAULT_FAILURE_LOG_FILE',
   'DEFAULT_LEVEL_MAPPING',
   'DEFAULT_NONCODE_GLOBS',
@@ -43,8 +44,6 @@ const EXPECTED_RUNTIME_EXPORTS = [
   'FailureRecorder',
   'FileKnowledgeStore',
   'GATE_DEFINITIONS',
-  'GUIDELINES',
-  'IRON_LAWS',
   'KnowledgeAudit',
   'KnowledgeHealthScorer',
   'KnowledgeIngest',
@@ -53,7 +52,6 @@ const EXPECTED_RUNTIME_EXPORTS = [
   'KnowledgeLinter',
   'KnowledgeQuery',
   'PHASE_SUBJECT_RE',
-  'PROMPTS',
   'PassesGate',
   'PerformanceGate',
   'ReferenceTracker',
@@ -71,11 +69,13 @@ const EXPECTED_RUNTIME_EXPORTS = [
   'assertGateRegistryClosed',
   'bootstrapHarness',
   'bootstrapHarnessSync',
+  'buildConstraintsUsageReport',
   'checkBeforeExecution',
   'checkConstraint',
   'checkConstraints',
   'classifyCommitFiles',
   'classifyError',
+  'collectUsageByConstraint',
   'configureTraceCollector',
   'createAnalyzer',
   'createCheckerGate',
@@ -89,6 +89,7 @@ const EXPECTED_RUNTIME_EXPORTS = [
   'createSecurityGate',
   'createSpecAcceptanceGate',
   'decisionFromResult',
+  'diagnoseRetireCandidates',
   'extractCodeStructure',
   'findConstraintsByTrigger',
   'getAllConstraints',
@@ -108,9 +109,9 @@ const EXPECTED_RUNTIME_EXPORTS = [
   'matchAnyGlob',
   'matchGlob',
   'migrateKnowledgeEntries',
+  'readProjectTraces',
+  'readProjectTracesReport',
   'registeredGateCount',
-  'renderConstraintsByTrigger',
-  'renderConstraintsSection',
   'resolveGlobs',
   'runGates',
   'sanitizeExternalContent',

package/src/__tests__/public-type-surface.test.ts

@@ -145,9 +145,11 @@ const PUBLISHED_ENTRY_TYPES: Record<string, string[]> = {
     'ConstraintContext',
     'ConstraintId',
     'ConstraintKind',
-    'ConstraintLevel',
+    'ConstraintSeverity',
     'ConstraintResult',
     'ConstraintTrigger',
+    'ConstraintUsageStats',
+    'ConstraintsUsageReport',
     'ConsumptionEvent',
     'ConsumptionMode',
     'ContextAverages',
@@ -159,10 +161,10 @@ const PUBLISHED_ENTRY_TYPES: Record<string, string[]> = {
     'ContractGateConfig',
     'ContractPresenceContext',
     'ContractPresenceResult',
-    'CustomConstraintDefinition',
     'DecayConfig',
     'DecisionRecord',
     'DeclarationInfo',
+    'DiagnoseThresholds',
     'DirCountActual',
     'DocDirCheck',
     'DocFreshnessCheck',
@@ -215,7 +217,8 @@ const PUBLISHED_ENTRY_TYPES: Record<string, string[]> = {
     'QueryFilter',
     'QueryResult',
     'ReferenceRecord',
-    'RenderConstraintsByTriggerOptions',
+    'RetireCandidate',
+    'RetireCandidateKind',
     'ReviewGateConfig',
     'SchemaLoader',
     'SecurityGateConfig',
@@ -265,14 +268,13 @@ const PUBLISHED_ENTRY_TYPES: Record<string, string[]> = {
     'ConstraintContext',
     'ConstraintId',
     'ConstraintKind',
-    'ConstraintLevel',
+    'ConstraintSeverity',
     'ConstraintResult',
     'ConstraintTrigger',
     'ContextFilesResolution',
     'EffectiveConfigLint',
     'IronLawContext',
     'PassesGateConfig',
-    'RenderConstraintsByTriggerOptions',
     'RunEnv',
     'RunTarget',
     'SpecSchemaDefinition',

package/src/__tests__/public-value-surface.test.ts

@@ -47,16 +47,12 @@ const ENTRY_SUBPATHS: string[] = Object.keys(EXPORTS_MAP);
 /** 每个已发布子路径入口的值面全量清单。增删任一项即公共面 breaking，见文件头。 */
 const PUBLISHED_ENTRY_VALUES: Record<string, string[]> = {
   './core': [
-    'CONSTRAINTS_END_MARKER',
-    'CONSTRAINTS_START_MARKER',
+    'CONSTRAINTS',
     'CSOValidator',
     'CheckCache',
     'CheckpointValidator',
     'ConstraintChecker',
     'ConstraintViolationError',
-    'GUIDELINES',
-    'IRON_LAWS',
-    'PROMPTS',
     'PassesGate',
     'ProjectConfigLoader',
     'SpecValidator',
@@ -73,8 +69,6 @@ const PUBLISHED_ENTRY_VALUES: Record<string, string[]> = {
     'getGovernanceConfig',
     'lintEffectiveConfig',
     'loadRawProjectConfig',
-    'renderConstraintsByTrigger',
-    'renderConstraintsSection',
     'resolveContextFiles',
   ],
   './presets': [

package/src/__tests__/skip-semantics.test.ts

@@ -3,8 +3,8 @@
  *
  * 覆盖：
  * - 三条存在性探测（capability_sync / context_doc_sync / docs_freshness）有/无约定两路
- * - flag 型铁律 undefined → skip（显式 false 仍 fail，true 仍 pass）
- * - Iron Law skip 不阻断 checkConstraints
+ * - flag 型 error 级约束 undefined → skip（显式 false 仍 fail，true 仍 pass）
+ * - error 级 skip 不阻断 checkConstraints
  * - detectTrigger 代码文件 → 附加 code_implementation 推断
  * - trace 记录 result: 'skip'；TraceAnalyzer 的 pass/fail 率分母不计 skip
  */
@@ -12,7 +12,7 @@
 import { describe, it, expect, beforeAll, afterAll } from '@jest/globals';
 import { ConstraintChecker } from '../core/constraints/checker';
 import { detectTrigger, buildConstraintContext } from '../core/constraints/context-builder';
-import { IRON_LAWS } from '../core/constraints/definitions';
+import { CONSTRAINTS } from '../core/constraints/definitions';
 import { TraceAnalyzer } from '../monitoring/trace-analyzer';
 import type { Constraint, ConstraintContext } from '../types/constraint';
 import type { ExecutionTrace } from '../types/trace';
@@ -26,10 +26,10 @@ const checker = new ConstraintChecker({ record: () => undefined });
 
 function makeConstraint(
   id: string,
-  level: 'iron_law' | 'guideline',
+  severity: 'error' | 'warning',
   trigger: string = 'commit'
 ): Constraint {
-  return { id, kind: 'check', level, rule: 'TEST', message: 'test', trigger, enforcement: 'test' };
+  return { id, kind: 'check', severity, rule: 'TEST', message: 'test', trigger, enforcement: 'test' };
 }
 
 describe('skip 三态语义（ADR-0001）', () => {
@@ -58,7 +58,7 @@ describe('skip 三态语义（ADR-0001）', () => {
       const dir = path.join(tempDir, 'cap-skip');
       fs.mkdirSync(dir, { recursive: true });
 
-      const result = await checker.check(makeConstraint('capability_sync', 'guideline'), {
+      const result = await checker.check(makeConstraint('capability_sync', 'warning'), {
         operation: 'commit',
         projectPath: dir,
       } as ConstraintContext);
@@ -75,7 +75,7 @@ describe('skip 三态语义（ADR-0001）', () => {
       // 散文文档（无表格）历史放行；此处只验证"进入评估"而非 skip
       fs.writeFileSync(path.join(dir, 'CAPABILITIES.md'), '# Capabilities\n\n- Feature: test');
 
-      const result = await checker.check(makeConstraint('capability_sync', 'guideline'), {
+      const result = await checker.check(makeConstraint('capability_sync', 'warning'), {
         operation: 'commit',
         projectPath: dir,
       } as ConstraintContext);
@@ -92,7 +92,7 @@ describe('skip 三态语义（ADR-0001）', () => {
       const dir = path.join(tempDir, 'ctx-skip');
       fs.mkdirSync(dir, { recursive: true });
 
-      const result = await checker.check(makeConstraint('context_doc_sync', 'guideline'), {
+      const result = await checker.check(makeConstraint('context_doc_sync', 'warning'), {
         operation: 'module_modification',
         projectPath: dir,
       } as ConstraintContext);
@@ -114,7 +114,7 @@ describe('skip 三态语义（ADR-0001）', () => {
         yaml.dump({ governance: { context_files: { enabled: true, required_dirs: ['src'] } } })
       );
 
-      const result = await checker.check(makeConstraint('context_doc_sync', 'guideline'), {
+      const result = await checker.check(makeConstraint('context_doc_sync', 'warning'), {
         operation: 'module_modification',
         projectPath: dir,
       } as ConstraintContext);
@@ -131,7 +131,7 @@ describe('skip 三态语义（ADR-0001）', () => {
       const dir = path.join(tempDir, 'fresh-skip');
       fs.mkdirSync(dir, { recursive: true });
 
-      const result = await checker.check(makeConstraint('docs_freshness', 'iron_law', 'file_modification'), {
+      const result = await checker.check(makeConstraint('docs_freshness', 'error', 'file_modification'), {
         operation: 'file_modification',
         projectPath: dir,
       } as ConstraintContext);
@@ -150,7 +150,7 @@ describe('skip 三态语义（ADR-0001）', () => {
         '# Capabilities\n\n| 模块 | 文件 | 说明 |\n|------|------|------|\n| ghost | src/ghost.ts | 不存在 |'
       );
 
-      const result = await checker.check(makeConstraint('docs_freshness', 'iron_law', 'file_modification'), {
+      const result = await checker.check(makeConstraint('docs_freshness', 'error', 'file_modification'), {
         operation: 'file_modification',
         projectPath: dir,
       } as ConstraintContext);
@@ -162,9 +162,9 @@ describe('skip 三态语义（ADR-0001）', () => {
     });
   });
 
-  describe('flag 型铁律：undefined → skip', () => {
+  describe('flag 型 error 级约束：undefined → skip', () => {
     it('hasVerificationEvidence undefined → skip；false → fail；true → pass', async () => {
-      const law = IRON_LAWS['no_completion_without_verification'];
+      const law = CONSTRAINTS['no_completion_without_verification'];
 
       const skipped = await checker.check(law, { operation: 'code_implementation' });
       expect(skipped.skipped).toBe(true);
@@ -185,33 +185,17 @@ describe('skip 三态语义（ADR-0001）', () => {
       expect(passed.satisfied).toBe(true);
     });
 
-    it('hasSingleTask / hasRequirement undefined → skip', async () => {
-      const single = await checker.check(IRON_LAWS['incremental_progress'], {
-        operation: 'code_implementation',
-      });
-      expect(single.skipped).toBe(true);
-
-      const req = await checker.check(IRON_LAWS['no_implementation_without_requirement'], {
-        operation: 'code_implementation',
-      });
-      expect(req.skipped).toBe(true);
-    });
-
     it('Iron Law skip 不阻断 checkConstraints', async () => {
-      // 三个 flag 全部未接线（CLI pre-commit 路径的典型形态）
+      // flag 未接线（CLI pre-commit 路径的典型形态）
       const result = await checker.checkConstraints({
         operation: 'code_implementation',
         projectPath: path.join(tempDir, 'empty'),
       });
 
       expect(result.passed).toBe(true);
-      const skippedIds = result.ironLaws.filter(r => r.skipped).map(r => r.id);
+      const skippedIds = result.errors.filter(r => r.skipped).map(r => r.id);
       expect(skippedIds).toEqual(
-        expect.arrayContaining([
-          'no_completion_without_verification',
-          'incremental_progress',
-          'no_implementation_without_requirement',
-        ])
+        expect.arrayContaining(['no_completion_without_verification'])
       );
     });
 
@@ -296,17 +280,17 @@ describe('skip 三态语义（ADR-0001）', () => {
 
       const skipTraces = records.filter(t => t.result === 'skip');
       expect(skipTraces.map(t => t.constraintId)).toEqual(
-        expect.arrayContaining(['incremental_progress', 'no_implementation_without_requirement'])
+        expect.arrayContaining(['no_completion_without_verification'])
       );
     });
 
     it('TraceAnalyzer：skip 单独计数，不计入 pass/fail 率分母', () => {
       const analyzer = new TraceAnalyzer(null as any);
       const traces: ExecutionTrace[] = [
-        { constraintId: 'c1', level: 'iron_law', timestamp: 1, result: 'pass' },
-        { constraintId: 'c1', level: 'iron_law', timestamp: 2, result: 'skip' },
-        { constraintId: 'c1', level: 'iron_law', timestamp: 3, result: 'skip' },
-        { constraintId: 'c1', level: 'iron_law', timestamp: 4, result: 'fail' },
+        { constraintId: 'c1', severity: 'error', timestamp: 1, result: 'pass' },
+        { constraintId: 'c1', severity: 'error', timestamp: 2, result: 'skip' },
+        { constraintId: 'c1', severity: 'error', timestamp: 3, result: 'skip' },
+        { constraintId: 'c1', severity: 'error', timestamp: 4, result: 'fail' },
       ];
 
       const [summary] = analyzer.summarize(traces);