@dommaker/harness 1.7.0 → 1.8.1

package/src/hooks/types.ts

@@ -11,9 +11,12 @@
 export type HookPhase = 'before' | 'after' | 'around';
 
 /**
- * Hook 错误处理策略
+ * Hook 错误处理策略（有效集合：'block' | 'warn'）
+ *
+ * #159 起原 'ignore' 退出有效面：策略的唯一声明点是 HookConfig（必填），
+ * 不存在「未声明 strategy」的运行时形态。
  */
-export type HookErrorStrategy = 'block' | 'warn' | 'ignore';
+export type HookErrorStrategy = 'block' | 'warn';
 
 /**
  * Hook 配置（G7 归一后形状：consumer 侧的 per-hook 声明表）
@@ -22,6 +25,10 @@ export type HookErrorStrategy = 'block' | 'warn' | 'ignore';
  * - 声明（HookConfig）是「定义」侧：引用未注册实现 → 抛错
  * - 注册（HookDefinition）是「实现」侧：注册无对应声明 → 抛错
  *
+ * #159 起本表是 `enabled` / `errorStrategy` 的**唯一声明点**：
+ * HookDefinition 不再携带这两个字段，有效值在注册环节由本表填充
+ * （见 EffectiveHook），声明与实现两处值矛盾在构造上不可能出现。
+ *
  * 对应 studio 侧 per-hook 运行时配置（hooks/config.ts 的 DEFAULTS）语义：
  * blocking:true ↔ errorStrategy 'block'（失败阻断管线），
  * blocking:false ↔ errorStrategy 'warn'（记录警告继续）——无损映射见
@@ -33,13 +40,14 @@ export interface HookConfig {
   /** 是否启用（false 时不进入管线） */
   enabled: boolean;
   /** 错误策略：block=失败阻断管线，warn=记录警告继续 */
