@dommaker/harness 1.2.2 → 1.3.0

package/dist/test-setup/mkdtemp-cleanup.js

@@ -0,0 +1,90 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.patchMktempCleanup = patchMktempCleanup;
+exports.isRegisteredTmpDir = isRegisteredTmpDir;
+exports.sweepStaleMkdtempDirs = sweepStaleMkdtempDirs;
+/**
+ * Jest setupFilesAfterEnv - mkdtemp 泄漏防护（2026-08-26 /tmp 3.9 万残留事故根因修复）
+ *
+ * 事故：5 个测试文件 fs.mkdtempSync 后零清理（constraints-retire / check-drift /
+ * constraints-report / agent-prompt-renderer / injection-drift），日常 jest 运行累积。
+ *
+ * 机制（studio apps/api/tests/mkdtemp-cleanup.ts 同款，jest 版）：
+ * 1) patch fs.mkdtempSync--本进程创建的临时目录全部进注册表，afterAll 统一 rmSync。
+ *    jest worker 被 kill 时 process 'exit' 不触发，必须用 afterAll（setupFilesAfterEnv
+ *    里注册 = 文件级钩子）。
+ * 2) import 时清扫 tmpdir 里 >24h 且符合 mkdtemp 签名的目录，兜底 worker 被 kill 的场景。
+ *
+ * 签名正则只匹配「小写字母数字连字符前缀 + 恰好 6 位大小写字母数字后缀」：
+ * chrome crashpad（org.chromium.Chromium.XXXX，含点）、tsx-0 / jest_0 等不匹配。
+ */
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const globals_1 = require("@jest/globals");
+const MKDTEMP_SUFFIX_RE = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*-[A-Za-z0-9]{6}$/;
+let patched = false;
+const registeredDirs = new Set();
+/** 幂等。setup 与测试文件重复调用安全。 */
+function patchMktempCleanup() {
+    if (patched)
+        return;
+    patched = true;
+    const orig = fs_1.default.mkdtempSync;
+    fs_1.default.mkdtempSync = ((prefix) => {
+        const dir = orig(prefix);
+        registeredDirs.add(dir);
+        return dir;
+    });
+    (0, globals_1.afterAll)(() => {
+        for (const dir of registeredDirs) {
+            try {
+                fs_1.default.rmSync(dir, { recursive: true, force: true });
+            }
+            catch {
+                // 清理失败不阻断测试
+            }
+        }
+        registeredDirs.clear();
+    });
+}
+function isRegisteredTmpDir(dir) {
+    return registeredDirs.has(dir);
+}
+/**
+ * 清扫 tmpDir 中超龄且符合 mkdtemp 签名的目录。返回删除数。
+ * 单条失败（竞态被别进程先删等）不阻断。
+ */
+function sweepStaleMkdtempDirs(tmpDir, ageMs) {
+    let entries;
+    try {
+        entries = fs_1.default.readdirSync(tmpDir);
+    }
+    catch {
+        return 0;
+    }
+    const now = Date.now();
+    let removed = 0;
+    for (const name of entries) {
+        if (!MKDTEMP_SUFFIX_RE.test(name))
+            continue;
+        try {
+            const p = path_1.default.join(tmpDir, name);
+            const st = fs_1.default.statSync(p);
+            if (st.isDirectory() && now - st.mtimeMs > ageMs) {
+                fs_1.default.rmSync(p, { recursive: true, force: true });
+                removed++;
+            }
+        }
+        catch {
+            // 单条竞态不阻断
+        }
+    }
+    return removed;
+}
+// setupFilesAfterEnv 顶层执行：打补丁 + 清扫历史残留
+patchMktempCleanup();
+sweepStaleMkdtempDirs(process.env.TMPDIR || '/tmp', 24 * 60 * 60 * 1000);
+//# sourceMappingURL=mkdtemp-cleanup.js.map

