@dommaker/harness 0.17.0 → 0.18.0

package/src/core/CONTEXT.md

@@ -5,7 +5,7 @@
 
 ## 核心导出
 - `constraints/` — 约束定义(IRON_LAWS/GUIDELINES/PROMPTS；TIPS 已退役为空表) + 检查引擎(ConstraintChecker) + 拦截器(ConstraintInterceptor) + 缓存(CheckCache) + 注入渲染(injection-renderer)/漂移校验(injection-drift)/使用统计(usage-report)
-- `effective-constraints.ts` — `getEffectiveConstraints(projectRoot)`：全仓唯一生效集来源（内置 → preset → config.yml 禁用 → custom 追加 → scenes 过滤）；`lintEffectiveConfig` 配置诊断
+- `effective-constraints.ts` — `getEffectiveConstraints(projectRoot)`：全仓唯一生效集来源（内置 → preset → config.yml 禁用（内置与 custom 同效）→ custom 追加（禁用/已退役的不追加）→ scenes 过滤）；`lintEffectiveConfig` 配置诊断
 - `validators/` — checkpoints、passes-gate、CSO 验证器
 - `session/` — 会话管理
 - `spec/validator` — SpecValidator

package/src/core/constraints/__tests__/injection-drift.test.ts

@@ -45,7 +45,7 @@ describe('detectInjectionDrift', () => {
     expect(drift.versionDrift).toBeUndefined();
     expect(drift.contentDrift).toBeUndefined();
     expect(drift.duplicateHeading).toBe(false);
-    expect(drift.fixHint).toContain('npx harness init');
+    expect(drift.fixHint).toContain('npx @dommaker/harness init');
     expect(drift.fixHint).toBe(INJECTION_DRIFT_FIX_HINT);
   });
 

package/src/core/constraints/__tests__/interceptor.test.ts

@@ -2,10 +2,10 @@
  * ConstraintInterceptor 测试
  */
 
-import { ConstraintInterceptor, constraintInterceptor } from '../interceptor';
+import { ConstraintInterceptor } from '../interceptor';
 import { constraintChecker } from '../checker';
