@dommaker/harness 1.2.3 → 1.4.0

package/src/knowledge/audit.ts

@@ -2,7 +2,7 @@
  * 知识库质量审计引擎
  *
  * 纯代码检测，零 token 成本。
- * 6 维度覆盖：结构完整性 / 内容质量 / 去重有效性 / 成熟度健康 / 新鲜度 / 飞轮验证
+ * 7 维度覆盖：结构完整性 / 内容质量 / 去重有效性 / 成熟度健康 / 新鲜度 / 飞轮验证 / 增量存活
  *
  * 两种模式：
  * - validate(entry): 单条入库检查（ingest gate）
@@ -13,6 +13,7 @@ import * as fs from 'fs';
 import * as path from 'path';
 import { FileKnowledgeStore } from './store';
 import type { KnowledgeStore } from './store';
+import { evaluateFlywheel, genuineRefs } from './flywheel-metrics';
 import type { KnowledgeEntry } from './types';
 
 // ── Types ─────────────────────────────────────────────────
@@ -99,22 +100,22 @@ const EVENT_NOISE_PATTERNS = [
   /^\[Session Feature\]\s/,
 ];
 const REQUIRED_FRONTMATTER = ['id', 'type', 'title', 'maturity'];
-const SYNTHETIC_REF_PATTERN = /^(search|test-agent|prompt-inject|monitor|analyst|auditor|triage|executor|session|trend|incident):\d{4}-\d{2}-\d{2}/;
-
-/** Filter out synthetic references (automated search/ops records, not genuine consumption) */
-function genuineRefs(refs: string[]): string[] {
-  return refs.filter(r => !SYNTHETIC_REF_PATTERN.test(r));
-}
 
 // ── Per-Entry Rules ───────────────────────────────────────
 
 interface AuditRule {
   name: AuditRuleName;
+  /** 中文展示文案正本（#109）：定义即注册，CLI 经 AUDIT_RULE_LABELS 消费，无 label 即编译期失败 */
+  label: string;
   severity: AuditIssue['severity'];
   action: AuditAction;
+  /** 规则适用人口：active = 跳过 archived 条目；all = 全人口（含已归档） */
+  scope: AuditRuleScope;
   detect: (entry: KnowledgeEntry, ctx: AuditContext) => string | null;
 }
 
