@dommaker/harness 1.7.0 → 1.8.1

package/src/cli/commands/__tests__/pre-push-hook.test.ts

@@ -0,0 +1,181 @@
+/**
+ * pre-push 钩子的真 push 行为（harness#144）
+ *
+ * scaffold/init 测试能看到「落盘了什么字节」，看不到 git 到底怎么待见这份字节。
+ * 本文件不 mock 任何 IO、也不重写一份钩子正文：在临时 git 仓库里把 `init` 落盘的
+ * 那份正文（`renderPrePushHook()` 正本）连可执行位一起装上，接一个本地 bare 远端，
+ * 把 PATH 上的 `npx` 换成记账替身，真跑 `git push`。按票验收标准逐条钉住：
+ * 1. 整仓全量兜底生效：任一失败（check 或 validate）→ push 非零退出、远端收不到东西、
+ *    输出指明是哪一道挡的；
+ * 2. 两道门禁全过 → push 成功，且调用序列就是 check → validate；
+ * 3. 不内建逃生机制：唯一的口子是 git 原生 `--no-verify`，它一开钩子整个人不被调用；
+ * 4. 不做增量：stdin 里没有待推 ref 清单（删远端分支）时照样整仓过一遍。
+ */
+
+import { execFileSync, spawnSync, type SpawnSyncReturns } from 'child_process';
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { renderPrePushHook } from '../scaffold-templates';
+
+/** 替身 npx：把每次调用的参数记进日志，按环境变量决定各自退出码 */
+const STUB = `#!/bin/sh
+printf '%s\\n' "$*" >> "$HARNESS_NPX_LOG"
+case "$*" in
+  *validate*) exit \${HARNESS_VALIDATE_EXIT:-0} ;;
+  *) exit \${HARNESS_CHECK_EXIT:-0} ;;
+esac
+`;
+
+/** 两道门禁各自的退出码（缺省 0 = 通过） */
+interface Knobs {
+  check?: number;
+  validate?: number;
+}
+
+interface Fixture {
+  /** 工作仓库（钩子装在它的 .git/hooks/pre-push） */
+  repo: string;
+  branch: string;
+  /** 真跑 git push（argv 数组，不经 shell） */
+  push: (knobs: Knobs, ...args: string[]) => SpawnSyncReturns<string>;
+  /** 替身 npx 被调用的参数清单 = 钩子里 harness 命令的真实调用序列 */
+  calls: () => string[];
+  resetCalls: () => void;
+  remoteHeads: () => string[];
+}
+
+function git(dir: string, ...args: string[]): void {
+  execFileSync('git', args, { cwd: dir, stdio: 'pipe' });
+}
+
+function fixture(): Fixture {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'harness-prepush-'));
+  const repo = path.join(root, 'work');
+  const remote = path.join(root, 'remote.git');
+  const stubDir = path.join(root, 'stub');
+  const log = path.join(root, 'npx.log');
+
+  fs.mkdirSync(stubDir, { recursive: true });
+  const stub = path.join(stubDir, 'npx');
+  fs.writeFileSync(stub, STUB, 'utf-8');
+  fs.chmodSync(stub, 0o755);
+
+  fs.mkdirSync(repo, { recursive: true });
+  git(repo, 'init', '-q');
+  git(repo, 'config', 'user.email', 'fixture@example.com');
+  git(repo, 'config', 'user.name', 'Fixture');
+  // 仓库级钉死钩子目录：全局 core.hooksPath 会把测试变成「测别人家的钩子」
+  git(repo, 'config', 'core.hooksPath', path.join(repo, '.git', 'hooks'));
+  fs.writeFileSync(path.join(repo, 'README.md'), '# fixture\n');
+  git(repo, 'add', '.');
+  git(repo, 'commit', '-q', '-m', 'baseline');
+
+  // 装上 init 会落的那份正文（正本，不手抄），连可执行位一起（mode 与站点同值 0o755）
+  const hook = path.join(repo, '.git', 'hooks', 'pre-push');
+  fs.writeFileSync(hook, renderPrePushHook(), 'utf-8');
+  fs.chmodSync(hook, 0o755);
+
+  git(repo, 'init', '-q', '--bare', remote);
+  git(repo, 'remote', 'add', 'origin', remote);
+  const branch = execFileSync('git', ['rev-parse', '--abbrev-ref', 'HEAD'], {
+    cwd: repo,
+    encoding: 'utf-8',
+  }).trim();
+
+  return {
+    repo,
+    branch,
+    push: (knobs, ...args) =>
+      spawnSync('git', ['push', ...args], {
+        cwd: repo,
+        encoding: 'utf-8',
+        env: {
+          ...process.env,
+          PATH: `${stubDir}:${process.env.PATH}`,
+          HARNESS_NPX_LOG: log,
+          HARNESS_CHECK_EXIT: String(knobs.check ?? 0),
+          HARNESS_VALIDATE_EXIT: String(knobs.validate ?? 0),
+        },
+      }),
+    calls: () =>
+      fs.existsSync(log)
+        ? fs
+            .readFileSync(log, 'utf-8')
+            .split('\n')
+            .map(line => line.trim())
+            .filter(Boolean)
+        : [],
+    resetCalls: () => {
+      try {
+        fs.unlinkSync(log);
+      } catch {
+        // 首趟就没跑过钩子，无日志可清
+      }
+    },
+    remoteHeads: () =>
+      execFileSync('git', ['ls-remote', '--heads', remote], { encoding: 'utf-8' })
+        .split('\n')
+        .map(line => line.trim())
+        .filter(Boolean),
+  };
+}
+
+const output = (r: SpawnSyncReturns<string>): string => `${r.stdout}${r.stderr}`;
+
+describe('pre-push 钩子真挡得住 push（harness#144）', () => {
+  it('两道门禁全过 → push 成功，钩子里 check 与 validate 各跑一次（check 不带 --staged）', () => {
+    const f = fixture();
+
+    const r = f.push({}, 'origin', 'HEAD');
+
+    expect(r.status).toBe(0);
+    expect(f.remoteHeads()).toHaveLength(1);
+    expect(f.calls()).toEqual(['@dommaker/harness check', '@dommaker/harness validate']);
+  });
+
+  it('check 失败 → push 被挡、退出非零、输出指明是铁律检查、远端一格未收', () => {
+    const f = fixture();
+
+    const r = f.push({ check: 1 }, 'origin', 'HEAD');
+
+    expect(r.status).not.toBe(0);
+    expect(output(r)).toContain('🔍 Running harness pre-push checks (whole repo)...');
+    expect(output(r)).toContain('❌ Iron law check failed');
+    expect(f.calls()).toEqual(['@dommaker/harness check']);
+    expect(f.remoteHeads()).toEqual([]);
+  });
+
+  it('validate 失败同样挡住 push（不是只看 check），输出指明是哪一道', () => {
+    const f = fixture();
+
+    const r = f.push({ check: 0, validate: 1 }, 'origin', 'HEAD');
+
+    expect(r.status).not.toBe(0);
+    expect(output(r)).toContain('❌ Validate failed');
+    expect(f.calls()).toEqual(['@dommaker/harness check', '@dommaker/harness validate']);
+    expect(f.remoteHeads()).toEqual([]);
+  });
+
+  it('唯一逃生口是 git 原生 --no-verify：失败门禁下 push 照过，钩子整个人没被调用', () => {
+    const f = fixture();
+
+    const r = f.push({ check: 1 }, '--no-verify', 'origin', 'HEAD');
+
+    expect(r.status).toBe(0);
+    expect(f.remoteHeads()).toHaveLength(1);
+    expect(f.calls()).toEqual([]);
+  });
+
+  it('不做增量：删远端分支时 stdin 里没有待推 ref 清单，仍整仓跑一遍 check', () => {
+    const f = fixture();
+    expect(f.push({}, 'origin', 'HEAD').status).toBe(0);
+    f.resetCalls();
+
+    const r = f.push({ check: 1 }, '--delete', 'origin', f.branch);
+
+    expect(r.status).not.toBe(0);
+    expect(f.calls()).toEqual(['@dommaker/harness check']);
+    expect(f.remoteHeads()).toHaveLength(1);
+  });
+});