-import type { Constraint, ConstraintContext, ConstraintTrigger } from '../../../types/constraint';
-import type { EnforcementExecutor, EnforcementResult } from '../../../types/enforcement';
+import type { ConstraintContext } from '../../../types/constraint';
+import type { EnforcementExecutor } from '../../../types/enforcement';
 
 // Mock constraintChecker
 jest.mock('../checker', () => ({

package/src/core/constraints/definitions/iron-laws.ts

@@ -22,8 +22,8 @@ export const IRON_LAWS: Record<string, Constraint> = {
     level: 'iron_law',
     trigger: 'code_implementation',
     enforcement: 'verify-completion',
-    description: '在声明任何任务完成之前，必须运行新鲜的、完整的验证命令。验证命令包括：npm test、npm run build、CI 流程。',
-    promptInjection: '在声明任务完成前，必须重新运行完整的验证命令（npm test、npm run build、type check），使用新鲜的输出作为完成证据，不得复用旧结果。',
+    description: '在声明任何任务完成之前，必须运行新鲜的验证命令（项目声明的测试 + type check），以新鲜输出作为完成证据。验证命令集由项目自行声明，全量验证留给 CI 流程。',
+    promptInjection: '在声明任务完成前，必须重新运行新鲜的验证命令（项目声明的测试 + type check），使用新鲜的输出作为完成证据，不得复用旧结果，不得凭记忆声称完成。',
   },
 
   /**

package/src/core/constraints/injection-drift.ts

@@ -42,7 +42,7 @@ export interface InjectionDrift {
 }
 
 /** 修复指引（重跑 init 幂等同步注入段） */
-export const INJECTION_DRIFT_FIX_HINT = '重跑 `npx harness init` 同步注入段（漂移仅警告，不阻断）';
+export const INJECTION_DRIFT_FIX_HINT = '重跑 `npx @dommaker/harness init` 同步注入段（漂移仅警告，不阻断）';
 
 const VERSION_LINE_RE = /<!-- version: ([^ ]+) -->/;
 const ENTRY_LINE_RE = /^- \*\*.+?\*\*: .+$/;

package/src/core/effective-constraints.ts

@@ -15,7 +15,8 @@ import { ProjectConfigLoader } from './project-config-loader';
  * 获取项目当前生效的约束集（check + prompt，带 kind）
  *
  * 内部完成完整合并：内置 → preset 裁剪 → config.yml `constraints.<id>.enabled:false`
- * 删除 → custom-constraints 追加/extend_exceptions → scenes 过滤
+ * 删除（内置与 custom 同效）→ custom-constraints 追加/extend_exceptions
+ * （禁用/已退役的 custom 不追加）→ scenes 过滤
  * （带 appliesTo 的 prompt 仅当 config.yml `scenes` 与其交集非空时保留，
  * 缺省 scenes=[] 即场景专属 prompt 默认不进入生效集）。
  *

package/src/core/project-config-loader.ts

@@ -156,7 +156,8 @@ export class ProjectConfigLoader {
    * 合并内置约束和自定义约束（ADR-0001 生效集完整链路）
    *
    * 合并顺序：内置 → preset 裁剪 → config.yml `constraints.<id>.enabled:false`
-   * 删除 → custom-constraints 追加/extend_exceptions → scenes 过滤
+   * 删除（对内置与 custom 同效）→ custom-constraints 追加/extend_exceptions
+   * （禁用/已退役的 custom 不追加）→ scenes 过滤
    * （带 appliesTo 的 prompt 仅当 scenes 交集非空时保留）。
    *
    * config.yml 中未知约束 id（如已移除约束的禁用残留）静默忽略，
@@ -201,8 +202,13 @@ export class ProjectConfigLoader {
       }
     }
 
-    // 2. 添加自定义约束
+    // 2. 添加自定义约束（config.yml 禁用的 id 不追加：step 1 已将其
+    // 收集进 disabled，custom 在 step 1 时尚未入桶，须在此兜底跳过；
+    // 条目带 retired 元数据的同样不追加——#82 D6 退役落点在条目自身）
     for (const [id, customDef] of Object.entries(this.customConstraints)) {
+      if (result.disabled.includes(id) || customDef.retired) {
+        continue;
+      }
       const extendExceptions = customDef.extend_exceptions;
       const isExtendOnly =
         !!extendExceptions && extendExceptions.length > 0 &&
@@ -300,6 +306,7 @@ export class ProjectConfigLoader {
       trigger: (def.trigger || 'manual') as ConstraintTrigger | ConstraintTrigger[],
       exceptions: def.exceptions,
       description: def.description,
+      promptInjection: def.promptInjection,
       enabled: def.enabled !== false,
       enforcement: 'custom',
     };

package/src/gates/__tests__/acceptance.test.ts

@@ -4,7 +4,6 @@
 
 import { SpecAcceptanceGate, createSpecAcceptanceGate } from '../acceptance';
 import * as fs from 'fs/promises';
-import * as path from 'path';
 import { exec } from 'child_process';
 
 // Mock dependencies

package/src/gates/__tests__/command.test.ts

@@ -2,7 +2,7 @@
  * CommandGate 测试
  */
 
-import { CommandGate, createCommandGate, isCommandAllowed, getCommandRiskLevel, DEFAULT_COMMAND_BLACKLIST } from '../command';
+import { CommandGate, isCommandAllowed, getCommandRiskLevel, DEFAULT_COMMAND_BLACKLIST } from '../command';
 
 describe('CommandGate', () => {
   describe('check', () => {

package/src/hooks/bootstrap.ts

@@ -70,7 +70,7 @@ export async function bootstrapHarness(
   const resolvedPath = projectPath || process.cwd();
 
   // 1. 异步加载配置（S9 fix）
-  const { config: _config, mergedConstraints } = await loadConfigAsync(resolvedPath);
+  const { mergedConstraints } = await loadConfigAsync(resolvedPath);
 
   // 2. 初始化核心组件
   const checker = ConstraintChecker.getInstance();

package/src/knowledge/__tests__/doctor.test.ts

@@ -5,10 +5,10 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import { FileKnowledgeStore as KnowledgeStore } from '../store';
-import { KnowledgeLinter, type LintReport } from '../lint';
+import { KnowledgeLinter } from '../lint';
 import { ReferenceTracker } from '../reference-tracker';
 import { KnowledgeHealthScorer } from '../doctor';
-import type { KnowledgeEntry, IndexEntry } from '../types';
+import type { KnowledgeEntry } from '../types';
 
 describe('KnowledgeHealthScorer', () => {
   const tempDir = path.join(process.cwd(), 'temp-test-knowledge-doctor');

package/src/knowledge/__tests__/ingest.test.ts

@@ -245,7 +245,7 @@ describe('KnowledgeIngest', () => {
       });
 
       // After stripping [prefix], normalizing: "api超时导致请求失败" contains "api超时导致"
-      const merged = ingest.ingestEntry(
+      ingest.ingestEntry(
         { title: '[Triage Fix] API 超时导致', content: 'different content but same issue', type: 'pitfall' },
         { source: 'test', layer: 'system' },
       );
@@ -287,7 +287,7 @@ describe('KnowledgeIngest', () => {
 
       // Keywords: prisma, 连接, 超时, 导致, api, 请求, 失败
       // Incoming: prisma, 超时, 请求, 失败 → 4/7 overlap
-      const merged = ingest.ingestEntry(
+      ingest.ingestEntry(
         { title: 'Prisma 超时导致请求失败', content: 'totally different content', type: 'pitfall' },
         { source: 'test', layer: 'system' },
       );

package/src/knowledge/__tests__/migration.test.ts

@@ -37,12 +37,6 @@ describe('migrateKnowledgeEntries', () => {
     fs.writeFileSync(path.join(tempDir, filename), raw, 'utf-8');
   }
 
-  function readMeta(filename: string): Record<string, unknown> {
-    const raw = fs.readFileSync(path.join(tempDir, filename), 'utf-8');
-    const match = raw.match(/^---\n([\s\S]*?)\n---/)!;
-    return JSON.parse(JSON.stringify(eval(`(${match[1].replace(/(\w+):/g, '"$1":').replace(/'/g, '"')})`)));
-  }
-
   it('should add consumptionMode and origin to entries missing them', () => {
     writeEntry('DEC-001.md', {
       id: 'DEC-001', type: 'decision', title: 'Test', maturity: 'draft',

package/src/knowledge/__tests__/store.test.ts

@@ -184,6 +184,19 @@ describe('KnowledgeStore', () => {
   });
 
   describe('edge cases', () => {
+    it('should round-trip sourceReferences with entryId through save/load', () => {
+      const sourceRefs = [
+        { workflow: 'test-flow', step: 'distill', commit: 'abc1234', timestamp: '2026-05-01', entryId: 'SRC-001' },
+        { workflow: 'test-flow', timestamp: '2026-05-02' },
+      ];
+      store.save(makeEntry({ id: 'DEC-001', sourceReferences: sourceRefs }));
+      const loaded = store.get('DEC-001');
+      expect(loaded?.sourceReferences).toStrictEqual(sourceRefs);
+      // 缺省 entryId 的 ref 不落 undefined 键：原始 frontmatter 中 entryId 只出现一次
+      const raw = fs.readFileSync(path.join(tempDir, 'decision-DEC-001.md'), 'utf-8');
+      expect(raw.match(/entryId/g)).toHaveLength(1);
+    });
+
     it('should round-trip consumptionMode and origin through save/load', () => {
       store.save(makeEntry({
         id: 'DEC-001',
@@ -212,7 +225,7 @@ describe('KnowledgeStore', () => {
 
     it('should create directory if it does not exist', () => {
       const newDir = path.join(process.cwd(), 'temp-test-knowledge-nested', 'sub', 'deep');
-      const s = new KnowledgeStore({ baseDir: newDir });
+      new KnowledgeStore({ baseDir: newDir });
       expect(fs.existsSync(newDir)).toBe(true);
       fs.rmSync(path.join(process.cwd(), 'temp-test-knowledge-nested'), { recursive: true, force: true });
     });

package/src/knowledge/store.ts

@@ -68,7 +68,7 @@ export class FileKnowledgeStore implements KnowledgeStore {
   list(filter?: QueryFilter): KnowledgeEntry[] {
     const index = this.readIndex();
     const effectiveFilter: QueryFilter = { excludeArchived: true, ...filter };
-    let entries = index.filter(e => this.matchesFilter(e, effectiveFilter));
+    const entries = index.filter(e => this.matchesFilter(e, effectiveFilter));
 
     return entries.map(idx => {
       const full = this.get(idx.id);

package/src/knowledge/types.ts

@@ -58,6 +58,8 @@ export interface SourceRef {
   step?: string;
   commit?: string;
   timestamp: string;
+  /** ID of the source material entry this knowledge was distilled/evolved from (entry-level back-reference) */
+  entryId?: string;
 }
 
 export interface ExecutionResult {

package/src/llm/__tests__/adapter.test.ts

@@ -53,7 +53,7 @@ describe('LLM Adapter', () => {
       it('应该抛出未实现错误', async () => {
         const gen = adapter.streamChat([{ role: 'user', content: 'test' }]);
         await expect(async () => {
-          for await (const _ of gen) { /* noop */ }
+          for await (const _ of gen) { void _; }
         }).rejects.toThrow('LLM streamChat 未实现');
       });
     });

package/src/monitoring/__tests__/knowledge-doctor.test.ts

@@ -226,7 +226,6 @@ describe('KnowledgeDoctor', () => {
 
     it('critical 严重度扣 10 分', () => {
       const doctor = new KnowledgeDoctor();
-      const issue: LintIssue = { type: 'contradiction', severity: 'high', entryId: 'e1', description: 'critical issue', suggestion: 'fix' };
       // 直接构造 critical 诊断来测试 calculateHealthScore 的 critical 分支
       // LintIssue severity 只有 low/medium/high，所以通过 checkDecay 的 high 来测试
       const entry = makeEntry({ maturity: 'proven', lastReferenced: '2020-01-01T00:00:00Z' });

package/src/monitoring/__tests__/performance-collector.test.ts

@@ -2,10 +2,9 @@
  * PerformanceCollector 测试
  */
 
-import { describe, it, expect, beforeEach, afterEach } from '@jest/globals';
+import { describe, it, expect, beforeEach } from '@jest/globals';
 import { PerformanceCollector } from '../performance-collector';
 import * as fs from 'fs';
-import * as path from 'path';
 
 // Mock fs
 jest.mock('fs', () => ({

package/src/safety/output-guardrail.ts

@@ -11,7 +11,7 @@ import type { OutputSafetyCheckResult, OutputViolation, OutputGuardrailConfig }
 
 const DEFAULT_SENSITIVE_PATTERNS: RegExp[] = [
   // API keys
-  /(?:api[_-]?key|apikey)\s*[:=]\s*['"]?([a-zA-Z0-9_\-]{20,})['"]?/gi,
+  /(?:api[_-]?key|apikey)\s*[:=]\s*['"]?([a-zA-Z0-9_-]{20,})['"]?/gi,
   // AWS
   /(?:AKIA|ASIA)[A-Z0-9]{16}/g,
   // Generic secrets
@@ -21,7 +21,7 @@ const DEFAULT_SENSITIVE_PATTERNS: RegExp[] = [
   // GitHub tokens
   /gh[ps]_[A-Za-z0-9_]{36,}/g,
   // Bearer tokens
-  /Bearer\s+[A-Za-z0-9_\-\.]{20,}/g,
+  /Bearer\s+[A-Za-z0-9_\-.]{20,}/g,
   // Connection strings
   /(?:mongodb|postgres|mysql|redis):\/\/[^\s'"]+/gi,
 ];

package/src/spec/__tests__/annotation-checker.test.ts

@@ -4,7 +4,6 @@
 
 import { checkFile, checkDirectory, generateReport } from '../annotation-checker';
 import * as fs from 'fs';
-import * as path from 'path';
 
 // Mock fs
 jest.mock('fs', () => ({

package/src/spec/annotation-checker.ts

@@ -152,7 +152,7 @@ function parseJSDoc(lines: string[], startLine: number): SpecAnnotation | null {
   }
 
   // @dependencies
-  const depsMatch = content.match(/@dependencies\s+([\w\-_,\s\/]+)/);
+  const depsMatch = content.match(/@dependencies\s+([\w\-_,\s/]+)/);
   if (depsMatch) {
     annotation.dependencies = depsMatch[1]
       .split(/[,\s]+/)

package/src/types/project-config.ts

@@ -34,8 +34,29 @@ export interface CustomConstraintDefinition {
   /** 描述（可选） */
   description?: string;
 
+  /**
+   * Prompt 注入文本（可选）
+   *
+   * 自定义约束统一 kind='prompt'（无 checker），该字段是进入 CLAUDE.md
+   * 注入段（renderConstraintsSection）的唯一通道——缺省不出现在注入段，
+   * 与内置无 promptInjection 的 check 条目行为一致。
+   */
+  promptInjection?: string;
+
   /** 是否启用（可选，默认 true） */
   enabled?: boolean;
+
+  /**
+   * 退役元数据（#82 D6 统一落点）
+   *
+   * 存在即视为已退役：不进生效集、不注入 CLAUDE.md。恢复 = 删除该段。
+   * 落点在 custom-constraints.yml 条目内（一处真相，不拆 config.yml 第二处）。
+   */
+  retired?: {
+    at?: string;
+    reason?: string;
+    stats?: { total: number; fail: number; failRate: number };
+  };
 }
 
 /**

package/src/utils/__tests__/file-walk.test.ts

@@ -0,0 +1,53 @@
+/**
+ * file-walk 工具测试
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import { findTsSourceFiles } from '../file-walk';
+
+describe('findTsSourceFiles', () => {
+  const tempDir = path.join(process.cwd(), 'temp-test-file-walk');
+
+  beforeAll(() => {
+    fs.mkdirSync(tempDir, { recursive: true });
+  });
+
+  afterAll(() => {
+    try {
+      fs.rmSync(tempDir, { recursive: true, force: true });
+    } catch {
+      // ignore
+    }
+  });
+
+  it('默认只收集 .ts（排除 .d.ts），.tsx 不进入结果', () => {
+    const dir = path.join(tempDir, 'default-ts-only');
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(path.join(dir, 'a.ts'), '');
+    fs.writeFileSync(path.join(dir, 'b.d.ts'), '');
+    fs.writeFileSync(path.join(dir, 'c.tsx'), '');
+
+    const names = findTsSourceFiles(dir).map(f => path.basename(f)).sort();
+    expect(names).toEqual(['a.ts']);
+
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  it('includeTsx: true 时同时收集 .tsx，skipIndex 排除 index.ts/index.tsx', () => {
+    const dir = path.join(tempDir, 'include-tsx');
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(path.join(dir, 'a.ts'), '');
+    fs.writeFileSync(path.join(dir, 'b.d.ts'), '');
+    fs.writeFileSync(path.join(dir, 'c.tsx'), '');
+    fs.writeFileSync(path.join(dir, 'index.ts'), '');
+    fs.writeFileSync(path.join(dir, 'index.tsx'), '');
+
+    const names = findTsSourceFiles(dir, { includeTsx: true, skipIndex: true })
+      .map(f => path.basename(f))
+      .sort();
+    expect(names).toEqual(['a.ts', 'c.tsx']);
+
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+});

package/src/utils/file-walk.ts

@@ -53,6 +53,8 @@ export function walkFiles(root: string, options: FileWalkOptions = {}): string[]
 export interface TsSourceWalkOptions {
   /** 是否跳过 barrel 文件 index.ts，默认 false */
   skipIndex?: boolean;
+  /** 是否同时收集 .tsx 文件，默认 false（只收集 .ts） */
+  includeTsx?: boolean;
   /** 跳过的目录名，默认 node_modules/__tests__/dist */
   skipDirs?: string[];
   /** 是否跳过 `.` 开头的条目，默认 false */
@@ -60,11 +62,30 @@ export interface TsSourceWalkOptions {
 }
 
 /**
- * 递归收集 TypeScript 源文件（.ts，排除 .d.ts）
+ * 文件名是否为 TypeScript 源文件（includeTsx 时含 .tsx，排除 .d.ts 与可选 barrel index）
+ *
+ * findTsSourceFiles 的过滤谓词；需要同口径判断的调用方（如 sync-docs 顶层文件分支）
+ * 复用此函数，避免扩展名规则在多处漂移。
+ */
+export function isTsSourceFile(
+  name: string,
+  options: { skipIndex?: boolean; includeTsx?: boolean } = {}
+): boolean {
+  const { skipIndex = false, includeTsx = false } = options;
+  return (
+    (name.endsWith('.ts') || (includeTsx && name.endsWith('.tsx'))) &&
+    !name.endsWith('.d.ts') &&
+    (!skipIndex || (name !== 'index.ts' && name !== 'index.tsx'))
+  );
+}
+
+/**
+ * 递归收集 TypeScript 源文件（.ts，includeTsx 时含 .tsx，排除 .d.ts）
  */
 export function findTsSourceFiles(root: string, options: TsSourceWalkOptions = {}): string[] {
   const {
     skipIndex = false,
+    includeTsx = false,
     skipDirs = ['node_modules', '__tests__', 'dist'],
     skipHidden = false,
   } = options;
@@ -72,7 +93,6 @@ export function findTsSourceFiles(root: string, options: TsSourceWalkOptions = {
   return walkFiles(root, {
     skipDirs,
     skipHidden,
-    filter: (name) =>
-      name.endsWith('.ts') && !name.endsWith('.d.ts') && (!skipIndex || name !== 'index.ts'),
+    filter: (name) => isTsSourceFile(name, { skipIndex, includeTsx }),
   });
 }

package/src/verification/__tests__/loop.test.ts

@@ -3,7 +3,7 @@
  */
 
 import { VerificationLoop } from '../loop';
-import type { VerificationLoopConfig, GatherState, VerificationResult } from '../types';
+import type { VerificationLoopConfig, GatherState } from '../types';
 
 describe('VerificationLoop', () => {
   const baseConfig: VerificationLoopConfig = {