+type AuditRuleScope = 'active' | 'all';
+
 interface AuditContext {
   shortContentThreshold: number;
   staleDays: number;
@@ -126,8 +127,10 @@ const perEntryRules: AuditRule[] = [
   // D1: 结构完整性
   {
     name: 'frontmatter-missing',
+    label: 'frontmatter 缺失',
     severity: 'high',
     action: 'reject',
+    scope: 'all',
     detect: (entry) => {
       const missing = REQUIRED_FRONTMATTER.filter(f => {
         const val = (entry as any)[f];
@@ -143,10 +146,11 @@ const perEntryRules: AuditRule[] = [
   // D2: 内容质量
   {
     name: 'test-data-pollution',
+    label: '测试数据污染',
     severity: 'critical',
     action: 'archive',
+    scope: 'active',
     detect: (entry) => {
-      if (entry.maturity === 'archived') return null;
       // Match test ID patterns
       if (/^(test-|inj-test)/.test(entry.id)) {
         return `测试 ID: "${entry.id}"`;
@@ -163,10 +167,11 @@ const perEntryRules: AuditRule[] = [
   },
   {
     name: 'daily-audit-noise',
+    label: '每日审计噪音',
     severity: 'high',
     action: 'archive',
+    scope: 'active',
     detect: (entry) => {
-      if (entry.maturity === 'archived') return null;
       if (DAILY_AUDIT_PATTERN.test(entry.title)) {
         return `每日审计摘要: "${entry.title}"`;
       }
@@ -175,10 +180,11 @@ const perEntryRules: AuditRule[] = [
   },
   {
     name: 'event-noise',
+    label: '运维事件噪音',
     severity: 'critical',
     action: 'archive',
+    scope: 'active',
     detect: (entry) => {
-      if (entry.maturity === 'archived') return null;
       for (const pattern of EVENT_NOISE_PATTERNS) {
         if (pattern.test(entry.title)) {
           return `运维事件标题: "${entry.title}"`;
@@ -189,8 +195,10 @@ const perEntryRules: AuditRule[] = [
   },
   {
     name: 'zero-content-proven',
+    label: '零内容 proven',
     severity: 'critical',
     action: 'demote',
+    scope: 'all',
     detect: (entry) => {
       if (entry.maturity === 'proven' && entry.content.trim().length < ZERO_CONTENT_THRESHOLD) {
         return `proven 条目内容仅 ${entry.content.trim().length} 字符`;
@@ -200,8 +208,10 @@ const perEntryRules: AuditRule[] = [
   },
   {
     name: 'maturity-inflation',
+    label: '成熟度虚高',
     severity: 'high',
     action: 'demote',
+    scope: 'all',
     detect: (entry) => {
       if (entry.maturity === 'verified' && entry.content.trim().length < ZERO_CONTENT_THRESHOLD) {
         return `verified 条目内容仅 ${entry.content.trim().length} 字符`;
@@ -211,10 +221,11 @@ const perEntryRules: AuditRule[] = [
   },
   {
     name: 'short-content',
+    label: '短内容',
     severity: 'medium',
     action: 'flag',
+    scope: 'active',
     detect: (entry, ctx) => {
-      if (entry.maturity === 'archived') return null;
       const len = entry.content.trim().length;
       if (len < ctx.shortContentThreshold && len >= ZERO_CONTENT_THRESHOLD) {
         return `内容 ${len} 字符 (阈值 ${ctx.shortContentThreshold})`;
@@ -226,10 +237,11 @@ const perEntryRules: AuditRule[] = [
   // D3: 去重有效性
   {
     name: 'title-duplicate',
+    label: '标题重复',
     severity: 'medium',
     action: 'flag',
+    scope: 'active',
     detect: (entry, ctx) => {
-      if (entry.maturity === 'archived') return null;
       if (!ctx.allEntries) return null;
       if (!entry.title) return null;
       const dupes = ctx.allEntries.filter(e =>
@@ -246,8 +258,10 @@ const perEntryRules: AuditRule[] = [
   },
   {
     name: 'source-refs-bloat',
+    label: 'sourceReferences 膨胀',
     severity: 'low',
     action: 'trim',
+    scope: 'all',
     detect: (entry) => {
       if ((entry.sourceReferences?.length || 0) > MAX_SOURCE_REFS) {
         return `sourceReferences ${entry.sourceReferences!.length} 条 (上限 ${MAX_SOURCE_REFS})`;
@@ -257,10 +271,11 @@ const perEntryRules: AuditRule[] = [
   },
   {
     name: 'fragment-cluster',
+    label: '碎片集群',
     severity: 'medium',
     action: 'flag',
+    scope: 'active',
     detect: (entry, ctx) => {
-      if (entry.maturity === 'archived') return null;
       if (!ctx.allEntries || entry.content.trim().length >= 100) return null;
       if (!entry.tags?.length) return null;
 
@@ -284,8 +299,10 @@ const perEntryRules: AuditRule[] = [
   // D4: 成熟度健康
   {
     name: 'promotion-blocked',
+    label: 'promotion 受阻',
     severity: 'medium',
     action: 'flag',
+    scope: 'all',
     detect: (entry, ctx) => {
       if (entry.maturity !== 'draft') return null;
       const created = new Date(entry.created);
@@ -298,8 +315,10 @@ const perEntryRules: AuditRule[] = [
   },
   {
     name: 'orphan-draft',
+    label: '孤儿 draft',
     severity: 'low',
     action: 'flag',
+    scope: 'all',
     detect: (entry) => {
       if (entry.maturity !== 'draft') return null;
       if (entry.contributors.length === 0 && entry.projects.length === 0 && genuineRefs(entry.referencedBy).length === 0) {
@@ -312,10 +331,11 @@ const perEntryRules: AuditRule[] = [
   // D5: 新鲜度
   {
     name: 'stale-entry',
+    label: '过期条目',
     severity: 'medium',
     action: 'flag',
+    scope: 'active',
     detect: (entry, ctx) => {
-      if (entry.maturity === 'archived') return null;
       const lastRef = entry.lastReferenced || entry.created;
       if (!lastRef) return null;
       const daysSinceRef = (Date.now() - new Date(lastRef).getTime()) / (1000 * 60 * 60 * 24);
@@ -329,10 +349,11 @@ const perEntryRules: AuditRule[] = [
   // D2b: 领域相关性 — 检测已废弃领域的残留条目
   {
     name: 'deprecated-domain',
+    label: '废弃领域残留',
     severity: 'high',
     action: 'archive',
+    scope: 'active',
     detect: (entry) => {
-      if (entry.maturity === 'archived') return null;
       const tags = (entry.tags ?? []).map(t => t.toLowerCase());
       // Tag-level: "pipeline" tag is deprecated (Studio Pipeline superseded by Agent Network)
       if (tags.includes('pipeline')) {
@@ -348,8 +369,19 @@ const perEntryRules: AuditRule[] = [
   },
 ];
 
+/** 规则 label 正本表（#109，ADR-0002 定义即注册）：派生自 perEntryRules，与规则键集编译期闭环，CLI 展示层直接消费 */
+export const AUDIT_RULE_LABELS: Record<AuditRuleName, string> = Object.fromEntries(
+  perEntryRules.map(r => [r.name, r.label])
+) as Record<AuditRuleName, string>;
+
 // ── Audit Engine ──────────────────────────────────────────
 
+/** 按 scope 决定是否评估：active 规则对 archived 条目不判定（人口过滤唯一落点） */
+function ruleDetail(rule: AuditRule, entry: KnowledgeEntry, ctx: AuditContext): string | null {
+  if (rule.scope === 'active' && entry.maturity === 'archived') return null;
+  return rule.detect(entry, ctx);
+}
+
 export class KnowledgeAudit {
   private store: KnowledgeStore;
   private shortContentThreshold: number;
@@ -372,21 +404,7 @@ export class KnowledgeAudit {
       staleDays: this.staleDays,
       promotionBlockDays: this.promotionBlockDays,
     };
-    const issues: AuditIssue[] = [];
-    for (const rule of perEntryRules) {
-      const detail = rule.detect(entry, ctx);
-      if (detail) {
-        issues.push({
-          rule: rule.name,
-          entryId: entry.id,
-          title: entry.title,
-          severity: rule.severity,
-          action: rule.action,
-          detail,
-        });
-      }
-    }
-    return issues;
+    return this.scanEntries([entry], ctx);
   }
 
   /**
@@ -402,22 +420,7 @@ export class KnowledgeAudit {
     };
 
     // Per-entry issues
-    const allIssues: AuditIssue[] = [];
-    for (const entry of entries) {
-      for (const rule of perEntryRules) {
-        const detail = rule.detect(entry, ctx);
-        if (detail) {
-          allIssues.push({
-            rule: rule.name,
-            entryId: entry.id,
-            title: entry.title,
-            severity: rule.severity,
-            action: rule.action,
-            detail,
-          });
-        }
-      }
-    }
+    const allIssues = this.scanEntries(entries, ctx);
 
     // Summary
     const summary = {} as Record<AuditRuleName, number>;
@@ -438,7 +441,7 @@ export class KnowledgeAudit {
 
     // Health score (after)
     const entriesAfter = options?.autoFix ? this.store.list({ excludeArchived: false }) : entries;
-    const issuesAfter = options?.autoFix ? this.runScan(entriesAfter, ctx) : allIssues;
+    const issuesAfter = options?.autoFix ? this.scanEntries(entriesAfter, ctx) : allIssues;
     const healthAfter = this.calculateHealthScore(entriesAfter, issuesAfter);
 
     return {
@@ -496,33 +499,23 @@ export class KnowledgeAudit {
     const staleRatio = active.length > 0 ? d5Issues.length / active.length : 0;
     const d5Score = active.length === 0 ? 100 : Math.max(0, 100 - (staleRatio * 100));
 
-    // D6: 飞轮验证
-    const withRefs = active.filter(e => genuineRefs(e.referencedBy).length > 0).length;
-    const refCoverage = active.length > 0 ? withRefs / active.length : 0;
-    const avgRefs = active.length > 0
-      ? active.reduce((sum, e) => sum + genuineRefs(e.referencedBy).length, 0) / active.length
-      : 0;
-
-    // Consumption hit rate from aggregated stats file (written by MonitorAgent)
-    let consumptionHitRate = 0;
+    // D6: 飞轮验证 —— 指标计算唯一实现在 flywheel-metrics，此处只做 fs 读取与报告层映射
     let dailyConsumptionEvents = 0;
     try {
       const statsPath = path.join(this.store.getBaseDir(), '.consumption-stats.json');
       if (fs.existsSync(statsPath)) {
         const stats = JSON.parse(fs.readFileSync(statsPath, 'utf-8'));
         dailyConsumptionEvents = stats.dailyEvents || 0;
-        // hitRate: daily events / active entries, capped at 1
-        consumptionHitRate = active.length > 0
-          ? Math.min(dailyConsumptionEvents / active.length, 1)
-          : 0;
       }
     } catch { /* best-effort */ }
 
+    const metrics = evaluateFlywheel({ entries: active, dailyConsumptionEvents });
+
     // Score: refCoverage * 50 + avgRefs * 20 + consumptionHitRate * 30
     const d6Score = Math.min(100, Math.round(
-      refCoverage * 50 +
-      Math.min(avgRefs / 5, 1) * 20 +
-      consumptionHitRate * 30
+      metrics.refCoverage * 50 +
+      Math.min(metrics.avgRefs / 5, 1) * 20 +
+      metrics.consumptionHitRate * 30
     ));
 
     return {
@@ -576,12 +569,12 @@ export class KnowledgeAudit {
         score: d6Score,
         issues: 0,
         details: {
-          activeEntries: active.length,
-          entriesWithRefs: withRefs,
-          refCoverage: Math.round(refCoverage * 100),
-          avgRefCount: Math.round(avgRefs * 10) / 10,
-          dailyConsumptionEvents,
-          consumptionHitRate: Math.round(consumptionHitRate * 100),
+          activeEntries: metrics.activeEntries,
+          entriesWithRefs: metrics.entriesWithRefs,
+          refCoverage: Math.round(metrics.refCoverage * 100),
+          avgRefCount: Math.round(metrics.avgRefs * 10) / 10,
+          dailyConsumptionEvents: metrics.dailyConsumptionEvents,
+          consumptionHitRate: Math.round(metrics.consumptionHitRate * 100),
         },
       },
       incremental: this.computeIncremental(),
@@ -608,11 +601,14 @@ export class KnowledgeAudit {
 
   // ── Internal ────────────────────────────────────────────
 
-  private runScan(entries: KnowledgeEntry[], ctx: AuditContext): AuditIssue[] {
+  /**
+   * 逐条目跑 perEntryRules（#111 收口）：validate（单条目）、run（全量）与 autoFix 重扫共用
+   */
+  private scanEntries(entries: KnowledgeEntry[], ctx: AuditContext): AuditIssue[] {
     const issues: AuditIssue[] = [];
     for (const entry of entries) {
       for (const rule of perEntryRules) {
-        const detail = rule.detect(entry, ctx);
+        const detail = ruleDetail(rule, entry, ctx);
         if (detail) {
           issues.push({
             rule: rule.name,

package/src/knowledge/flywheel-metrics.ts

@@ -0,0 +1,71 @@
+/**
+ * 知识飞轮指标（harness#81）
+ *
+ * 纯判定 module：吃 active 条目数组（+ 可选当日消费事件数），一次产出 canonical 飞轮指标。
+ * 零 IO——人口筛选（哪些条目算 active）与 `.consumption-stats.json` 读取都留在调用方。
+ *
+ * 此前同一组分子计算在 audit.ts D6、knowledge stats、knowledge health 三处独立实现，
+ * 后两处直接数 `referencedBy.length`，把 search / prompt-inject / test-agent 等自动化
+ * 触碰算成真实消费——同一知识库报出两套飞轮健康度（实测 refCoverage 26% vs 28%、
+ * avgRefs 0.4 vs 0.6）。飞轮指标是退役/降级判定的输入，口径必须唯一：
+ * **分子一律为过滤 synthetic 后的 genuine refs**（ADR-0013）。
+ *
+ * 单位约定：本 module 只出比例（0..1），百分比取整/一位小数等是展示层的事。
+ */
+
+import type { KnowledgeEntry } from './types';
+
+/**
+ * 自动化写入方形成的引用键：`<contributor>:<YYYY-MM-DD>`（contributor 见 recordReference）。
+ * 这些是检索/运维动作的按天记账，不代表条目被真实消费，不计入飞轮分子。
+ * `unknown:`（query() 注入路径）不在过滤面内——注入即消费，维持既有语义。
+ */
+const SYNTHETIC_REF_PATTERN = /^(search|test-agent|prompt-inject|monitor|analyst|auditor|triage|executor|session|trend|incident):\d{4}-\d{2}-\d{2}/;
+
+/** 剔除 synthetic refs，返回真实消费引用（唯一口径） */
+export function genuineRefs(refs: string[]): string[] {
+  return refs.filter(r => !SYNTHETIC_REF_PATTERN.test(r));
+}
+
+export interface FlywheelEnv {
+  /** 参与统计的条目人口（调用方筛选，本 module 不再过滤 archived/deprecated） */
+  entries: KnowledgeEntry[];
+  /** 当日消费事件数（`.consumption-stats.json` 的 dailyEvents，MonitorAgent 汇总写入）；未提供视为 0 */
+  dailyConsumptionEvents?: number;
+}
+
+export interface FlywheelMetrics {
+  /** 人口大小 */
+  activeEntries: number;
+  /** 分子：有 genuine 引用（含 1 条即算）的条目数 */
+  entriesWithRefs: number;
+  /** entriesWithRefs / activeEntries，0..1；空人口为 0 */
+  refCoverage: number;
+  /** genuine 引用总数 / activeEntries，未取整比例 */
+  avgRefs: number;
+  /** 透传输入，供报告层复用 */
+  dailyConsumptionEvents: number;
+  /** dailyConsumptionEvents / activeEntries，capped at 1；无消费事件为 0 */
+  consumptionHitRate: number;
+}
+
+export function evaluateFlywheel(env: FlywheelEnv): FlywheelMetrics {
+  const entries = env.entries;
+  const dailyConsumptionEvents = env.dailyConsumptionEvents ?? 0;
+  const activeEntries = entries.length;
+
+  const refCounts = entries.map(e => genuineRefs(e.referencedBy).length);
+  const entriesWithRefs = refCounts.filter(n => n > 0).length;
+  const totalRefs = refCounts.reduce((sum, n) => sum + n, 0);
+
+  return {
+    activeEntries,
+    entriesWithRefs,
+    refCoverage: activeEntries > 0 ? entriesWithRefs / activeEntries : 0,
+    avgRefs: activeEntries > 0 ? totalRefs / activeEntries : 0,
+    dailyConsumptionEvents,
+    consumptionHitRate: activeEntries > 0
+      ? Math.min(dailyConsumptionEvents / activeEntries, 1)
+      : 0,
+  };
+}

package/src/knowledge/import.ts

@@ -183,9 +183,7 @@ export class ColdStartImporter {
     }
 
     // 写入知识库
-    for (const entry of entries) {
-      this.config.store.save(entry);
-    }
+    this.config.store.saveAll(entries);
 
     return { source, entries, errors };
   }
@@ -202,12 +200,6 @@ export class ColdStartImporter {
       const { execSync } = require('child_process');
       const cwd = this.config.projectRoot;
 
-      // 分析大型重构提交
-      execSync(
-        'git log --oneline --diff-filter=M --numstat --since="6 months ago" | head -100',
-        { cwd, encoding: 'utf-8', timeout: 10000 },
-      );
-
       // 查找 fix/hotfix 相关提交
       const fixCommits = execSync(
         'git log --oneline --grep="fix\\|hotfix\\|bug" --since="6 months ago" | head -20',
@@ -247,9 +239,7 @@ export class ColdStartImporter {
       });
     }
 
-    for (const entry of entries) {
-      this.config.store.save(entry);
-    }
+    this.config.store.saveAll(entries);
 
     return { source, entries, errors };
   }
@@ -317,9 +307,7 @@ export class ColdStartImporter {
       }
     }
 
-    for (const entry of entries) {
-      this.config.store.save(entry);
-    }
+    this.config.store.saveAll(entries);
 
     return { source, entries, errors };
   }
@@ -354,9 +342,7 @@ export class ColdStartImporter {
       }
     }
 
-    for (const entry of entries) {
-      this.config.store.save(entry);
-    }
+    this.config.store.saveAll(entries);
 
     return { source, entries, errors };
   }

package/src/knowledge/index-generator.ts

@@ -9,7 +9,7 @@
 
 import * as fs from 'fs';
 import * as path from 'path';
-import * as yaml from 'js-yaml';
+import { splitFrontmatter } from '../utils/frontmatter';
 
 const EXCLUDED_DIRS = ['.archive', 'archived', '.snapshots', 'resolutions'];
 const INDEX_FILENAME = '_index.md';
@@ -59,7 +59,7 @@ export class KnowledgeIndexGenerator {
       `# Types: ${Object.entries(byType).map(([t, n]) => `${t}:${n}`).join(' ')}`,
       `#`,
       `# Usage:`,
-      `#   grep "<keyword>" ~/.studio/knowledge/_index.md`,
+      `#   grep "<keyword>" ~/.harness/knowledge/_index.md`,
       `#   Then Read the matching file for full content.`,
       `#`,
       `# filename|id|type|title|maturity|tags|terms`,
@@ -131,32 +131,37 @@ export class KnowledgeIndexGenerator {
       // 跳过 ghost 文件（文件名为 .md）
       if (path.basename(filename) === '.md') return null;
 
-      // 尝试解析 YAML frontmatter
-      const fmMatch = raw.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
-      if (fmMatch) {
-        const meta = yaml.load(fmMatch[1]) as Record<string, unknown>;
-        const body = fmMatch[2];
-        const headings = this.extractHeadings(body);
+      // 尝试解析 YAML frontmatter（语法与失败走法正本：utils/frontmatter）
+      const fm = splitFrontmatter(raw);
+      if (fm.state === 'malformed') {
+        // 统一口径（harness#89）：损坏必须显式上报，恢复动作是 best-effort 索引原文
+        console.error(
+          `[harness] 知识索引 frontmatter ${fm.reason}（${fm.detail}），按无 frontmatter 处理 ${filename}`
+        );
+      }
+      if (fm.state === 'ok') {
+        const meta = fm.meta;
+        const headings = this.extractHeadings(fm.body);
 
         // 检测 skill schema（name/description 而非 id/type）
-        const type = meta?.type
+        const type = meta.type
           ? String(meta.type)
-          : meta?.name
+          : meta.name
             ? 'skill'
             : this.inferType(filename);
 
         return {
           filename,
-          id: String(meta?.id ?? meta?.name ?? path.basename(filePath, '.md')),
+          id: String(meta.id ?? meta.name ?? path.basename(filePath, '.md')),
           type,
-          title: String(meta?.title ?? meta?.description ?? ''),
-          maturity: String(meta?.maturity ?? 'unknown'),
-          tags: Array.isArray(meta?.tags) ? (meta.tags as unknown[]).map(String) : [],
+          title: String(meta.title ?? meta.description ?? ''),
+          maturity: String(meta.maturity ?? 'unknown'),
+          tags: Array.isArray(meta.tags) ? (meta.tags as unknown[]).map(String) : [],
           headings,
         };
       }
 
-      // 无 frontmatter — best effort
+      // absent（含空 meta）或已上报的 malformed — best effort
       const headings = this.extractHeadings(raw);
       const h1Match = raw.match(/^#\s+(.+)$/m);
 

package/src/knowledge/ingest.ts

@@ -13,6 +13,7 @@ import type {
 } from './types';
 import type { KnowledgeStore } from './store';
 import { KnowledgeAudit } from './audit';
+import { splitFrontmatter } from '../utils/frontmatter';
 
 const MAX_SOURCE_REFS = 20;
 const MAX_EXTERNAL_CONTENT_LENGTH = 5000;
@@ -178,7 +179,10 @@ export class KnowledgeIngest {
 
   private generateId(type: KnowledgeSubsystem): string {
     const prefix = type.toUpperCase().slice(0, 3);
-    const existing = this.store.list({ types: [type] });
+    // 序号取自索引计数（harness#107）：不再走 list() 逐条读条目文件；
+    // 与 list() 默认过滤口径一致，archived/deprecated 不计入序号
+    const existing = this.store.readIndex()
+      .filter(e => e.type === type && e.maturity !== 'archived' && e.maturity !== 'deprecated');
     const seq = String(existing.length + 1).padStart(3, '0');
     return `${prefix}-${seq}`;
   }
@@ -242,9 +246,10 @@ export class KnowledgeIngest {
 
   /** Extract first 50 chars of content body (after frontmatter), stripped of whitespace */
   private getContentPrefix(content: string): string {
-    // Strip YAML frontmatter (may be nested if content includes raw markdown)
-    const body = content.replace(/^---[\s\S]*?---\n?/, '').trim();
-    return body.slice(0, 50).replace(/\s+/g, '');
+    // 正本判定（harness#89）：只有合法 frontmatter 块才剥头，正文里的 --- 分隔线不再被误吞
+    const fm = splitFrontmatter(content);
+    const body = fm.state === 'ok' ? fm.body : content;
+    return body.trim().slice(0, 50).replace(/\s+/g, '');
   }
 
   /** Calculate keyword overlap ratio between two normalized titles */

package/src/knowledge/migration.ts

@@ -7,7 +7,7 @@
 
 import * as fs from 'fs';
 import * as path from 'path';
-import * as yaml from 'js-yaml';
+import { splitFrontmatter, joinFrontmatter } from '../utils/frontmatter';
 
 interface MigrationResult {
   total: number;
@@ -40,14 +40,19 @@ export function migrateKnowledgeEntries(baseDir: string): MigrationResult {
     const filePath = path.join(baseDir, file);
     try {
       const raw = fs.readFileSync(filePath, 'utf-8');
-      const match = raw.match(/^---\n([\s\S]*?)\n---\n\n?([\s\S]*)$/);
-      if (!match) {
+      const fm = splitFrontmatter(raw);
+      if (fm.state === 'absent') {
         result.errors.push(`${file}: no frontmatter found`);
         continue;
       }
+      if (fm.state === 'malformed') {
+        // 统一口径（harness#89）：损坏的 frontmatter 落 errors，不静默丢
+        result.errors.push(`${file}: frontmatter ${fm.reason} (${fm.detail})`);
+        continue;
+      }
 
-      const meta = yaml.load(match[1]) as Record<string, unknown>;
-      const content = match[2];
+      const meta = fm.meta;
+      const content = fm.body;
 
       // Check if migration needed
       if (meta.consumptionMode && meta.origin) {
@@ -60,9 +65,7 @@ export function migrateKnowledgeEntries(baseDir: string): MigrationResult {
       if (!meta.origin) meta.origin = 'agent';
 
       // Write back
-      const newFrontmatter = yaml.dump(meta, { lineWidth: 120 });
-      const newContent = `---\n${newFrontmatter}---\n\n${content}`;
-      fs.writeFileSync(filePath, newContent, 'utf-8');
+      fs.writeFileSync(filePath, joinFrontmatter(meta, content), 'utf-8');
       result.migrated++;
     } catch (err) {
       result.errors.push(`${file}: ${err instanceof Error ? err.message : String(err)}`);

package/src/knowledge/reference-tracker.ts

@@ -5,8 +5,8 @@
  * Storage: append-only JSONL at .harness/knowledge/references.jsonl
  */
 
-import * as fs from 'fs';
 import * as path from 'path';
+import { appendJsonl, readJsonl } from '../utils/jsonl';
 import type { ReferenceRecord } from './types';
 import type { KnowledgeStore } from './store';
 
@@ -33,7 +33,8 @@ export class ReferenceTracker {
       entryIds,
       timestamp: new Date().toISOString(),
     };
-    fs.appendFileSync(this.filePath, JSON.stringify(record) + '\n', 'utf-8');
+    // 写链收口：ensureDir + append（harness#82；原实现不 ensureDir，依赖 store 建目录）
+    appendJsonl(this.filePath, record);
   }
 
   /**
@@ -85,13 +86,16 @@ export class ReferenceTracker {
   // ── Internal ───────────────────────────────────────────────
 
   private readAll(): ReferenceRecord[] {
-    if (!fs.existsSync(this.filePath)) return [];
     try {
-      const raw = fs.readFileSync(this.filePath, 'utf-8');
-      return raw
-        .split('\n')
-        .filter(line => line.trim())
-        .map(line => JSON.parse(line) as ReferenceRecord);
+      // 坏行策略：skip（harness#82：原「逐行 map 会抛 + 外层 catch 吞成整文件 []」
+      // ——坏一行丢全部记录——不可接受，改为单行损坏只丢该行）；
+      // 外层 catch 仅兜 IO 读取错误，沿用原吞掉语义
+      // 计数去向：豁免（harness#100）——三个消费点 getReferencesForEntry /
+      // getReferencesForDecision / updateReferencedBy 只按合法记录取引用关系。
+      // 代价如实记录：checkOrphans（knowledge/lint.ts）以 refs.length>0 判孤儿，
+      // 坏行会让它给出假孤儿判定，不只是少报；透传需要给 LintIssue / `knowledge health`
+      // 报告加计数位，属 knowledge 域输出形状变更，另票收口
+      return readJsonl<ReferenceRecord>(this.filePath, 'skip').records;
     } catch {
       return [];
     }