package/dist/test-setup/mkdtemp-cleanup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mkdtemp-cleanup.js","sourceRoot":"","sources":["../../src/test-setup/mkdtemp-cleanup.ts"],"names":[],"mappings":";;;;;AAyBA,gDAoBC;AAED,gDAEC;AAMD,sDAuBC;AA9ED;;;;;;;;;;;;;;GAcG;AACH,4CAAoB;AACpB,gDAAwB;AACxB,2CAAyC;AAEzC,MAAM,iBAAiB,GAAG,gDAAgD,CAAC;AAE3E,IAAI,OAAO,GAAG,KAAK,CAAC;AACpB,MAAM,cAAc,GAAG,IAAI,GAAG,EAAU,CAAC;AAEzC,4BAA4B;AAC5B,SAAgB,kBAAkB;IAChC,IAAI,OAAO;QAAE,OAAO;IACpB,OAAO,GAAG,IAAI,CAAC;IACf,MAAM,IAAI,GAAG,YAAE,CAAC,WAAyC,CAAC;IAC1D,YAAE,CAAC,WAAW,GAAG,CAAC,CAAC,MAAc,EAAE,EAAE;QACnC,MAAM,GAAG,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC;QACzB,cAAc,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACxB,OAAO,GAAG,CAAC;IACb,CAAC,CAA0B,CAAC;IAE5B,IAAA,kBAAQ,EAAC,GAAG,EAAE;QACZ,KAAK,MAAM,GAAG,IAAI,cAAc,EAAE,CAAC;YACjC,IAAI,CAAC;gBACH,YAAE,CAAC,MAAM,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;YACnD,CAAC;YAAC,MAAM,CAAC;gBACP,YAAY;YACd,CAAC;QACH,CAAC;QACD,cAAc,CAAC,KAAK,EAAE,CAAC;IACzB,CAAC,CAAC,CAAC;AACL,CAAC;AAED,SAAgB,kBAAkB,CAAC,GAAW;IAC5C,OAAO,cAAc,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;AACjC,CAAC;AAED;;;GAGG;AACH,SAAgB,qBAAqB,CAAC,MAAc,EAAE,KAAa;IACjE,IAAI,OAAiB,CAAC;IACtB,IAAI,CAAC;QACH,OAAO,GAAG,YAAE,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC;IACnC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,CAAC,CAAC;IACX,CAAC;IACD,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IACvB,IAAI,OAAO,GAAG,CAAC,CAAC;IAChB,KAAK,MAAM,IAAI,IAAI,OAAO,EAAE,CAAC;QAC3B,IAAI,CAAC,iBAAiB,CAAC,IAAI,CAAC,IAAI,CAAC;YAAE,SAAS;QAC5C,IAAI,CAAC;YACH,MAAM,CAAC,GAAG,cAAI,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;YAClC,MAAM,EAAE,GAAG,YAAE,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;YAC1B,IAAI,EAAE,CAAC,WAAW,EAAE,IAAI,GAAG,GAAG,EAAE,CAAC,OAAO,GAAG,KAAK,EAAE,CAAC;gBACjD,YAAE,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;gBAC/C,OAAO,EAAE,CAAC;YACZ,CAAC;QACH,CAAC;QAAC,MAAM,CAAC;YACP,UAAU;QACZ,CAAC;IACH,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,uCAAuC;AACvC,kBAAkB,EAAE,CAAC;AACrB,qBAAqB,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,IAAI,MAAM,EAAE,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC"}

package/dist/types/failure.d.ts

@@ -4,6 +4,13 @@
  * 提供通用的错误分类和失败记录类型
  * 不包含业务逻辑，只定义数据结构
  */
+/**
+ * 默认 failure 日志路径（相对项目根目录）
+ *
+ * 读写双方必须统一引用此常量（DEFAULT_TRACE_FILE 同款先例）；
+ * 自定义路径时向 FailureRecorder 传入自定 logFile
+ */
+export declare const DEFAULT_FAILURE_LOG_FILE = ".harness/logs/failures.log";
 /**
  * 错误类型枚举
  */

