@dommaker/harness 1.3.0 → 1.4.0

package/src/cli/commands/update-user-model.ts

@@ -22,10 +22,12 @@ import * as path from 'path';
 import * as os from 'os';
 import {
   readTranscriptSessions,
+  type TranscriptFilter,
   extractCorrectionMatches,
   cleanCorrectionConcept,
   jaccardChinese,
 } from '../session-mining';
+import { log, processIO, type CommandIO, type CommandResult } from '../command-contract';
 
 export interface UpdateUserModelOptions {
   days?: number;    // 只处理最近 N 天（自然日，含今天）的会话；缺省不过滤（向后兼容）
@@ -51,7 +53,7 @@ interface ModelState {
 const STATE_FILE = path.join(os.homedir(), '.claude', 'user-model-state.json');
 const PROFILE_FILE = path.join(os.homedir(), '.claude', 'projects', '-root-projects', 'memory', 'user_profile.md');
 
-export async function updateUserModel(options: UpdateUserModelOptions): Promise<void> {
+export async function updateUserModel(options: UpdateUserModelOptions, io: CommandIO = processIO): Promise<CommandResult> {
   const transcriptDir = process.env.CLAUDE_TRANSCRIPTS_DIR
     || path.join(os.homedir(), '.claude', 'projects', '-root--claude');
 
@@ -61,8 +63,8 @@ export async function updateUserModel(options: UpdateUserModelOptions): Promise<
   // 2. Scan new data
   const newSessions = findNewSessions(transcriptDir, state.sessionsProcessed, options.days);
   if (newSessions.length === 0) {
-    console.log(chalk.gray('No new sessions to process'));
-    return;
+    log(io, chalk.gray('No new sessions to process'));
+    return { kind: 'skip', reason: '没有新会话可处理' };
   }
 
   // 3. Extract signals from new data
@@ -94,12 +96,13 @@ export async function updateUserModel(options: UpdateUserModelOptions): Promise<
 
   // 6. Output
   if (options.json) {
-    console.log(JSON.stringify({ newSessions: newSessions.length, changes }, null, 2));
-    return;
+    log(io, JSON.stringify({ newSessions: newSessions.length, changes }, null, 2));
+    return { kind: 'ok' };
   }
 
-  console.log(chalk.blue(`📊 Processed ${newSessions.length} new sessions\n`));
-  printChanges(changes, signals);
+  log(io, chalk.blue(`📊 Processed ${newSessions.length} new sessions\n`));
+  printChanges(changes, signals, io);
+  return { kind: 'ok' };
 }
 
 // ── State I/O ──
@@ -139,17 +142,20 @@ interface SimpleSession {
 }
 
 function findNewSessions(dir: string, processed: string[], days?: number): SimpleSession[] {
-  let sessions = readTranscriptSessions(dir)
-    .filter(s => !processed.includes(s.id));
+  // 过滤下推 seam（harness#112）：excludeIds 走文件名、since 走 stat，未命中不 parse
+  const filter: TranscriptFilter = { excludeIds: processed };
 
   // 「最近 N 天」：自然日窗口（含今天）。days<=0 视为不过滤，与缺省一致。
+  // date 是 mtime 的 UTC 日，date >= cutoff ⟺ mtimeMs >= cutoff 日 UTC 零点
   if (days !== undefined && days > 0) {
     const cutoff = new Date(Date.now() - (days - 1) * 86_400_000)
       .toISOString()
       .slice(0, 10);
-    sessions = sessions.filter(s => s.date >= cutoff);
+    filter.since = Date.parse(cutoff);
   }
 
+  const sessions = readTranscriptSessions(dir, filter);
+
   sessions.sort((a, b) => a.date.localeCompare(b.date));
 
   return sessions.map(s => ({
@@ -329,6 +335,8 @@ function applySignals(state: ModelState, signals: SessionSignals[], mergedConcep
   const now = new Date().toISOString().slice(0, 10);
 
   // Update patterns from merged concept clusters
+  // occurrences 唯一来源：mergedConcepts 聚合值（含 correction phrase 的 ×3 加权，
+  // 见 buildMergedConcepts）。不再叠加 per-session 原始 count —— 那是 #113 裁决的双计 bug。
   for (const [concept, agg] of Object.entries(mergedConcepts)) {
     if (!state.patterns[concept]) {
       state.patterns[concept] = {
@@ -344,26 +352,6 @@ function applySignals(state: ModelState, signals: SessionSignals[], mergedConcep
     p.trend = p.occurrences >= 5 ? 'stable' : 'rising';
   }
 
-  // Also track per-session concepts
-  for (const sig of signals) {
-    for (const [concept, count] of Object.entries(sig.concepts)) {
-      if (!state.patterns[concept]) {
-        state.patterns[concept] = {
-          firstSeen: now,
-          occurrences: 0,
-          sessions: [],
-          trend: 'new',
-          lastSeen: now,
-        };
-      }
-      const p = state.patterns[concept];
-      p.occurrences += count;
-      if (!p.sessions.includes(sig.sessionId)) p.sessions.push(sig.sessionId);
-      p.lastSeen = now;
-      p.trend = p.occurrences >= 5 ? 'stable' : 'rising';
-    }
-  }
-
   // Update lens weights from correction signals
   for (const sig of signals) {
     if (sig.correctionPhrases.length > 0) {
@@ -430,9 +418,9 @@ function updateProfile(state: ModelState): void {
 
 // ── Output ──
 
-function printChanges(changes: Change[], signals: SessionSignals[]): void {
+function printChanges(changes: Change[], signals: SessionSignals[], io: CommandIO): void {
   if (changes.length === 0) {
-    console.log(chalk.green('No significant changes detected'));
+    log(io, chalk.green('No significant changes detected'));
     return;
   }
 
@@ -443,31 +431,31 @@ function printChanges(changes: Change[], signals: SessionSignals[]): void {
   };
 
   if (byType.new_pattern.length > 0) {
-    console.log(chalk.yellow(`🌱 New patterns: ${byType.new_pattern.length}`));
+    log(io, chalk.yellow(`🌱 New patterns: ${byType.new_pattern.length}`));
     for (const c of byType.new_pattern.slice(0, 5)) {
-      console.log(chalk.gray(`   ${c.key}: ${c.detail}`));
+      log(io, chalk.gray(`   ${c.key}: ${c.detail}`));
     }
-    console.log();
+    log(io);
   }
 
   if (byType.rising.length > 0) {
-    console.log(chalk.green(`📈 Re-emerging: ${byType.rising.length}`));
+    log(io, chalk.green(`📈 Re-emerging: ${byType.rising.length}`));
     for (const c of byType.rising.slice(0, 5)) {
-      console.log(chalk.gray(`   ${c.key}: ${c.detail}`));
+      log(io, chalk.gray(`   ${c.key}: ${c.detail}`));
     }
-    console.log();
+    log(io);
   }
 
   if (byType.lens_shift.length > 0) {
-    console.log(chalk.cyan(`🎯 Lens shifts:`));
+    log(io, chalk.cyan(`🎯 Lens shifts:`));
     for (const c of byType.lens_shift) {
-      console.log(chalk.gray(`   ${c.key}: ${c.detail}`));
+      log(io, chalk.gray(`   ${c.key}: ${c.detail}`));
     }
-    console.log();
+    log(io);
   }
 
-  console.log(chalk.bold(`Total signals processed:`));
-  console.log(`  Sessions: ${signals.length}`);
-  console.log(`  Correction phrases: ${signals.reduce((s, sig) => s + sig.correctionPhrases.length, 0)}`);
-  console.log(`  Concepts extracted: ${signals.reduce((s, sig) => s + Object.keys(sig.concepts).length, 0)}`);
+  log(io, chalk.bold(`Total signals processed:`));
+  log(io, `  Sessions: ${signals.length}`);
+  log(io, `  Correction phrases: ${signals.reduce((s, sig) => s + sig.correctionPhrases.length, 0)}`);
+  log(io, `  Concepts extracted: ${signals.reduce((s, sig) => s + Object.keys(sig.concepts).length, 0)}`);
 }

package/src/cli/commands/validate.ts

@@ -10,6 +10,7 @@ import * as path from 'path';
 import * as yaml from 'js-yaml';
 import { CheckpointValidator } from '../../core/validators/checkpoint';
 import type { Checkpoint, CheckpointContext } from '../../types/checkpoint';
+import { log, processIO, type CommandIO, type CommandResult } from '../command-contract';
 
 export interface ValidateOptions {
   /** 检查点文件路径 */
@@ -28,13 +29,13 @@ const DEFAULT_CHECKPOINT_FILE = '.harness/checkpoints.yml';
 /**
  * 加载检查点配置
  */
-async function loadCheckpoints(filePath: string): Promise<Checkpoint[]> {
+async function loadCheckpoints(filePath: string, io: CommandIO): Promise<Checkpoint[]> {
   try {
     const content = await fs.readFile(filePath, 'utf-8');
     const data = yaml.load(content) as { checkpoints?: Checkpoint[] };
     return data.checkpoints || [];
   } catch (error) {
-    console.log(chalk.yellow(`⚠️  未找到检查点文件: ${filePath}`));
+    log(io, chalk.yellow(`⚠️  未找到检查点文件: ${filePath}`));
     return [];
   }
 }
@@ -42,23 +43,26 @@ async function loadCheckpoints(filePath: string): Promise<Checkpoint[]> {
 /**
  * 执行检查点验证
  */
-export async function validate(options: ValidateOptions): Promise<void> {
-  console.log(chalk.blue('🔍 验证检查点...'));
+export async function validate(
+  options: ValidateOptions,
+  io: CommandIO = processIO,
+): Promise<CommandResult> {
+  log(io, chalk.blue('🔍 验证检查点...'));
 
   const projectPath = options.projectPath || process.cwd();
   const checkpointFile = options.file || path.join(projectPath, DEFAULT_CHECKPOINT_FILE);
 
   // 加载检查点
-  const checkpoints = await loadCheckpoints(checkpointFile);
+  const checkpoints = await loadCheckpoints(checkpointFile, io);
 
   if (checkpoints.length === 0) {
-    console.log(chalk.gray('没有定义检查点，跳过验证'));
-    return;
+    log(io, chalk.gray('没有定义检查点，跳过验证'));
+    return { kind: 'skip', reason: `没有定义检查点: ${checkpointFile}` };
   }
 
-  console.log(chalk.gray(`检查点文件: ${checkpointFile}`));
-  console.log(chalk.gray(`检查点数量: ${checkpoints.length}`));
-  console.log();
+  log(io, chalk.gray(`检查点文件: ${checkpointFile}`));
+  log(io, chalk.gray(`检查点数量: ${checkpoints.length}`));
+  log(io);
 
   // 构建上下文
   const context: CheckpointContext = {
@@ -69,20 +73,22 @@ export async function validate(options: ValidateOptions): Promise<void> {
   // 执行验证
   const validator = CheckpointValidator.getInstance();
   const results = [];
+  const failedIds: string[] = [];
 
   for (const checkpoint of checkpoints) {
     const result = await validator.validate(checkpoint, context);
     results.push(result);
 
     if (result.passed) {
-      console.log(chalk.green(`✅ ${checkpoint.id}: 通过`));
+      log(io, chalk.green(`✅ ${checkpoint.id}: 通过`));
     } else {
-      console.log(chalk.red(`❌ ${checkpoint.id}: 失败`));
+      log(io, chalk.red(`❌ ${checkpoint.id}: 失败`));
       result.checks.forEach(check => {
         if (!check.passed) {
-          console.log(chalk.red(`   - ${check.checkId}: ${check.message || check.error}`));
+          log(io, chalk.red(`   - ${check.checkId}: ${check.message || check.error}`));
         }
       });
+      failedIds.push(checkpoint.id);
     }
   }
 
@@ -90,16 +96,16 @@ export async function validate(options: ValidateOptions): Promise<void> {
   const passed = results.filter(r => r.passed).length;
   const failed = results.filter(r => !r.passed).length;
 
-  console.log();
-  console.log(chalk.gray(`通过: ${passed}/${results.length}`));
+  log(io);
+  log(io, chalk.gray(`通过: ${passed}/${results.length}`));
 
   if (failed > 0) {
-    console.log(chalk.red(`\n🛑 ${failed} 个检查点未通过`));
+    log(io, chalk.red(`\n🛑 ${failed} 个检查点未通过`));
     // 工单 23：门控语义——检查点失败一律非零退出（此前仅 --strict 退出，钩子/CI 形同虚设）
-    process.exit(1);
-  } else {
-    console.log(chalk.green('\n✅ 所有检查点验证通过'));
+    return { kind: 'fail', reason: `${failed} 个检查点未通过: ${failedIds.join(', ')}` };
   }
+  log(io, chalk.green('\n✅ 所有检查点验证通过'));
+  return { kind: 'ok' };
 }
 
 /**
@@ -138,14 +144,14 @@ export const DEFAULT_CHECKPOINTS: Checkpoint[] = [
 /**
  * 创建示例检查点文件
  */
-export async function createExampleCheckpoint(projectPath: string): Promise<void> {
+export async function createExampleCheckpoint(projectPath: string, io: CommandIO = processIO): Promise<void> {
   const filePath = path.join(projectPath, DEFAULT_CHECKPOINT_FILE);
   const dir = path.dirname(filePath);
 
   // 如果已存在，不覆盖
   try {
     await fs.access(filePath);
-    console.log(chalk.gray(`checkpoints.yml 已存在，跳过`));
+    log(io, chalk.gray(`checkpoints.yml 已存在，跳过`));
     return;
   } catch {
     // 文件不存在，创建
@@ -156,7 +162,7 @@ export async function createExampleCheckpoint(projectPath: string): Promise<void
   const content = yaml.dump({ checkpoints: DEFAULT_CHECKPOINTS }, { indent: 2 });
   await fs.writeFile(filePath, content, 'utf-8');
 
-  console.log(chalk.green(`✅ 已创建示例检查点文件: ${filePath}`));
+  log(io, chalk.green(`✅ 已创建示例检查点文件: ${filePath}`));
 }
 
 /**
@@ -180,14 +186,14 @@ const DEFAULT_RESOLUTIONS = {
 /**
  * 创建示例 Resolutions 文件（RKB dogfood）
  */
-export async function createExampleResolutions(projectPath: string): Promise<void> {
+export async function createExampleResolutions(projectPath: string, io: CommandIO = processIO): Promise<void> {
   const harnessDir = path.join(projectPath, '.harness');
   const filePath = path.join(harnessDir, 'resolutions.json');
 
   // 如果已存在，不覆盖
   try {
     await fs.access(filePath);
-    console.log(chalk.gray(`resolutions.json 已存在，跳过`));
+    log(io, chalk.gray(`resolutions.json 已存在，跳过`));
     return;
   } catch {
     // 文件不存在，创建
@@ -198,5 +204,5 @@ export async function createExampleResolutions(projectPath: string): Promise<voi
   const content = JSON.stringify(DEFAULT_RESOLUTIONS, null, 2);
   await fs.writeFile(filePath, content, 'utf-8');
 
-  console.log(chalk.green(`✅ 已创建 Resolutions 文件: ${filePath}`));
+  log(io, chalk.green(`✅ 已创建 Resolutions 文件: ${filePath}`));
 }

package/src/cli/session-mining/__tests__/transcript.test.ts

@@ -0,0 +1,118 @@
+/**
+ * readTranscriptSessions 坏行/null 记录容错测试（harness#82）
+ *
+ * transcript 行可 parse 但值为 null（或提取异常）时，
+ * 与原逐行 catch 实现一致：该条跳过，不影响其余记录。
+ */
+
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { readTranscriptSessions } from '../transcript';
+
+describe('readTranscriptSessions 坏行容错（harness#82）', () => {
+  let dir: string;
+
+  beforeEach(() => {
+    dir = fs.mkdtempSync(path.join(os.tmpdir(), 'harness-transcript-'));
+  });
+
+  afterEach(() => {
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  it('null 行与坏行只丢该行，合法 turn 照常提取', () => {
+    const lines = [
+      JSON.stringify({ message: { role: 'user', content: 'hello' } }),
+      'null', // parse 合法但值为 null，原实现经逐行 catch 跳过
+      '{"broken',
+      JSON.stringify({ message: { role: 'assistant', content: [{ type: 'text', text: 'hi' }] } }),
+    ];
+    fs.writeFileSync(path.join(dir, 'session-a.jsonl'), lines.join('\n') + '\n', 'utf-8');
+
+    const sessions = readTranscriptSessions(dir);
+    expect(sessions).toHaveLength(1);
+    expect(sessions[0].turns.map(t => t.role)).toEqual(['user', 'assistant']);
+    expect(sessions[0].turns[1].content).toBe('hi');
+  });
+
+  it('目录不可读返回空数组', () => {
+    expect(readTranscriptSessions(path.join(dir, 'missing'))).toEqual([]);
+  });
+});
+
+describe('readTranscriptSessions 过滤（harness#112）', () => {
+  let dir: string;
+
+  beforeEach(() => {
+    dir = fs.mkdtempSync(path.join(os.tmpdir(), 'harness-transcript-filter-'));
+  });
+
+  afterEach(() => {
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  function writeSession(name: string, text: string, mtime?: Date): void {
+    const p = path.join(dir, name);
+    fs.writeFileSync(
+      p,
+      JSON.stringify({ message: { role: 'user', content: text } }) + '\n',
+      'utf-8',
+    );
+    if (mtime) fs.utimesSync(p, mtime, mtime);
+  }
+
+  it('excludeIds：命中的会话不进结果（文件名级过滤，不 parse）', () => {
+    writeSession('session-a.jsonl', '甲会话内容');
+    writeSession('session-b.jsonl', '乙会话内容');
+
+    const sessions = readTranscriptSessions(dir, { excludeIds: ['session-a'] });
+    expect(sessions.map(s => s.id)).toEqual(['session-b']);
+  });
+
+  it('excludeIds 按截断 40 字符的会话 ID 匹配', () => {
+    const longName = 'a'.repeat(50);
+    writeSession(`${longName}.jsonl`, '长名会话内容');
+    writeSession('session-b.jsonl', '乙会话内容');
+
+    const sessions = readTranscriptSessions(dir, { excludeIds: [longName.slice(0, 40)] });
+    expect(sessions.map(s => s.id)).toEqual(['session-b']);
+  });
+
+  it('since：mtimeMs 早于窗口的文件不进结果（stat 级过滤，不 parse）', () => {
+    writeSession('old.jsonl', '旧会话内容', new Date(Date.now() - 30 * 86_400_000));
+    writeSession('recent.jsonl', '新会话内容');
+
+    const since = Date.now() - 7 * 86_400_000;
+    const sessions = readTranscriptSessions(dir, { since });
+    expect(sessions.map(s => s.id)).toEqual(['recent']);
+  });
+
+  it('since 边界含等于：mtimeMs == since 仍计入', () => {
+    const t = new Date('2026-08-01T12:00:00.000Z');
+    writeSession('edge.jsonl', '边界会话内容', t);
+
+    const sessions = readTranscriptSessions(dir, { since: t.getTime() });
+    expect(sessions.map(s => s.id)).toEqual(['edge']);
+  });
+
+  it('since 与 excludeIds 可叠加', () => {
+    writeSession('old.jsonl', '旧会话内容', new Date(Date.now() - 30 * 86_400_000));
+    writeSession('excluded.jsonl', '被排除会话');
+    writeSession('kept.jsonl', '保留会话内容');
+
+    const sessions = readTranscriptSessions(dir, {
+      since: Date.now() - 7 * 86_400_000,
+      excludeIds: ['excluded'],
+    });
+    expect(sessions.map(s => s.id)).toEqual(['kept']);
+  });
+
+  it('无 filter：全量读取（向后兼容）', () => {
+    writeSession('a.jsonl', '甲会话内容', new Date(Date.now() - 30 * 86_400_000));
+    writeSession('b.jsonl', '乙会话内容');
+
+    const sessions = readTranscriptSessions(dir);
+    expect(sessions).toHaveLength(2);
+  });
+});

package/src/cli/session-mining/transcript.ts

@@ -7,6 +7,7 @@
 
 import * as fs from 'fs';
 import * as path from 'path';
+import { readJsonl } from '../../utils/jsonl';
 
 export interface MinedTurn {
   role: string;
@@ -41,8 +42,18 @@ function extractText(content: unknown): string {
  *
  * 不可读/损坏的行静默跳过（与原实现一致）。
  */
-export function readTranscriptSessions(dir: string): MinedSession[] {
+export interface TranscriptFilter {
+  /** 只读 mtimeMs >= since 的文件（stat 级过滤，命中即不 parse）；缺省不过滤 */
+  since?: number;
+  /** 按会话 ID（文件名去 .jsonl、截断 40 字符）排除（文件名级过滤，不 stat 不 parse）；缺省不排除 */
+  excludeIds?: string[];
+}
+
+export function readTranscriptSessions(dir: string, filter: TranscriptFilter = {}): MinedSession[] {
   const sessions: MinedSession[] = [];
+  const exclude = filter.excludeIds && filter.excludeIds.length > 0
+    ? new Set(filter.excludeIds)
+    : undefined;
 
   let files: string[];
   try {
@@ -53,6 +64,8 @@ export function readTranscriptSessions(dir: string): MinedSession[] {
 
   for (const file of files) {
     if (!file.endsWith('.jsonl')) continue;
+    const id = file.replace('.jsonl', '').slice(0, 40);
+    if (exclude?.has(id)) continue;
     const filePath = path.join(dir, file);
 
     let stat: fs.Stats;
@@ -61,21 +74,26 @@ export function readTranscriptSessions(dir: string): MinedSession[] {
     } catch {
       continue;
     }
+    if (filter.since !== undefined && stat.mtimeMs < filter.since) continue;
 
     const turns: MinedTurn[] = [];
     const toolCalls: string[] = [];
 
-    let content: string;
+    let records: Record<string, any>[];
     try {
-      content = fs.readFileSync(filePath, 'utf-8');
+      // 损坏行静默跳过（坏行策略 skip，与原实现一致，harness#82 走 jsonl 正本）；
+      // 外层 catch 兜文件不可读，沿用原「跳过该文件」语义
+      // 计数去向：豁免（harness#100）——读的是外部 Claude Code transcript（非 harness 写入面）。
+      // 影响方向如实：坏行使该会话少几条 turn，而 analyze-sessions 的候选按次数阈值筛
+      // （frequency>=4 / 跨会话>=2 / confidence=len/10）→ 只会少出候选，不会造出候选，且候选须人审；
+      // 告知需改 MinedSession 形状并波及 analyze-sessions/update-user-model 两个调用方，另票收口
+      records = readJsonl<Record<string, any>>(filePath, 'skip').records;
     } catch {
       continue;
     }
 
-    for (const line of content.split('\n')) {
-      if (!line.trim()) continue;
+    for (const entry of records) {
       try {
-        const entry = JSON.parse(line);
         const msg = entry.message;
         if (msg?.role && (msg.content || entry.type === 'user')) {
           turns.push({ role: msg.role, content: extractText(msg.content) });
@@ -88,13 +106,13 @@ export function readTranscriptSessions(dir: string): MinedSession[] {
           }
         }
       } catch {
-        // 损坏行跳过
+        // 单条记录提取异常跳过（原逐行 catch 语义：parse 已由 module skip，此处兜提取）
       }
     }
 
     if (turns.length > 0) {
       sessions.push({
-        id: file.replace('.jsonl', '').slice(0, 40),
+        id,
         date: stat.mtime.toISOString().slice(0, 10),
         mtimeMs: stat.mtimeMs,
         turns,

package/src/context/session-manager.ts

@@ -8,6 +8,7 @@
 
 import * as fs from 'fs';
 import * as path from 'path';
+import { readJsonl, appendJsonl } from '../utils/jsonl';
 import { ContextTracker } from '../monitoring/context-tracker';
 import type {
   SessionEvent,
@@ -65,20 +66,12 @@ export class SessionManager {
     // 从磁盘恢复
     const eventsPath = path.join(this.getSessionDir(id), 'events.jsonl');
     try {
-      if (!fs.existsSync(eventsPath)) return undefined;
-
-      const content = fs.readFileSync(eventsPath, 'utf-8');
-      const lines = content.trim().split('\n').filter(Boolean);
-      if (lines.length === 0) return undefined;
-
-      const events: SessionEvent[] = [];
-      for (const line of lines) {
-        try {
-          events.push(JSON.parse(line) as SessionEvent);
-        } catch {
-          // 跳过损坏行
-        }
-      }
+      // 坏行策略：skip（原逐行 catch 跳过语义不变，harness#82）；
+      // 空文件判定保持原始非空行数口径（合法 + 坏行 = 0 才算空）
+      // 计数去向：并进空事件判定的原始行数口径（harness#100 记名豁免：会话恢复面只区分
+      // "有没有事件"，单列坏行数不改变任何输出；会话事件写链在本地，损坏=半写入截断）
+      const { records: events, skippedLines } = readJsonl<SessionEvent>(eventsPath, 'skip');
+      if (events.length + skippedLines === 0) return undefined;
 
       const stat = fs.statSync(eventsPath);
       const handle: SessionHandle = {
@@ -178,22 +171,16 @@ export class SessionManager {
           // 从 events.jsonl 恢复事件
           const eventsPath = path.join(sessionsDir, sessionId, 'events.jsonl');
           if (fs.existsSync(eventsPath)) {
-            const content = fs.readFileSync(eventsPath, 'utf-8');
-            const lines = content.trim().split('\n').filter(Boolean);
-
-            // 只恢复 checkpoint 之前的事件
-            const events = lines
-              .slice(0, checkpointData.eventCount)
-              .map(line => {
-                try {
-                  return JSON.parse(line) as SessionEvent;
-                } catch {
-                  return null;
-                }
-              })
-              .filter((e): e is SessionEvent => e !== null);
-
-            handle.events = events;
+            // 坏行策略：skip（原逐行 null-filter 语义不变，harness#82）；
+            // 只恢复 checkpoint 之前的原始行（head 截断在 parse 之前）；
+            // !== null 沿用原过滤口径
+            // 计数去向：豁免（harness#100）——恢复路径没有用户可见输出面（失败即整体抛
+            // `Checkpoint ${id} 不存在`），坏行只会让恢复出的事件少于 checkpoint 声明数；
+            // 告知需要改 loadCheckpoint 的抛错形状，属行为变更不在本票
+            const { records } = readJsonl<SessionEvent>(eventsPath, 'skip', {
+              head: checkpointData.eventCount,
+            });
+            handle.events = records.filter((e): e is SessionEvent => e !== null);
           }
 
           return handle;
@@ -237,9 +224,8 @@ export class SessionManager {
    */
   private appendEvent(sessionId: string, event: SessionEvent): void {
     try {
-      const eventsPath = path.join(this.getSessionDir(sessionId), 'events.jsonl');
-      const line = JSON.stringify(event) + '\n';
-      fs.appendFileSync(eventsPath, line, 'utf-8');
+      // 写链收口：ensureDir + append（harness#82）
+      appendJsonl(path.join(this.getSessionDir(sessionId), 'events.jsonl'), event);
     } catch {
       // 持久化失败，静默处理
     }

package/src/core/CONTEXT.md

@@ -4,27 +4,30 @@
 约束引擎核心：check/prompt 二元约束系统（ADR-0001）、生效集合并（effective-constraints）、检查点验证器(CSO/passes-gate)、会话管理、Spec 验证器、项目配置加载。
 
 ## 核心导出
-- `constraints/` — 约束定义(IRON_LAWS/GUIDELINES/PROMPTS) + 检查引擎(ConstraintChecker，拦截统一由 checkBeforeExecution 承担，ADR-0004) + 缓存(CheckCache：TTL 缓存 + 计数采样，H6/G5 起公开导出) + 注入渲染(injection-renderer) + Agent prompt 渲染(agent-prompt-renderer：trigger 参数化分组渲染，role 路由留 studio，H6/G6)/漂移校验(injection-drift：含注入段落点路由 resolveInjectionTarget，CLAUDE.md 有标记优先、否则 AGENTS.md PRESERVE:governance，studio #307)/使用统计(usage-report)；CheckEnv 生产侧唯一构造点 `buildCheckEnv(context, providers|'none')`（checkers/types.ts：providers = 证据接线，'none' = 显式不接 → evidence flag checker 按契约 skip）
+- `constraints/` — 约束定义(IRON_LAWS/GUIDELINES/PROMPTS) + 检查引擎(ConstraintChecker，拦截统一由 checkBeforeExecution 承担，ADR-0004) + 缓存(CheckCache：TTL 缓存 + 计数采样，H6/G5 起公开导出) + 注入渲染(injection-renderer) + 落点写入器(injection-writer：「声明→对照→幂等替换」中 marker-range 替换的唯一 writer——replaceStandaloneRange/replaceEnclosedRange/cutMarkerBlock + 半标记守护；落点路由读写两侧同住此模块 resolveInjectionTarget(CLAUDE.md 有标记段优先、否则 AGENTS.md PRESERVE:governance，studio #307)/resolveGovernanceLanding(init 写侧，含旧版无标记 Governance Rules 块豁免)，ADR-0011) + Agent prompt 渲染(agent-prompt-renderer：trigger 参数化分组渲染，role 路由留 studio，H6/G6)/漂移校验(injection-drift：纯检测只读，路由消费 injection-writer)/使用统计(usage-report：constraints report·retire 的只读数据层，读 trace 两个入口——`readProjectTracesReport()` 带 `skippedLines`、`readProjectTraces()` 兼容包装丢计数；报告模型 `ConstraintsUsageReport` 的降级位 = `traceFileExists` + `skippedLines`，harness#100)/清单对照(capabilities-reconcile：CAPABILITIES.md 与代码实况的覆盖/幽灵判定唯一实现，capability_sync·docs_freshness·sync-docs 共消费，ADR-0009)；CheckEnv 生产侧唯一构造点 `buildCheckEnv(context, providers|'none')`（checkers/types.ts：providers = 证据接线，git 两项绑 GitEvidence 实例，'none' = 显式不接 → evidence flag checker 按契约 skip）
+- `git-evidence.ts` — 全仓唯一 git 取证点（#87）：`createGitEvidence(projectPath, run?)` 返回 `GitEvidence{stagedDiff, changedFileNames(staged), headDirs}`，seam 上两个真 adapter（缺省 `realGitCommandRunner` 走真 git / 注入 runner 供计数与替身）。命令级 memo 落在此实例（含失败结果），实例生命周期 = 一次 check run，故 context-builder 与 ConstraintChecker 传同一实例即共用证据；判定语义与迁移前一致（diff 取证失败 → 空串，`git ls-tree` 失败 → null = 所有目录视为新）；`parseHeadDirs`/`splitFileNames` 是配套纯函数
+- `constraints/context-builder.ts` — 只装配不取证：`buildConstraintContext(options.evidence?)` 与 `detectTrigger(options.evidence?)` 经 GitEvidence 取 git 事实（不传 = 自建真 adapter），本模块无 child_process import；其余证据标志（traces/文档标记）仍为本地探测
 - `effective-constraints.ts` — `getEffectiveConstraints(projectRoot, {preset?})`：全仓唯一生效集来源（内置 → preset → config.yml 禁用（内置与 custom 同效）→ custom 追加（禁用/已退役的不追加）→ scenes 过滤）；`getMergedConstraintsConfig(projectRoot, {preset?})`：同链路的完整 MergedConstraintsConfig 形状（含 disabled/custom/unknownIds），内置工单 23 优先级规则（--preset 仅在无项目自定义配置时生效），check 命令经此入口；`lintEffectiveConfig` 配置诊断
 - `effective-set.ts` — `filterEnabledEntries(knownIds, entries, {onUnknownId})`：约束侧（collect）与门禁侧（throw）共用的 config 条目筛选器
-- `validators/` — checkpoints、passes-gate、CSO 验证器
+- `validators/` — checkpoints、passes-gate、CSO 验证器；`test-output.ts` —「测试产物解读」唯一实现：`extractFailures` 提取函数 + `judgeTestRun` 判定入口（退出码为主 + 行首锚定的文本失败信号交叉否决；文本救不回非零退出，`allowPartialPass` 只作用于文本否决那一维），passes-gate 与 `gates/acceptance` 的结论一律从它取、各自体内不写判定 `if`（解析收口 ADR-0012，判定依据 ADR-0014）；**不读覆盖率**——harness 核心判定对覆盖率不取数不执法，判覆盖率的两处（CLI `passes-gate --coverage`、`gates/performance`）各自读 json-summary，`extractCoverage` 与 `TaskTestResult.coverage` 已随 ADR-0015 删除；`PassesGate.runTests(workDir)` 的执行与证据落盘根是**必传形参**，本层不再取 cwd（harness#95，约定正本见 `src/cli/commands/CONTEXT.md`）；`detectTestCommand` 是测试命令探测唯一正本（模块级导出：test:ci → test 排 echo 占位 → test:e2e → test:coverage → Python 标记 pyproject.toml/pytest.ini → go.mod，探不到返回 undefined，兜底归调用方——CLI 映射 skip、PassesGate 内部 fail-closed，不再兜底 'npm test'；CLI 本地版已删，架构评审 A2）；PassesGate 扩展注册表（registerExtension/unregisterExtension/getExtensionNames/runAllTests/checkAllPasses + PassesGateExtension/ExtensionTestResult 两类型与包根导出）已整段删除——零 adapter 假想 seam 且扩展结果本就不参与 allowed 判定，需要扩展测试类型时按 ADR-0014 判例在 `judgeTestRun` 层加，不恢复旧 seam（harness#104，架构评审 B1）；包内模块，不进 `src/index.ts` 导出面
 - `session/` — 会话管理
 - `spec/validator` — SpecValidator
-- `project-config-loader` — 项目配置加载 + 约束合并（mergeConstraints 内含 preset 裁剪：presets/ 纯数据 + 未知名回落 standard，禁用到未知 id 经 effective-set 共享筛选器 collect 模式）
+- `project-config-loader` — 项目配置加载 + 约束合并（mergeConstraints 内含 preset 裁剪：presets/ 纯数据 + 未知名回落 standard，禁用到未知 id 经 effective-set 共享筛选器 collect 模式）；`getGovernanceConfig` 是全仓唯一允许手写钻取 `config.governance` 的点（工单 84），消费方一律经它或经 `resolveContextFiles`（三态：unconfigured / enabled-empty / enabled，dirs 元素类型在此收口）取数据，不得再自己 cast `Record<string, unknown>`；checker 对前两态一律 skip，自动探测回落只属于 init/扫描类工具流调用方
 
 ## 依赖关系
 - 被所有模块依赖（基础层，无上层依赖）
 - 依赖 `src/types/` 类型定义
 - 依赖 `src/utils/` 工具函数
-- 依赖 `src/monitoring/traces` TraceCollector
+- 对 `cli/`、`gates/`、`monitoring/` **零值导入**（type-only 允许）：方向由 eslint.config.mjs 的 `@typescript-eslint/no-restricted-imports`（error 级）锁死，守卫测试见 `src/__tests__/layering.test.ts`（harness#88）
 
 ## 约定
 - 约束定义在 `constraints/definitions/{iron-laws,guidelines,prompts}.ts`，不在运行时代码中定义
 - check 层必须带真实 checker（注册表闭环，引用未注册 checker 构建报错）
 - Iron Law 违规必须 throw ConstraintViolationError
-- 检查器使用单例模式(ConstraintChecker.getInstance())
+- 上行数据一律注入，不在 core 内 require 上层（harness#88）：trace 记录器经 `ConstraintChecker` 构造参数注入（缺省 no-op，`getInstance()`/`constraintChecker` 即未接线的默认实例，只评估不写 trace），真实收集器由组合根接线（CLI check/report、`bootstrapHarness`）；CAPABILITIES.md 能力清单计数经 `capabilities-parser` 的 `CapabilityDefinitionSource` 由 cli 侧注入定义表
+- git 事实只能经 `constraints/git-evidence.ts` 的 adapter 取（#87）：core/cli 内不得出现 `execSync('git …')`；一次 run 一份实例、沿调用链显式传递（CLI check → buildConstraintContext → checkConstraints），memo 既不做成模块级全局也不做成单例字段
 
 ## 注意事项
 - 零 Token 成本：所有分析纯文件操作，无 LLM 调用
 - 约束配置支持 .harness/config.yml 自定义合并（preset 真实生效）
-- 存在性探测约束（capability_sync/docs_freshness/context_doc_sync）在约定文件缺失时 skip，不计 pass/fail
+- 存在性探测约束（capability_sync/docs_freshness/context_doc_sync）在约定文件缺失，或 context_files 约定已立但无目标（enabled-empty）时 skip，不计 pass/fail；context_doc_sync 与 docs_freshness 对三态判定同构（工单 84）