@dommaker/harness 1.3.0 → 1.4.0

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

@@ -0,0 +1,212 @@
+/**
+ * 治理注入段落点写入器（架构评审候选1，ADR-0011）
+ *
+ * 「按渲染 body 替换标记区间 + 尾换行规一」的切片数学此前手抄 4 份
+ * （init.ts 三个 writer / constraints-retire 一份），落点路由读写两侧各抄一份。
+ * 本模块是唯一 writer：init/retire 退化为「渲染 body + 调 writer」。
+ *
+ * 形状两种（排版约定不同，非"算哪些"的差异，故合法分叉）：
+ * - replaceStandaloneRange：区间独立成节，END 标记后折叠为恰好一个空行
+ *   （CLAUDE.md 约束段 / Output Style 段 / retire 注入段同步）
+ * - replaceEnclosedRange：区间后紧跟外层收口标记（AGENTS.md PRESERVE 段内
+ *   的 HARNESS_CONSTRAINTS 区间）——恰好剥一个换行，手写余文原样落回
+ *
+ * 半标记守护：单边缺失或顺序颠倒 → 'half'，拒写（旧实现此时或追加出双份
+ * 正本或产生乱序切片，属二次损坏路径，收紧为告警交人工，见 ADR-0011）。
+ *
+ * 落点路由同规则一份：
+ * - resolveInjectionTarget：读侧（漂移检测/retire 同步）——CLAUDE.md 有完整
+ *   标记段优先（旧模型仓豁免），否则 AGENTS.md（新模型仓住 PRESERVE 段内）
+ * - resolveGovernanceLanding：写侧（init 落点选择）——额外承认 CLAUDE.md
+ *   无标记的 `## Governance Rules` 旧块（续写不制造双份正本）
+ *
+ * 探测/判定同住本模块（#83，ADR-0011 补注：收口范围含探测器，不只写器）——
+ * 「这份文档里有没有治理契约 / 有几个正本标题」此前手抄 4 份且正则已漂移，
+ * 见文末 GOVERNANCE_HEADING / hasGovernanceContract / countGovernanceHeadings /
+ * hasPreserveBlock。
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import {
+  CONSTRAINTS_START_MARKER,
+  CONSTRAINTS_END_MARKER,
+} from './injection-renderer';
+
+/** 注入段落点文件名（检测顺序即路由优先级：旧模型仓 CLAUDE.md 优先） */
+export const INJECTION_FILES = ['CLAUDE.md', 'AGENTS.md'] as const;
+export type InjectionFile = (typeof INJECTION_FILES)[number];
+
+/** 标记区间替换结果 */
+export type MarkerWrite =
+  | { kind: 'updated'; content: string }
+  | { kind: 'absent' }
+  | { kind: 'half' };
+
+/** 完整标记块的内容切分（inner 含首尾标记行外的全部文本，含原换行） */
+export interface MarkerBlock {
+  before: string;
+  inner: string;
+  /** 后标记之后的原文（未规一） */
+  after: string;
+}
+
+export function readIfExists(filePath: string): string | null {
+  try {
+    const content = fs.readFileSync(filePath, 'utf-8');
+    return typeof content === 'string' ? content : null;
+  } catch {
+    return null;
+  }
+}
+
+/** 定位完整标记对：两标记俱在且顺序正确 */
+function findPair(content: string, begin: string, end: string): { startIdx: number; endIdx: number } | 'absent' | 'half' {
+  const startIdx = content.indexOf(begin);
+  const endIdx = content.indexOf(end);
+  if (startIdx === -1 && endIdx === -1) return 'absent';
+  if (startIdx === -1 || endIdx === -1 || endIdx < startIdx) return 'half';
+  return { startIdx, endIdx };
+}
+
+/**
+ * 切出完整标记块（before + begin + inner + end + after）。
+ * 'absent' = 两俱无；'half' = 残缺/乱序，拒切。
+ */
+export function cutMarkerBlock(content: string, begin: string, end: string): MarkerBlock | 'absent' | 'half' {
+  const pair = findPair(content, begin, end);
+  if (pair === 'absent' || pair === 'half') return pair;
+  return {
+    before: content.slice(0, pair.startIdx),
+    inner: content.slice(pair.startIdx + begin.length, pair.endIdx),
+    after: content.slice(pair.endIdx + end.length),
+  };
+}
+
+/**
+ * 替换独立成节的标记区间：body 为含首尾标记的完整替换文本（以换行结尾），
+ * 区间后文剥除全部前导换行、以恰好一个空行相接（幂等：重复替换结果稳定）。
+ */
+export function replaceStandaloneRange(content: string, begin: string, end: string, body: string): MarkerWrite {
+  const pair = findPair(content, begin, end);
+  if (pair === 'absent' || pair === 'half') return { kind: pair };
+  const after = content.slice(pair.endIdx + end.length).replace(/^\n+/, '');
+  return {
+    kind: 'updated',
+    content: content.slice(0, pair.startIdx) + body + (after ? '\n' + after : ''),
+  };
+}
+
+/**
+ * 替换后跟外层收口标记的区间：body 含首尾标记且以换行结尾（收口标记落自己行），
+ * 区间后文恰好剥一个换行（外层标记拼接位），其余手写余文原样保留。
+ */
+export function replaceEnclosedRange(content: string, begin: string, end: string, body: string): MarkerWrite {
+  const pair = findPair(content, begin, end);
+  if (pair === 'absent' || pair === 'half') return { kind: pair };
+  const tail = content.slice(pair.endIdx + end.length).replace(/^\n/, '');
+  return {
+    kind: 'updated',
+    content: content.slice(0, pair.startIdx) + body + tail,
+  };
+}
+
+/**
+ * 读侧路由：定位含完整 HARNESS_CONSTRAINTS 标记段的文件（studio #307）。
+ * detectInjectionDrift 与 retire 注入段同步共用。
+ */
+export function resolveInjectionTarget(
+  projectRoot: string
+): { file: InjectionFile; content: string; startIdx: number; endIdx: number } | null {
+  for (const file of INJECTION_FILES) {
+    const content = readIfExists(path.join(projectRoot, file));
+    if (content === null) continue;
+    const startIdx = content.indexOf(CONSTRAINTS_START_MARKER);
+    const endIdx = content.indexOf(CONSTRAINTS_END_MARKER);
+    if (startIdx !== -1 && endIdx !== -1 && endIdx > startIdx) {
+      return { file, content, startIdx, endIdx };
+    }
+  }
+  return null;
+}
+
+/**
+ * 写侧路由（init 落点选择，原 setupGovernanceConstraints 内联判定收于此）：
+ * CLAUDE.md 有约束标记段或有旧版 `## Governance Rules` 块 → 续写 CLAUDE.md
+ * （旧模型仓豁免，不制造双份正本）；否则 AGENTS.md PRESERVE:governance。
+ */
+export function resolveGovernanceLanding(
+  projectRoot: string
+): { target: 'claude-md' | 'agents-md'; claudeContent: string | null } {
+  const claudeContent = readIfExists(path.join(projectRoot, 'CLAUDE.md'));
+  if (claudeContent !== null && hasGovernanceContract(claudeContent)) {
+    return { target: 'claude-md', claudeContent };
+  }
+  return { target: 'agents-md', claudeContent };
+}
+
+/**
+ * 治理正本标题字面量（单一来源，#83）：init 的标题写点与下列两个判定谓词
+ * 都由它派生，仓内不再本地拼写。字面量无正则元字符，可直接拼入 RegExp。
+ *
+ * 两谓词回答两个问题，**共享字面量而非共享正则**（triage 裁决 2026-09-02）：
+ * 强行合一要么在场守护 fail-open 失效（取严格），要么重复计数引入无行尾
+ * 锚定的误报（取宽松）。
+ */
+export const GOVERNANCE_HEADING = '## Governance Rules';
+
+/** 标题文本（去 `## ` 前缀），宽松谓词按 `##` + 任意空白 + 此文本匹配 */
+const GOVERNANCE_HEADING_TEXT = GOVERNANCE_HEADING.replace(/^##\s+/, '');
+
+/** 宽松标题正则：容忍 `##  Governance Rules` 双空格等排版漂移 */
+const GOVERNANCE_HEADING_LOOSE_RE = new RegExp(`^##\\s+${GOVERNANCE_HEADING_TEXT}`, 'm');
+
+/** 严格标题正则：精确拼写 + 行尾锚定（行尾仅容忍空白） */
+const GOVERNANCE_HEADING_STRICT_RE = new RegExp(`^${GOVERNANCE_HEADING}[ \\t]*$`, 'gm');
+
+/** 约束标记裸文本（去注释壳），宽松谓词按「标记文本在场」判定，容忍壳残缺 */
+const CONSTRAINTS_START_TEXT = CONSTRAINTS_START_MARKER.replace(/^<!--\s*|\s*-->$/g, '');
+
+/**
+ * 宽松谓词：内容里是否有治理契约在场——标题宽松匹配或 HARNESS 约束标记
+ * 文本在场即算。fail-open 偏向：排版漂移宁可信其有，漏报「约束正本静默
+ * 丢失」的代价高于误报。消费方：governance_presence / sync-docs 治理计数 /
+ * init 落点路由（#83）。
+ */
+export function hasGovernanceContract(content: string): boolean {
+  return GOVERNANCE_HEADING_LOOSE_RE.test(content) || content.includes(CONSTRAINTS_START_TEXT);
+}
+
+/**
+ * 严格计数：全文统计治理标题数（精确拼写 + 行尾锚定），drift 重复章节
+ * 检测专用。宽松变体（如双空格）不计入——在场判定与正本计数是两个问题，
+ * 见 GOVERNANCE_HEADING。
+ */
+export function countGovernanceHeadings(content: string): number {
+  return (content.match(GOVERNANCE_HEADING_STRICT_RE) ?? []).length;
+}
+
+/**
+ * PRESERVE 标记块存在性判定：块存在且块体非空（governance_presence 在场
+ * 守护消费，#83 收编其手写切片）。标记契约与 sync-docs/preserve-block 一致：
+ * 首尾标记均须独占一行——开始标记行首锚定（行尾仅空白），结束标记行 trim
+ * 后等于标记文本。结束标记嵌在行中 / 缺失 / 乱序均为畸形块 → false，在场
+ * 守护按契约丢失报警（原 presence「行中结束标记也算在场」显式收紧，#83）。
+ * name 仅允许字母/数字/下划线/连字符（PRESERVE 命名约定，调用方传常量段名）。
+ */
+export function hasPreserveBlock(content: string, name: string): boolean {
+  const beginMarker = `<!-- PRESERVE:${name} -->`;
+  const endMarker = `<!-- /PRESERVE:${name} -->`;
+  const lines = content.split('\n');
+  const begin = lines.findIndex(line => line.trimEnd() === beginMarker);
+  if (begin === -1) return false;
+  let end = -1;
+  for (let j = begin + 1; j < lines.length; j++) {
+    if (lines[j].trim() === endMarker) {
+      end = j;
+      break;
+    }
+  }
+  if (end === -1) return false;
+  return lines.slice(begin + 1, end).join('\n').trim().length > 0;
+}

package/src/core/constraints/usage-report.ts

@@ -13,6 +13,7 @@ import * as path from 'path';
 import type { Constraint } from '../../types/constraint';
 import type { ExecutionTrace } from '../../types/trace';
 import { DEFAULT_TRACE_FILE } from '../../types/trace';
+import { readJsonl } from '../../utils/jsonl';
 import { getEffectiveConstraints, lintEffectiveConfig } from '../effective-constraints';
 import type { EffectiveConfigLint } from '../effective-constraints';
 
@@ -67,6 +68,14 @@ export interface RetireCandidate {
   reason: string;
 }
 
+/** 候选种类的呈现名（constraints report / retire 共用） */
+export const CANDIDATE_KIND_LABEL: Record<RetireCandidateKind, string> = {
+  zero_trigger: '零触发',
+  unevaluable: '不可评估',
+  high_noise: '高噪',
+  zero_intercept: '零拦截',
+};
+
 /**
  * 候选诊断阈值（CLI 可覆盖）
  */
@@ -99,27 +108,36 @@ export interface ConstraintsUsageReport {
   lint: EffectiveConfigLint;
   /** trace 文件是否存在 */
   traceFileExists: boolean;
+  /**
+   * trace 文件被跳过的坏行数（harness#100，与 `traceFileExists` 同一降级维度）
+   *
+   * 恒有值，0 = 无损坏。文件级口径：坏行没有 timestamp，归不进任何统计窗口。
+   */
+  skippedLines: number;
 }
 
 /**
- * 读取项目 traces.log（只读，容错：坏行跳过）
+ * 读取项目 traces.log 并带出坏行计数（只读，harness#100 报告入口）
+ *
+ * 坏行策略：skip（原语义不变——report 只读，不因单行损坏失败）；
+ * 计数去向：透传——`skippedLines` 随本方法返回，进 `ConstraintsUsageReport.skippedLines`，
+ * 消费面为 `constraints report` 的文本行 / `--json` 字段 / `--export` 摘要。
+ */
+export function readProjectTracesReport(projectRoot: string): { traces: ExecutionTrace[]; skippedLines: number } {
+  const { records, skippedLines } = readJsonl<ExecutionTrace>(
+    path.join(projectRoot, DEFAULT_TRACE_FILE),
+    'skip'
+  );
+  return { traces: records, skippedLines };
+}
+
+/**
+ * 读取项目 traces.log（只读）
+ *
+ * 兼容签名：只返回记录数组、丢坏行计数，需要计数的消费方走 `readProjectTracesReport()`。
  */
 export function readProjectTraces(projectRoot: string): ExecutionTrace[] {
-  const tracePath = path.join(projectRoot, DEFAULT_TRACE_FILE);
-  if (!fs.existsSync(tracePath)) return [];
-
-  const content = fs.readFileSync(tracePath, 'utf-8');
-  const traces: ExecutionTrace[] = [];
-  for (const line of content.split('\n')) {
-    const trimmed = line.trim();
-    if (!trimmed) continue;
-    try {
-      traces.push(JSON.parse(trimmed) as ExecutionTrace);
-    } catch {
-      // 坏行跳过（report 只读，不因单行损坏失败）
-    }
-  }
-  return traces;
+  return readProjectTracesReport(projectRoot).traces;
 }
 
 /**
@@ -234,7 +252,7 @@ export function buildConstraintsUsageReport(
   const activePromptIds = effective.filter(c => c.kind === 'prompt').map(c => c.id);
 
   const tracePath = path.join(projectRoot, DEFAULT_TRACE_FILE);
-  const traces = readProjectTraces(projectRoot);
+  const { traces, skippedLines } = readProjectTracesReport(projectRoot);
   const usage = collectUsageByConstraint(traces);
 
   const stats = checkConstraints.map(c => toStats(c.id, c.level, usage.get(c.id)));
@@ -247,5 +265,6 @@ export function buildConstraintsUsageReport(
     activePromptIds,
     lint,
     traceFileExists: fs.existsSync(tracePath),
+    skippedLines,
   };
 }

package/src/core/index.ts

@@ -84,13 +84,15 @@ export type {
   SpecType,
 } from '../types/spec';
 
-// 项目配置加载器
+// 项目配置加载器（governance 段读取一律经访问器，禁止消费方手写钻取）
 export {
   ProjectConfigLoader,
   loadRawProjectConfig,
+  getGovernanceConfig,
+  resolveContextFiles,
   getCapabilitiesMode,
 } from './project-config-loader';
-export type { CapabilitiesMode } from './project-config-loader';
+export type { CapabilitiesMode, ContextFilesResolution } from './project-config-loader';
 
 // 生效约束集（ADR-0001：唯一生效集来源）
 export {

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

@@ -14,6 +14,7 @@ import type {
   CustomConstraintDefinition,
   MergedConstraintsConfig,
   CapabilitiesConfig,
+  GovernanceConfig,
 } from '../types/project-config';
 import { IRON_LAWS, GUIDELINES, PROMPTS } from './constraints/definitions';
 import { PRESETS_BY_NAME, STANDARD_PRESET } from '../presets';
@@ -78,20 +79,59 @@ export function loadRawProjectConfig(projectPath: string): Record<string, unknow
 export type CapabilitiesMode = NonNullable<CapabilitiesConfig['mode']>;
 
 /**
- * 读取 governance.capabilities.mode（缺省 'file'，向后兼容）
+ * 读取 governance 段（全仓唯一手写钻取点，工单 84）
  *
- * 配置缺失/解析失败/取值非法时一律回落 'file'。
+ * 基于 loadRawProjectConfig 的进程级 memoize，不引入第二次 yaml 解析。
+ * 配置缺失 / 解析失败 / 形状不符时返回 undefined，由调用方按未配置处理。
  */
-export function getCapabilitiesMode(projectPath: string): CapabilitiesMode {
+export function getGovernanceConfig(projectPath: string): GovernanceConfig | undefined {
   try {
     const raw = loadRawProjectConfig(projectPath);
-    const governance = raw?.governance as Record<string, unknown> | undefined;
-    const capabilities = governance?.capabilities as Record<string, unknown> | undefined;
-    const mode = capabilities?.mode;
-    if (mode === 'file' || mode === 'module' || mode === 'listing') return mode;
+    const governance = raw?.governance;
+    if (governance === null || typeof governance !== 'object') return undefined;
+    return governance as GovernanceConfig;
   } catch {
-    // 配置缺失或解析失败，按默认 file 处理
+    return undefined;
   }
+}
+
+/**
+ * governance.context_files 三态分辨率（工单 84 triage 裁决口径）
+ *
+ * - unconfigured：段缺失 / enabled 为假 / 解析失败——约定未采用
+ * - enabled-empty：enabled 但 required_dirs 缺失、非数组、含非字符串项或空——
+ *   约定已立但无可用目标
+ * - enabled：enabled 且 required_dirs 为非空字符串数组——约定有效
+ */
+export type ContextFilesResolution =
+  | { state: 'unconfigured' }
+  | { state: 'enabled-empty' }
+  | { state: 'enabled'; dirs: string[] };
+
+/**
+ * 分辨 governance.context_files 三态（语义见 ContextFilesResolution）
+ *
+ * 消费方约定：约束 checker 对前两态一律 skip（与 ADR-0001 存在性探测同构）；
+ * init / 扫描类工具流的自动探测回落保留在调用方，不进本访问器。
+ * 元素类型在此收口：脏配置（如 required_dirs: [1]）不得流入调用方 path.join。
+ */
+export function resolveContextFiles(projectPath: string): ContextFilesResolution {
+  const contextFiles = getGovernanceConfig(projectPath)?.context_files;
+  if (!contextFiles?.enabled) return { state: 'unconfigured' };
+  const dirs = contextFiles.required_dirs;
+  if (!Array.isArray(dirs) || dirs.length === 0) return { state: 'enabled-empty' };
+  if (!dirs.every(dir => typeof dir === 'string')) return { state: 'enabled-empty' };
+  return { state: 'enabled', dirs };
+}
+
+/**
+ * 读取 governance.capabilities.mode（缺省 'file'，向后兼容）
+ *
+ * 配置缺失/解析失败/取值非法时一律回落 'file'。
+ */
+export function getCapabilitiesMode(projectPath: string): CapabilitiesMode {
+  const mode = getGovernanceConfig(projectPath)?.capabilities?.mode;
+  if (mode === 'file' || mode === 'module' || mode === 'listing') return mode;
   return 'file';
 }
 
@@ -228,7 +268,7 @@ export class ProjectConfigLoader {
 
     // 2. 添加自定义约束（config.yml 禁用的 id 不追加：step 1 已将其
     // 收集进 disabled，custom 在 step 1 时尚未入桶，须在此兜底跳过；
-    // 条目带 retired 元数据的同样不追加——#82 D6 退役落点在条目自身）
+    // 条目带 retired 元数据的同样不追加——studio#82 D6 退役落点在条目自身）
     for (const [id, customDef] of Object.entries(this.customConstraints)) {
       if (result.disabled.includes(id) || customDef.retired) {
         continue;

package/src/core/validators/__tests__/passes-gate.test.ts

@@ -1,8 +1,9 @@
 /**
  * Tests for passes-gate.ts
  *
- * Priority: test pure logic methods (check, extractCoverage, extractFailures, extension management)
+ * Priority: test pure logic methods (check)
  * Skip methods that do real file I/O / exec (setPasses, runTests, runTest, detectTestCommand, etc.)
+ * 测试产物解析判定不在此面：见 test-output.test.ts（ADR-0012）
  */
 
 import { PassesGate, createPassesGate } from '../passes-gate';
@@ -67,65 +68,10 @@ describe('PassesGate', () => {
     });
   });
 
-  describe('extension management', () => {
-    it('registerExtension adds an extension', () => {
-      const gate = createPassesGate();
-      const ext = { name: 'e2e', run: async () => ({ passed: true, command: 'e2e' }) };
-      gate.registerExtension('e2e', ext);
-      expect(gate.getExtensionNames()).toContain('e2e');
-    });
-
-    it('unregisterExtension removes an extension', () => {
-      const gate = createPassesGate();
-      const ext = { name: 'e2e', run: async () => ({ passed: true, command: 'e2e' }) };
-      gate.registerExtension('e2e', ext);
-      const removed = gate.unregisterExtension('e2e');
-      expect(removed).toBe(true);
-      expect(gate.getExtensionNames()).not.toContain('e2e');
-    });
-
-    it('unregisterExtension returns false for non-existent extension', () => {
-      const gate = createPassesGate();
-      const removed = gate.unregisterExtension('nonexistent');
-      expect(removed).toBe(false);
-    });
-
-    it('getExtensionNames returns empty array when no extensions', () => {
-      const gate = createPassesGate();
-      expect(gate.getExtensionNames()).toEqual([]);
-    });
-
-    it('getExtensionNames returns multiple extension names', () => {
-      const gate = createPassesGate();
-      gate.registerExtension('a', { name: 'a', run: async () => ({ passed: true, command: 'a' }) });
-      gate.registerExtension('b', { name: 'b', run: async () => ({ passed: true, command: 'b' }) });
-      const names = gate.getExtensionNames();
-      expect(names).toContain('a');
-      expect(names).toContain('b');
-      expect(names).toHaveLength(2);
-    });
-  });
-
   describe('getTestResult', () => {
     it('returns undefined for unknown task', () => {
       const gate = createPassesGate();
       expect(gate.getTestResult('unknown')).toBeUndefined();
     });
   });
-
-  describe('extractCoverage (via extractCoverage private method behavior check)', () => {
-    // extractCoverage is private but we can infer behavior through public API
-    // runTest uses it internally — but that method is not easily testable without mocking exec
-    it('PassesGate instance is properly constructed', () => {
-      const gate = createPassesGate({ testCommand: 'npm test' });
-      expect(gate).toBeInstanceOf(PassesGate);
-    });
-  });
-
-  describe('extractFailures (via extractFailures private method behavior check)', () => {
-    it('PassesGate handles config properly', () => {
-      const gate = createPassesGate({ allowPartialPass: true, maxRetries: 0, retryDelay: 0 });
-      expect(gate).toBeInstanceOf(PassesGate);
-    });
-  });
 });