package/dist/types/failure.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"failure.d.ts","sourceRoot":"","sources":["../../src/types/failure.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;GAEG;AACH,oBAAY,SAAS;IACnB,WAAW,gBAAgB;IAC3B,WAAW,gBAAgB;IAC3B,kBAAkB,uBAAuB;IACzC,gBAAgB,qBAAqB;IACrC,OAAO,YAAY;IACnB,aAAa,kBAAkB;IAC/B,WAAW,gBAAgB;IAC3B,UAAU,eAAe;IACzB,gBAAgB,qBAAqB;IACrC,OAAO,YAAY;CACpB;AAED;;;;;;;GAOG;AACH,oBAAY,YAAY;IACtB,EAAE,OAAO;IACT,EAAE,OAAO;IACT,EAAE,OAAO;IACT,EAAE,OAAO;CACV;AAED;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC,cAAc;IACd,IAAI,EAAE,SAAS,CAAC;IAChB,aAAa;IACb,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,oBAAoB;IACpB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,WAAW;IACX,KAAK,CAAC,EAAE,YAAY,CAAC;IACrB,WAAW;IACX,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,WAAW;IACX,IAAI,EAAE,SAAS,CAAC;IAChB,WAAW;IACX,KAAK,EAAE,YAAY,CAAC;IACpB,WAAW;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU;IACV,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU;IACV,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,WAAW;IACX,IAAI,EAAE,SAAS,CAAC;IAChB,WAAW;IACX,KAAK,EAAE,YAAY,CAAC;IACpB,iBAAiB;IACjB,WAAW,CAAC,EAAE,uBAAuB,CAAC;IACtC,WAAW;IACX,aAAa,EAAE,KAAK,CAAC;CACtB;AAED;;;;GAIG;AACH,eAAO,MAAM,4BAA4B,EAAE,uBAAuB,EA2DjE,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,qBAAqB,EAAE,MAAM,CAAC,SAAS,EAAE,YAAY,CAWjE,CAAC"}
+{"version":3,"file":"failure.d.ts","sourceRoot":"","sources":["../../src/types/failure.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB,+BAA+B,CAAC;AAErE;;GAEG;AACH,oBAAY,SAAS;IACnB,WAAW,gBAAgB;IAC3B,WAAW,gBAAgB;IAC3B,kBAAkB,uBAAuB;IACzC,gBAAgB,qBAAqB;IACrC,OAAO,YAAY;IACnB,aAAa,kBAAkB;IAC/B,WAAW,gBAAgB;IAC3B,UAAU,eAAe;IACzB,gBAAgB,qBAAqB;IACrC,OAAO,YAAY;CACpB;AAED;;;;;;;GAOG;AACH,oBAAY,YAAY;IACtB,EAAE,OAAO;IACT,EAAE,OAAO;IACT,EAAE,OAAO;IACT,EAAE,OAAO;CACV;AAED;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC,cAAc;IACd,IAAI,EAAE,SAAS,CAAC;IAChB,aAAa;IACb,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,oBAAoB;IACpB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,WAAW;IACX,KAAK,CAAC,EAAE,YAAY,CAAC;IACrB,WAAW;IACX,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,WAAW;IACX,IAAI,EAAE,SAAS,CAAC;IAChB,WAAW;IACX,KAAK,EAAE,YAAY,CAAC;IACpB,WAAW;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU;IACV,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU;IACV,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,WAAW;IACX,IAAI,EAAE,SAAS,CAAC;IAChB,WAAW;IACX,KAAK,EAAE,YAAY,CAAC;IACpB,iBAAiB;IACjB,WAAW,CAAC,EAAE,uBAAuB,CAAC;IACtC,WAAW;IACX,aAAa,EAAE,KAAK,CAAC;CACtB;AAED;;;;GAIG;AACH,eAAO,MAAM,4BAA4B,EAAE,uBAAuB,EA2DjE,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,qBAAqB,EAAE,MAAM,CAAC,SAAS,EAAE,YAAY,CAWjE,CAAC"}

package/dist/types/failure.js

@@ -6,7 +6,14 @@
  * 不包含业务逻辑，只定义数据结构
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DEFAULT_LEVEL_MAPPING = exports.DEFAULT_CLASSIFICATION_RULES = exports.FailureLevel = exports.ErrorType = void 0;
+exports.DEFAULT_LEVEL_MAPPING = exports.DEFAULT_CLASSIFICATION_RULES = exports.FailureLevel = exports.ErrorType = exports.DEFAULT_FAILURE_LOG_FILE = void 0;
+/**
+ * 默认 failure 日志路径（相对项目根目录）
+ *
+ * 读写双方必须统一引用此常量（DEFAULT_TRACE_FILE 同款先例）；
+ * 自定义路径时向 FailureRecorder 传入自定 logFile
+ */
+exports.DEFAULT_FAILURE_LOG_FILE = '.harness/logs/failures.log';
 /**
  * 错误类型枚举
  */

package/dist/types/failure.js.map

@@ -1 +1 @@
-{"version":3,"file":"failure.js","sourceRoot":"","sources":["../../src/types/failure.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"failure.js","sourceRoot":"","sources":["../../src/types/failure.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dommaker/harness",
-  "version": "1.2.2",
+  "version": "1.3.0",
   "description": "通用工程约束框架 - 铁律系统、检查点验证、测试门控",
   "keywords": [
     "harness",

package/src/__tests__/failure-recorder.test.ts

@@ -333,3 +333,12 @@ describe('FailureRecorder', () => {
     });
   });
 });
+
+describe('DEFAULT_FAILURE_LOG_FILE', () => {
+  it('锁口径：统一到 .harness/logs/（与 DEFAULT_TRACE_FILE 同目录约定），从 barrel 公开导出', async () => {
+    const { DEFAULT_FAILURE_LOG_FILE } = await import('../types/failure');
+    const barrel = await import('../index');
+    expect(DEFAULT_FAILURE_LOG_FILE).toBe('.harness/logs/failures.log');
+    expect(barrel.DEFAULT_FAILURE_LOG_FILE).toBe(DEFAULT_FAILURE_LOG_FILE);
+  });
+});

package/src/__tests__/public-exports.test.ts