package/src/cli/commands/__tests__/project-path-anchoring.test.ts

@@ -1,22 +1,30 @@
 /**
  * -p/--project-path 锚定回归（harness#95）
  *
- * 两条门禁命令都接受 -p，但真正执行/IO 的一侧过去取 process.cwd()：不 cd 到目标工程调用，
+ * 各站点的命令都接受 -p，但真正执行/IO 的一侧过去取 process.cwd()：不 cd 到目标工程调用，
  * 就会拿 A 工程的命令、在 B 目录跑、把证据写进 B；acceptance 的「无 tasks.yml 即跳过」
  * 本身是 passed:true，于是 -p 失效直接表现为假绿。
  *
  * 既有单测全部 mock fs/exec + 假 projectPath，恰好抹平两种取径的差异。本文件不 mock 任何 IO，
  * 前提统一为 **cwd ≠ projectPath**（cwd = A，-p = B），断言读写位置落在 B。
  * 站点 2 从两面各断言一次：CLI 命令面（`acceptance -p`）与门禁实例面（默认构造 = 注册表单例形状）。
+ *
+ * 站点 3（harness#139）是 trace 落点：`check --project-path B` 的约束评估真跑了 B，
+ * 但 trace 写进了 A——写侧不锚，按 projectPath 直读的读侧（`status`）就读不到刚写的记录，
+ * 即 #95 点名的假绿族。故本站点从写、读两面各断言一次。
  */
 
 import * as fs from 'fs';
 import * as path from 'path';
