@dommaker/harness 1.6.0 → 1.8.0

package/src/__tests__/skip-semantics.test.ts

@@ -18,6 +18,7 @@ import type { Constraint, ConstraintContext } from '../types/constraint';
 import type { ExecutionTrace } from '../types/trace';
 import * as fs from 'fs';
 import * as path from 'path';
+import * as os from 'os';
 import { execSync } from 'child_process';
 
 /** 套件共用 checker：显式 no-op 记录器（trace 断言的用例自带记录器实例） */
@@ -32,10 +33,10 @@ function makeConstraint(
 }
 
 describe('skip 三态语义（ADR-0001）', () => {
-  const tempDir = path.join(process.cwd(), 'temp-test-skip-semantics');
+  let tempDir: string;
 
   beforeAll(() => {
-    fs.mkdirSync(tempDir, { recursive: true });
+    tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'temp-test-skip-semantics-'));
     execSync('git init', { cwd: tempDir });
     execSync('git config user.email "test@test.com"', { cwd: tempDir });
     execSync('git config user.name "Test"', { cwd: tempDir });
@@ -227,9 +228,10 @@ describe('skip 三态语义（ADR-0001）', () => {
   });
 
   describe('detectTrigger 补 code_implementation 推断', () => {
-    const triggerDir = path.join(tempDir, 'trigger-probe');
+    let triggerDir: string;
 
     beforeAll(() => {
+      triggerDir = path.join(tempDir, 'trigger-probe');
       // src/ 下有已提交 .ts 文件 → detectSourceRoots 命中 'src'
       fs.mkdirSync(path.join(triggerDir, 'src'), { recursive: true });
       fs.writeFileSync(path.join(triggerDir, 'src', 'existing.ts'), 'export const x = 1;');

package/src/__tests__/spec-validator.test.ts

@@ -6,13 +6,14 @@ import { describe, it, expect, beforeAll, afterAll } from '@jest/globals';
 import { SpecValidator } from '../core/spec/validator';
 import * as fs from 'fs';
 import * as path from 'path';
+import * as os from 'os';
 
 describe('SpecValidator', () => {
-  const tempDir = path.join(process.cwd(), 'temp-test-spec');
+  let tempDir: string;
   let validator: SpecValidator;
 
   beforeAll(() => {
-    fs.mkdirSync(tempDir, { recursive: true });
+    tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'temp-test-spec-'));
     validator = SpecValidator.getInstance();
   });
 

package/src/__tests__/sub-barrels-explicit.test.ts

@@ -0,0 +1,87 @@
+/**
+ * 子 barrel 显式清单闸（harness#137，判据同 ADR-0003 / ADR-0022）
+ *
+ * ADR-0003 的「禁 export *」此前只钉到五个 `exports` 入口（`public-type-surface.test.ts`
+ * 的写法白名单闸），子目录 `index.ts` 的星号再导出不受管——星号让「这个 barrel 到底
+ * 对外给了什么」无法按名字回答，同名遮蔽（两个 `types.ts` 撞名）也在此处静默发生。
+ * 本闸把它扩到 src 下全部 barrel：**逐文件、逐条**登记豁免，未登记的 `export *` 即红。
+ *
+ * 与两道公共面闸的分工：入口清单（`src/index.ts` 等五个）由 `public-type-surface.test.ts`
+ * 与 `public-value-surface.test.ts` 逐字冻结，本闸不重复钉入口，只管**入口之外**的目录级
+ * barrel；新增子 barrel 星号由本闸管住。
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+
+const SRC_DIR = path.join(__dirname, '..');
+
+/**
+ * 已核无星号的 barrel 若日后引入 `export *`，需要在这里登记理由。
+ * 当前为空：harness#137 已把 8 处目录级星号全部改成显式清单（`failure/types.ts` 那处
+ * 是兼容再导出 shim，随票删除而非改写清单）。
+ */
+const STAR_EXEMPTIONS: Record<string, string> = {};
+
+/** 收集 src 下所有目录级 barrel（`<dir>/index.ts`），不含 `__tests__` 内的测试辅助文件 */
+function listBarrels(dir: string, out: string[] = []): string[] {
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name);
+    if (!entry.isDirectory() || entry.name === '__tests__') continue;
+    const indexTs = path.join(full, 'index.ts');
+    if (fs.existsSync(indexTs)) out.push(indexTs);
+    listBarrels(full, out);
+  }
+  return out;
+}
+
+/** 行首 `export *` / `export type *` / `export * as ns`（去注释后判定） */
+const STAR_EXPORT_RE = /^export\s+(?:type\s+\*)\s*|^export\s+\*/;
+
+function stripComments(code: string): string {
+  return code.replace(/\/\*[\s\S]*?\*\//g, '').replace(/^\s*\/\/.*$/gm, '');
+}
+
+function starExports(barrel: string): string[] {
+  const text = stripComments(fs.readFileSync(barrel, 'utf-8'));
+  return text
+    .split('\n')
+    .map(line => line.trim())
+    .filter(line => STAR_EXPORT_RE.test(line));
+}
+
+describe('子 barrel 显式清单（harness#137）', () => {
+  const barrels = [path.join(SRC_DIR, 'index.ts'), ...listBarrels(SRC_DIR)];
+
+  it('扫到了 barrel（扫空即说明遍历失效，不得假绿）', () => {
+    expect(barrels.length).toBeGreaterThan(5);
+  });
+
+  it('src 下每个目录 barrel 都不含 `export *`（豁免须逐条登记理由）', () => {
+    const offenders = barrels
+      .map(barrel => ({
+        barrel: path.relative(SRC_DIR, barrel),
+        stars: starExports(barrel),
+      }))
+      .filter(entry => entry.stars.length > 0 && !STAR_EXEMPTIONS[entry.barrel]);
+    expect(offenders).toEqual([]);
+  });
+
+  it('豁免登记是死账：登记过却已无星号的条目须撤销（防豁免面只增不减）', () => {
+    const stale = Object.keys(STAR_EXEMPTIONS).filter(
+      rel => !starExports(path.join(SRC_DIR, rel)).length
+    );
+    expect(stale).toEqual([]);
+  });
+
+  it('failure/types.ts 兼容再导出 shim 已删除（转发链第三跳收口）', () => {
+    // 正本在 src/types/failure.ts（工单 14 归位），原模块路径经双仓核实无引用方
+    expect(fs.existsSync(path.join(SRC_DIR, 'failure', 'types.ts'))).toBe(false);
+  });
+
+  it('failure barrel 直连类型正本，不再经 shim 中转', () => {
+    const text = stripComments(fs.readFileSync(path.join(SRC_DIR, 'failure', 'index.ts'), 'utf-8'));
+    expect(text).toContain("from '../types/failure'");
+    expect(text).not.toMatch(/from '\.\/types'/);
+  });
+});

package/src/__tests__/test-fixture-hygiene.test.ts

@@ -0,0 +1,53 @@
+/**
+ * 测试夹具卫生闸（harness#145）
+ *
+ * 钉住一件事：`__tests__` 里的文件系统夹具根一律经 `fs.mkdtempSync` 取每轮唯一目录，
+ * 不得再出现「cwd 下固定名 temp-test 目录」这种夹具形状。
+ *
+ * 固定名的危害：同一 checkout 的两个并发 jest 进程共享该路径，一方的 afterAll rmSync
+ * 会删掉另一方在用的夹具（表现为像产品 bug 的 flaky）；被 kill 的运行还会留下目录，
+ * 下一轮从脏夹具起步。唯一后缀（mkdtemp 前缀以 `-` 结尾）从根上消掉这两条。
+ *
+ * 只判「名字是否唯一」，不判「落在哪个父目录」：cwd 锚定行为本身是被测语义的套件
+ * （injection-writer / init-injection / parentDir opt-out）留在 cwd 是有意为之。
+ */
+
+import { describe, it, expect } from '@jest/globals';
+import * as fs from 'fs';
+import * as path from 'path';
+
+/** 固定名夹具形状：cwd 拼一个字面量 temp-test 目录名，且该名字不以 `-` 结尾（非 mkdtemp 前缀） */
+const FIXED_FIXTURE_RE = /(?:path\.)?join\(\s*process\.cwd\(\)\s*,\s*(['"])temp-test-([^'"]*)\1\s*\)/g;
+
+function collectTestFiles(dir: string, out: string[] = []): string[] {
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    if (entry.name === 'node_modules' || entry.name === 'dist' || entry.name === 'coverage') continue;
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) collectTestFiles(full, out);
+    else if (entry.name.endsWith('.test.ts')) out.push(full);
+  }
+  return out;
+}
+
+describe('测试夹具卫生（#145）', () => {
+  const repoRoot = path.join(__dirname, '..', '..');
+  const files = collectTestFiles(repoRoot);
+
+  it('扫描面非空（防止 glob 失效把闸扫成空集）', () => {
+    expect(files.length).toBeGreaterThan(100);
+  });
+
+  it('__tests__ 内不存在固定名 temp-test-* 夹具目录', () => {
+    const offenders: string[] = [];
+    for (const file of files) {
+      fs.readFileSync(file, 'utf-8').split('\n').forEach((line, idx) => {
+        FIXED_FIXTURE_RE.lastIndex = 0;
+        let m: RegExpExecArray | null;
+        while ((m = FIXED_FIXTURE_RE.exec(line)) !== null) {
+          if (!m[2].endsWith('-')) offenders.push(`${path.relative(repoRoot, file)}:${idx + 1}: ${line.trim()}`);
+        }
+      });
+    }
+    expect(offenders).toEqual([]);
+  });
+});

package/src/__tests__/trace-analyzer-extra.test.ts

@@ -7,16 +7,18 @@ import { TraceAnalyzer, createAnalyzer } from '../monitoring/trace-analyzer';
 import { TraceCollector } from '../monitoring/traces';
 import * as fs from 'fs';
 import * as path from 'path';
+import * as os from 'os';
 import type { ExecutionTrace } from '../types/trace';
 
 describe('TraceAnalyzer - 补充覆盖', () => {
-  const tempDir = path.join(process.cwd(), 'temp-test-analyzer-extra');
-  const logFile = path.join(tempDir, 'traces.log');
+  let tempDir: string;
+  let logFile: string;
   let collector: TraceCollector;
   let analyzer: TraceAnalyzer;
 
   beforeAll(() => {
-    fs.mkdirSync(tempDir, { recursive: true });
+    tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'temp-test-analyzer-extra-'));
+    logFile = path.join(tempDir, 'traces.log');
     fs.writeFileSync(logFile, '');
   });
 

package/src/__tests__/trace-analyzer.test.ts

@@ -11,16 +11,18 @@ import {
 import { TraceCollector } from '../monitoring/traces';
 import * as fs from 'fs';
 import * as path from 'path';
+import * as os from 'os';
 import type { ExecutionTrace, TraceSummary } from '../types/trace';
 
 describe('TraceAnalyzer', () => {
-  const tempDir = path.join(process.cwd(), 'temp-test-analyzer');
-  const logFile = path.join(tempDir, 'traces.log');
+  let tempDir: string;
+  let logFile: string;
   let collector: TraceCollector;
   let analyzer: TraceAnalyzer;
 
   beforeAll(() => {
-    fs.mkdirSync(tempDir, { recursive: true });
+    tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'temp-test-analyzer-'));
+    logFile = path.join(tempDir, 'traces.log');
     fs.writeFileSync(logFile, '');
     collector = new TraceCollector({ traceFile: logFile, enabled: true });
     analyzer = new TraceAnalyzer(collector);

package/src/__tests__/trace-collector.test.ts

@@ -6,15 +6,17 @@ import { describe, it, expect, beforeAll, afterAll, beforeEach } from '@jest/glo
 import { TraceCollector } from '../monitoring/traces';
 import * as fs from 'fs';
 import * as path from 'path';
+import * as os from 'os';
 import type { ExecutionTrace } from '../types/trace';
 
 describe('TraceCollector', () => {
-  const tempDir = path.join(process.cwd(), 'temp-test-traces');
-  const traceFile = path.join(tempDir, 'traces.log');
+  let tempDir: string;
+  let traceFile: string;
   let collector: TraceCollector;
 
   beforeAll(() => {
-    fs.mkdirSync(tempDir, { recursive: true });
+    tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'temp-test-traces-'));
+    traceFile = path.join(tempDir, 'traces.log');
   });
 
   afterAll(() => {

package/src/agents/index.ts

@@ -1,2 +1,13 @@
-export * from './types';
-export * from './lifecycle';
+/**
+ * Agents 模块导出（ADR-0003：显式清单，禁 export *，harness#137）
+ */
+
+export type {
+  AgentStatus,
+  AgentConfig,
+  AgentState,
+  AgentEvent,
+  FallbackStrategy,
+} from './types';
+export { AgentLifecycle } from './lifecycle';
+export type { EventHandler } from './lifecycle';

package/src/cli/__tests__/gate-command.test.ts

@@ -0,0 +1,162 @@
+/**
+ * 门禁命令共享面测试（架构评审候选1）
+ *
+ * 替身是「假门禁产决策」：不碰 git、不装 gh、不跑真扫描。
+ * 断言「六条门禁的失败措辞形状一致」——这份断言在映射散在 6 个 handler 时写不出来。
+ */
+
+import {
+  gateCommandResult,
+  reportGateDecision,
+  reportGateError,
+  type GateCommandView,
+} from '../gate-command';
+import { decisionFromResult } from '../../gates/decision';
+import { gateResult } from '../../gates/types';
+import type { GateDecisionStatus } from '../../gates/types';
+import { captureIO, type CapturingIO } from '../command-contract';
+
+jest.mock('chalk', () => ({
+  blue: jest.fn((s: string) => s),
+  green: jest.fn((s: string) => s),
+  red: jest.fn((s: string) => s),
+  gray: jest.fn((s: string) => s),
+}));
+
+function decide(
+  gateId: string,
+  passed: boolean,
+  message: string,
+  details?: Record<string, any>,
+  status?: GateDecisionStatus
+) {
+  return decisionFromResult(gateResult(gateId, passed, message, Date.now(), details), status);
+}
+
+function view(over: Partial<GateCommandView> = {}): GateCommandView {
+  return { gateId: 'review', label: '代码审查门控', ...over };
+}
+
+describe('gateCommandResult — 决策到命令结果的唯一映射', () => {
+  it('放行 → ok 且不带 reason', () => {
+    expect(gateCommandResult('review', decide('review', true, 'ok'))).toEqual({ kind: 'ok' });
+  });
+
+  it('拦下 → fail，reason 为 `<gateId> gate denied: <message>`', () => {
+    expect(gateCommandResult('review', decide('review', false, 'needs approval'))).toEqual({
+      kind: 'fail',
+      reason: 'review gate denied: needs approval',
+    });
+  });
+
+  it('六条门禁的 denied reason 形状一致', () => {
+    for (const id of ['review', 'security', 'performance', 'contract', 'acceptance', 'command']) {
+      expect(gateCommandResult(id, decide(id, false, 'boom'))).toEqual({
+        kind: 'fail',
+        reason: `${id} gate denied: boom`,
+      });
+    }
+  });
+
+  it('ask 无实现者 → fail-closed 按拦下计（与 runGates 聚合同规则）', () => {
+    expect(gateCommandResult('review', decide('review', true, 'need human', undefined, 'ask'))).toEqual({
+      kind: 'fail',
+      reason: 'review gate denied: need human',
+    });
+  });
+});
+
+describe('reportGateDecision — ✓/✗ 输出骨架', () => {
+  let io: CapturingIO;
+
+  beforeEach(() => {
+    io = captureIO();
+  });
+
+  it('通过：空行 + 通过横幅 + onPass 行', () => {
+    const result = reportGateDecision(
+      io,
+      view({ onPass: (r) => [`   审批: ${r.details!.approvals}`] }),
+      decide('review', true, 'ok', { approvals: 2 })
+    );
+
+    expect(io.outLines()).toEqual(['', '✅ 代码审查门控检查通过', '   审批: 2']);
+    expect(result).toEqual({ kind: 'ok' });
+  });
+
+  it('未通过：横幅 + message 行 + onFail 行（空串 = 空行）', () => {
+    const result = reportGateDecision(
+      io,
+      view({ onFail: () => ['', 'see the audit'] }),
+      decide('review', false, 'needs approval')
+    );
+
+    expect(io.outLines()).toEqual([
+      '',
+      '❌ 代码审查门控检查失败',
+      '   needs approval',
+      '',
+      'see the audit',
+    ]);
+    expect(result).toEqual({ kind: 'fail', reason: 'review gate denied: needs approval' });
+  });
+
+  it('不传闭包时只出空行与横幅（未通过仍出 message 行）', () => {
+    reportGateDecision(io, view(), decide('review', true, 'ok'));
+    reportGateDecision(io, view(), decide('review', false, 'nope'));
+
+    expect(io.outLines()).toEqual([
+      '',
+      '✅ 代码审查门控检查通过',
+      '',
+      '❌ 代码审查门控检查失败',
+      '   nope',
+    ]);
+  });
+
+  it('闭包返回空数组不产生多余行', () => {
+    reportGateDecision(io, view({ onPass: () => [] }), decide('review', true, 'ok'));
+    expect(io.outLines()).toEqual(['', '✅ 代码审查门控检查通过']);
+  });
+
+  it('label 决定横幅用词（验收标准无「门控」二字）', () => {
+    reportGateDecision(io, view({ gateId: 'acceptance', label: '验收标准' }), decide('acceptance', true, 'ok'));
+    expect(io.outLines()).toEqual(['', '✅ 验收标准检查通过']);
+  });
+});
+
+describe('reportGateError — 门禁之外的抛出物', () => {
+  let io: CapturingIO;
+
+  beforeEach(() => {
+    io = captureIO();
+  });
+
+  it('出错横幅 + `<gateId> gate error: <message>`', () => {
+    const result = reportGateError(io, 'review', '代码审查门控', new Error('boom'));
+
+    expect(io.outLines()).toEqual(['', '❌ 代码审查门控检查出错', '   boom']);
+    expect(result).toEqual({ kind: 'fail', reason: 'review gate error: boom' });
+  });
+
+  it('extra 按错误文本追加提示行', () => {
+    reportGateError(io, 'review', '代码审查门控', new Error('not a git repository'), (msg) =>
+      msg.includes('not a git repository') ? ['', '提示: 此命令需要在 Git 仓库中运行'] : []
+    );
+
+    expect(io.outLines()).toEqual([
+      '',
+      '❌ 代码审查门控检查出错',
+      '   not a git repository',
+      '',
+      '提示: 此命令需要在 Git 仓库中运行',
+    ]);
+  });
+
+  it('非 Error 抛出物按 String() 取原因', () => {
+    expect(reportGateError(io, 'contract', '契约门控', 'plain string')).toEqual({
+      kind: 'fail',
+      reason: 'contract gate error: plain string',
+    });
+  });
+});

package/src/cli/commands/CONTEXT.md

@@ -10,8 +10,12 @@ H5（#44）起：
 ## 核心导出
 - `COMMAND_DEFINITIONS`（definitions.ts）— 全部非门禁命令定义（纯数据模块、零闭包，禁止 import 命令实现；ADR-0010）
 - 命令契约（`src/cli/command-contract.ts`，上层目录）— `CommandResult` / `CommandKind` / `CommandIO` / `processIO` / `captureIO` / `lastJsonOutput` / `log` / `logError`
+- 门禁命令共享面（`src/cli/gate-command.ts`，上层目录）— `GateDecision → CommandResult` 的唯一映射 `gateCommandResult`，加 ✓/✗ 输出骨架 `reportGateDecision` 与出错横幅 `reportGateError`。同一句失败措辞此前抄在 6 个 handler 里（「`<id>` gate denied」×6 / 「`<id>` gate error」×4），门禁特有的指标行经 `onPass`/`onFail` 闭包传入（架构评审候选1）
+- 脚手架落盘面（`src/cli/commands/scaffold.ts`）— 受管文件（managed file）三态判定 `writeManagedFile` / 一组落盘 `runPlan` + 9 个站点工厂（含对外文案）；模板正文住 `scaffold-templates.ts`，落盘注入面 `ScaffoldFileSystem` 可换内存替身（harness#132）；CI 站点工厂 `harnessCheckCiFile` 带平台维度（github / gitlab，harness#143）；两道 Git hook 工厂 `preCommitHookFile` / `prePushHookFile`（后者 harness#144，带可执行位）
+- knowledge 投影面（`src/cli/commands/knowledge-view.ts`）— 11 个 knowledge 子操作的**display model** 渲染与出口：`emitKnowledgeView`（json/人读唯一分派 + 退出码）、`announce`（取数期进度行，`--json` 下静默）、`TONE_STYLES` 角色→样式单表、维度/规则 label 与 `toneForMaturity`/`toneForScore`/`toneForSeverity` 三张映射、`resolveKnowledgeBaseDir` + `openKnowledgeStore`（路径兜底与 store 构造单点）（harness#133）
 - 各命令文件：check / validate / passes-gate / init / report / status / spec / sync-docs / knowledge / sdd / failure / posteval-plan / release / constraints / spec-baseline-check
-- 6 门禁命令实现在 `acceptance` / `command` / `contract` / `performance` / `review` / `security`（其 CLI 元数据在 `src/gates/definitions.ts`，形状同为 `CommandDefinition`，ADR-0007）
+- 6 门禁命令实现在 `acceptance` / `command` / `contract` / `performance` / `review` / `security`（其 CLI 元数据在 `src/gates/definitions.ts`，形状同为 `CommandDefinition`，ADR-0007）；**判定一律穿过统一接口 `evaluate()`**，成败与措辞由共享面映射。`command` 只复用映射、保留自己的单行 ✓/✗ 输出（已对外的机器友好形状）；`security audit` / `acceptance list` / `contract validate-schema` / `review status` / `command --list/--level` 是只展示不判断的子命令，直读报告面（`scan()` 等），不套骨架
+- CLI 子命令 `command` 的两个分支共用同一台 gate 实例（#135/ADR-0024）：默认分支经 `evaluate()` 取裁决、`--level` 经同一实例的 `getRiskLevel()` 取等级，命令侧不再引用模块级单例出口——「配置传进去却到不了判定」的那条路已封。`--strict` 旗帜随 `CommandGateConfig.strict`（零消费者、从不生效）一并删除
 
 `constraints` 下挂治理子命令：`constraints report`（使用统计 + 退役候选诊断 + 配置健康 + 注入漂移，`--export` 脱敏）、`constraints retire`（交互选择 + 人确认退役；带 id 直达需显式 `--yes`（#24 人确认闸门），无 `--yes` 报错 + 非零退出码且不落盘；内置落 config.yml retired 元数据，custom 落 custom-constraints.yml 条目 retired 段（studio#82 D6 一处真相）+ KnowledgeStore 沉淀 + 治理注入段同步）。
 
@@ -25,29 +29,49 @@ H5（#44）起：
 
 ## 约定
 - 每个命令一个实现文件，命名与命令名一致（sync-docs 为模块族目录）
+- **CONTEXT.md 内容判定的采集侧住本层（harness#142 / ADR-0025）**：`sync-docs/context-syncer.ts` 的 `collectContextExportSurface(dirPath, projectPath)` 负责目录遍历（`findTsSourceFiles`，排 `__tests__/`、`*.d.ts`）、`export *` 与具名再导出的仓内目标解析（越出 projectPath、命中 `node_modules`/跳过目录即不并入）并按正本声明剔除类型-only；判定本体是 `core/constraints/context-reconcile.ts` 的纯函数，本层不写判定规则。`sync-docs` 的 4b 段对每个含 CONTEXT.md 的目录跑一次对撞：**内容漂移 → `--check` 判 fail 且 reason 点名文件与符号**；mtime 差异自此只是本地提示（`process.env.CI` 置位时连提示都不给，因全新 checkout 的时序无意义）。写入模式**不改写 CONTEXT.md**（散文不可机械生成），退出码面不变；`--json` 侧新增 `contentDrift` 与 `summary.contextContentDrift`
 - **新增命令 = 命令实现文件 + definitions.ts 一条定义（含 CLI 元数据与实现引用）+ 测试**，不再改 bin/harness.js
 - **definitions.ts 是纯数据模块（ADR-0010 后零闭包）**：禁止 import 任何命令实现/运行时依赖（保 --help/--version 懒加载）；子命令别名是数据（条目 `aliases: string[]`，不复印整块），实参编组（缺参闸门/强转/兜底）归各命令模块的具名导出（如 `knowledgeSearchCommand`/`coverageCheck`）；实现引用可解析性由 `__tests__/registry.test.ts` 构建/测试期断言
 - 命令选项类型命名规范：XxxOptions
-- **本层是上行数据的注入方（harness#88）**：core 对 cli/gates/monitoring 零值导入，故 `check`/`report` 自己 `new ConstraintChecker(getTraceCollector())`（组合根接线 trace 记录器；用 `constraintChecker`/`getInstance()` 拿到的默认实例不写 trace），`sync-docs` 把 `COMMAND_DEFINITIONS` + `GATE_DEFINITIONS` 组装成 `CapabilityDefinitionSource` 注入 `capabilities-parser` 供能力清单计数
+- **本层是上行数据的注入方（harness#88）**：core 对 cli/gates/monitoring 零值导入，故 `check`/`report` 自己 `new ConstraintChecker(new TraceCollector({ projectPath }))`（组合根接线 trace 记录器，#139 起收集器锚根构造；用 `constraintChecker`/`getInstance()` 拿到的默认实例不写 trace），`sync-docs` 把 `COMMAND_DEFINITIONS` + `GATE_DEFINITIONS` 组装成 `CapabilityDefinitionSource` 注入 `capabilities-parser` 供能力清单计数
 - **数据已在手就不再构造带 IO 副作用的实例（ADR-0020）**：`status` 按 projectPath 直读出 traces 后，直调 `monitoring/trace-analyzer` 的模块级纯函数 `summarizeTraces()`/`detectTraceAnomalies()`，不再 `new TraceCollector({traceFile})` + `new TraceAnalyzer(c)`——collector 构造函数带 mkdir 副作用，而这条路径上它的读方法从未被调用，实例纯属构造仪式。机器可检：`__tests__/status-analysis-wiring.test.ts`（源形状闸：命令体不得出现 `new TraceCollector`/`new TraceAnalyzer`，也不 import `monitoring/traces`）
 - **projectPath 只在入口兜底一次，并传到每个 IO/执行点（harness#95）**：`-p/--project-path` 的 cwd 兜底唯一落点是命令模块入口（`const projectPath = options.projectPath || process.cwd()`）；往下每层只能收参数，**禁止再取一次 `process.cwd()`、也禁止用相对路径默认值**——两者都让 `-p` 半失效：执行/读写位置悄悄回到调用方 cwd，而 acceptance 的「无 tasks.yml 即跳过」本身就是 `passed:true`，于是失效表现为假绿。落地形状：执行/IO 根用**必传形参**表达（`PassesGate.runTests(workDir)`），门禁内的相对子路径锚到 projectPath：`ContractGate` 一直是 `path.join(context.projectPath, contractPath)`，`SpecAcceptanceGate` 的 tasksPath 随 #95 对齐成 `path.resolve(projectPath, 相对值)`（绝对值原样，缺省 `<projectPath>/tasks.yml`）
-  - 机器可检：`__tests__/project-path-convention.test.ts` 三道闸——CLI 层 cwd 必须是 `xxx || process.cwd()` 兜底形状、下游层（= src 减 cli）cwd 站点**逐行**冻结（#98，豁免文件内新增行/行变形同样失败）、相对路径默认值冻结（#98 收紧：`xxxPath: '相对值'` 对象字面量之外，参数默认值形/模板字面量/双引号形同罪，扫描域 = 整个下游层）；豁免逐条带理由，站点消失却不删条目同样失败
-  - 行为可检：`__tests__/project-path-anchoring.test.ts` 前提统一 **cwd ≠ projectPath**、不 mock 任何 IO，断言测试真在 B 执行、证据落 `B/.harness/evidence/`、acceptance 读 `B/tasks.yml`。「根已传入却又取 cwd」这类静态看不出的漂移由它守，冻结表守的是不再新增站点
+  - 机器可检：`__tests__/project-path-convention.test.ts` 四道闸——CLI 层 cwd 必须是 `xxx || process.cwd()` 兜底形状、下游层（= src 减 cli）cwd 站点**逐行**冻结（#98，豁免文件内新增行/行变形同样失败）、相对路径默认值冻结（#98 收紧：`xxxPath: '相对值'` 对象字面量之外，参数默认值形/模板字面量/双引号形同罪；#139 再扩两形：键名后缀 `Path` → `Path|File|Log`，加 `xxxFile: SOME_CONSTANT` 常量引用臂——traceFile 病灶正是「键名不带 Path + 值引用常量」两头都不认的形状。只扫使用点，常量定义本体是正本、不入闸）、组合根对 cwd 锚定的 `getTraceCollector()` 单例零消费（#139）；豁免逐条带理由，站点消失却不删条目同样失败
+  - 行为可检：`__tests__/project-path-anchoring.test.ts` 前提统一 **cwd ≠ projectPath**、不 mock 任何 IO，断言测试真在 B 执行、证据落 `B/.harness/evidence/`、acceptance 读 `B/tasks.yml`、`check --project-path` 的 trace 落 `B/.harness/logs/traces.log` 且 `status` 读得到它（站点 3，#139）。「根已传入却又取 cwd」这类静态看不出的漂移由它守，冻结表守的是不再新增站点
 - **读到部分结果必须告知（harness#100）**：命令面以 `skip` 策略读 JSONL（traces.log / failures.log）时，坏行计数要到用户可见输出，**不允许默默丢弃**。共同约束：无损坏零噪声（计数为 0 不出行）、不改任何既有计数口径（`status` 的 `记录数` 仍是原始非空行数，逐字节不变）、计数一律取自 `src/utils/jsonl` 读链返回的 `skippedLines`（经报告入口透传或在读点就地取用），**禁止**用「原始行数 − 统计条数」反推（窗过滤掉的合法行与坏行分不开）。三处落点各自对得上一行代码：
   - `status`：告知**走 stderr**（`logError(io, …)`），因为 stdout 是报告体、其字节已被 `记录数` 那一行定死，挤进去等于改输出
   - `constraints report`：提示属于**报告体内的降级位**，与既有的 `traceFileExists` 说明同在 stdout；结构化面另两份——`--json` 的 `skippedLines` 字段、`--export` markdown 的警示行（只报条数，不报路径与坏行内容）
   - `constraints retire`：两条路径都**走 stderr**——交互模式在候选列表前一行（沿用本函数既有的 console 例外，`console.error`），`--yes` 直达分支在落盘前 `logError(io, …)`（`retireConstraint` 本身按契约「纯执行无交互」不打印）
   - 原则正本与逐点去向见 `src/monitoring/CONTEXT.md`「约定」段；机器可检面是 `src/utils/__tests__/jsonl-skip-disposition.test.ts`（冻结全仓 skip 读点集合 + 要求每个读点记名声明 `计数去向：`）
+- **一次命令运行内，同一份数据至多取一次（harness#146，#140 A 票；与 ADR-0023 同族，但不扩 `RunEnv` 公共面）**：`spec-baseline-check` 的三条验证路径（文件存在性 / 依赖 / 代码模式）一律从命令级共享索引 `createBaselineIndex(projectPath)` 取数，不再各自裸调 `fs`——全仓 `.ts`/`.js` 内容扫描一遍建成 `路径 → 内容` 表、`package.json` 读解析一次（**读取失败态同样入库**，不逐条重试）、同一落点的存在性探测只 stat 一次；逐条前置与每个关键词只在索引上重放判定。索引**懒建**（没有前置需要某类数据时该类读取一次都不发生）、**运行结束即弃**（不跨命令复用：本命令是独立命令而非 `harness check` 的子步骤，「同一口径取一次」命令内自足即够，#140 triage 裁决 5）。改前代价 = 前置条件数 × 关键词数 × 源文件数，改后与条数无关，判定/证据文案/stdout/退出码逐字不变。**驻留上界（harness#162）**：索引容量有双上限 `SOURCE_INDEX_MAX_ENTRIES = 5000` / `SOURCE_INDEX_MAX_BYTES = 64MB`——超任一上限即放弃驻留、**回落逐文件流式读**（每个关键词重扫一遍，读完即弃），峰值内存由 O(全仓源码) 回到 O(单文件)，正常规模仓保留「一次遍历」收益；取数面相应由 `sourceContents(): Map` 改为 `countFilesContaining(keyword)`，容量策略全部收在索引内部。机器可检：`__tests__/spec-baseline-read-count.test.ts`（形状照 `check-read-count.test.ts`：`readFileSync`·只读 `openSync`·`existsSync`·`readdirSync` 记件 + 整张读取表与目录扫描表逐条冻结 + 「同一份数据的同一口径至多取一次」+ N×K 缩放不变式 + 懒建不扫 + 失败态入库）+ `__tests__/spec-baseline-index-cap.test.ts`（驻留上界闸：上限内每文件至多读一遍、超条目/字节上限回落流式且判定不变）
+- **先判定「本次要什么」再决定「读什么」，且清单顺序是对外面（harness#147，#140 B 票）**：`sync-docs/index.ts` 把 CAPABILITIES.md 的**格式判定放在源码扫描之前**——capability-listing 格式的判定面是计数、不做条目级比对，模块清单在本次运行里无人消费，于是整棵源码树**一份 `.ts` 内容都不读**（改造前是无条件全树逐文件 `await readFile`，只为首行注释）。要描述的分支（file-table）照旧取描述，但 `project-reader.ts` 分两步：先按目录遍历序定清单，再经 `extractFileDescriptions()` **并发**取数（上限固定 16，按票下裁决不做成配置面）并**按原索引回填**。清单顺序对外可见（`--check` 逐行比对生成的表格、人看 diff），票下裁决是「顺序逐字保持现状、不改字典序」，故「按并发完成顺序 append」属行为漂移而非优化。读盘次数之外一切不变：判定、漂移检测、写回内容逐字保持。机器可检：`__tests__/sync-docs-read-count.test.ts`（形状照 `check-read-count.test.ts`——listing 模式 `.ts` 内容读 = 0 + file-table 反证每份文件恰读一次 + 整张读取表冻结）、`sync-docs/__tests__/module-descriptions.test.ts`（替身把「起始序」与「完成序」刻意错开：串位或重排即红，另钉上限）、`__tests__/sync-docs-module-order.test.ts`（生成表格行序 = 目录遍历序、两次运行逐字复现）
 
 ## 注意事项
 - 新增命令需同步更新 CLAUDE.md / CAPABILITIES.md / src/CONTEXT.md
+- **scaffold 三态模型（harness#132 已落地）**：init/validate 的「目标在不在场→写或告知」判定（9 站点 = init 7 + validate 2，#132 收口时 8 处）收口为 scaffold 模块。术语：**managed file**（受管文件）= harness 模板拥有正本、用户可持有的落盘文件；三态 = `created`（不在场→落盘）/ `exists`（在场→告知跳过，**不细分内容是否等于模板**，内容比较是独立特性）/ `manual`（在场→打印片段请用户手工合并）。纪律：scaffold 不持有覆盖/跳过策略（`--no-git-hooks`/`--no-github-actions` 由命令层翻成 plan 列表，scaffold 只见 plan）；模板留代码内住 `scaffold-templates.ts`，不落 `templates/`（其无运行时消费者、integrity 清单不覆盖）；**打印给用户的片段必须是落盘正文的一部分**（GH Actions 站点冲突分支打印完整 workflow 全文而非 job 片段，#103 判据）；`--print-snippets` 的片段视图同判据且**由正本裁剪派生**（harness#153：`GITHUB_ACTIONS_SNIPPET` = `HARNESS_CHECK_WORKFLOW` 的 `jobs:` 段之后，形状与 GitLab 侧「打印的是落盘正文的尾巴」对仗。它曾是手抄的第二份文本，比落盘正本少 `validate` / `passes-gate` 两道门禁——照抄的用户拿到比同版本 `harness init` 弱一半的 CI；引导语随之改准为「以下正文取自 harness-check.yml 的 job 段」，`--print-snippets` 旗帜本身保留）；gitlab 形同判据由 harness#157 补齐——`printSnippets` 收 `governanceLevel`、打 `renderGitLabCiJobs(governanceLevel)`，与落盘 / 冲突分支同一个正本函数（此前打无 level 的 `GITLAB_CI_SNIPPET`，`-g` 档照抄的用户静默少拿治理与 docs 新鲜度两个任务）；CLAUDE.md/AGENTS.md 标记化幂等写（读-改-写形状）不纳入 scaffold；死选项 `-t/--type` 已随本票删除。GitLab CI 接线决议见下条；pre-push 站点已随 harness#144 落地，见「本地防线两道」条
+  - 9 站点的落点（#132 收口时 8 处，pre-push 是 harness#144 加的第 9 处）：`scaffold.ts` 存 9 个 `ManagedFile` 工厂（目标路径 + 三态文案 + 冲突片段），`init.ts` 只留「前置告知（无 .git / 目录不在场 / 已有 workflow 覆盖治理命令）+ runPlan」；原住 `validate.ts` 的 `createExampleCheckpoint`/`createExampleResolutions` 随工厂迁入 scaffold，`init.ts` 对 `validate` 的反向 import 因此消失，`validate.ts` 反向消费 `scaffold-templates` 的检查点文件路径约定。新增受管文件 = 一个工厂 + 一条 plan。**#132 口径外的第 9 处同形写手**（`sync-docs/context-syncer.ts:createContextMd` 自带一份 CONTEXT.md 正文、与正本已漂移）已于 harness#150 归位——现走 `contextDocFile` + `runPlan`，与 init 共用同一模板正本（`scaffold-templates.ts:renderContextDoc`）
+  - 可检面：`__tests__/scaffold.test.ts`（注入内存 fs 替身，零真实文件系统测全三态 + 9 站点文案逐字冻结 + 同源闸及其反证探针（两道 hook 各一条）+ 片段视图的「是正本裁出来的一段」包含闸）、`__tests__/init-ondisk.test.ts`（临时目录真跑 init：第一遍逐字节断言落盘内容并对齐改造前的整屏输出（#149 起这份整屏多出治理段 writer 的一行落盘提示——那行本就一直在真机上，只是此前 io 被丢、不进捕获面），第二遍断言 9 站点第三态与「打印即磁盘正文」；另有「`--print-snippets` 的 GitHub Actions 片段视图」两道闸——同源闸对 `harness-check.yml` 的字节级冻结基线、steps 集合闸按 YAML 解析枚举 job 的 `run:` 命令；harness#157 起「`--print-snippets` 的 GitLab CI 片段视图」四道闸——`-g standard` 同源闸（打印正文逐字等于 `GITLAB_GOVERNED` 基线的任务段 + 与真落盘 `.gitlab-ci.yml` 按 YAML 解析比对 harness-* 任务集合，正本删一个任务即红）、script 集合闸、不传 `-g` 单任务回归、`-g` 非法值 usage-error 零打印）
+  - 同族不同面：#150（已落地）是同一份 CONTEXT.md 模板被 `init` 与 `sync-docs` 两个命令各抄一份（`sync-docs/context-syncer.ts:createContextMd` 自带一份、与正本 `renderContextDoc` 已漂移），本条 #153 是同一命令的两个出口（打印 / 落盘）各抄一份——判据同一个（#103），落点不同，两票不并。#150 收口后 `createContextMd` 走 `contextDocFile` + `runPlan`（含 io / 注入 fs，正常只落 `created`），可检面 `__tests__/context-syncer.test.ts`（对撞闸：sync-docs 落点与 init 站点的骨架逐字相同；正本并入两行引导 + 注释形占位钉住；present→exists 不覆盖；#158 补骨架正文逐字冻结字面量——对撞闸只钉「两侧同源」，正本被改由冻结字面量撞红）与 `__tests__/init-ondisk.test.ts`（#158 起 `src/CONTEXT.md` 落盘从 `toContain` 升为 `CONTEXT_MD_BYTES` 字节级基线，同 `PRE_PUSH_HOOK_BYTES` 手法）
+- **CI 平台维度（harness#143 已落地）**：init 的服务端 CI 接线带平台维度。术语：**CI 平台（ci platform）** = 服务端门禁的接线目标（`github` / `gitlab` / `none`，`none` = 不接线，即旧 `--no-github-actions`），一次平台选择贯通三个面（harness-check 站点、治理 CI 面、`--print-snippets` 的 CI 片段）。决议 ①–⑥ 的落地形状：① 显式 `--ci <github|gitlab|none>`、缺省 `github`、**不做 remote URL 自动检测**（init 常跑在首次 push 前，检测错是静默写错文件）；② 最小参数化——CI 站点工厂 `harnessCheckCiFile(projectPath, platform, existingCiWorkflows, governanceLevel?)` 收平台参数，GitLab 正文住 `scaffold-templates.ts`（`GITLAB_CI_SNIPPET` / `renderGitLabCiJobs` / `renderGitLabCiFile`），`renderGovernanceWorkflow(level, platform)` 同步参数化，不建注册表抽象；③ 解析链 = flag > `.harness/config.yml` 的 `ci.platform` > `github`（读点 `readConfiguredCiPlatform`，缺失/脏值按未配置），**只有非默认平台才写 `ci.platform`**——github 不写键，而 init 每次都重写 config.yml，故「不写」即等于清除，旧配置零迁移、validate 不报错；④ `--no-github-actions` 保留为 `--ci none` 别名并打 deprecation 警告，与显式 `--ci <非 none>` 同时出现判 `usage-error` 且完全不落盘（不猜意图）；⑤ `.gitlab-ci.yml` 三态：不在场 → `created`、在场 → `manual`（打印 harness 任务正文，它是落盘全文的尾巴 → #103 判据成立），GH 侧冲突判定逐字不变；⑥ GitLab 模板与 GH 对仗（同三条命令 + `image: node:20` + `stage: test` + `rules:` 触发 MR 与 main/master push + 无缓存），治理档 `sync-docs --check` 的非阻断对应 `allow_failure: true`
+  - 平台维度带来的两处形状差（GH 侧行为逐字节不变）：**一个平台一份 CI 文件**——GitLab 没有「第二个 CI 文件位」，`-g` 档的治理任务并入同一份 `.gitlab-ci.yml` 正文，gitlab 形下 `governanceWorkflowFile` 无站点；**`none` = 不接线任何服务端 CI、不创建任何 CI 文件，治理 CI 面随之不建**（harness#156 裁决 F1，推翻 #143「`none` 只摘 harness-check 站点、`-g` 档照建 GH 治理 workflow」的有意保留——旧边界让 `config.yml` 写 `ci.platform: none` 而磁盘上躺着一份 GitHub Actions 文件，状态自相矛盾）；治理文档面（CHANGELOG、约束段、CONTEXT.md）由 `-g` 独立决定，`none` 下照常生成。`--print-snippets` 照出 GH 片段（非落盘面，#156 未动）。切回 `github` 时 init 不删既有的 `.gitlab-ci.yml`——scaffold 只有「落盘 / 告知」两种动作，删除不是它的能力
+  - `-g` 值域校验在命令入口（harness#156 裁决 F2，与 #152 脏输入 fail-loud 同判据）：合法值域 = `GOVERNANCE_PRESETS` 键集合（入口校验与装配共用同一份表），非法值判 `usage-error` 退 1、先于任何落盘，github / gitlab / none 三平台同判（旧行为：gitlab 侧非法值透传模板落三个任务、github 侧查表 miss 静默不建——同一输入两种后果）。隶属判定用 `Object.hasOwn` 而非 `in`（harness#164）：`in` 走原型链，`-g constructor`/`toString` 曾穿透校验、把 `Object` 构造函数写进 `configData` 并在 `yaml.dump` 抛 `YAMLException`
+  - 可检面：`__tests__/scaffold.test.ts`「CI 站点的平台维度」+ 同源闸两形覆盖、`__tests__/init-ondisk.test.ts`「init --ci 平台维度」（`.gitlab-ci.yml` 逐字节 / 第二趟 manual / 治理并入 / 持久化回读 / 别名与冲突与非法值）与「init --ci × -g 组合边界（harness#156）」（`--ci none -g standard` 落盘文件集合 + config.yml 两投影逐字冻结、`-g` 非法值三平台一致性钉、合法值回归）
+- **本地防线两道（harness#144 已落地）**：术语：**本地防线** = init 落的两个 Git hook 站点，分工是设计而非冗余——**pre-commit** 查暂存的（`check --staged` + plan 覆盖，增量、快反馈），**pre-push** 查整仓的（第 9 站点 `prePushHookFile` → `.git/hooks/pre-push`，`mode 0o755`，全量 `harness check` 不带 `--staged` + `harness validate`，任一失败 `exit 1` 挡住 push），兜的是 `git commit --no-verify` 绕出去的内容。三道决定按 #132 grilling 定论钉死：① **不做增量**——不解析 pre-push 从 stdin 收到的 `<local_ref> <local_oid> <remote_ref> <remote_oid>` 清单，无论推什么（含删远端分支这种 stdin 空清单的场景）整仓过一遍，钩子内子进程一律 `< /dev/null`、不让它吃掉 ref 清单；② **不内建逃生机制**——无环境变量开关、无超时、无「慢则降级」，唯一口子是 git 原生 `git push --no-verify`；③ **定位不变**——本地 hook = 自检与提醒，服务端 CI（见「CI 平台维度」条）才是门禁，pre-push 不替代它。`--no-git-hooks` 一并覆盖本站点（策略仍在命令层翻成 plan，scaffold 不持策略、不新增跳过旗帜）；`--print-snippets` 与冲突分支打印的片段 = 落盘正文去 shebang 头（#103 判据）；init 收尾提示与本站点引导语写明「查暂存的 / 查整仓的，重复是设计使然」。仓库自身的 `bin/install-precommit-hook.sh`（`npm run hooks:install`）仍是 pre-commit 单道，本票不动它
+- **knowledge view 收口模型（harness#133 已落地）**：knowledge 11 个子操作的「取数 + json 投影 + 人读排版 + 退出码」四件事拆开——命令模块只产 `{ data, human() }`（`data` 是 `--json` 正文的唯一正本，11 个 `knowledgeXxxView` 具名导出即投影本体），`knowledge-view.ts` 收口排版渲染、上色、label 映射、json/人读分派与退出码、路径解析与 store 构造。术语：**display model** = `human()` 返回的结构化人读视图 `{ sections: [{ title, rows: [{ cells }] }] }`，一格（cell）三选一：`label`（纯文案）/ `field`（点分路径声明它投影自 json 面哪个字段，数组下标与 `.length` 合法）/ `derived`（json 面没有的派生量，须在测试豁免表登记理由）。空行是显式的一行（`blankLine()`），不再靠 `\n` 前后缀藏排版。颜色只经 `DisplayTone` 角色查 `TONE_STYLES` 一张表，命令侧零 `chalk` 调用。可检面：`__tests__/knowledge-view.test.ts`（四道闸：源形状 / 11·11 json 字段清单冻结 / 两投影一致性 + 派生量双向对撞 / 满态与空态人读逐行冻结，基线取自改造前实现实测捕获）+ `__tests__/knowledge-tone-mapping.test.ts`（#151 加：tone 映射的纯函数级冻结，判据见下两条）。
+  - **冻结类测试的两条判据（#133 收尾须知自报第一条，#151 补完其推论）**：
+    - **fixture 走不到的分支须逐个建形，不共用一个空根**。闸 4b 的 `emptyRoot()` 是裸 `mkdtemp` 目录，天然没有 `.harness/knowledge-docs/`，于是 `syncRagRows` 的两个空态分支只有第一个（`!docsPresent`）进过基线，第二个（目录在场、无 `.md`）在测试里走不到——文案改字全绿。而 json 面两分支恒同形（`data = {directory, files}`），`--json` 断言钉不住人读第二行。落点：闸 4c 的平行表 `EXTRA_EMPTY_HUMAN_CASES`（每 case 自带 `makeRoot` + 人读逐行基线 + json 形状；不改 `EMPTY_HUMAN_BASELINE: Record<SubName, string[]>` 的形状，一个子命令只装一种形状的约束留在原表）。
+    - **渲染类映射（tone / label / 颜色）必须有纯函数级断言，identity-mock 的文本基线不算覆盖**。`knowledge-view.test.ts` 把 chalk mock 成 identity（其注释「人读断言看的是文本，不看 ANSI」即本条病灶的自供），于是 `TONE_STYLES` 与 `toneForMaturity`/`toneForSeverity`/`toneForScore` 全仓零命中，#133 有意偏离③（`stats` 的 `verified` 由黄变青）改回去不会有任何测试红。落点：`knowledge-tone-mapping.test.ts` 逐格冻两张表——「输入值 → tone」（6 个成熟度 / 7 个 severity / 分数边界各一格）与「tone → chalk 样式键」（7 个档位；chalk 替身按样式键给文本加标签，断言走 `renderDisplayModel` / `announce` 的真实渲染链而非只读表），另加「表键集合穷尽」双钉（编译期 `Record<DisplayTone, …>` 缺键即 tsc 红 + 运行期与源码 `DisplayTone` 联合、`TONE_STYLES` 字面量逐字对撞）。**生产侧零改动**：`TONE_STYLES` 仍不导出——本闸钉的是它的行为与声明形状，不是它的可访问性（导出会动 `knowledge-view.ts` 的公开面，ADR-0022 口径下得另走定级）。#158 补最后一跳：`knowledge-view.test.ts` 另有一条 display model 结构断言「stats 成熟度格必须携带 `tone` 且 = `toneForMaturity(maturity)`」——命令侧把 `tone:` 从格上摘掉（复审 M7）由它撞红，看结构不看 ANSI，不违 identity-mock 立场。
+  - **json 面现状冻结**：11 个顶层形状逐字不动（双仓核实 `knowledge --json` 零程序化消费者，studio 走 library 直调；统一包壳是纯 churn，删除 `--json` 死面按 ADR-0022 口径另票评估）。三处有意偏离，均不改字段集合：① `snapshot`/`index` 的 `--json` 由单行紧凑改为两空格缩进（分派单点化的直接结果，与其余 9 个子操作同形）；② `sync-rag` 的两个空态此前把人类文案直接打到 `--json` 的 stdout（吐出的不是 JSON），现由 display model 承担，json 面恒为 `{directory, files}`；③ `stats` 人读面 `verified` 成熟度的颜色随 `toneForMaturity` 单表变为青色（此前 list 青 / stats 黄两处手抄不一致，文字不变）。
+  - 与 #134（KnowledgeAudit 收 store）独立落地，唯一交点 `knowledgeAudit` 命令函数——#134 是后到方并已适配：`knowledgeAuditView` 经 `openKnowledgeStore` 取 store 作引擎第一形参、`shortContentThreshold` 作第二形参（构造期不再自建 store）。审计后重建索引「只在人读路径发生」是本票保留的既有策略（`--json` 不写盘），也是 `knowledge.ts` 内被逐行冻结的唯一 `options.json` 分支。
 - init 治理约束段写入落点（studio #302，ADR 2026-08-21 落点模型）：新仓 → AGENTS.md `PRESERVE:governance` 段（sync-docs 重新生成时保留）；旧模型仓（CLAUDE.md 已有 HARNESS_CONSTRAINTS 标记或 `## Governance Rules` 块）→ 续写 CLAUDE.md，幂等重跑不制造双份正本。治理段「在场守护」由 core 侧 governance_presence checker 承担（段缺失/为空时 check 报警）
 - PRESERVE:governance 段内写入纪律：机器管理的只有 HARNESS_CONSTRAINTS 标记区间——有标记只换标记区间，无标记（纯手写段）在段尾追加注入段；段内其余手写内容（治理契约引言/流程/纪律等）必须原样保留（曾整段替换清空手写内容的回归，init-injection.test 有防回归用例）
 - 注入段落点路由与 marker-range 替换收口在 `core/constraints/injection-writer`（ADR-0011）：读侧 `resolveInjectionTarget`（漂移检测/retire 同步共用「CLAUDE.md 有标记优先，否则 AGENTS.md」）+ 写侧 `resolveGovernanceLanding`（init 落点选择）；init 三个治理段 writer 与 retire 注入同步均为「渲染 body + 调 writer」，半标记（单边/乱序）一律拒写告警；未注入 = 两处均无完整标记段
 - knowledge 命令包含 11 个子操作（list/search/import/decay/stats/sync-rag/audit/snapshot/migrate/index/health）；upsert/sync-status 已迁至 studio CLI（harness#110，二者硬编码 localhost Studio 内部端点，不属 harness「通用框架、文件驱动」定位）
 - `stats` / `health` 的飞轮数字不在 CLI 内计算：分子口径唯一实现是 `knowledge/flywheel-metrics.ts`（`evaluateFlywheel`，ADR-0013），本层只做百分比取整/一位小数与字段名映射；`.consumption-stats.json` 的读取留在各命令（module 零 IO）
 - 特殊路由（选项条件、子命令兜底、裸跑语义）表达在定义表的 optionRoutes / subcommands / subcommandStrict / bareRunsAction 字段，bin 是纯通用引擎、不含单命令知识
+- **数值旗帜装配口径（harness#152）**：`<n>` / `<rate>` 这类数值旗帜经 commander 到命令侧**恒是字符串**（`defaultValue: '50'` 也是），所以入参声明必须跟着运行时形状走——装配点之前声明 `string`（或双形 `string | number`，如 `failure --limit`），数值只在装配点转一次。装配点有两处：**有 `mapActionArgs` 的命令在定义表装配**（`status --hours`、`constraints report` 三阈值、门禁 `--coverage-threshold`/`--bundle-threshold`/`--min-reviewers`），**knowledge 族是「纯投影条目」故编组归命令模块**（`knowledgeSearchCommand` 的 `--limit`、`knowledgeAudit` 的 `--threshold`）；两形都对，判据是「声明与运行时一致」，因此 `as any` 不该出现在这条链上（它替编译器记住了旗帜的实际形状，去掉 `parseInt` 就是往数值槽塞字符串）。**转不出来必须 fail-loud**（`logError` + `usage-error`，非零退出）：下游兜底写的多是 `?? 缺省值`，而 `??` 只兜 `null`/`undefined`、NaN 照单全收，于是一句 `len < NaN` 恒 false 就把一道质量判定静默关掉、退出码仍是 0（#152 病灶正本：`knowledge audit --threshold abc`）。上游按口径挡住的，引擎侧不再重复兜（库面向的守卫已落 harness#163：`KnowledgeAudit` 构造器对 `shortContentThreshold`/`staleDays`/`promotionBlockDays` 三槽的显式脏值（NaN/±Infinity/负数）构造期抛 `TypeError`，未传/显式 `undefined` 走缺省、显式 `0` 合法）。可检面：`__tests__/knowledge-audit-threshold.test.ts`（脏值 fail-loud / 缺省 '50' 与未传同果 / 显式 '0' 不被当未传 / `knowledge.ts` 零 `as any`）+ `__tests__/bin-exit-mapping.test.ts`（对外退出码 1 的端到端证据）；knowledge 的 `kind:` 逐行冻结豁免表在 `__tests__/knowledge-view.test.ts` 闸 1（#152 起两行、#154 起三行，理由随表注）。其余数值旗帜的脏输入后果（fail-closed 与静默按缺省两类）逐项判定见 #152 票面，#152 只收 `knowledge audit --threshold` 一处；**harness#154 已把口径推广到全部数值旗帜**（已推广清单如下），**唯一解析器 = `src/utils/numeric-flag.ts`**（本条目指名的正本：`parseNumericFlag` 判别 + `numericFlagMessage` 文案模板 + `requireNumericFlag` 抛出 + `NumericFlagError`；`parseInt`/`parseFloat` 的前缀截断 `'30abc'→30`、`'1e2'→1` 同属静默误读，禁回）。两消费形同一条判定规则：定义表 `mapActionArgs` 站点（`constraints report` 三阈值、`performance --coverage-threshold`/`--bundle-threshold`、`review --min-reviewers`）走 `requireNumericFlag` 抛出、bin 在 `runDefinition` 捕获映射 usage-error——定义表是纯数据模块返回不了 CommandResult，装配失败的通道只此一条，bin 不因此新增单命令知识；命令模块站点（`knowledge search --limit`、`failure list --limit`、`passes-gate --coverage-threshold` 的 `coverageCheck`）走 `parseNumericFlag` 就地 `logError` + `usage-error`，且都先于 store/recorder 构造与任何执行（脏值零落盘）。#152 的 `assembleShortContentThreshold` 改为委派 `parseNumericFlag`（函数面与 #152 报错文案保留、冻结测试钉死，未新建第二套解析器）。**#152 判为 fail-closed 的两处不保留、一并收敛 fail-loud**（#154 裁定）：`passes-gate --coverage-threshold` 的「覆盖率不足 (x% < NaN%)」自证异常文案与 `review --min-reviewers` 的恒不通过——脏输入属用法错误、自证异常的文案即缺陷；合法输入路径逐字不变，退出码面 review 1→1、passes-gate coverage 脏值 0→1 属缺陷修正（定级与 CHANGELOG 入账见该票）。边界不动：门禁/引擎构造器侧的 falsy/`??` 约定是库面向语义（显式 `0` 在 performance 门禁内仍 = 不检查该项），与 #163 同例不重复兜；`status --hours` 是死旗帜，另族另票。可检面新增：`src/utils/__tests__/numeric-flag.test.ts`（解析规则矩阵）+ `src/cli/commands/__tests__/numeric-flag-assembly.test.ts`（定义表逐旗帜装配 + 命令入口 + 端到端 spawn：脏输入 / 合法路径对拍 / 显式 `0`）
 - **命令 interface = `CommandResult` + 注入 io（架构评审候选7）**：命令实现一律声明 `Promise<CommandResult>`（判别联合 `ok|skip|fail|usage-error`，`fail`/`usage-error` 必附可定位的 `reason`，多闸门命令 reason 含 `gate <id>`），末位可选形参 `io: CommandIO = processIO`；类型与写入面在 `src/cli/command-contract.ts`
+  - **writer 层 `io` 必传，缺省只留在对外命令入口（harness#149）**：`= processIO` 的缺省是给 bin 不注入时的对外入口用的（每个命令模块一处，如 `init()`）。命令内部的落盘 writer 与它们的路由一律收**必传** `io`——缺省留在链路上时，调用点漏传不报错，只是静默把提示兜到真实 stdout：`captureIO()` 的测试面因此天然缺那批行，`⚠️ …标记残缺…请人工修复` 这类唯一提示写坏了没有测试会红。init 治理段的三个 writer（Output Style / AGENTS.md / CLAUDE.md，共 14 条 `log(io, …)`）与落点路由 `setupGovernanceConstraints` 已按此收口；机器可检：`__tests__/init-governance-io.test.ts`（源形状闸：`init.ts` 内该缺省只剩 `init()` 一处 + 四个 writer 签名必传 + `setupGovernance` 调用点逐个传 io）与行为面（临时目录真跑 init，断言这批提示落进注入面；#158 把 `⚠️ …标记残缺…请人工修复` 四处分支补齐——CLAUDE.md 的 Output Style 段 / AGENTS.md 的 PRESERVE 外层单边 / 段内 HARNESS_CONSTRAINTS 单边 / CLAUDE.md 的 HARNESS_CONSTRAINTS 单边各一条捕获面断言，fixture 各自单建）
 - **本目录零 `process.exit` / `process.exitCode`**：kind → 退出码的唯一映射在 `bin/harness.js`（`ok`/`skip` → 0，`fail`/`usage-error` → 1，未知 kind fail-closed）。历史上两处条件式（`command --level` 按严重级、门禁按 passed）已由命令侧译成 kind；`sync-docs --check` 的漂移改由实现返回 `fail`（定义表的 `afterRun` 逃生门随之废除）
 - **输出不得直接用 console**：流式打印走 `log(io, …)` / `logError(io, …)`（`util.format` + 换行，与 console 逐字节等价，见 `src/cli/__tests__/command-contract.test.ts`）；测试断言输出用 `captureIO()`，不再 `spyOn(process, 'exit')`；`--json` 输出断言用 `lastJsonOutput(io)`（JSON.parse 正本，harness#108）。例外：`constraints retire` 交互正文仍走 console（其 `RetireIO` 只注入 readline 流），退役结果打印已接注入流
-- **#95 同型扫荡结论**：两门禁站点已修（`passes-gate` 执行/证据落 projectPath、`acceptance` 去掉 `tasksPath: './tasks.yml'` 相对默认值）。逐点判定后的豁免三处，理由与站点原文一起冻结在 `__tests__/project-path-convention.test.ts` 的豁免表：`release` 的 `pkgPath`（定义表本无 `-p`，pkgPath 就是该命令唯一的根且已逐个传给每条 `run(cmd, pkgPath)`，不构成半失效；给发布流水线新增 `-p` 属新能力）、`constraints` 的 `join(process.cwd(), 'package.json')`（报的是 harness 自身包版本，主锚 `__dirname`，cwd 仅兜底）、`core/spec/validator.ts` 的 `schemaPath: './specs/schemas'`（**确是同型病灶**：`validateAll(projectPath)` 用 projectPath 找 spec 文件、却用 cwd 找 schema；但 `validateFile`/`loadSchema` 签名里没有根，补齐要穿透整个 spec 域，留待 spec 单票收口）
+- **#95 同型扫荡结论**：两门禁站点已修（`passes-gate` 执行/证据落 projectPath、`acceptance` 去掉 `tasksPath: './tasks.yml'` 相对默认值）。逐点判定后的豁免四处，理由与站点原文一起冻结在 `__tests__/project-path-convention.test.ts` 的豁免表：`release` 的 `pkgPath`（定义表本无 `-p`，pkgPath 就是该命令唯一的根且已逐个传给每条 `run(cmd, pkgPath)`，不构成半失效；给发布流水线新增 `-p` 属新能力）、`command` 的 `evaluate({ projectPath: process.cwd(), … })`（`CommandGate` 只做命令串正则判定、零文件读写，且该命令定义表里没有 `-p`，取 cwd 仅为满足 `GateContext` 形状，架构评审候选1）、`constraints` 的 `join(process.cwd(), 'package.json')`（报的是 harness 自身包版本，主锚 `__dirname`，cwd 仅兜底）、`core/spec/validator.ts` 的 `schemaPath: './specs/schemas'`（**确是同型病灶**：`validateAll(projectPath)` 用 projectPath 找 spec 文件、却用 cwd 找 schema；但 `validateFile`/`loadSchema` 签名里没有根，补齐要穿透整个 spec 域，留待 spec 单票收口）