@dommaker/harness 1.7.0 → 1.8.0

package/src/knowledge/import.ts

@@ -269,6 +269,8 @@ export class ColdStartImporter {
 
         if (stat.isDirectory()) {
           // 扫描目录下的 markdown 文件
+          // 口径记名（harness#134）：本 walker 吃的是**项目文档树**（README/docs/），不是知识库树，
+          // 故不适用 tree-walker 的条目排除口径——知识树的 `_index.md`/`.snapshots` 在这里没有对应物。
           const files = fs.readdirSync(fullPath)
             .filter(f => f.endsWith('.md'))
             .slice(0, 10); // 最多 10 个

package/src/knowledge/index-generator.ts

@@ -10,9 +10,7 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import { splitFrontmatter } from '../utils/frontmatter';
-
-const EXCLUDED_DIRS = ['.archive', 'archived', '.snapshots', 'resolutions'];
-const INDEX_FILENAME = '_index.md';
+import { INDEX_MD_FILE, isEntryFile, isInfraDir } from './tree-walker';
 
 interface IndexEntry {
   filename: string;
@@ -37,7 +35,7 @@ export class KnowledgeIndexGenerator {
   regenerate(): string {
     const output = this.generate();
     fs.mkdirSync(this.baseDir, { recursive: true });
-    fs.writeFileSync(path.join(this.baseDir, INDEX_FILENAME), output, 'utf-8');
+    fs.writeFileSync(path.join(this.baseDir, INDEX_MD_FILE), output, 'utf-8');
     return output;
   }
 
@@ -112,10 +110,10 @@ export class KnowledgeIndexGenerator {
       const relPath = relative ? path.join(relative, name) : name;
 
       if (item.isDirectory()) {
-        if (EXCLUDED_DIRS.includes(name)) continue;
+        if (isInfraDir(name)) continue;
         if (name.startsWith('.')) continue;
         results.push(...this.scanFiles(fullPath, relPath));
-      } else if (name.endsWith('.md') && name !== INDEX_FILENAME) {
+      } else if (isEntryFile(name)) {
         results.push(fullPath);
       }
     }

package/src/knowledge/index.ts

@@ -4,7 +4,32 @@
  * Re-exports all knowledge module components.
  */
 
-export * from './types';
+export { DEFAULT_DECAY_CONFIG } from './types';
+export type {
+  KnowledgeSubsystem,
+  MaturityLevel,
+  StorageLayer,
+  ConsumptionMode,
+  KnowledgeOrigin,
+  KnowledgeEntry,
+  SourceRef,
+  ExecutionResult,
+  KnowledgeReference,
+  QueryBudget,
+  QueryResult,
+  QueryFilter,
+  LintIssueType,
+  LintIssue,
+  IngestOptions,
+  MaturityChange,
+  DecayConfig,
+  DecisionRecord,
+  ReferenceRecord,
+  IndexEntry,
+  SnapshotSurvival,
+  ConsumptionStats,
+  StoreUpdate,
+} from './types';
 export type { KnowledgeStore } from './store';
 export { FileKnowledgeStore } from './store';
 export { KnowledgeQuery } from './query';
@@ -16,7 +41,7 @@ export { KnowledgeLinter } from './lint';
 export { ColdStartImporter } from './import';
 export { KnowledgeHealthScorer } from './doctor';
 export { KnowledgeAudit } from './audit';
-export type { AuditRuleName, AuditAction, AuditIssue, AuditReport, AuditOptions } from './audit';
+export type { AuditRuleName, AuditAction, AuditIssue, AuditReport, AuditOptions } from './audit-scoring';
 export { migrateKnowledgeEntries } from './migration';
 export { extractCodeStructure } from './primitives/code-structure';
 export type { CodeStructure, DeclarationInfo, ImportInfo } from './primitives/code-structure';

package/src/knowledge/ingest.ts

@@ -71,7 +71,7 @@ export class KnowledgeIngest {
     const entry = this.buildEntry(partial, options);
 
     // Quality gate: audit before saving
-    const audit = new KnowledgeAudit({ baseDir: this.store.getBaseDir() });
+    const audit = new KnowledgeAudit(this.store);
     let issues = audit.validate(entry);
     const critical = issues.filter(i => i.action === 'reject');
     if (critical.length > 0) {

package/src/knowledge/lifecycle.ts

@@ -10,6 +10,7 @@ import type {
   MaturityLevel,
   MaturityChange,
   DecayConfig,
+  StoreUpdate,
 } from './types';
 import { DEFAULT_DECAY_CONFIG } from './types';
 import type { KnowledgeStore } from './store';
@@ -159,6 +160,7 @@ export class KnowledgeLifecycle {
   runDecayCycle(): MaturityChange[] {
     const entries = this.store.list({ excludeArchived: false });
     const changes: MaturityChange[] = [];
+    const updates: StoreUpdate[] = [];
 
     for (const entry of entries) {
       const targetMaturity = this.checkEntryDecay(entry.id);
@@ -169,11 +171,12 @@ export class KnowledgeLifecycle {
           to: targetMaturity,
           reason: `Auto-decay: ${entry.maturity} → ${targetMaturity} (unreferenced for threshold)`,
         };
-        this.store.update(entry.id, { maturity: targetMaturity });
+        updates.push({ id: entry.id, partial: { maturity: targetMaturity } });
         changes.push(change);
       }
     }
 
+    this.store.applyAll(updates);
     return changes;
   }
 
@@ -350,7 +353,7 @@ export class KnowledgeLifecycle {
   private checkRuleDecay(entry: KnowledgeEntry): MaturityLevel | undefined {
     if (entry.maturity !== 'active') return undefined;
     const rate = this.getExecutionSuccessRate(entry.id);
-    if (rate && rate.total >= RULE_MIN_RESULTS_FOR_DECAY && rate.rate < RULE_FAIL_THRESHOLD) return 'deprecated';
+    if (rate && rate.total >= RULE_MIN_RESULTS_FOR_DECAY && rate.rate <= RULE_FAIL_THRESHOLD) return 'deprecated';
     return undefined;
   }
 

package/src/knowledge/migration.ts

@@ -8,6 +8,7 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import { splitFrontmatter, joinFrontmatter } from '../utils/frontmatter';
+import { isEntryFile } from './tree-walker';
 
 interface MigrationResult {
   total: number;
@@ -20,6 +21,9 @@ interface MigrationResult {
  * Migrate all knowledge .md files in a directory to include
  * consumptionMode and origin fields if missing.
  *
+ * 条目人口按 `tree-walker` 的排除口径判定（harness#134）：`_index.md` 这类树生成物
+ * 既不是迁移对象，也不再计入 `total`/`errors`（此前被报成「no frontmatter found」假阳性）。
+ *
  * Existing files without these fields get defaults:
  * - consumptionMode: 'reference'
  * - origin: 'agent'
@@ -33,7 +37,7 @@ export function migrateKnowledgeEntries(baseDir: string): MigrationResult {
     return result;
   }
 
-  const files = fs.readdirSync(baseDir).filter(f => f.endsWith('.md'));
+  const files = fs.readdirSync(baseDir).filter(isEntryFile);
   result.total = files.length;
 
   for (const file of files) {
@@ -42,7 +46,9 @@ export function migrateKnowledgeEntries(baseDir: string): MigrationResult {
       const raw = fs.readFileSync(filePath, 'utf-8');
       const fm = splitFrontmatter(raw);
       if (fm.state === 'absent') {
-        result.errors.push(`${file}: no frontmatter found`);
+        // 统一口径（harness#89 裁决 2 / harness#161）：'absent' 是合法输入、不上报——
+        // 按非条目语义静默跳过，计入 skipped（非损坏、非迁移对象，仅保证 total 计数闭环）
+        result.skipped++;
         continue;
       }
       if (fm.state === 'malformed') {

package/src/knowledge/query.ts

@@ -19,6 +19,13 @@ import { KnowledgeLifecycle } from './lifecycle';
 // ── Constants ──────────────────────────────────────────────
 
 const CACHE_TTL_MS = 5 * 60 * 1000; // 5 minutes
+
+/**
+ * 外部来源条目的 prompt 标记（harness#161：三层防御第二层 marking 的唯一正本）。
+ * `KnowledgeQuery.formatForPrompt()` 与 `KnowledgeInjector` 的格式化共用，
+ * 仓内不允许存在第二份字面量。
+ */
+export const EXTERNAL_SOURCE_MARKER = '[External Source — verify before acting]';
 const MATURITY_RANK: Record<MaturityLevel, number> = {
   proven: 3,
   verified: 2,
@@ -180,7 +187,7 @@ export class KnowledgeQuery {
    */
   static formatForPrompt(entry: KnowledgeEntry): string {
     const prefix = entry.origin === 'external'
-      ? '[External Source — verify before acting]\n'
+      ? `${EXTERNAL_SOURCE_MARKER}\n`
       : '';
     return `${prefix}${entry.title}: ${entry.content}`;
   }

package/src/knowledge/reference-tracker.ts

@@ -7,7 +7,7 @@
 
 import * as path from 'path';
 import { appendJsonl, readJsonl } from '../utils/jsonl';
-import type { ReferenceRecord } from './types';
+import type { ReferenceRecord, StoreUpdate } from './types';
 import type { KnowledgeStore } from './store';
 
 const REFERENCES_FILE = 'references.jsonl';
@@ -63,6 +63,7 @@ export class ReferenceTracker {
   updateReferencedBy(): void {
     const records = this.readAll();
     const entryToDecisions = new Map<string, Set<string>>();
+    const updates: StoreUpdate[] = [];
 
     for (const record of records) {
       for (const entryId of record.entryIds) {
@@ -74,13 +75,10 @@ export class ReferenceTracker {
     }
 
     for (const [entryId, decisions] of entryToDecisions) {
-      const entry = this.store.get(entryId);
-      if (entry) {
-        this.store.update(entryId, {
-          referencedBy: [...decisions],
-        });
-      }
+      updates.push({ id: entryId, partial: { referencedBy: [...decisions] } });
     }
+    // 未知 id 由 applyAll 逐条跳过（与原先的 store.get 存在性判定同语义）
+    this.store.applyAll(updates);
   }
 
   // ── Internal ───────────────────────────────────────────────

package/src/knowledge/store.ts

@@ -9,10 +9,19 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import { splitFrontmatter, joinFrontmatter } from '../utils/frontmatter';
-import type { KnowledgeEntry, IndexEntry, QueryFilter } from './types';
+import { isEntryFile, SNAPSHOTS_DIR } from './tree-walker';
+import type {
+  KnowledgeEntry,
+  IndexEntry,
+  QueryFilter,
+  ConsumptionStats,
+  SnapshotSurvival,
+  StoreUpdate,
+} from './types';
 
 const DEFAULT_DIR = '.harness/knowledge';
 const INDEX_FILE = 'index.json';
+const CONSUMPTION_STATS_FILE = '.consumption-stats.json';
 
 interface StoreConfig {
   baseDir: string;
@@ -35,6 +44,11 @@ export interface KnowledgeStore {
    * 消除逐条 save 的 O(K·N) 全量索引重写。空批为零读写 no-op。
    */
   saveAll(entries: KnowledgeEntry[]): void;
+  /**
+   * 按 id 批量部分更新（harness#134）：`update(id, partial)` 的批量形，语义与逐条一致
+   * （读不到该 id 即跳过），循环内只更新内存索引、结束一次 writeIndex。空批零读写。
+   */
+  applyAll(updates: StoreUpdate[]): void;
   delete(id: string): boolean;
   update(id: string, partial: Partial<KnowledgeEntry>): KnowledgeEntry | undefined;
   rebuildIndex(): void;
@@ -42,7 +56,12 @@ export interface KnowledgeStore {
   readEntriesFromDisk(): KnowledgeEntry[];
   snapshot(): string;
   getSnapshot(date: string): IndexEntry[] | undefined;
-  getSurvivalRate(daysAgo: number): { rate: number; survived: number; total: number; snapshotDate: string } | undefined;
+  getSurvivalRate(daysAgo: number): SnapshotSurvival | undefined;
+  /**
+   * 读 `.consumption-stats.json` 的当日消费计数（harness#134：打分核心的 IO 归 store 供给）；
+   * 文件缺失或损坏 = undefined（无数据，不是零消费）
+   */
+  getConsumptionStats(): ConsumptionStats | undefined;
 }
 
 /**
@@ -55,8 +74,8 @@ export class FileKnowledgeStore implements KnowledgeStore {
   /**
    * index.json 解析结果的实例级缓存（harness#106）
    *
-   * mtimeMs+size 指纹（先例：project-config-loader.ts rawConfigCache）：
-   * 文件未变则复用解析结果，消除 list() 一次调用内 N+1 次全量重读；
+   * mtimeMs+size 指纹（实例级，作用域限于本 store 的一次 list()）：
+   * 文件未变则复用解析结果，消除一次调用内 N+1 次全量重读；
    * 文件变更（含外部进程改写、删除）自动失效。
    */
   private indexCache: { mtimeMs: number; size: number; entries: IndexEntry[] } | undefined;
@@ -90,9 +109,7 @@ export class FileKnowledgeStore implements KnowledgeStore {
   }
 
   save(entry: KnowledgeEntry): void {
-    const filePath = this.entryPath(entry);
-    const content = joinFrontmatter(this.toFrontmatter(entry), entry.content);
-    fs.writeFileSync(filePath, content, 'utf-8');
+    this.writeEntryFile(entry);
     this.updateIndexEntry(entry);
   }
 
@@ -101,9 +118,7 @@ export class FileKnowledgeStore implements KnowledgeStore {
     const index = this.readIndex();
     const position = new Map(index.map((e, i) => [e.id, i]));
     for (const entry of entries) {
-      const filePath = this.entryPath(entry);
-      const content = joinFrontmatter(this.toFrontmatter(entry), entry.content);
-      fs.writeFileSync(filePath, content, 'utf-8');
+      this.writeEntryFile(entry);
       const indexEntry = this.toIndexEntry(entry);
       const idx = position.get(entry.id);
       if (idx !== undefined) {
@@ -116,6 +131,30 @@ export class FileKnowledgeStore implements KnowledgeStore {
     this.writeIndex(index);
   }
 
+  applyAll(updates: StoreUpdate[]): void {
+    if (updates.length === 0) return;
+    const index = this.readIndex();
+    const position = new Map(index.map((e, i) => [e.id, i]));
+    let applied = 0;
+    for (const { id, partial } of updates) {
+      const existing = this.get(id);
+      if (!existing) continue;
+      const updated: KnowledgeEntry = { ...existing, ...partial, id };
+      this.writeEntryFile(updated);
+      const indexEntry = this.toIndexEntry(updated);
+      const idx = position.get(id);
+      if (idx !== undefined) {
+        index[idx] = indexEntry;
+      } else {
+        position.set(id, index.length);
+        index.push(indexEntry);
+      }
+      applied++;
+    }
+    if (applied === 0) return;
+    this.writeIndex(index);
+  }
+
   delete(id: string): boolean {
     const filePath = this.findFile(id);
     if (!filePath) return false;
@@ -176,6 +215,15 @@ export class FileKnowledgeStore implements KnowledgeStore {
     return path.join(this.baseDir, `${safeType}-${safeId}.md`);
   }
 
+  /** 条目文件正文的唯一落盘写法（save / saveAll / applyAll 三条路径共用，#134） */
+  private writeEntryFile(entry: KnowledgeEntry): void {
+    fs.writeFileSync(
+      this.entryPath(entry),
+      joinFrontmatter(this.toFrontmatter(entry), entry.content),
+      'utf-8'
+    );
+  }
+
   private findFile(id: string): string | undefined {
     // 1. Fast path: index has id→type mapping, construct exact filename
     const index = this.readIndex();
@@ -197,7 +245,7 @@ export class FileKnowledgeStore implements KnowledgeStore {
   private listFiles(): string[] {
     if (!fs.existsSync(this.baseDir)) return [];
     return fs.readdirSync(this.baseDir)
-      .filter(f => f.endsWith('.md'))
+      .filter(isEntryFile)
       .map(f => path.join(this.baseDir, f));
   }
 
@@ -324,13 +372,11 @@ export class FileKnowledgeStore implements KnowledgeStore {
 
   // ── Snapshots ────────────────────────────────────────────
 
-  private static readonly SNAPSHOTS_DIR = '.snapshots';
-
   /**
    * 保存当日 index.json 快照
    */
   snapshot(): string {
-    const snapDir = path.join(this.baseDir, FileKnowledgeStore.SNAPSHOTS_DIR);
+    const snapDir = path.join(this.baseDir, SNAPSHOTS_DIR);
     if (!fs.existsSync(snapDir)) {
       fs.mkdirSync(snapDir, { recursive: true });
     }
@@ -347,7 +393,7 @@ export class FileKnowledgeStore implements KnowledgeStore {
    * 读取指定日期的快照
    */
   getSnapshot(date: string): IndexEntry[] | undefined {
-    const snapPath = path.join(this.baseDir, FileKnowledgeStore.SNAPSHOTS_DIR, `index-${date}.json`);
+    const snapPath = path.join(this.baseDir, SNAPSHOTS_DIR, `index-${date}.json`);
     if (!fs.existsSync(snapPath)) return undefined;
     try {
       return JSON.parse(fs.readFileSync(snapPath, 'utf-8')) as IndexEntry[];
@@ -360,7 +406,7 @@ export class FileKnowledgeStore implements KnowledgeStore {
    * 计算 N 天前快照中条目的存活率
    * 存活 = 当前 index 中存在且 maturity !== 'archived'
    */
-  getSurvivalRate(daysAgo: number): { rate: number; survived: number; total: number; snapshotDate: string } | undefined {
+  getSurvivalRate(daysAgo: number): SnapshotSurvival | undefined {
     const target = new Date(Date.now() - daysAgo * 24 * 60 * 60 * 1000).toISOString().slice(0, 10);
     const snapshot = this.getSnapshot(target);
     if (!snapshot || snapshot.length === 0) return undefined;
@@ -382,6 +428,19 @@ export class FileKnowledgeStore implements KnowledgeStore {
     };
   }
 
+  /**
+   * 读 `.consumption-stats.json` 的当日消费计数（打分核心唯一的消费统计取数口，harness#134）
+   */
+  getConsumptionStats(): ConsumptionStats | undefined {
+    const statsPath = path.join(this.baseDir, CONSUMPTION_STATS_FILE);
+    try {
+      const stats = JSON.parse(fs.readFileSync(statsPath, 'utf-8')) as { dailyEvents?: number };
+      return { dailyEvents: stats.dailyEvents ?? 0 };
+    } catch {
+      return undefined;
+    }
+  }
+
   // ── Index I/O ────────────────────────────────────────────
 
   readIndex(): IndexEntry[] {

package/src/knowledge/tree-walker.ts

@@ -0,0 +1,29 @@
+/**
+ * 知识树布局正本（harness#134：walker 排除口径单点化）
+ *
+ * 「什么算条目」的唯一判定。此前 store 顶层扫描、migration 顶层扫描、index-generator
+ * 递归扫描各有各的排除口径，后果是 `knowledge index` 落在 baseDir 的生成物 `_index.md`
+ * 被 `knowledge migrate` 判成「no frontmatter found」计入 errors——同一份树，两个命令两套人口。
+ *
+ * 本模块只管**排除口径**，不管遍历深度：store 与 migration 是顶层扫描器，index-generator
+ * 会下钻业务子目录（`skills/`、`arch-patterns/`），那是各自的功能而非口径分歧。
+ */
+
+/** 索引生成物：由 `harness knowledge index` 落在 baseDir，是树的基建不是条目 */
+export const INDEX_MD_FILE = '_index.md';
+
+/** 快照目录：`store.snapshot()` 的落点 */
+export const SNAPSHOTS_DIR = '.snapshots';
+
+/** 树基建目录：归档区 / 快照区 / 决议区，任何 walker 都不把它们的内容当条目人口 */
+const INFRA_DIRS = ['.archive', 'archived', SNAPSHOTS_DIR, 'resolutions'];
+
+/** 目录名是否属于树基建 */
+export function isInfraDir(name: string): boolean {
+  return INFRA_DIRS.includes(name);
+}
+
+/** 文件名是否是知识条目（.md 且非生成物） */
+export function isEntryFile(name: string): boolean {
+  return name.endsWith('.md') && name !== INDEX_MD_FILE;
+}

package/src/knowledge/types.ts

@@ -188,3 +188,22 @@ export interface IndexEntry {
   consumptionMode: ConsumptionMode;
   origin: KnowledgeOrigin;
 }
+
+/** `getSurvivalRate()` 的返回面：N 天前快照条目在当前索引里的存活计数 */
+export interface SnapshotSurvival {
+  rate: number;
+  survived: number;
+  total: number;
+  snapshotDate: string;
+}
+
+/** `getConsumptionStats()` 的返回面：`.consumption-stats.json` 里打分要用的计数（harness#134） */
+export interface ConsumptionStats {
+  dailyEvents: number;
+}
+
+/** `applyAll()` 的一条按 id 部分更新（harness#134：`update(id, partial)` 的批量形） */
+export interface StoreUpdate {
+  id: string;
+  partial: Partial<KnowledgeEntry>;
+}

package/src/monitoring/CONTEXT.md

@@ -4,17 +4,20 @@
 运行时监控：Execution Trace（收集/分析）+ 上下文使用追踪。
 
 ## 核心导出
-- `TraceCollector` — 执行追踪收集（append-only JSONL，`.harness/logs/traces.log`）。读入口两个：`readReport(filter?)` 报告入口（返回 `{ traces, skippedLines }`，harness#100）与 `read()/readRecent()/readByConstraint()` 兼容包装（#82 裁决 4 冻结的签名，丢计数）
+- `TraceCollector` — 执行追踪收集（append-only JSONL，`.harness/logs/traces.log`）。读入口三个：`readReport(filter?)` 报告入口（返回 `{ traces, skippedLines }`，harness#100）、`read()/readRecent()/readByConstraint()` 兼容包装（#82 裁决 4 冻结的签名，丢计数）、`getStats()` 文件级统计（`{ fileExists, fileSize, totalLines, oldestTrace?, newestTrace? }`，harness#114 起经 `readJsonlEnds` 只 parse 两端；坏行并进 `totalLines` 的原始行数口径，要单列坏行数用 `readReport()`）
+- 模块级出口：`getTraceCollector()` / `configureTraceCollector(config)`——进程级单例面，**cwd 锚定**（构造不带 projectPath），本仓生产代码零消费、保留仅为跨仓兼容（锚根约定见「约定」第一条）；`createAnalyzer(config?)` 同理，等价 `new TraceAnalyzer(new TraceCollector(), config)`
 - `TraceAnalyzer` — 追踪统计分析 + 异常检测（共用 analyzer-base 纯函数）。`analyzeRecentReport(hours)` 带坏行数，`analyzeRecent()/analyzeConstraint()` 仍返回 `TraceSummary[]`。**ADR-0020**：`summarize`/`detectAnomalies` 的判定本体是 trace-analyzer.ts 的模块级纯函数 `summarizeTraces(traces)` / `detectTraceAnomalies(summaries, config?)`（阈值经参数传入，不再是实例状态），类壳只转发——类壳是 studio 的运行时消费面（`new TraceAnalyzer(c)` + `analyzeRecentReport`/`detectAnomalies`，签名逐字不动），已持有数据的消费端直调纯函数。两函数**不进包根导出**（ADR-0003 零扩张），仓内经相对 import
 - `ContextTracker` — LLM 调用上下文使用快照记录
 
 ## 依赖关系
 - 依赖 `src/types/trace` ExecutionTrace 类型
-- 消费者：`src/cli/commands/{check,report}` 与 `src/hooks/bootstrap`——组合根经 `getTraceCollector()` 把收集器注入 `ConstraintChecker` 构造参数（harness#88）；`status` 按 projectPath 直读读链正本后**直调模块级纯函数**，不构造 collector/类壳（ADR-0020：collector 构造函数的 mkdir 副作用就此退出该路径）
+- 消费者：`src/cli/commands/{check,report}` 与 `src/hooks/bootstrap`——组合根**锚根构造**收集器 `new TraceCollector({ projectPath })` 并注入 `ConstraintChecker` 构造参数（harness#88 接线，#139 收根：cwd 锚定的 `getTraceCollector()` 单例在本仓生产代码已零消费，保留仅为跨仓兼容面）；`status` 按 projectPath 直读读链正本后**直调模块级纯函数**，不构造 collector/类壳（ADR-0020：collector 构造函数的 mkdir 副作用就此退出该路径）
+- `ContextTracker` 的仓内持有者是 `src/context/session-manager`：构造时收 `basePath` 并经 `getTracker()` 交出。仓内**无** `record()` 调用点，`getRecent()/getAverages()/detectIssues()` 也无 CLI 接线（`getTracker()` 零仓内调用方），快照的写入方与读方都是库消费者（经包根 `ContextTracker` 出口，ADR-0003）——harness#142 核对补上这条消费边，此前只列了 trace 侧消费者
 - core 不再依赖本模块（方向由 eslint no-restricted-imports 锁死，`src/__tests__/layering.test.ts` 守卫）
 
 ## 约定
 - Trace 文件存储在 .harness/ 目录（不提交）
+- **落点锚在 projectPath 上，不锚 cwd（harness#139，#95 约定的 trace 侧）**：`DEFAULT_TRACE_FILE` 是**项目相对片段**、不是可直接打开的路径，`TraceCollector` 构造收可选 `projectPath`——给了则缺省/相对的 `traceFile` 一律 `path.resolve(projectPath, …)`，没给则保持 cwd 解析（`getTraceCollector()`/`configureTraceCollector()` 是留给跨仓消费者的 cwd 锚定兼容面，本仓生产代码零消费）。写侧锚根与读侧（`status`/`constraints report` 按 projectPath 直读 jsonl 正本）必须同锚，否则从别处带 `--project-path` 跑一次 check 就是「评估真跑了 B、trace 写进 A」的假绿。可检面：`__tests__/trace-file-anchoring.test.ts`（两态落点 + 读侧同锚）、`src/cli/commands/__tests__/project-path-anchoring.test.ts` 站点 3（命令面写-读闭环）、`src/cli/commands/__tests__/project-path-convention.test.ts` 闸 3（`xxxPath|File|Log` 相对默认值冻结，含常量引用臂）与闸 4（组合根不复活单例取用口）
 - 追加写入，单行 JSON，自动滚动
 - 零 Token 成本：不调用 LLM
 - **凡以 `skip` 策略读 JSONL，坏行计数必须到达该消费面的用户可见输出，或在该调用点显式记名豁免并写明理由（harness#100）**——静默吞掉「数据不全」不是一种可选项。承载方式纯增量：新报告入口带计数，旧入口退化为丢计数的薄包装（#82 裁决 4 的兼容约束继续成立），不另立第二份计数概念、不把 `JsonlReadResult` 提升进包根（ADR-0003）

package/src/monitoring/__tests__/context-tracker.test.ts

@@ -6,14 +6,22 @@ import { ContextTracker } from '../context-tracker';
 import * as fs from 'fs';
 import type { ContextUsageSnapshot } from '../../context/types';
 
-jest.mock('fs', () => ({
-  existsSync: jest.fn().mockReturnValue(true),
-  mkdirSync: jest.fn(),
-  readFileSync: jest.fn().mockReturnValue(''),
-  appendFileSync: jest.fn(),
-  statSync: jest.fn().mockReturnValue({ size: 0 }),
-  renameSync: jest.fn(),
-}));
+jest.mock('fs', () => {
+  // 两条读入口必须同源：utils/jsonl 的 tail 走倒读分块（openSync/fstatSync/readSync，
+  // ADR-0023 决策 3），head 与全文走 readFileSync。假件收在 test-setup/jsonl-fake-fs
+  // 承接两处消费（jest.mock 工厂被提升，只能 require）。
+  const { jsonlBoundedReadChain } = require('../../test-setup/jsonl-fake-fs');
+  const readFileSync = jest.fn().mockReturnValue('');
+  return {
+    existsSync: jest.fn().mockReturnValue(true),
+    mkdirSync: jest.fn(),
+    readFileSync,
+    appendFileSync: jest.fn(),
+    statSync: jest.fn().mockReturnValue({ size: 0 }),
+    renameSync: jest.fn(),
+    ...jsonlBoundedReadChain((p: string) => readFileSync(p, 'utf-8')),
+  };
+});
 
 const mockFs = fs as jest.Mocked<typeof fs>;
 

package/src/monitoring/__tests__/trace-file-anchoring.test.ts

@@ -0,0 +1,80 @@
+/**
+ * TraceCollector 落点锚根（harness#139，#95 约定的 trace 侧）
+ *
+ * 不 mock IO：落点本身就是被测行为，只有 **cwd ≠ projectPath** 才看得出锚到了哪一侧
+ * （前提形状照 `src/cli/commands/__tests__/project-path-anchoring.test.ts`）。
+ * 两态都要钉：给了 projectPath → 锚项目根；没给 → 保持 cwd 解析（跨仓消费者的兼容面）。
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import { TraceCollector } from '../traces';
+import { DEFAULT_TRACE_FILE, type ExecutionTrace } from '../../types/trace';
+import { createProjectFixture } from '../../test-setup/project-fixture';
+
+const trace = (constraintId: string): ExecutionTrace => ({
+  constraintId,
+  level: 'guideline',
+  timestamp: 1700000000000,
+  result: 'pass',
+});
+
+const traceLines = (projectRoot: string): string[] =>
+  fs.readFileSync(path.join(projectRoot, DEFAULT_TRACE_FILE), 'utf-8').split('\n').filter(Boolean);
+
+describe('TraceCollector 落点锚根（harness#139）', () => {
+  const originalCwd = process.cwd();
+  let cwdSide: string;
+  let projectSide: string;
+
+  beforeEach(() => {
+    cwdSide = createProjectFixture({ name: 'traceanchor-cwd' });
+    projectSide = createProjectFixture({ name: 'traceanchor-project' });
+    process.chdir(cwdSide);
+  });
+
+  afterEach(() => {
+    process.chdir(originalCwd);
+  });
+
+  it('给了 projectPath → 缺省落点锚到 <projectPath> 下，cwd 侧不产生文件', () => {
+    new TraceCollector({ projectPath: projectSide }).record(trace('anchored'));
+
+    expect(traceLines(projectSide).map(l => JSON.parse(l).constraintId)).toEqual(['anchored']);
+    expect(fs.existsSync(path.join(cwdSide, DEFAULT_TRACE_FILE))).toBe(false);
+  });
+
+  it('没给 projectPath → 缺省落点仍按 cwd 解析（兼容语义，行为逐字不变）', () => {
+    new TraceCollector().record(trace('cwd_default'));
+
+    expect(traceLines(cwdSide).map(l => JSON.parse(l).constraintId)).toEqual(['cwd_default']);
+    expect(fs.existsSync(path.join(projectSide, DEFAULT_TRACE_FILE))).toBe(false);
+  });
+
+  it('显式绝对 traceFile 优先，不被 projectPath 改写', () => {
+    const custom = path.join(cwdSide, 'custom.log');
+
+    new TraceCollector({ projectPath: projectSide, traceFile: custom }).record(trace('explicit'));
+
+    expect(fs.existsSync(custom)).toBe(true);
+    expect(fs.existsSync(path.join(projectSide, DEFAULT_TRACE_FILE))).toBe(false);
+  });
+
+  it('projectPath + 相对 traceFile → 相对落点在 projectPath 之下（自定义片段的锚定形状）', () => {
+    new TraceCollector({ projectPath: projectSide, traceFile: 'logs/custom.log' }).record(
+      trace('relative')
+    );
+
+    // 自定义片段跟缺省片段同一条锚定规则：给了根就锚根，不给仍按 cwd（兼容面逐字不变）
+    expect(fs.existsSync(path.join(projectSide, 'logs', 'custom.log'))).toBe(true);
+    expect(fs.existsSync(path.join(cwdSide, 'logs', 'custom.log'))).toBe(false);
+  });
+
+  it('读侧同锚：另一实例按同一 projectPath 构造，read()/getStats() 读到刚写的记录', () => {
+    new TraceCollector({ projectPath: projectSide }).record(trace('roundtrip'));
+
+    const reader = new TraceCollector({ projectPath: projectSide });
+    expect(reader.read().map(t => t.constraintId)).toEqual(['roundtrip']);
+    expect(reader.getStats().totalLines).toBe(1);
+  });
+});