@@ -29,6 +29,7 @@ const EXPECTED_RUNTIME_EXPORTS = [
   'DEFAULT_COMMAND_BLACKLIST',
   'DEFAULT_COMPACTION_CONFIG',
   'DEFAULT_DECAY_CONFIG',
+  'DEFAULT_FAILURE_LOG_FILE',
   'DEFAULT_LEVEL_MAPPING',
   'DEFAULT_NONCODE_GLOBS',
   'DEFAULT_TEST_GLOBS',
@@ -103,6 +104,7 @@ const EXPECTED_RUNTIME_EXPORTS = [
   'getCommandGate',
   'getCommandRiskLevel',
   'getConstraint',
+  'getCriticalArtifacts',
   'getEffectiveConstraints',
   'getEffectiveGates',
   'getFailureLevel',
@@ -127,6 +129,7 @@ const EXPECTED_RUNTIME_EXPORTS = [
   'validateSpec',
   'verifyContractPresence',
   'verifyPhaseFormat',
+  'verifyReleaseArtifacts',
   'verifyTddChain',
 ];
 

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

@@ -68,13 +68,20 @@ const MOCK_REPORT = {
 };
 
 describe('getKnowledgeDir', () => {
+  const fs = require('fs');
   const os = require('os');
   const path = require('path');
   const storeModule = require('../../../knowledge/store');
   let storeCtorSpy: jest.SpyInstance;
+  let homedirSpy: jest.SpyInstance;
+  let errorSpy: jest.SpyInstance;
+  let tmpHome: string;
 
   beforeEach(() => {
     delete process.env.KNOWLEDGE_BASE_DIR;
+    tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), 'harness-kdir-'));
+    homedirSpy = jest.spyOn(os, 'homedir').mockReturnValue(tmpHome);
+    errorSpy = jest.spyOn(console, 'error').mockImplementation();
     storeCtorSpy = jest.spyOn(storeModule, 'FileKnowledgeStore').mockImplementation(() => ({
       list: jest.fn().mockReturnValue([]),
     }));
@@ -82,7 +89,10 @@ describe('getKnowledgeDir', () => {
 
   afterEach(() => {
     storeCtorSpy.mockRestore();
+    homedirSpy.mockRestore();
+    errorSpy.mockRestore();
     delete process.env.KNOWLEDGE_BASE_DIR;
+    fs.rmSync(tmpHome, { recursive: true, force: true });
   });
 
   it('should use KNOWLEDGE_BASE_DIR env var when set', async () => {
@@ -93,11 +103,33 @@ describe('getKnowledgeDir', () => {
     }));
   });
 
-  it('should default to ~/.studio/knowledge when no env var', async () => {
-    const expected = path.join(os.homedir(), '.studio', 'knowledge');
+  it('should default to ~/.harness/knowledge when no env var and no legacy data', async () => {
+    await knowledgeStats({ json: true });
+    expect(storeCtorSpy).toHaveBeenCalledWith(expect.objectContaining({
+      baseDir: path.join(tmpHome, '.harness', 'knowledge'),
+    }));
+  });
+
+  it('should keep legacy ~/.studio/knowledge when it still has data, with deprecation notice shown once', async () => {
+    const legacyDir = path.join(tmpHome, '.studio', 'knowledge');
+    fs.mkdirSync(legacyDir, { recursive: true });
+    fs.writeFileSync(path.join(legacyDir, 'guideline-x.md'), 'data');
+    await knowledgeStats({ json: true });
+    expect(storeCtorSpy).toHaveBeenCalledWith(expect.objectContaining({
+      baseDir: legacyDir,
+    }));
+    expect(errorSpy).toHaveBeenCalledWith(expect.stringContaining('旧目录'));
+    // 闩锁：同进程重复解析只提示一次
+    await knowledgeStats({ json: true });
+    const notices = errorSpy.mock.calls.filter((c: any[]) => typeof c[0] === 'string' && c[0].includes('旧目录'));
+    expect(notices).toHaveLength(1);
+  });
+
+  it('should ignore legacy dir when it exists but is empty', async () => {
+    fs.mkdirSync(path.join(tmpHome, '.studio', 'knowledge'), { recursive: true });
     await knowledgeStats({ json: true });
     expect(storeCtorSpy).toHaveBeenCalledWith(expect.objectContaining({
-      baseDir: expected,
+      baseDir: path.join(tmpHome, '.harness', 'knowledge'),
     }));
   });
 

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

@@ -12,6 +12,7 @@
  */
 
 import * as fs from 'fs';
+import * as path from 'path';
 import { execSync } from 'child_process';
 import { release } from '../release';
 
@@ -53,7 +54,13 @@ jest.mock('chalk', () => {
 const mockExecSync = execSync as jest.MockedFunction<typeof execSync>;
 const mockFs = fs as jest.Mocked<typeof fs>;
 
-const PKG_JSON = JSON.stringify({ name: '@dommaker/harness', version: '0.18.0' });
+const PKG_JSON = JSON.stringify({
+  name: '@dommaker/harness',
+  version: '0.18.0',
+  main: './dist/index.js',
+  bin: './bin/harness.js',
+  exports: { '.': './dist/index.js' },
+});
 
 describe('release command', () => {
   let consoleSpy: jest.SpyInstance;
@@ -135,6 +142,20 @@ describe('release command', () => {
     expect(errorSpy).toHaveBeenCalledWith(expect.stringContaining('Uncommitted changes'));
   });
 
+  test('dist 关键发布物缺失：发布前闸门 exit 1（不触 npm version）', async () => {
+    mockFs.existsSync.mockImplementation((p) => {
+      if (String(p).endsWith('package.json')) return true;
+      if (String(p).includes(`${path.sep}dist${path.sep}`)) return false;
+      return true;
+    });
+
+    await expect(release({ bumpType: 'patch' })).rejects.toThrow('__exit_1__');
+    expect(errorSpy).toHaveBeenCalledWith(expect.stringContaining('dist missing critical artifacts'));
+    expect(errorSpy).toHaveBeenCalledWith(expect.stringContaining('dist/index.js'));
+    const commands = mockExecSync.mock.calls.map(c => String(c[0]));
+    expect(commands.some(c => c.startsWith('npm version'))).toBe(false);
+  });
+
   test('dry-run patch：计算目标版本 0.18.1，exit 0', async () => {
     await expect(release({ bumpType: 'patch', dryRun: 'true' })).rejects.toThrow('__exit_0__');
     expect(consoleSpy).toHaveBeenCalledWith(

package/src/cli/commands/__tests__/sync-docs-agents.test.ts

@@ -242,18 +242,18 @@ describe('sync-docs --agents', () => {
     fs.rmSync(testDir, { recursive: true, force: true });
   });
 
-  describe('知识入口行：.studio/CONTEXT.md 正本模型（studio #188）', () => {
-    it('.studio/CONTEXT.md 存在时生成正本行，替代散置指引（散置文件同时在场也一样），--check 无漂移', async () => {
-      const testDir = path.join(tempDir, 'studio-context-model');
+  describe('知识入口行：模块上下文正本模型', () => {
+    it('.harness/CONTEXT.md 存在时生成正本行指向新正本，替代散置指引，--check 无漂移', async () => {
+      const testDir = path.join(tempDir, 'canonical-context-model');
       createFixture(testDir, { pnpm: true, withCapabilities: true });
       // 夹具已带散置 src/CONTEXT.md：正本在场时整行替代，与是否残留散置文件无关
-      fs.mkdirSync(path.join(testDir, '.studio'), { recursive: true });
-      fs.writeFileSync(path.join(testDir, '.studio', 'CONTEXT.md'), '# 模块上下文\n\n## src\n\n职责：夹具\n');
+      fs.mkdirSync(path.join(testDir, '.harness'), { recursive: true });
+      fs.writeFileSync(path.join(testDir, '.harness', 'CONTEXT.md'), '# 模块上下文\n\n## src\n\n职责：夹具\n');
 
       await syncDocs({ projectPath: testDir, agents: true });
 
       const content = fs.readFileSync(path.join(testDir, 'AGENTS.md'), 'utf-8');
-      expect(content).toContain('模块上下文正本：`.studio/CONTEXT.md`（模块锚点组织），改动代码时同步更新');
+      expect(content).toContain('模块上下文正本：`.harness/CONTEXT.md`（模块锚点组织），改动代码时同步更新');
       expect(content).not.toContain('各源码目录的 `CONTEXT.md`');
       expect(content).not.toContain('缺失目录可由 `harness sync-docs` 生成模板');
       // 知识库行不受影响
@@ -267,7 +267,30 @@ describe('sync-docs --agents', () => {
       fs.rmSync(testDir, { recursive: true, force: true });
     });
 
-    it('.studio/CONTEXT.md 不存在时保持散置模型行，--check 无漂移', async () => {
+    it('旧正本 .studio/CONTEXT.md 仍在场时兼容沿用（免迁移），两者同在以 .harness/ 为准', async () => {
+      const legacyDir = path.join(tempDir, 'legacy-context-model');
+      createFixture(legacyDir, { pnpm: true, withCapabilities: true });
+      fs.mkdirSync(path.join(legacyDir, '.studio'), { recursive: true });
+      fs.writeFileSync(path.join(legacyDir, '.studio', 'CONTEXT.md'), '# 模块上下文\n\n## src\n\n职责：夹具\n');
+      await syncDocs({ projectPath: legacyDir, agents: true });
+      expect(fs.readFileSync(path.join(legacyDir, 'AGENTS.md'), 'utf-8'))
+        .toContain('模块上下文正本：`.studio/CONTEXT.md`（模块锚点组织），改动代码时同步更新');
+      fs.rmSync(legacyDir, { recursive: true, force: true });
+
+      const bothDir = path.join(tempDir, 'both-context-model');
+      createFixture(bothDir, { pnpm: true, withCapabilities: true });
+      fs.mkdirSync(path.join(bothDir, '.studio'), { recursive: true });
+      fs.writeFileSync(path.join(bothDir, '.studio', 'CONTEXT.md'), '# 旧\n');
+      fs.mkdirSync(path.join(bothDir, '.harness'), { recursive: true });
+      fs.writeFileSync(path.join(bothDir, '.harness', 'CONTEXT.md'), '# 新\n');
+      await syncDocs({ projectPath: bothDir, agents: true });
+      const content = fs.readFileSync(path.join(bothDir, 'AGENTS.md'), 'utf-8');
+      expect(content).toContain('模块上下文正本：`.harness/CONTEXT.md`');
+      expect(content).not.toContain('.studio/CONTEXT.md');
+      fs.rmSync(bothDir, { recursive: true, force: true });
+    });
+
+    it('正本不存在时保持散置模型行，--check 无漂移', async () => {
       const testDir = path.join(tempDir, 'scattered-context-model');
       createFixture(testDir, { pnpm: true, withCapabilities: true });
 
@@ -282,10 +305,10 @@ describe('sync-docs --agents', () => {
       fs.rmSync(testDir, { recursive: true, force: true });
     });
 
-    it('.studio/CONTEXT.md 是目录而非文件时不视为正本', async () => {
-      const testDir = path.join(tempDir, 'studio-context-dir');
+    it('正本路径是目录而非文件时不视为正本', async () => {
+      const testDir = path.join(tempDir, 'context-doc-dir');
       createFixture(testDir, { pnpm: true, withCapabilities: true });
-      fs.mkdirSync(path.join(testDir, '.studio', 'CONTEXT.md'), { recursive: true });
+      fs.mkdirSync(path.join(testDir, '.harness', 'CONTEXT.md'), { recursive: true });
 
       await syncDocs({ projectPath: testDir, agents: true });
 

package/src/cli/commands/definitions.ts

@@ -251,7 +251,7 @@ export const COMMAND_DEFINITIONS: CommandDefinition[] = [
       { flags: '--title <title>', description: '知识标题（用于 upsert）' },
       { flags: '--content <content>', description: '知识内容 Markdown（用于 upsert）' },
       { flags: '--file <path>', description: '从文件读取内容（用于 upsert）' },
-      { flags: '--source <source>', description: '知识来源 (analyst/cli/design)', defaultValue: 'cli' },
+      { flags: '--source <source>', description: '知识来源 (cli/design)', defaultValue: 'cli' },
       { flags: '--fix', description: '自动修复（用于 audit）', defaultValue: false },
       { flags: '--dry-run', description: '只输出报告不修改（用于 audit）', defaultValue: false },
       { flags: '--threshold <n>', description: '短内容阈值（字符数，用于 audit）', defaultValue: '50' },

package/src/cli/commands/failure.ts

@@ -7,6 +7,7 @@
 import chalk from 'chalk';
 import * as path from 'path';
 import { FailureRecorder } from '../../failure/recorder';
+import { DEFAULT_FAILURE_LOG_FILE } from '../../types/failure';
 
 export interface FailureOptions {
   /** 项目路径 */
@@ -21,7 +22,7 @@ export interface FailureOptions {
 function getRecorder(projectPath?: string): FailureRecorder {
   const base = projectPath || process.cwd();
   return new FailureRecorder({
-    logFile: path.join(base, '.harness', 'failures', 'failures.log'),
+    logFile: path.join(base, DEFAULT_FAILURE_LOG_FILE),
   });
 }
 

package/src/cli/commands/knowledge.ts

@@ -499,10 +499,35 @@ export async function knowledgeHealth(options: KnowledgeOptions & { dir?: string
   }
 }
 
+/** 缺省知识库数据根（相对用户 home） */
+const KNOWLEDGE_DATA_DIR = path.join('.harness', 'knowledge');
+/** 旧缺省数据根（曾寄居 studio home），仍有数据时兼容沿用，免迁移 */
+const LEGACY_KNOWLEDGE_DATA_DIR = path.join('.studio', 'knowledge');
+
+let legacyKnowledgeDirNotified = false;
+
+function hasKnowledgeData(dir: string): boolean {
+  try {
+    return fs.existsSync(dir) && fs.readdirSync(dir).length > 0;
+  } catch {
+    return false;
+  }
+}
+
 function getKnowledgeDir(projectPath?: string): string {
   if (projectPath) return `${projectPath}/.harness/knowledge`;
   if (process.env.KNOWLEDGE_BASE_DIR) return process.env.KNOWLEDGE_BASE_DIR;
-  return path.join(os.homedir(), '.studio', 'knowledge');
+  const defaultDir = path.join(os.homedir(), KNOWLEDGE_DATA_DIR);
+  const legacyDir = path.join(os.homedir(), LEGACY_KNOWLEDGE_DATA_DIR);
+  if (hasKnowledgeData(legacyDir)) {
+    if (!legacyKnowledgeDirNotified) {
+      legacyKnowledgeDirNotified = true;
+      // stderr：不污染 --json 的 stdout 输出
+      console.error(chalk.yellow(`⚠ 缺省知识库根已改为 ${defaultDir}；旧目录 ${legacyDir} 仍有数据，本次沿用（免迁移，可用 KNOWLEDGE_BASE_DIR 覆盖）`));
+    }
+    return legacyDir;
+  }
+  return defaultDir;
 }
 
 /**

package/src/cli/commands/release.ts

@@ -21,6 +21,7 @@ import { execSync } from 'child_process';
 import * as fs from 'fs';
 import * as path from 'path';
 import chalk from 'chalk';
+import { verifyReleaseArtifacts } from '../../release';
 
 export interface ReleaseOptions {
   bumpType?: 'patch' | 'minor' | 'major';
@@ -92,28 +93,13 @@ export async function release(options: ReleaseOptions): Promise<void> {
   }
   console.log(chalk.green('✅ tsc: built'));
 
-  // ── 4. Verify dist ──
-  const criticalFiles = [
-    'dist/index.js',
-    'dist/knowledge/index.js',
-    'dist/knowledge/store.js',
-    'dist/knowledge/ingest.js',
-    'dist/knowledge/query.js',
-    'dist/knowledge/lifecycle.js',
-    'dist/knowledge/lint.js',
-    'dist/knowledge/types.js',
-    'dist/knowledge/import.js',
-    'dist/knowledge/reference-tracker.js',
-    'dist/knowledge/lifecycle-hooks.js',
-    'dist/knowledge/doctor.js',
-    'dist/core/constraints/prompt-injection.js',
-  ];
-  const missing = criticalFiles.filter(f => !fs.existsSync(path.join(pkgPath, f)));
-  if (missing.length > 0) {
-    console.error(chalk.red(`❌ dist missing critical files: ${missing.join(', ')}`));
+  // ── 4. Verify dist（发布物完整性自检，harness#77：清单随源码维护，不再本文件硬编码）──
+  const integrity = verifyReleaseArtifacts(pkgPath);
+  if (!integrity.ok) {
+    console.error(chalk.red(`❌ dist missing critical artifacts (${integrity.missing.length}): ${integrity.missing.join(', ')}`));
     process.exit(1);
   }
-  console.log(chalk.green('✅ dist: verified'));
+  console.log(chalk.green(`✅ dist: verified (${integrity.checked.length} critical artifacts)`));
 
   if (dryRun) {
     const [major, minor, patch] = oldVersion.split('.').map(Number);

package/src/cli/commands/sync-docs/agents-syncer.ts

@@ -60,11 +60,11 @@ export interface GovernanceInfo {
  */
 export async function buildAgentsMd(projectPath: string, srcDirs: string[]): Promise<string> {
   const pkg = await readPackageJsonLite(projectPath);
-  const [dirs, governance, hasKnowledge, hasStudioContext, contextDocCount] = await Promise.all([
+  const [dirs, governance, hasKnowledge, contextDocPath, contextDocCount] = await Promise.all([
     getTopLevelDirEntries(projectPath, srcDirs),
     getGovernanceInfo(projectPath),
     hasKnowledgeDir(projectPath),
-    hasStudioContextDoc(projectPath),
+    findCanonicalContextDoc(projectPath),
     countContextDocs(projectPath, srcDirs),
   ]);
 
@@ -128,10 +128,10 @@ export async function buildAgentsMd(projectPath: string, srcDirs: string[]): Pro
     // 写进受 --check 漂移比对的文档会制造「必然过期」竞态（任何知识写入都使已提交文档过期）
     lines.push('- `.harness/knowledge/`：项目知识库，用 `harness knowledge` 查询');
   }
-  if (hasStudioContext) {
-    // 正本模型（studio #152/T12）：模块上下文沉淀归并到业务仓 .studio/CONTEXT.md，
-    // 散置 CONTEXT.md 指引与该裁决矛盾，正本在场时整行替代
-    lines.push('- 模块上下文正本：`.studio/CONTEXT.md`（模块锚点组织），改动代码时同步更新');
+  if (contextDocPath) {
+    // 正本模型：模块上下文沉淀归并到业务仓单一正本（模块锚点组织），
+    // 散置 CONTEXT.md 指引与该模型矛盾，正本在场时整行替代
+    lines.push(`- 模块上下文正本：\`${contextDocPath}\`（模块锚点组织），改动代码时同步更新`);
   } else {
     lines.push(
       contextDocCount > 0
@@ -254,17 +254,30 @@ async function hasKnowledgeDir(projectPath: string): Promise<boolean> {
   }
 }
 
+/** 模块上下文正本候选路径（相对项目根）：新正本优先，旧正本兼容沿用（免迁移） */
+const CONTEXT_DOC_PATHS: string[][] = [
+  ['.harness', 'CONTEXT.md'],
+  ['.studio', 'CONTEXT.md'],
+];
+
 /**
- * 判断 .studio/CONTEXT.md 是否存在（正本模型标记，studio #152/T12）：
+ * 定位模块上下文正本（正本模型）：
  * 模块上下文沉淀归并到业务仓单一正本（模块锚点组织）时，知识入口行改指正本，
- * 不再输出散置 CONTEXT.md 指引。只判存在性，不解析内容。
+ * 不再输出散置 CONTEXT.md 指引。正本路径缺省 `.harness/CONTEXT.md`；
+ * 旧正本 `.studio/CONTEXT.md` 在场时兼容沿用，两者同时在场上以 `.harness/` 为准。
+ * 返回相对 projectPath 的正本路径（posix 分隔符），无正本返回 null。只判存在性，不解析内容。
  */
-async function hasStudioContextDoc(projectPath: string): Promise<boolean> {
-  try {
-    return (await fs.stat(path.join(projectPath, '.studio', 'CONTEXT.md'))).isFile();
-  } catch {
-    return false;
+async function findCanonicalContextDoc(projectPath: string): Promise<string | null> {
+  for (const segments of CONTEXT_DOC_PATHS) {
+    try {
+      if ((await fs.stat(path.join(projectPath, ...segments))).isFile()) {
+        return segments.join('/');
+      }
+    } catch {
+      // 该候选不存在，看下一个
+    }
   }
+  return null;
 }
 
 /** 统计源码根内的 CONTEXT.md 数量（含源码根本身，跨根去重） */

package/src/completion-checkers/CONTEXT.md

@@ -1,7 +1,7 @@
 # completion-checkers/
 
 ## 职责
-WU 收尾软观测三纯判定函数（T7-E1，studio#160）：tdd-chain 引用链 / phase-format subject 结构 / contract-presence 契约在场。纯函数，不碰文件系统与 git，commits 由调用方（studio completion-gates 第四段守卫，T7-E2）供给。
+提交集收尾软观测三纯判定函数：tdd-chain 引用链 / phase-format subject 结构 / contract-presence 契约在场。纯函数，不碰文件系统与 git，commits 由调用方（completion-gates 类守卫）供给。
 
 ## 核心导出
 - `verifyTddChain(commits, config)`（`tdd-chain.ts`）——实现 commit 须带 trailer `Tested-By: <sha>`（`TESTED_BY_RE` 写死）；被引 sha 须在本提交集内、位置在前、文件清单命中 test_globs；`Tests: none`（`TESTS_NONE_RE`）→ waiver；纯测试/纯非代码 commit 天然免检

package/src/completion-checkers/__tests__/contract-presence.test.ts

@@ -1,5 +1,5 @@
 /**
- * verifyContractPresence 测试（studio#160 验收：契约标记缺失 / 无表项 skip）
+ * verifyContractPresence 测试（契约标记缺失 / 无表项 skip）
  */
 
 import { verifyContractPresence } from '../contract-presence';

package/src/completion-checkers/__tests__/phase-format.test.ts

@@ -1,5 +1,5 @@
 /**
- * verifyPhaseFormat 测试（studio#160 验收：subject 不合规 / merge commit 违规）
+ * verifyPhaseFormat 测试（subject 不合规 / merge commit 违规）
  */
 
 import { verifyPhaseFormat } from '../phase-format';

package/src/completion-checkers/__tests__/tdd-chain.test.ts

@@ -1,5 +1,5 @@
 /**
- * verifyTddChain 测试（studio#160 验收：伪造引用三形态 / Tests: none waiver / 免检分类）
+ * verifyTddChain 测试（伪造引用三形态 / Tests: none waiver / 免检分类）
  */
 
 import { verifyTddChain } from '../tdd-chain';
@@ -34,7 +34,7 @@ describe('verifyTddChain', () => {
     const commits = [commit({ sha: sha(2), body: 'Tested-By: ' + sha(9) })];
     const result = verifyTddChain(commits);
     expect(result.verdict).toBe('violation');
-    expect(result.commits[0].reason).toContain('不在本 WU 提交集内');
+    expect(result.commits[0].reason).toContain('不在本提交集内');
   });
 
   it('伪造引用：被引 commit 位置在本 commit 之后 → violation', () => {

package/src/completion-checkers/index.ts

@@ -1,13 +1,13 @@
 /**
- * Completion Checkers（T7-E1，studio#160）
+ * Completion Checkers
  *
- * WU 收尾软观测三件套——纯判定函数库：
+ * 提交集收尾软观测三件套——纯判定函数库：
  * - verifyTddChain：实现 commit 的 Tested-By 引用链验证
  * - verifyPhaseFormat：phase(...) subject 结构验证
  * - verifyContractPresence：通用契约在场引擎
  *
  * 与 ConstraintCheck 闭环注册表无关：直接 export，不注册、不碰 checkers/index.ts。
- * 函数不碰文件系统与 git；commits 由调用方（studio 第四段守卫，T7-E2）供给。
+ * 函数不碰文件系统与 git；commits 由调用方（completion-gates 类守卫）供给。
  */
 
 export * from './types';

package/src/completion-checkers/phase-format.ts

@@ -1,5 +1,5 @@
 /**
- * phase-format：WU 提交 subject 的 phase 结构验证（Q4 定稿）
+ * phase-format：提交 subject 的 phase 结构验证（Q4 定稿）
  *
  * 协议（正则写死在函数里，不进配置）：
  * - 全部非 merge commit 的 subject 命中 `^phase\([a-z0-9-]+\):\s+\S`
@@ -32,7 +32,7 @@ export function verifyPhaseFormat(
 
   const verdicts: CommitVerdict[] = commits.map((commit) => {
     if (isMergeCommit(commit)) {
-      return { sha: commit.sha, verdict: 'violation', reason: 'WU 提交集内出现 merge commit' };
+      return { sha: commit.sha, verdict: 'violation', reason: '提交集内出现 merge commit' };
     }
     if (!PHASE_SUBJECT_RE.test(commit.subject)) {
       return { sha: commit.sha, verdict: 'violation', reason: `subject 不合规：${commit.subject}` };