+import { execFileSync } from 'child_process';
 import { createProjectFixture } from '../../../test-setup/project-fixture';
 import { SpecAcceptanceGate } from '../../../gates/acceptance';
+import { DEFAULT_TRACE_FILE } from '../../../types/trace';
 import { captureIO } from '../../command-contract';
 import { runPassesGate } from '../passes-gate';
 import { acceptance } from '../acceptance';
+import { check } from '../check';
+import { status } from '../status';
 
 /** 在自身 cwd 落标记文件：哪一侧被真正调用，标记就出现在哪一侧的目录里 */
 function markScript(marker: string): string {
@@ -92,7 +100,7 @@ describe('-p 锚定：执行与 IO 必须落在 projectPath（cwd ≠ projectPat
   });
 
   describe('acceptance（站点 2：tasks.yml 解析）', () => {
-    it('默认构造的门禁实例（registry / getEffectiveGates 形状）→ 读 B/tasks.yml，不读 cwd 的', async () => {
+    it('默认构造的门禁实例（注册表单例形状）→ 读 B/tasks.yml，不读 cwd 的', async () => {
       const cwdSide = createProjectFixture({
         name: 'acccfg-cwd-side',
         files: { 'tasks.yml': tasksYml(true) },
@@ -154,4 +162,89 @@ describe('-p 锚定：执行与 IO 必须落在 projectPath（cwd ≠ projectPat
       });
     });
   });
+
+  describe('check / status（站点 3：trace 落点与读-写闭环）', () => {
+    /** 在 fixture 里跑 git（argv 数组，不经 shell） */
+    function git(dir: string, ...args: string[]): void {
+      execFileSync('git', args, { cwd: dir, stdio: 'pipe' });
+    }
+
+    /** check 能真跑完的项目：已提交基线 + staged 改动 + 一条 pass trace（验证证据） */
+    function checkProject(name: string): string {
+      const dir = createProjectFixture({
+        name,
+        files: { 'README.md': '# fixture\n', 'src/existing.ts': 'export const a = 1;\n' },
+        traces: [{ constraintId: 'fixture', result: 'pass' }],
+      });
+      git(dir, 'init', '-q');
+      git(dir, 'config', 'user.email', 'fixture@example.com');
+      git(dir, 'config', 'user.name', 'Fixture');
+      git(dir, 'add', '.');
+      git(dir, 'commit', '-q', '-m', 'baseline');
+      fs.writeFileSync(path.join(dir, 'src/existing.ts'), 'export const a = 2;\n', 'utf-8');
+      git(dir, 'add', '--', 'src/existing.ts');
+      return dir;
+    }
+
+    /** trace 正本的行（按生产落点 DEFAULT_TRACE_FILE 解析，不另立路径口径） */
+    function traceLinesOf(projectRoot: string): string[] {
+      return fs
+        .readFileSync(path.join(projectRoot, DEFAULT_TRACE_FILE), 'utf-8')
+        .split('\n')
+        .filter(Boolean);
+    }
+
+    it('--project-path B → trace 落 B/.harness/logs/traces.log，A 侧不长出文件', async () => {
+      const cwdSide = createProjectFixture({ name: 'traceanchor-cwd' });
+      const projectSide = checkProject('traceanchor-project');
+      process.chdir(cwdSide);
+      const seeded = traceLinesOf(projectSide).length;
+
+      const result = await check(
+        { staged: true, projectPath: projectSide, trigger: 'code_implementation' },
+        captureIO()
+      );
+      expect(result).toEqual({ kind: 'ok' });
+
+      const written = traceLinesOf(projectSide)
+        .slice(seeded)
+        .map(l => JSON.parse(l) as { constraintId: string; projectPath?: string });
+      expect(written.map(t => t.constraintId)).toEqual(
+        expect.arrayContaining(['incremental_progress', 'no_implementation_without_requirement'])
+      );
+      expect(written.every(t => t.projectPath === projectSide)).toBe(true);
+      // 病灶：修复前这一支落在调用方 cwd（A），B 侧 mtime 不动
+      expect(fs.existsSync(path.join(cwdSide, DEFAULT_TRACE_FILE))).toBe(false);
+    });
+
+    it('读-写闭环：status --project-path B 读得到上一步 check 刚写的 trace', async () => {
+      const cwdSide = createProjectFixture({ name: 'traceanchor-rw-cwd' });
+      const projectSide = checkProject('traceanchor-rw-project');
+      process.chdir(cwdSide);
+
+      await check(
+        { staged: true, projectPath: projectSide, trigger: 'code_implementation' },
+        captureIO()
+      );
+
+      const io = captureIO();
+      expect(await status({ projectPath: projectSide }, io)).toEqual({ kind: 'ok' });
+      // 记录数取自 B 的正本行数：写侧漏到 A 就必然对不上（假绿），读到 A 也读不到 check 的落点
+      expect(io.outText()).toContain(`记录数: ${traceLinesOf(projectSide).length} 条`);
+      expect(io.outText()).toContain('no_implementation_without_requirement');
+    });
+
+    it('不带 --project-path 的项目内使用：落点仍是当下 cwd（存量使用者无感）', async () => {
+      const projectSide = checkProject('traceanchor-nop');
+      process.chdir(projectSide);
+      const seeded = traceLinesOf(projectSide).length;
+
+      const result = await check(
+        { staged: true, trigger: 'code_implementation' },
+        captureIO()
+      );
+      expect(result).toEqual({ kind: 'ok' });
+      expect(traceLinesOf(projectSide).length).toBeGreaterThan(seeded);
+    });
+  });
 });

package/src/cli/commands/__tests__/project-path-convention.test.ts

@@ -5,19 +5,23 @@
  * 兜底，之后必须传到每个 IO/执行点**——下游禁止再取一次 cwd，也禁止用相对路径默认值
  * （两者都会让 `-p` 半失效：读写/执行位置悄悄回到调用方的 cwd）。
  *
- * 本文件是这条约定的机器可检面，三道闸：
+ * 本文件是这条约定的机器可检面，四道闸：
  * 1. CLI 入口层：cwd 只能以 `xxx || process.cwd()` 的兜底形状出现，例外逐个点名并记理由
  * 2. 下游层（= src 减 cli，含 core / gates / context / monitoring / hooks 等）：cwd 站点**逐行**冻结
  *    （harness#98，不再只冻文件键集——豁免文件内新增站点/行变形同样失败），
  *    要么把根传下去，要么在此记下豁免理由
  * 3. 相对路径默认值同理冻结（harness#98 收紧：对象字面量 `xxxPath: '相对'` 之外，
- *    参数默认值形 `xxxPath = '相对'`（含类型标注）与模板字面量同罪；扫描域 = 整个下游层）
+ *    参数默认值形 `xxxPath = '相对'`（含类型标注）与模板字面量同罪；harness#139 再扩两形：
+ *    键名后缀 `Path` → `Path|File|Log`，以及引用常量的 `xxxFile: SOME_CONST` 臂；扫描域 = 整个下游层）
+ * 4. 组合根自己锚根构造，不再消费 cwd 锚定的全局单例（harness#139：src/cli、src/hooks 生产代码
+ *    对 `getTraceCollector()` 零消费——单例是留给跨仓消费者的兼容面，不是本仓的取用口）
  *
  * 冻结集合还要求**每条豁免仍然成立**（站点消失却不删条目 → 同样失败），豁免不会烂成化石。
  * 「根参数已传入却又取 cwd」这类静态看不出的漂移，由 project-path-anchoring.test.ts 的真实 IO 行为用例守。
  */
 
 import * as fs from 'fs';
+import * as os from 'os';
 import * as path from 'path';
 
 const SRC_ROOT = path.join(__dirname, '..', '..', '..', '..', 'src');
@@ -59,6 +63,15 @@ function cwdSites(files: string[]): Map<string, string[]> {
   return sites;
 }
 
+/** 闸 3 的取站点本体（反证用例与冻结表用例共用同一判据） */
+function relativePathDefaultSites(files: string[]): Set<string> {
+  const hits = new Set<string>();
+  for (const file of files) {
+    if (codeLines(file).some(line => RELATIVE_PATH_DEFAULT.test(line))) hits.add(repoPath(file));
+  }
+  return hits;
+}
+
 // ========================================
 // 闸 1：CLI 入口层的非兜底形状 cwd
 // ========================================
@@ -68,6 +81,14 @@ const ENTRY_FALLBACK_SHAPE = /\|\|\s*process\.cwd\(\)/;
 
 /** 兜底形状之外的 CLI cwd 站点：逐个裁决过，理由与站点原文一起冻结 */
 const CLI_CWD_EXEMPTIONS: Record<string, { lines: string[]; reason: string }> = {
+  'src/cli/commands/command.ts': {
+    lines: ['const decision = await gate.evaluate({ projectPath: process.cwd(), command: cmd });'],
+    reason:
+      '统一门禁接口的 GateContext 要求项目根，而 CommandGate 只做命令串的正则判定、零文件读写；' +
+      '本命令定义表里没有 -p/--project-path（只有 --level/--list/--json），' +
+      '取真实 cwd 仅为满足上下文形状，不存在「给了 -p 却被 IO 绕回 cwd」的半失效路径。' +
+      '架构评审候选1 步骤 2：六个门禁的判定统一穿过 evaluate()。',
+  },
   'src/cli/commands/release.ts': {
     lines: ['const pkgPath = process.cwd();'],
     reason:
@@ -97,10 +118,12 @@ const DOWNSTREAM_CWD_EXEMPTIONS: Record<string, { lines: string[]; reason: strin
   'src/core/constraints/checker.ts': {
     lines: [
       'const projectPath = context.projectPath || process.cwd();',
-      'const run = evidence ?? createGitEvidence(context.projectPath || process.cwd());',
-      'const run = evidence ?? createGitEvidence(context.projectPath || process.cwd());',
+      'const projectPath = context.projectPath || process.cwd();',
+      'const projectPath = context.projectPath || process.cwd();',
     ],
-    reason: 'check 上下文缺 projectPath 时的根兜底（3 处同一形状）',
+    reason:
+      'check 三个 run 入口（checkPrecondition / runAllConstraints / beforeExecution）各取一次根兜底，' +
+      'git 证据与运行级观察面都从该变量派生、不再内联取 cwd（ADR-0023 步骤 3）',
   },
   'src/core/constraints/checkers/types.ts': {
     lines: ['const projectPath = context.projectPath || process.cwd();'],
@@ -113,21 +136,23 @@ const DOWNSTREAM_CWD_EXEMPTIONS: Record<string, { lines: string[]; reason: strin
     ],
     reason: 'buildCheckEnv 的 options.projectPath 缺省兜底（2 处）',
   },
+  'src/core/constraints/run-env.ts': {
+    lines: ['return createRunEnv(target || process.cwd());'],
+    reason:
+      'resolveRunEnv 的根兜底：RunTarget 只给了路径或什么也没给时自造一枚一次性观察面' +
+      '（配置访问器族与 ProjectConfigLoader 的入参归一点，ADR-0023 决策 2）',
+  },
   'src/core/constraints/usage-report.ts': {
     lines: ['projectRoot: string = process.cwd(),'],
     reason: 'projectRoot 形参默认值（库层可选根）',
   },
   'src/core/effective-constraints.ts': {
     lines: [
-      'projectRoot: string = process.cwd(),',
-      'projectRoot: string = process.cwd(),',
+      'target: RunTarget = process.cwd(),',
+      'target: RunTarget = process.cwd(),',
       'export function lintEffectiveConfig(projectRoot: string = process.cwd()): EffectiveConfigLint {',
     ],
-    reason: '生效集三函数 projectRoot 形参默认值（库层可选根，JSDoc 已声明）',
-  },
-  'src/core/project-config-loader.ts': {
-    lines: ['this.projectPath = projectPath || process.cwd();'],
-    reason: 'config 加载器 projectPath 构造参数缺省兜底',
+    reason: '生效集三函数根形参默认值（库层可选根，JSDoc 已声明；前两者入参含 RunEnv，ADR-0023）',
   },
   'src/core/spec/validator.ts': {
     lines: ['const cwd = projectPath || process.cwd();'],
@@ -137,10 +162,6 @@ const DOWNSTREAM_CWD_EXEMPTIONS: Record<string, { lines: string[]; reason: strin
     lines: ['const projectPath = ctx.projectPath || process.cwd();'],
     reason: 'GateContext.projectPath 缺省兜底（门禁适配器的根入口）',
   },
-  'src/gates/effective-gates.ts': {
-    lines: ['export function getEffectiveGates(projectRoot: string = process.cwd()): Gate[] {'],
-    reason: 'projectRoot 形参默认值（库层可选根）',
-  },
   'src/hooks/bootstrap.ts': {
     lines: [
       'const resolvedPath = projectPath || process.cwd();',
@@ -159,18 +180,38 @@ const DOWNSTREAM_CWD_EXEMPTIONS: Record<string, { lines: string[]; reason: strin
 // ========================================
 
 /**
- * key 必须 camelCase 以 Path 结尾，值为相对字面量——这类默认值按 cwd 解析，即 #95 的病根形状。
+ * 键名必须是 camelCase 且以 Path/File/Log 结尾，值为相对字面量或引用常量——这类默认值按 cwd 解析，
+ * 即 #95 的病根形状。
+ *
  * harness#98 收紧匹配形状（原为只认对象字面量 `xxxPath: '相对'`）：
  * 参数默认值形 `xxxPath = '相对'`、带类型标注的 `xxxPath: string = '相对'`、模板字面量、
  * 双引号形同罪（仓内 lint 不强制引号风格，三种引号都得认）。
+ *
+ * harness#139 再扩两形（traceFile 病灶的形状是「键名不带 Path + 值引用常量」，原闸两头都不认）：
+ * - 臂 1 的键名后缀 `Path` → `Path|File|Log`（落点类键名的全集，Log 覆盖 `xxxLog` 一族）
+ * - 臂 2 新增常量引用形 `xxxFile: SOME_CONSTANT`（值不在本行，是相对片段正本的另一半）
+ *
+ * 只扫**使用点**，不冻结常量定义本体（`export const DEFAULT_TRACE_FILE = '.harness/…'` 是正本，
+ * 锚定责任在消费点）。扩形后下游层新增命中恰好 2 处（本票病灶 traces.ts + trace-analyzer.ts 的
+ * summaryFile），连同既有的 validator 豁免共 3 条，零假阳性——见下方豁免表。
  */
-const RELATIVE_PATH_DEFAULT = /\b\w+Path\s*(?::\s*[^=,)]+?)?[:=]\s*['"`](?!\/)/;
+const RELATIVE_PATH_DEFAULT =
+  /\b\w+(?:Path|File|Log)\s*(?::\s*[^=,)]+?)?[:=]\s*['"`](?!\/)|\b\w+(?:Path|File|Log)\s*[:=]\s*[A-Z][A-Z0-9_]+\b/;
 
 const RELATIVE_PATH_DEFAULT_EXEMPTIONS: Record<string, string> = {
   'src/core/spec/validator.ts':
     'schemaPath: "./specs/schemas" 确实按 cwd 解析（同型病灶）。不随 #95 修：validateFile()/loadSchema() ' +
     '签名里没有根，补齐要把根穿透整个 spec 域（属 spec 重构，非本票两门禁）。CLI 侧 `spec -s` 已 ' +
     'path.resolve(projectPath, schema)，给了 -s 时口径正确。留待 spec 域单票收口。',
+  'src/monitoring/traces.ts':
+    'DEFAULT_CONFIG.traceFile 引用的是**项目相对片段**正本（#139 明确其语义），锚定在构造函数里做：' +
+    '给了 projectPath → path.resolve(projectPath, traceFile)，没给 → 保持 cwd 解析（跨仓消费者的兼容面）。' +
+    '本行是「相对片段」的声明处，不是「按 cwd 打开」的执行处；锚定行为由 monitoring/__tests__/' +
+    'trace-file-anchoring.test.ts 与 cli/commands/__tests__/project-path-anchoring.test.ts 站点 3 钉。',
+  'src/monitoring/trace-analyzer.ts':
+    'summaryFile: ".harness/logs/traces-summary.json" 同型病灶（#139 实测的第二处命中）。不在本票修：' +
+    'harness 侧无生产写点（`status` 自 ADR-0020 起直调纯函数，不构造 analyzer），修它等于给无人消费的面' +
+    '新增根参数。与 trace 的 failure/summary 三件套同型病灶一并由 studio 侧迁移票带走（#139 Out of scope）。',
 };
 
 describe('projectPath 传递约定（harness#95）', () => {
@@ -211,13 +252,10 @@ describe('projectPath 传递约定（harness#95）', () => {
   });
 
   describe('闸 3：相对路径默认值不再按 cwd 解析', () => {
-    it('下游层（= src 减 cli）的相对字面量路径默认值 = 冻结豁免表', () => {
-      const hits = new Set<string>();
-      for (const file of downstreamFiles) {
-        if (codeLines(file).some(line => RELATIVE_PATH_DEFAULT.test(line))) hits.add(repoPath(file));
-      }
-
-      expect([...hits].sort()).toEqual(Object.keys(RELATIVE_PATH_DEFAULT_EXEMPTIONS).sort());
+    it('下游层（= src 减 cli）的相对字面量/常量引用路径默认值 = 冻结豁免表', () => {
+      expect([...relativePathDefaultSites(downstreamFiles)].sort()).toEqual(
+        Object.keys(RELATIVE_PATH_DEFAULT_EXEMPTIONS).sort()
+      );
     });
 
     it('acceptance 的 tasks.yml 默认不再有相对路径常量（站点 2 的收口形状）', () => {
@@ -227,5 +265,45 @@ describe('projectPath 传递约定（harness#95）', () => {
       expect(body).not.toMatch(/tasksPath\s*:\s*'/);
       expect(body).toMatch(/path\.resolve\(\s*context\.projectPath\s*,\s*[^)]*'tasks\.yml'/);
     });
+
+    it('反证（#139）：未锚的 xxxFile 相对默认值顶闸，锚定与绝对形状不误报', () => {
+      const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'gate3probe-'));
+      const write = (name: string, body: string): string => {
+        const file = path.join(dir, name);
+        fs.writeFileSync(file, body, 'utf-8');
+        return file;
+      };
+
+      // 臂 2（常量引用）与臂 1（File/Log 后缀的相对字面量）各自要真打得中，冻结表才不是空转
+      expect([
+        write('unanchored-const.ts', 'export const cfg = { traceFile: DEFAULT_TRACE_FILE };\n'),
+        write('unanchored-literal.ts', "export const cfg = { errorLog: 'logs/error.log' };\n"),
+        write('unanchored-param.ts', "function f({ summaryPath = './x/y.json' }: { summaryPath?: string }) {}\n"),
+      ].map(f => relativePathDefaultSites([f]).size)).toEqual([1, 1, 1]);
+
+      // 锚定动作、绝对值、值非大写常量、键名不在后缀集内 → 都不算站点
+      expect([
+        write('anchored.ts', 'export const cfg = { traceFile: path.resolve(projectPath, DEFAULT_TRACE_FILE) };\n'),
+        write('absolute.ts', "export const cfg = { traceFile: '/abs/traces.log' };\n"),
+        write('lowercase-value.ts', 'export const cfg = { traceFile: resolvedFile };\n'),
+        write('other-suffix.ts', 'export const cfg = { maxFileSize: 10 * 1024 * 1024 };\n'),
+      ].map(f => relativePathDefaultSites([f]).size)).toEqual([0, 0, 0, 0]);
+    });
+  });
+
+  describe('闸 4：组合根锚根构造，不消费 cwd 锚定的单例（harness#139）', () => {
+    it('src/cli 与 src/hooks 的生产代码对 getTraceCollector() 零消费', () => {
+      const offenders: string[] = [];
+      for (const dir of ['cli', 'hooks']) {
+        for (const file of listTsFiles(path.join(SRC_ROOT, dir))) {
+          const lines = codeLines(file).filter(line => /getTraceCollector\s*\(/.test(line));
+          if (lines.length > 0) offenders.push(`${repoPath(file)}: ${lines.join(' | ')}`);
+        }
+      }
+
+      // 单例保留是给跨仓消费者的兼容面（#139 裁决：公共面不摘除）；本仓四个组合根各自
+      // new TraceCollector({ projectPath })，取用口一旦复活，-p 就又半失效一次
+      expect(offenders).toEqual([]);
+    });
   });
 });

package/src/cli/commands/__tests__/registry.test.ts

@@ -274,6 +274,8 @@ smoke('bin/harness.js 端到端（dist 存在时）', () => {
     expect(r.status).toBe(0);
     expect(JSON.parse(r.stdout)).toHaveProperty('total');
     expect(r.implModules).toEqual([
+      // #133 起 knowledge 的投影面随命令模块一并懒加载（探针按字典序列出加载项）
+      expect.stringContaining('/dist/cli/commands/knowledge-view.js'),
       expect.stringContaining('/dist/cli/commands/knowledge.js'),
     ]);
   });

package/src/cli/commands/__tests__/report.test.ts

@@ -4,6 +4,10 @@
 
 import { report } from '../report';
 import { captureIO, type CapturingIO } from '../../command-contract';
+import { DEFAULT_TRACE_FILE } from '../../../types/trace';
+import * as nodeFs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
 import * as fs from 'fs/promises';
 
 // Mock fs/promises
@@ -52,9 +56,27 @@ describe('report command', () => {
       expect(io.outText()).toContain('报告已保存');
     });
 
+    // 自定义 projectPath 用例的临时目录：afterEach 兜底清理，用例失败也不留垃圾
+    let projectPath: string;
+    afterEach(() => {
+      if (projectPath) {
+        nodeFs.rmSync(projectPath, { recursive: true, force: true });
+        projectPath = '';
+      }
+    });
+
     it('应该使用自定义项目路径', async () => {
-      await report({ format: 'json', projectPath: '/custom/path' }, io);
+      // 原断言传的是假绝对路径 '/custom/path'：#139 之前 report 不在该路径落任何文件，假路径无感；
+      // #139 之后 TraceCollector 按 projectPath 锚根创建 trace 目录，这条路径变成真实写请求——
+      // 以 root 身份跑恰好 mkdir 成功（并在文件系统根下留下目录），非 root 的 CI runner 直接 EACCES。
+      // 换成现场创建的临时目录：环境无关，并把 #139 的锚根行为写成断言（原来只验「有输出」）。
+      projectPath = nodeFs.mkdtempSync(path.join(os.tmpdir(), 'harness-report-pp-'));
+
+      await report({ format: 'json', projectPath }, io);
       expect(io.outText()).not.toBe('');
+      expect(
+        nodeFs.existsSync(path.join(projectPath, path.dirname(DEFAULT_TRACE_FILE)))
+      ).toBe(true);
     });
 
     it('Markdown 报告应包含表格结构', async () => {

package/src/cli/commands/__tests__/review.test.ts

@@ -4,6 +4,7 @@
 
 import { review, reviewStatus } from '../review';
 import { captureIO, type CapturingIO } from '../../command-contract';
+import { decide, fakeGate, throwingGate } from './gate-decision';
 import { execAsync } from '../../../utils/exec';
 import { ReviewGate } from '../../../gates/review';
 
@@ -13,7 +14,7 @@ jest.mock('../../../utils/exec', () => ({
 
 jest.mock('../../../gates/review', () => ({
   ReviewGate: jest.fn().mockImplementation(() => ({
-    check: jest.fn(),
+    evaluate: jest.fn(),
   })),
 }));
 
@@ -41,12 +42,9 @@ describe('review command', () => {
   describe('review', () => {
     it('should print success when check passes', async () => {
       mockExec.mockResolvedValue({ stdout: 'main\n', stderr: '' });
-      const mockCheck = jest.fn().mockResolvedValue({
-        passed: true,
-        message: 'ok',
-        details: { approvals: 2, changesRequested: 0 },
-      });
-      MockGate.mockImplementation(() => ({ check: mockCheck }) as any);
+      MockGate.mockImplementation(() =>
+        fakeGate(decide('review', true, 'ok', { approvals: 2, changesRequested: 0 })) as any
+      );
 
       const result = await review({}, io);
 
@@ -56,12 +54,9 @@ describe('review command', () => {
 
     it('should print failure and exit 1 when check fails', async () => {
       mockExec.mockResolvedValue({ stdout: 'main\n', stderr: '' });
-      const mockCheck = jest.fn().mockResolvedValue({
-        passed: false,
-        message: 'needs approval',
-        details: { suggestion: 'Request review from a teammate' },
-      });
-      MockGate.mockImplementation(() => ({ check: mockCheck }) as any);
+      MockGate.mockImplementation(() =>
+        fakeGate(decide('review', false, 'needs approval', { suggestion: 'Request review from a teammate' })) as any
+      );
 
       const result = await review({}, io);
 
@@ -74,8 +69,7 @@ describe('review command', () => {
 
     it('should handle errors and exit 1', async () => {
       mockExec.mockResolvedValue({ stdout: 'main\n', stderr: '' });
-      const mockCheck = jest.fn().mockRejectedValue(new Error('gate error'));
-      MockGate.mockImplementation(() => ({ check: mockCheck }) as any);
+      MockGate.mockImplementation(() => throwingGate(new Error('gate error')) as any);
 
       const result = await review({}, io);
 
@@ -100,8 +94,7 @@ describe('review command', () => {
 
     it('should parse allowedReviewers from comma-separated string', async () => {
       mockExec.mockResolvedValue({ stdout: 'main\n', stderr: '' });
-      const mockCheck = jest.fn().mockResolvedValue({ passed: true, message: 'ok' });
-      MockGate.mockImplementation(() => ({ check: mockCheck }) as any);
+      MockGate.mockImplementation(() => fakeGate(decide('review', true, 'ok')) as any);
 
       await review({ allowedReviewers: 'alice, bob, charlie' }, io);