-  errorStrategy: 'block' | 'warn';
+  errorStrategy: HookErrorStrategy;
 }
 
 /**
  * Hook 定义
  *
  * Consumer 自行选择 name（如 'beforeAgentExecute'），harness 只提供管线。
+ * `enabled` / `errorStrategy` 不在此处声明——唯一声明点是 HookConfig（#159）。
  */
 export interface HookDefinition<C = unknown, R = unknown> {
   /** Hook 唯一名称（consumer 定义语义） */
@@ -48,16 +56,25 @@ export interface HookDefinition<C = unknown, R = unknown> {
   phase: HookPhase;
   /** 优先级（越小越先执行，默认 100） */
   priority?: number;
-  /** 错误策略：block=阻断管线, warn=记录警告继续, ignore=静默跳过 */
-  errorStrategy?: HookErrorStrategy;
   /** 采样率 0-1（1=100% 执行，0.1=10% 采样） */
   sampleRate?: number;
-  /** 是否启用 */
-  enabled?: boolean;
   /** Hook 执行函数 */
   execute: (context: C) => Promise<HookResult<R>>;
 }
 
+/**
+ * 有效 hook = HookDefinition + 注册环节由 HookConfig 填充的有效值
+ *
+ * 管线与注册表的判定（启用过滤、block/warn 分派）只读本类型，
+ * 值来源单一（HookConfig），不存在第二声明点。
+ */
+export interface EffectiveHook<C = unknown, R = unknown> extends HookDefinition<C, R> {
+  /** 是否启用（来自 HookConfig.enabled） */
+  enabled: boolean;
+  /** 错误策略（来自 HookConfig.errorStrategy） */
+  errorStrategy: HookErrorStrategy;
+}
+
 /**
  * Hook 执行结果
  */
@@ -84,6 +101,8 @@ export interface HookExecutionRecord {
   passed: boolean;
   error?: string;
   sampled?: boolean;
+  /** 未执行标记之二：enabled:false 被 runOne 跳过（实现体零调用，镜像 sampled 先例） */
+  skipped?: boolean;
 }
 
 /**

package/src/index.ts

@@ -152,7 +152,6 @@ export {
   registeredGateCount,
   assertGateRegistryClosed,
   runGates,
-  getEffectiveGates,
   createCheckerGate,
 } from './gates';
 export type {
@@ -163,7 +162,6 @@ export type {
   GateDecisionStatus,
   GateDefinition,
   GateRunResult,
-  GatesConfig,
   PerformanceThresholds,
   ReviewGateConfig,
   SecurityGateConfig,
@@ -357,6 +355,7 @@ export {
 export type {
   HookDefinition,
   HookConfig,
+  EffectiveHook,
   HookErrorStrategy,
   HookExecutionRecord,
   HookPhase,

package/src/knowledge/CONTEXT.md

@@ -17,13 +17,16 @@
 - 所有模式支持 `decayAt` 硬过期
 
 ## 核心导出
-- `KnowledgeStore` — 知识条目 CRUD + 结构化存储；`saveAll()` 批量写入（循环内只更新内存索引、结束一次 writeIndex，harness#107）
+- `KnowledgeStore`（类型面）/ `FileKnowledgeStore`（`store.ts`，barrel 与包根交出的**值**符号——store 的文件系统实现，构造收 `{ baseDir }`；仓内构造点两处：`cli/commands/knowledge-view.ts` 的 `openKnowledgeStore()`（knowledge 各子命令的取数口）与 `cli/commands/constraints-retire.ts` 的退役沉淀写入）— 知识条目 CRUD + 结构化存储；`saveAll()` 全量批量写入（循环内只更新内存索引、结束一次 writeIndex，harness#107）、`applyAll()` 按 id 部分更新的批量出口（`update(id, partial)` 的批量形，语义含未知 id 逐条跳过与空批零读写，harness#134）、`getConsumptionStats()` 读 `.consumption-stats.json` 的当日消费计数（打分核心唯一的消费统计取数口，harness#134）
 - `KnowledgeQuery` — 语义搜索 + 类型/标签过滤 + `queryByMode()` + `consume(taskContext)`；`query()` 是 budget 截断管线（仅用于 prompt 注入），`search()` 是全语料文本搜索（先匹配→排序→limit，交互搜索专用，勿用 query() 代替）
-- `KnowledgeLifecycle` — per-mode 生命周期管理
+- `KnowledgeLifecycle` — per-mode 生命周期管理；缺省阈值常量 `DEFAULT_DECAY_CONFIG`（`provenDecayMonths: 12` / `verifiedDecayMonths: 6` / `draftDecayMonths: 3` / `autoPromoteSources: []`，正本 `types.ts`）经构造器 `{...DEFAULT_DECAY_CONFIG, ...config}` 合并，barrel 与包根一并交出
+- `extractCodeStructure(dir)`（`primitives/code-structure.ts`，配 `CodeStructure`/`DeclarationInfo`/`ImportInfo` 三类型对外）— 目录代码结构提取；仓内零调用方，是留给下游的公开面
 - `KnowledgeIngest` — 知识摄取引擎（含 ingest gate 质量门）+ `ingestExternal()` 外部内容摄入
 - `sanitizeExternalContent` — 外部内容安全清洗（过滤注入模式 + 长度限制）
-- `migrateKnowledgeEntries` — AS-021 迁移工具（为现有条目添加 consumptionMode/origin）
-- `KnowledgeAudit` — 7 维度质量审计引擎。per-entry 规则记录带 `scope: 'active' | 'all'`（active = 不判定 archived 条目）；人口过滤由 `ruleDetail()` 统一执行，规则内禁止再写 `entry.maturity === 'archived'` 早返回。规则中文 label 正本在规则定义的 `label` 字段（harness#109，ADR-0002 定义即注册），`AUDIT_RULE_LABELS` 派生导出、与 `AuditRuleName` 编译期闭环，CLI 展示层直接消费、禁止另建 label 表
+- `migrateKnowledgeEntries` — AS-021 迁移工具（为现有条目添加 consumptionMode/origin）；条目人口按 `tree-walker` 口径判定，`_index.md` 等树生成物不计入 `total`/`errors`（harness#134 修此前假阳性）
+- `KnowledgeAudit` — 7 维度质量审计**引擎**：构造收 `KnowledgeStore`（与 lint / doctor / query / lifecycle / ingest 同形，harness#134——此前收目录并自建 store，致使打分判定无法脱离文件系统测试）+ 可选阈值形参（三个数值槽显式传 NaN/±Infinity/负数时构造期抛 `TypeError`（message 含槽名与实参），不放行到打分层静默关掉 short-content/stale-entry/promotion-blocked 三条判定；未传/显式 `undefined` 走缺省、显式 `0` 合法按 0 生效，harness#163）。职责只剩装配：取条目、经 store 取环境数据、把整批修复动作交 `store.applyAll()`。per-entry 规则记录带 `scope: 'active' | 'all'`（active = 不判定 archived 条目）；人口过滤由 `ruleDetail()` 统一执行，规则内禁止再写 `entry.maturity === 'archived'` 早返回。规则中文 label 正本在规则定义的 `label` 字段（harness#109，ADR-0002 定义即注册），`AUDIT_RULE_LABELS` 派生导出、与 `AuditRuleName` 编译期闭环，CLI 展示层直接消费、禁止另建 label 表
+- `audit-scoring`（**值面**不进导出面；类型面是例外——`AuditRuleName`/`AuditAction`/`AuditIssue`/`AuditReport`/`AuditOptions` 经 `index.ts` 再导出并上包根，ADR-0003 显式清单）— D1–D7 打分**纯模块**（harness#134）：规则表、`scanEntries()` / `summarizeIssues()` / `computeDimensions()` / `calculateHealthScore()`，零 fs——环境数据（消费统计、快照存活）由调用方经 store 取好喂入。审计判定的唯一正本在此，可脱离合建目录测试
+- `tree-walker`（包内，不进导出面）— 知识树排除口径单点（harness#134）：`isEntryFile()` / `isInfraDir()` / `INDEX_MD_FILE` / `SNAPSHOTS_DIR`，由 store 顶层扫描、migration 顶层扫描、index-generator 递归扫描三处共同消费
 - `flywheel-metrics`（包内，不进导出面）— 知识飞轮指标唯一实现：`evaluateFlywheel(env)` 出 canonical 比例、`genuineRefs()` 出 synthetic 过滤口径，audit D6 / `knowledge stats` / `knowledge health` 三处共消费（ADR-0013）
 - `ReferenceTracker` — 知识引用关系图谱
 - `KnowledgeLinter` — 知识质量检查(完整性/一致性/时效性)
@@ -31,19 +34,22 @@
 - `KnowledgeHealthScorer` — 知识健康评分（doctor.ts）
 
 ## 依赖关系
-- 依赖 `src/types/` 知识相关类型
+- 知识类型正本在**本模块** `src/knowledge/types.ts`（`KnowledgeEntry`/`MaturityLevel`/`ConsumptionMode`/`KnowledgeOrigin`/`DecayConfig`…）；本目录对 `src/types/` **零 import**——旧条目「依赖 `src/types/` 知识相关类型」不实（harness#142 逐条核对）
 - 依赖 `src/utils/frontmatter` — markdown frontmatter 解析/序列化的唯一正本（harness#89：store、migration、index-generator、ingest 共用同一套语法判定，不再各写正则）
 - 不依赖 `src/context/`（原 `lifecycle-hooks.ts` 是唯一 import `context/types` 的文件，已随 ADR-0022 删除），也不依赖 monitoring——知识健康评分由本目录 doctor.ts 的 KnowledgeHealthScorer 承载
 - 被 `src/cli/commands/knowledge.ts` CLI 消费（含 `migrate` 子命令）
 
 ## 约定
-- 知识条目文件的 frontmatter 语法只由 `src/utils/frontmatter` 定义（harness#89）：缺头/空 meta = `absent`（合法输入，按非条目静默处理）；未闭合/YAML 非法 = `malformed`（必须显式上报后按消费方语义恢复——migration 落 `errors`、store 与 index-generator 打一行 stderr 后跳过或走 best-effort），禁止静默丢条目；canonical 字段序是 `store.toFrontmatter` 的私有策略，`join` 只管包裹格式
+- 知识条目文件的 frontmatter 语法只由 `src/utils/frontmatter` 定义（harness#89）：缺头/空 meta = `absent`（合法输入，按非条目静默处理、不上报——migration 对 `absent` 不计 `errors`、不迁移，只计 `skipped` 保证 `total` 计数闭环，harness#161 对齐 #89 裁决 2）；未闭合/YAML 非法 = `malformed`（必须显式上报后按消费方语义恢复——migration 落 `errors`、store 与 index-generator 打一行 stderr 后跳过或走 best-effort），禁止静默丢条目；canonical 字段序是 `store.toFrontmatter` 的私有策略，`join` 只管包裹格式
+- **知识树的排除口径只有一个正本 `tree-walker`**（harness#134）：`_index.md`（索引生成物）、`.snapshots`、`.archive` / `archived`、`resolutions` 是树基建、不是条目人口。store 与 migration 的顶层扫描、index-generator 的递归扫描三处都走它；新增 walker 禁止另立排除清单。统一的是**排除口径**不是遍历深度（store/migration 顶层、index-generator 递归）。例外须原地记名理由：`import.ts` 的 docs 扫描吃的是**项目文档树**，本口径在它那里没有对应物
+- **循环内禁止逐条 `store.update()`**（harness#134）：`update()` 的形状是 get→save、`save()` 每次全量重写 index.json，N 条修复 = N 次全量重写。批量形是 `applyAll(id → partial)`；一次 `audit --fix`、一轮 `runDecayCycle()`、一次 `updateReferencedBy()` 各只重写一次索引，计数闸见 `audit-write-count.test.ts` 与 `lifecycle.test.ts` / `reference-tracker.test.ts` 的 stringify 计数项
+- **审计判定脱离文件系统可测**（harness#134）：规则表与 D1–D7 打分住 `audit-scoring.ts`，零 fs（源形状闸钉在 `audit-scoring.test.ts`）；引擎 `audit.ts` 只做 store 装配，环境数据经 `store.getConsumptionStats()` / `getSurvivalRate()` 取好喂入
 - 知识条目有明确的生命周期状态（按 consumptionMode 分化）
 - 约束退役（`harness constraints retire`，人确认）时写入 KnowledgeStore：规则原文 + 退役原因 + 历史统计
 - Linter 检查完整性/一致性/时效性三个维度
 - Audit 7 维度评分：D1结构 D2内容 D3去重 D4成熟度 D5新鲜度 D6飞轮 D7增量存活
 - Ingest gate: ingestEntry() 先经 audit.validate() 检查，reject 不入库
-- 外部内容三层防御：ingest sanitization + retrieval marking + prompt constraint
+- 外部内容三层防御：ingest sanitization + retrieval marking + prompt constraint。第二层 marking 已接线（harness#161）：标记正本是 `knowledge/query.ts` 的 `EXTERNAL_SOURCE_MARKER` 常量（`[External Source — verify before acting]`），`KnowledgeQuery.formatForPrompt()` 与注入路径 `context/knowledge-injector.ts` 的 `formatEntry()`/`formatEntrySummary()` 共用同一常量——`origin === 'external'` 条目注入 prompt 时带来源前缀，注入 source 的 metadata 带 `origin`。第三层（prompt constraint）在本仓不可核（属 studio/agent 侧提示词），未核不改
 - 消费饱和度替代固定 TTL 用于 signal 过期判断
 - **飞轮指标只有一个实现**（ADR-0013）：`refCoverage` / `avgRefs` / `consumptionHitRate` 一律出自 `flywheel-metrics.evaluateFlywheel()`，canonical 分子 = `genuineRefs()` 过滤后的真实消费引用（`search|test-agent|prompt-inject|monitor|analyst|...:<date>` 自动化按天记账键不算消费，`unknown:` 注入键算消费）。audit D6 / `knowledge stats` / `knowledge health` 只在展示层做单位与字段名映射（百分比取整、一位小数、`avgRefs`→`avgRefCount`），人口筛选留在各调用方。新增消费方禁止自行数 `referencedBy.length`。
 
@@ -53,3 +59,4 @@
 - `MaturityLevel` 包含 6 个值: draft/verified/proven/archived/active/deprecated
 - `excludeArchived` 同时排除 archived 和 deprecated
 - 仍有两处按**原始** `referencedBy.length` 判定，不属飞轮指标、ADR-0013 明确列为范围外：`lifecycle.ts` 的 signal 饱和 / reference 激活（退役阈值调整另票）、`knowledge health` 的 D1「verified 零引用」线索提示（逐条 issue 线索，非聚合分子）
+- #134 收口后仍在的逐条写点（同型问题，本票裁决点名的循环之外，需要时另票）：`lint.ts` 的三处 autoFix `store.update()`、`lifecycle.recordReference()`（逐事件调用，返回更新后条目并触发回调，批量化会改它的契约）、`ingest.mergeEntries()`；`store.list()` 每条一次 `findFile()` 线性扫索引的 O(N²) 按 #134 裁决**未动**，待把知识树实际规模重新量一次再判是否单开票

package/src/knowledge/__tests__/audit-labels.test.ts

@@ -1,15 +1,18 @@
 /**
  * 审计规则 label 闭环测试（架构评审 A6，#109）
  *
- * label 正本在 audit.ts 规则定义上（定义即注册），AUDIT_RULE_LABELS 派生自规则表。
- * 新增规则无 label → 编译期/本测试期即失败，CLI 不再静默回落英文键名。
+ * label 正本在规则定义上（定义即注册，#134 后随规则表住在 audit-scoring.ts），
+ * AUDIT_RULE_LABELS 派生自规则表。新增规则无 label → 编译期/本测试期即失败，
+ * CLI 不再静默回落英文键名。
  */
 
 import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
-import { KnowledgeAudit, AUDIT_RULE_LABELS } from '../audit';
-import type { AuditRuleName } from '../audit';
+import { KnowledgeAudit } from '../audit';
+import { AUDIT_RULE_LABELS } from '../audit-scoring';
+import type { AuditRuleName } from '../audit-scoring';
+import { FileKnowledgeStore } from '../store';
 
 function makeTmpDir(): string {
   return fs.mkdtempSync(path.join(os.tmpdir(), 'audit-labels-test-'));
@@ -27,7 +30,7 @@ describe('AUDIT_RULE_LABELS', () => {
   });
 
   it('应与运行期 summary 的规则键集完全一致（双向闭环）', () => {
-    const report = new KnowledgeAudit({ baseDir: tmpDir }).run();
+    const report = new KnowledgeAudit(new FileKnowledgeStore({ baseDir: tmpDir })).run();
     const summaryKeys = Object.keys(report.summary).sort();
     const labelKeys = (Object.keys(AUDIT_RULE_LABELS) as AuditRuleName[]).sort();
     expect(labelKeys).toEqual(summaryKeys);

package/src/knowledge/__tests__/audit-scoring.test.ts

@@ -0,0 +1,230 @@
+/**
+ * audit-scoring 纯模块测试（harness#134）
+ *
+ * 本模块的立身之本是**零 IO**：判定只吃条目数组与已取好的环境数据。
+ * 因此这里既有行为断言，也有一道源形状闸——有人往打分核心塞回 fs，就跑红。
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import {
+  AUDIT_RULE_LABELS,
+  DEFAULT_PROMOTION_BLOCK_DAYS,
+  DEFAULT_SHORT_CONTENT_THRESHOLD,
+  DEFAULT_STALE_DAYS,
+  MAX_SOURCE_REFS,
+  calculateHealthScore,
+  computeDimensions,
+  resolveThresholds,
+  scanEntries,
+  summarizeIssues,
+} from '../audit-scoring';
+import type { AuditIssue } from '../audit-scoring';
+import type { KnowledgeEntry } from '../types';
+
+const SOURCE = fs.readFileSync(path.join(__dirname, '../audit-scoring.ts'), 'utf-8');
+
+function makeEntry(overrides: Partial<KnowledgeEntry> = {}): KnowledgeEntry {
+  return {
+    id: 'SCORE-001',
+    type: 'guideline',
+    title: 'Scoring Entry',
+    content: 'Some meaningful content that is long enough to pass thresholds',
+    maturity: 'draft',
+    layer: 'project',
+    created: new Date().toISOString(),
+    lastReferenced: new Date().toISOString(),
+    contributors: ['tester'],
+    projects: ['probe'],
+    tags: [],
+    applicablePhases: [],
+    sourceReferences: [],
+    referencedBy: [],
+    executionResults: [],
+    consumptionMode: 'reference',
+    origin: 'agent',
+    ...overrides,
+  };
+}
+
+describe('源形状闸：打分核心零 IO', () => {
+  it('不 import fs/path，也不直读 store 之外的任何东西', () => {
+    expect(SOURCE).not.toMatch(/from '(node:)?fs'/);
+    expect(SOURCE).not.toMatch(/from 'path'/);
+    expect(SOURCE).not.toMatch(/\bfs\.(readFileSync|existsSync|writeFileSync|readdirSync)\b/);
+    expect(SOURCE).not.toMatch(/new FileKnowledgeStore/);
+  });
+
+  it('条目集合外唯一的入参是 env（消费统计与存活率由调用方取好喂入）', () => {
+    expect(SOURCE).toContain('env: AuditEnv');
+    expect(SOURCE).toContain('dailyConsumptionEvents?: number');
+  });
+});
+
+describe('resolveThresholds', () => {
+  it('未给阈值时落三张缺省值', () => {
+    expect(resolveThresholds()).toEqual({
+      shortContentThreshold: DEFAULT_SHORT_CONTENT_THRESHOLD,
+      staleDays: DEFAULT_STALE_DAYS,
+      promotionBlockDays: DEFAULT_PROMOTION_BLOCK_DAYS,
+    });
+  });
+
+  it('显式值原样生效（含 0 不被缺省兜掉）', () => {
+    expect(resolveThresholds({ shortContentThreshold: 0, staleDays: 7 }).shortContentThreshold).toBe(0);
+    expect(resolveThresholds({ staleDays: 7 }).staleDays).toBe(7);
+  });
+});
+
+describe('scanEntries 的人口语义', () => {
+  it('单条目模式（不传人口）下跨条目规则不判定', () => {
+    const dupes = [
+      makeEntry({ id: 'P-1', title: 'Same', type: 'guideline' }),
+      makeEntry({ id: 'P-2', title: 'Same', type: 'guideline' }),
+    ];
+    for (const entry of dupes) {
+      expect(scanEntries([entry], {}).some(i => i.rule === 'title-duplicate')).toBe(false);
+    }
+  });
+
+  it('传入人口时同一对条目互相判重（两条都报）', () => {
+    const dupes = [
+      makeEntry({ id: 'P-1', title: 'Same', type: 'guideline' }),
+      makeEntry({ id: 'P-2', title: 'Same', type: 'guideline' }),
+    ];
+    const issues = scanEntries(dupes, {}, dupes);
+    expect(issues.filter(i => i.rule === 'title-duplicate')).toHaveLength(2);
+  });
+
+  it('人口与扫描集合可不同：autoFix 重扫沿用修复前人口的现状口径', () => {
+    const before = [
+      makeEntry({ id: 'Q-1', title: 'Dup', type: 'guideline' }),
+      makeEntry({ id: 'Q-2', title: 'Dup', type: 'guideline' }),
+    ];
+    const after = before.map(e => ({ ...e, maturity: 'archived' as const }));
+    // 扫描已归档的集合、对照未归档的人口：active 规则不判定 archived，故零问题
+    expect(scanEntries(after, {}, before)).toHaveLength(0);
+    // 对照集合同为已归档：同样零问题（人口过滤唯一落点在 ruleDetail）
+    expect(scanEntries(after, {}, after)).toHaveLength(0);
+  });
+});
+
+describe('summarizeIssues', () => {
+  it('未命中的规则也出零值键，键集与 label 正本表一致', () => {
+    const summary = summarizeIssues([]);
+    expect(Object.keys(summary).sort()).toEqual(Object.keys(AUDIT_RULE_LABELS).sort());
+    expect(Object.values(summary).every(n => n === 0)).toBe(true);
+  });
+
+  it('命中计数逐条累加', () => {
+    const issues: AuditIssue[] = [
+      { rule: 'short-content', entryId: 'a', title: 'A', severity: 'medium', action: 'flag', detail: '' },
+      { rule: 'short-content', entryId: 'b', title: 'B', severity: 'medium', action: 'flag', detail: '' },
+      { rule: 'event-noise', entryId: 'c', title: 'C', severity: 'critical', action: 'archive', detail: '' },
+    ];
+    const summary = summarizeIssues(issues);
+    expect(summary['short-content']).toBe(2);
+    expect(summary['event-noise']).toBe(1);
+  });
+});
+
+describe('computeDimensions 的环境数据入参', () => {
+  const active = [
+    makeEntry({ id: 'D-1', maturity: 'verified', referencedBy: ['x:2026-09-01'] }),
+    makeEntry({ id: 'D-2', maturity: 'verified' }),
+  ];
+
+  it('D6 消费事件数来自 env，透传到报告明细', () => {
+    const withOut = computeDimensions(active, [], {});
+    const withEnv = computeDimensions(active, [], { dailyConsumptionEvents: 8 });
+    expect(withOut.flywheel.details.dailyConsumptionEvents).toBe(0);
+    expect(withEnv.flywheel.details.dailyConsumptionEvents).toBe(8);
+    expect(withEnv.flywheel.score).toBeGreaterThan(withOut.flywheel.score);
+  });
+
+  it('D7 由 env.survival 供给：无快照 = 满分带说明，有快照 = 分数即存活率', () => {
+    expect(computeDimensions(active, [], {}).incremental).toEqual({
+      score: 100,
+      issues: 0,
+      details: { note: 'no 30d snapshot available' },
+    });
+    expect(computeDimensions(active, [], {
+      survival: { rate: 60, survived: 6, total: 10, snapshotDate: '2026-08-10' },
+    }).incremental).toEqual({
+      score: 60,
+      issues: 4,
+      details: { survivalRate: 60, survived: 6, total: 10, snapshotDate: '2026-08-10' },
+    });
+  });
+
+  it('空人口：结构与成熟度满分、飞轮零分（无活动可测）', () => {
+    const dims = computeDimensions([], [], {});
+    expect(dims.structure.score).toBe(100);
+    expect(dims.maturity.score).toBe(100);
+    expect(dims.flywheel.score).toBe(0);
+  });
+});
+
+describe('calculateHealthScore', () => {
+  const base = [makeEntry({ id: 'H-1', maturity: 'verified' }), makeEntry({ id: 'H-2', maturity: 'verified' })];
+  const issue = (severity: AuditIssue['severity']): AuditIssue => ({
+    rule: 'short-content', entryId: 'H-1', title: 'H', severity, action: 'flag', detail: '',
+  });
+
+  it('无问题 = 100', () => {
+    expect(calculateHealthScore(base, [])).toBe(100);
+  });
+
+  it('惩罚按严重度分级：critical > high > medium > low', () => {
+    const critical = calculateHealthScore(base, [issue('critical')]);
+    const low = calculateHealthScore(base, [issue('low')]);
+    expect(critical).toBeLessThan(low);
+    expect(low).toBeLessThan(100);
+  });
+
+  it('四档严重度各自的罚分权重（满分 100，人口 2 → 每条满罚 10 分权重）', () => {
+    // penalty / (entries × 10) → critical 10、high 5、medium 2、low 1
+    expect(calculateHealthScore(base, [issue('critical')])).toBe(50);
+    expect(calculateHealthScore(base, [issue('high')])).toBe(75);
+    expect(calculateHealthScore(base, [issue('medium')])).toBe(90);
+    expect(calculateHealthScore(base, [issue('low')])).toBe(95);
+  });
+
+  it('条目为空时恒 100（无人口不判健康度）', () => {
+    expect(calculateHealthScore([], [issue('critical')])).toBe(100);
+  });
+});
+
+describe('fragment-cluster（跨条目规则）', () => {
+  it('同 type + 共享 ≥2 标签 + 正文均 <100 字符且 peers≥2 才成簇', () => {
+    const short = (id: string, tags: string[]): KnowledgeEntry =>
+      makeEntry({ id, type: 'guideline', maturity: 'verified', content: '短'.repeat(20), tags });
+    const population = [short('FC-1', ['auth', 'db']), short('FC-2', ['auth', 'db']), short('FC-3', ['auth', 'db'])];
+    const issues = scanEntries(population, {}, population);
+    expect(issues.filter(i => i.rule === 'fragment-cluster').map(i => i.entryId).sort())
+      .toEqual(['FC-1', 'FC-2', 'FC-3']);
+  });
+
+  it('peers 只有 1 个时不成簇', () => {
+    const short = (id: string): KnowledgeEntry =>
+      makeEntry({ id, type: 'guideline', maturity: 'verified', content: '短'.repeat(20), tags: ['auth', 'db'] });
+    const population = [short('FC-1'), short('FC-2'), makeEntry({ id: 'FC-LONG', type: 'guideline', maturity: 'verified', content: '长'.repeat(120), tags: ['auth', 'db'] })];
+    const issues = scanEntries(population, {}, population);
+    expect(issues.filter(i => i.rule === 'fragment-cluster')).toHaveLength(0);
+  });
+});
+
+describe('MAX_SOURCE_REFS', () => {
+  it('正好上限不报，超一条才报', () => {
+    const atLimit = makeEntry({
+      id: 'R-1',
+      sourceReferences: Array.from({ length: MAX_SOURCE_REFS }, (_, i) => ({ workflow: `w${i}`, timestamp: '' })),
+    });
+    const overLimit = makeEntry({
+      id: 'R-2',
+      sourceReferences: Array.from({ length: MAX_SOURCE_REFS + 1 }, (_, i) => ({ workflow: `w${i}`, timestamp: '' })),
+    });
+    expect(scanEntries([atLimit], {}).some(i => i.rule === 'source-refs-bloat')).toBe(false);
+    expect(scanEntries([overLimit], {}).some(i => i.rule === 'source-refs-bloat')).toBe(true);
+  });
+});

package/src/knowledge/__tests__/audit-write-count.test.ts

@@ -0,0 +1,131 @@
+/**
+ * 一次 `audit --fix` 的索引重写计数闸（harness#134 验收 2）
+ *
+ * 手法照 `src/cli/commands/__tests__/check-read-count.test.ts`：真执行、只在中间记一笔，
+ * 不改任何行为。数的是**底层 index.json 被重写了几次**——`store.writeIndex()` 的唯一出口
+ * 就是 `fs.writeFileSync(index.json)`，而 fs 属性不可 spyOn，故按该文件的做法整体 mock。
+ *
+ * 收口前：一次修复 = 一次 `store.update()` = 一次全量索引重写 → 计数 = 问题条数。
+ * 收口后：整批经 `store.applyAll()` → 计数 = 1。夹具必须让四种修复动作都真发生，
+ * 否则闸门是空跑的。
+ */
+
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { KnowledgeAudit } from '../audit';
+import { FileKnowledgeStore } from '../store';
+import type { KnowledgeEntry } from '../types';
+
+type WriteCall = { file: string };
+
+// 计数器挂在 globalThis：jest.mock 工厂会被提前调用，闭包外提会撞 TDZ
+jest.mock('fs', () => {
+  const actual = jest.requireActual<typeof import('fs')>('fs');
+  const g = globalThis as unknown as { __H134_INDEX_WRITES__?: WriteCall[] };
+  if (!g.__H134_INDEX_WRITES__) g.__H134_INDEX_WRITES__ = [];
+  const bucket = g.__H134_INDEX_WRITES__;
+  const name = (p: unknown): string => (Buffer.isBuffer(p) ? p.toString('utf8') : String(p));
+
+  return {
+    ...actual,
+    writeFileSync: jest.fn((p: unknown, ...rest: unknown[]) => {
+      bucket.push({ file: name(p) });
+      return (actual.writeFileSync as (...args: unknown[]) => unknown)(p, ...rest);
+    }),
+  };
+});
+
+const writes = () =>
+  ((globalThis as unknown as { __H134_INDEX_WRITES__?: WriteCall[] }).__H134_INDEX_WRITES__ ||= []);
+
+function makeEntry(overrides: Partial<KnowledgeEntry> = {}): KnowledgeEntry {
+  return {
+    id: 'WC-001',
+    type: 'guideline',
+    title: 'Write Count Entry',
+    content: 'Some meaningful content that is long enough to pass thresholds',
+    maturity: 'verified',
+    layer: 'project',
+    created: new Date().toISOString(),
+    lastReferenced: new Date().toISOString(),
+    contributors: ['tester'],
+    projects: ['probe'],
+    tags: [],
+    applicablePhases: [],
+    sourceReferences: [],
+    referencedBy: [],
+    executionResults: [],
+    consumptionMode: 'reference',
+    origin: 'agent',
+    ...overrides,
+  };
+}
+
+/** 四种修复动作各一条：archive（测试标签）/ demote（零内容 proven）/ flag（短内容）/ trim（refs 膨胀） */
+function fixtureEntries(): KnowledgeEntry[] {
+  return [
+    makeEntry({ id: 'WC-ARCH', title: 'Archive Me', maturity: 'verified', tags: ['test-scope-wc'] }),
+    makeEntry({ id: 'WC-DEMOTE', title: 'Demote Me', maturity: 'proven', content: 'tiny' }),
+    makeEntry({ id: 'WC-FLAG', title: 'Flag Me', maturity: 'verified', content: 'a'.repeat(30) }),
+    makeEntry({
+      id: 'WC-TRIM',
+      title: 'Trim Me',
+      maturity: 'verified',
+      sourceReferences: Array.from({ length: 25 }, (_, i) => ({ workflow: `wf-${i}`, timestamp: '' })),
+    }),
+  ];
+}
+
+describe('一次 audit --fix 的 index.json 重写计数（harness#134）', () => {
+  let dir: string;
+
+  beforeEach(() => {
+    writes().length = 0;
+    dir = fs.mkdtempSync(path.join(os.tmpdir(), 'audit-write-count-'));
+    const seed = new FileKnowledgeStore({ baseDir: dir });
+    for (const entry of fixtureEntries()) seed.save(entry);
+    writes().length = 0; // 只数审计这一段
+  });
+
+  afterEach(() => {
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  it('4 条修复只重写一次 index.json，条目文件各重写一次', () => {
+    const audit = new KnowledgeAudit(new FileKnowledgeStore({ baseDir: dir }));
+    const report = audit.run({ autoFix: true });
+
+    // 正对照：四种动作全部真发生
+    expect(report.autoFixed).toBe(4);
+
+    const indexWrites = writes().filter(w => path.basename(w.file) === 'index.json');
+    const entryWrites = writes().filter(w => w.file.endsWith('.md'));
+    expect(indexWrites).toHaveLength(1);
+    expect(entryWrites.map(w => path.basename(w.file)).sort()).toEqual([
+      'guideline-WC-ARCH.md',
+      'guideline-WC-DEMOTE.md',
+      'guideline-WC-FLAG.md',
+      'guideline-WC-TRIM.md',
+    ]);
+  });
+
+  it('无修复项时零索引重写（applyAll 空批不落盘）', () => {
+    const cleanDir = fs.mkdtempSync(path.join(os.tmpdir(), 'audit-write-count-clean-'));
+    const seed = new FileKnowledgeStore({ baseDir: cleanDir });
+    seed.save(makeEntry({
+      id: 'WC-CLEAN',
+      title: 'Perfectly Ordinary Title',
+      maturity: 'verified',
+      content: 'x'.repeat(200),
+      referencedBy: ['someone:2026-09-14'],
+    }));
+    writes().length = 0;
+
+    const report = new KnowledgeAudit(new FileKnowledgeStore({ baseDir: cleanDir })).run({ autoFix: true });
+
+    expect(report.autoFixed).toBe(0); // 正对照：确实无可修项
+    expect(writes().filter(w => path.basename(w.file) === 'index.json')).toHaveLength(0);
+    fs.rmSync(cleanDir, { recursive: true, force: true });
+  });
+});