@dommaker/harness 1.10.0 → 1.12.0

package/src/cli/commands/CONTEXT.md

@@ -1,7 +1,7 @@
 # cli/commands/
 
 ## 职责
-CLI 子命令实现：21 个顶层命令 + constraints 治理子命令 report/retire，覆盖约束检查/门禁验证/文档同步/知识管理/失败诊断/发布等。
+CLI 子命令实现：20 个顶层命令 + constraints 治理子命令 report/retire/reactivate/pack-proposal，覆盖约束检查/门禁验证/文档同步/知识管理/失败诊断/发布等。
 
 H5（#44）起：
 - **命令定义即注册**：`definitions.ts` 的 `COMMAND_DEFINITIONS` 是命令形状（名称/别名/位置参数/选项/子命令/实现引用）的单一来源；bin/harness.js 遍历本表注册表驱动生成，不再手写 commander 命令块，不再有 index.ts barrel 两处同步（R6）
@@ -14,11 +14,12 @@ H5（#44）起：
 - 门禁命令共享面（`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` + 8 个站点工厂（含对外文案；ADR-0029：custom-constraints.yml 示例站随 custom 约束面退役移除）；模板正文住 `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
+- 各命令文件：check / validate / passes-gate / init / report / status / spec / sync-docs / knowledge / sdd / failure / release / constraints / spec-baseline-check
+- `report` 的约束面走生效集（ADR-0033 修缺口）：collectConstraints 传 getMergedConstraintsConfig 的 merged config（与 check.ts 同一入口），总数/分级计数按生效集——此前跑内置全集，config.yml 禁用与应用层条目（`.harness/constraints.yml`）都进不了报告面
 - 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 元数据 + KnowledgeStore 沉淀。ADR-0029：注入漂移小节、prompt 注入清单、custom 落点与治理注入段同步已随文本注入层关停移除）。
+`constraints` 下挂治理子命令：`constraints report`（使用统计 + 退役候选诊断 + 配置健康，`--export` 脱敏；JSON 输出走 `--json-output`——原名 `--json` 与父命令同名会被 commander 消费在父侧、JSON 分支不可达，E1 复盘修正 M3.1 换名，闸见 `__tests__/constraints-report-json-flag.test.ts`）、`constraints retire`（交互选择 + 人确认退役；带 id 直达需显式 `--yes`（#24 人确认闸门），无 `--yes` 报错 + 非零退出码且不落盘；落 config.yml retired 墓碑 + KnowledgeStore 沉淀——沉淀写口的 baseDir 走 knowledge-view `openKnowledgeStore` 同一解析点，与 knowledge 读口同根，不再硬编码 projectRoot 拼接（harness#177）。ADR-0029：注入漂移小节、prompt 注入清单、custom 落点与治理注入段同步已随文本注入层关停移除。ADR-0032：already_retired 只认 retired 墓碑，裸 enabled:false 由退休流程接管补墓碑+沉淀（票 02 断点 6）；落盘后 git 仓内附 commit 提示，不替用户动 git（断点 4）。ADR-0033：findRetireTarget 扩到内置 + 应用层（`.harness/constraints.yml`）——应用层退休墓碑同写 config.yml（enabled:false + retired 同形），constraints.yml 条文保留不删，沉淀条目 tags 加 `source:app`）、`constraints reactivate`（点对点复活：删 retired 墓碑段 + 写 `constraint-reactivated-<id>` 新沉淀，不改历史（ADR-0032 决策 6.5，票 02 断点 5）；直达同需 `--yes`，无交互模式；ADR-0033 起对应用层约束同路径可用）、`constraints pack-proposal`（升级提案材料打包，ADR-0033 决策 4，块 3 子项 5：条文 + checker 模板与参数 + traces 使用统计 + 升级理由留白的脱敏 markdown，缺省落 `.harness/reports/proposal-<id>-<YYYYMMDD>.md`，`--stdout` 打印不落盘；脱敏只做项目根路径→`<repoRoot>` 替换，params 原文带出并标注人工确认——打包是质量前置不是保密闸门，人拿材料去 harness 仓开 issue）。
 
 ## 依赖关系
 - 依赖 `src/core/constraints/` 约束引擎
@@ -41,7 +42,7 @@ H5（#44）起：
   - 行为可检：`__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 report`：提示属于**报告体内的降级位**，与既有的 `traceFileExists` 说明同在 stdout；结构化面另两份——`--json-output` 的 `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`（驻留上界闸：上限内每文件至多读一遍、超条目/字节上限回落流式且判定不变）

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

@@ -165,8 +165,8 @@ describe('check command（真 git fixture）', () => {
         io
       );
 
-      expect(io.outText()).toContain('✅ error 级约束: 全部通过 (1 条)');
-      expect(io.outText()).toContain('✅ warning 级约束: 1/1 通过');
+      // ADR-0032 起凭证扫描为 error 级：code_implementation 下 error 评 2 条，warning 无命中不输出
+      expect(io.outText()).toContain('✅ error 级约束: 全部通过 (2 条)');
       expect(io.outText()).toContain('✅ 约束检查通过');
       expect(result).toEqual({ kind: 'ok' });
     });
@@ -204,7 +204,7 @@ describe('check command（真 git fixture）', () => {
       expect(result.kind).toBe('fail');
     });
 
-    it('staged 硬编码凭证 → warning 级警告但不阻断', async () => {
+    it('staged 硬编码凭证 → error 级违规即阻断（ADR-0032 升级）', async () => {
       const dir = gitRepo();
       stageChange(
         dir,
@@ -220,8 +220,26 @@ describe('check command（真 git fixture）', () => {
         io
       );
 
+      // error 级违规走 throw 契约（#119）：异常外溢为 fail，消息即约束 message
+      expect(io.outText()).toContain('❌ 约束检查异常: 禁止在代码/文档/配置文件中硬编码密码');
+      expect(result.kind).toBe('fail');
+    });
+
+    it('warning 级违规（治理契约缺失）→ 警告但不阻断', async () => {
+      const dir = gitRepo();
+      // 采用 harness 治理（config.yml 在场）但无 PRESERVE:governance 段 → governance_presence 判 warning
+      write(dir, '.harness/config.yml', 'preset: standard\n');
+      stageChange(dir, 'src/existing.ts', 'export const a = 2;\n');
+      passTraces(dir);
+
+      // 不显式传 trigger：governance_presence 的触发词是 file_modification，由 diff 推断
+      const result = await check(
+        { preset: 'standard', staged: true, projectPath: dir },
+        io
+      );
+
       expect(io.outText()).toContain('⚠️  warning 级约束警告: 1 条');
-      expect(io.outText()).toContain('- no_hardcoded_credentials');
+      expect(io.outText()).toContain('- governance_presence');
       expect(io.outText()).toContain('✅ 约束检查通过');
       expect(result).toEqual({ kind: 'ok' });
     });

package/src/cli/commands/__tests__/constraints-pack-proposal.test.ts

@@ -0,0 +1,142 @@
+/**
+ * harness constraints pack-proposal 测试（ADR-0033 决策 4，块 3 子项 5）
+ *
+ * 覆盖：材料内容形状（条文/severity/checker/统计/升级理由留白）、路径脱敏（<repoRoot>）、
+ * 应用层约束带模板 id 与 params 原文、未知 id → usage-error、--stdout、缺省落盘路径。
+ *
+ * 使用真实临时目录（loadAppConstraints / traces 读真实 fs）。
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import { captureIO, type CapturingIO } from '../../command-contract';
+import { constraintsPackProposal, renderProposalMarkdown } from '../constraints-pack-proposal';
+import { createProjectFixture, writeProjectTraces } from '../../../test-setup/project-fixture';
+import type { Constraint } from '../../../types/constraint';
+
+const APP_YML = [
+  'constraints:',
+  '  - id: app_no_internal_url',
+  '    rule: Web code must not contain internal URLs',
+  '    checker: regex-scan',
+  '    params:',
+  "      pattern: 'https?://10\\.'",
+  "      glob: 'apps/web/src/**'",
+  '    severity: warning',
+  '    message: 检测到内网地址，请改用环境变量配置',
+  '',
+].join('\n');
+
+const NOW = new Date('2026-09-22T00:00:00.000Z');
+
+let io: CapturingIO;
+beforeEach(() => {
+  io = captureIO();
+});
+
+describe('constraintsPackProposal', () => {
+  it('内置约束：材料含条文/severity/统计/升级理由留白，缺省落 .harness/reports/proposal-<id>-<YYYYMMDD>.md', async () => {
+    const root = createProjectFixture({ name: 'pack-proposal-test' });
+    writeProjectTraces(root, [
+      { constraintId: 'no_hardcoded_credentials', result: 'pass', timestamp: 1700000000000 },
+      { constraintId: 'no_hardcoded_credentials', result: 'fail', timestamp: 1700000001000 },
+      { constraintId: 'no_hardcoded_credentials', result: 'skip', timestamp: 1700000002000 },
+    ]);
+
+    const result = await constraintsPackProposal('no_hardcoded_credentials', { projectPath: root, now: NOW }, io);
+
+    expect(result.kind).toBe('ok');
+    const outPath = path.join(root, '.harness', 'reports', 'proposal-no_hardcoded_credentials-20260922.md');
+    expect(fs.existsSync(outPath)).toBe(true);
+
+    const md = fs.readFileSync(outPath, 'utf-8');
+    expect(md).toContain('# 约束升级提案材料：no_hardcoded_credentials');
+    expect(md).toContain('- 生成日期: 2026-09-22');
+    expect(md).toContain('- 来源: 内置');
+    expect(md).toContain('- severity: error');
+    expect(md).toContain('## 条文');
+    expect(md).toContain('## checker');
+    expect(md).toContain('内置定制 checker');
+    // 统计：total=3，evaluated=2（skip 不计入），只有计数
+    expect(md).toContain('- total: 3');
+    expect(md).toContain('- evaluated: 2（pass 1 / fail 1 / skip 1）');
+    expect(md).toContain('- 首次触发: 2023-11-14');
+    expect(md).toContain('## 升级理由');
+    expect(md).toContain('请在此填写');
+    // 脱敏：材料不含项目根绝对路径
+    expect(md).not.toContain(root);
+  });
+
+  it('应用层约束：checker 段带模板 id 与 params 原文 + 人工确认标注', async () => {
+    const root = createProjectFixture({
+      name: 'pack-proposal-test',
+      files: { [path.join('.harness', 'constraints.yml')]: APP_YML },
+    });
+
+    const result = await constraintsPackProposal('app_no_internal_url', { projectPath: root, stdout: true, now: NOW }, io);
+
+    expect(result.kind).toBe('ok');
+    const out = io.outText();
+    expect(out).toContain('- 来源: 应用层（.harness/constraints.yml）');
+    expect(out).toContain('模板: `regex-scan`');
+    expect(out).toContain('pattern:');
+    expect(out).toContain('https?://10\\.');
+    expect(out).toContain("glob: apps/web/src/**");
+    expect(out).toContain('请人工确认无应用内部信息');
+    expect(out).toContain('message: 检测到内网地址，请改用环境变量配置');
+    // --stdout：不落盘
+    expect(fs.existsSync(path.join(root, '.harness', 'reports'))).toBe(false);
+  });
+
+  it('路径脱敏：params/条文中出现的项目根绝对路径替换为 <repoRoot>', () => {
+    const root = '/home/someone/my-app';
+    const constraint: Constraint = {
+      id: 'app_x',
+      kind: 'check',
+      rule: '不得引用 /home/someone/my-app/secrets 下的文件',
+      message: 'm',
+      severity: 'warning',
+      trigger: [],
+      enforcement: '',
+      source: 'app',
+      checker: 'file-exists',
+      params: { path: '/home/someone/my-app/.harness/config.yml' },
+    };
+
+    const md = renderProposalMarkdown(
+      { constraint, stats: { total: 0, pass: 0, fail: 0, skip: 0, evaluated: 0 } },
+      root,
+      NOW
+    );
+
+    expect(md).not.toContain(root);
+    expect(md).toContain('<repoRoot>/secrets');
+    expect(md).toContain('<repoRoot>/.harness/config.yml');
+  });
+
+  it('未知 id → usage-error，不落盘', async () => {
+    const root = createProjectFixture({ name: 'pack-proposal-test' });
+
+    const result = await constraintsPackProposal('ghost_constraint', { projectPath: root }, io);
+
+    expect(result.kind).toBe('usage-error');
+    expect(result.kind === 'usage-error' && result.reason).toContain('ghost_constraint');
+    expect(io.errText()).toContain('未知约束 id');
+    expect(fs.existsSync(path.join(root, '.harness', 'reports'))).toBe(false);
+  });
+
+  it('缺 id → usage-error', async () => {
+    const result = await constraintsPackProposal(undefined, { projectPath: '/nonexistent' }, io);
+    expect(result.kind).toBe('usage-error');
+  });
+
+  it('无 trace 时统计为零计数且不报错', async () => {
+    const root = createProjectFixture({ name: 'pack-proposal-test' });
+
+    await constraintsPackProposal('docs_freshness', { projectPath: root, stdout: true, now: NOW }, io);
+
+    const out = io.outText();
+    expect(out).toContain('- total: 0');
+    expect(out).toContain('（无记录）');
+  });
+});

package/src/cli/commands/__tests__/constraints-reactivate.test.ts

@@ -0,0 +1,210 @@
+/**
+ * harness constraints reactivate 测试（ADR-0032 决策 6.5，票 02 断点 5）
+ *
+ * 执行逻辑（reactivateConstraint，纯函数化）：墓碑段删除、复活沉淀条目、
+ * not_retired / unknown_id 保护、旧 retired 沉淀不改历史。
+ * CLI 直达（constraintsReactivate）：--yes 人确认闸门。
+ *
+ * 使用真实临时目录。
+ */
+
+import * as fs from 'fs';
+import { captureIO, type CapturingIO } from '../../command-contract';
+import * as os from 'os';
+import * as path from 'path';
+import * as yaml from 'js-yaml';
+import { getEffectiveConstraints } from '../../../core/effective-constraints';
+import { FileKnowledgeStore } from '../../../knowledge/store';
+import { retireConstraint } from '../constraints-retire';
+import { reactivateConstraint, constraintsReactivate, printReactivateResult } from '../constraints-reactivate';
+import { createProjectFixture, writeProjectConfig } from '../../../test-setup/project-fixture';
+
+const FIXED_NOW = new Date('2026-08-08T12:00:00.000Z');
+const REACTIVATE_NOW = new Date('2026-09-01T08:00:00.000Z');
+
+function readConfig(root: string): any {
+  return yaml.load(fs.readFileSync(path.join(root, '.harness', 'config.yml'), 'utf-8'));
+}
+
+let io: CapturingIO;
+beforeEach(() => {
+  io = captureIO();
+  // 复活沉淀写口与 retire 同一解析点：不隔离会写进真实用户主目录
+  process.env.KNOWLEDGE_BASE_DIR = fs.mkdtempSync(path.join(os.tmpdir(), 'harness-reactivate-kb-'));
+});
+afterEach(() => {
+  fs.rmSync(process.env.KNOWLEDGE_BASE_DIR!, { recursive: true, force: true });
+  delete process.env.KNOWLEDGE_BASE_DIR;
+});
+
+describe('reactivateConstraint 执行逻辑', () => {
+  it('复活落盘：config.yml 墓碑段删除，约束回到生效集', () => {
+    const root = createProjectFixture({ name: 'harness-reactivate-test' });
+    retireConstraint(root, 'capability_sync', { reason: '先退', now: FIXED_NOW });
+    expect(getEffectiveConstraints(root).some(c => c.id === 'capability_sync')).toBe(false);
+
+    const result = reactivateConstraint(root, 'capability_sync', { reason: '误退', now: REACTIVATE_NOW });
+
+    expect(result.status).toBe('reactivated');
+    const config = readConfig(root);
+    expect(config.constraints?.capability_sync).toBeUndefined();
+    expect(getEffectiveConstraints(root).some(c => c.id === 'capability_sync')).toBe(true);
+  });
+
+  it('KnowledgeStore 写复活条目：引用原 retired 条目 + 复活原因 + signal 模式；旧沉淀不改历史', () => {
+    const root = createProjectFixture({ name: 'harness-reactivate-test' });
+    retireConstraint(root, 'capability_sync', { reason: '先退', now: FIXED_NOW });
+
+    const result = reactivateConstraint(root, 'capability_sync', { reason: '模型能力回退，仍需兜底', now: REACTIVATE_NOW });
+
+    expect(result.status).toBe('reactivated');
+    expect(result.knowledgeEntryId).toBe('constraint-reactivated-capability_sync');
+    expect(result.knowledgeBaseDir).toBe(process.env.KNOWLEDGE_BASE_DIR);
+
+    const store = new FileKnowledgeStore({ baseDir: process.env.KNOWLEDGE_BASE_DIR! });
+    const entry = store.get('constraint-reactivated-capability_sync');
+    expect(entry).toBeDefined();
+    expect(entry!.consumptionMode).toBe('signal');
+    expect(entry!.origin).toBe('human');
+    expect(entry!.tags).toContain('constraint-reactivated');
+    expect(entry!.tags).toContain('constraint:capability_sync');
+    expect(entry!.content).toContain('constraint-retired-capability_sync');
+    expect(entry!.content).toContain('模型能力回退，仍需兜底');
+    expect(entry!.content).toContain(REACTIVATE_NOW.toISOString());
+
+    // 不改历史：旧 retired 沉淀原样保留（原因仍是"先退"）
+    const retired = store.get('constraint-retired-capability_sync');
+    expect(retired).toBeDefined();
+    expect(retired!.content).toContain('先退');
+  });
+
+  it('裸 disable（enabled:false 无 retired 墓碑）：not_retired，不落盘不吞配置', () => {
+    const root = createProjectFixture({
+      name: 'harness-reactivate-test',
+      config: 'constraints:\n  capability_sync:\n    enabled: false\n',
+    });
+
+    const result = reactivateConstraint(root, 'capability_sync', { now: REACTIVATE_NOW });
+
+    expect(result.status).toBe('not_retired');
+    // 配置原样保留（裸 disable 的处置权在用户，reactivate 不代为"清理"）
+    expect(readConfig(root).constraints.capability_sync.enabled).toBe(false);
+    const store = new FileKnowledgeStore({ baseDir: process.env.KNOWLEDGE_BASE_DIR! });
+    expect(store.get('constraint-reactivated-capability_sync')).toBeUndefined();
+  });
+
+  it('从未配置的约束：not_retired，不落盘任何文件', () => {
+    const root = createProjectFixture({ name: 'harness-reactivate-test' });
+
+    const result = reactivateConstraint(root, 'capability_sync', { now: REACTIVATE_NOW });
+
+    expect(result.status).toBe('not_retired');
+    expect(fs.existsSync(path.join(root, '.harness'))).toBe(false);
+  });
+
+  it('未知 id：unknown_id，不落盘任何文件', () => {
+    const root = createProjectFixture({ name: 'harness-reactivate-test' });
+    const result = reactivateConstraint(root, 'not_a_constraint', { now: REACTIVATE_NOW });
+    expect(result.status).toBe('unknown_id');
+    expect(fs.existsSync(path.join(root, '.harness'))).toBe(false);
+  });
+
+  it('复活结果打印：git 仓内附 commit 提示，非 git 目录不提示（票 02 断点 4）', () => {
+    const gitRoot = createProjectFixture({ name: 'harness-reactivate-test', files: { '.git/HEAD': 'ref: refs/heads/master\n' } });
+    retireConstraint(gitRoot, 'capability_sync', { now: FIXED_NOW });
+    const inGit = reactivateConstraint(gitRoot, 'capability_sync', { now: REACTIVATE_NOW });
+    printReactivateResult(inGit, io, gitRoot);
+    expect(io.outText()).toContain('git add .harness/config.yml');
+
+    const plainRoot = createProjectFixture({ name: 'harness-reactivate-test' });
+    retireConstraint(plainRoot, 'capability_sync', { now: FIXED_NOW });
+    const plainIo = captureIO();
+    const notInGit = reactivateConstraint(plainRoot, 'capability_sync', { now: REACTIVATE_NOW });
+    printReactivateResult(notInGit, plainIo, plainRoot);
+    expect(plainIo.outText()).not.toContain('git add');
+  });
+});
+
+describe('constraintsReactivate 非交互直达', () => {
+  it('无 --yes 直达：报错 + 非零退出码 + 不落盘任何文件（人确认闸门）', async () => {
+    const root = createProjectFixture({ name: 'harness-reactivate-test' });
+    retireConstraint(root, 'capability_sync', { now: FIXED_NOW });
+
+    const result = await constraintsReactivate('capability_sync', { projectPath: root, reason: '误退' }, io);
+
+    expect(io.errText()).toContain('--yes');
+    expect(result.kind).toBe('usage-error');
+    // 墓碑原样在，复活条目未写
+    expect(readConfig(root).constraints.capability_sync.retired).toBeDefined();
+    const store = new FileKnowledgeStore({ baseDir: process.env.KNOWLEDGE_BASE_DIR! });
+    expect(store.get('constraint-reactivated-capability_sync')).toBeUndefined();
+  });
+
+  it('--yes 直达复活：落盘并打印结果', async () => {
+    const root = createProjectFixture({ name: 'harness-reactivate-test' });
+    retireConstraint(root, 'capability_sync', { reason: '先退', now: FIXED_NOW });
+
+    const result = await constraintsReactivate('capability_sync', { projectPath: root, reason: '误退', yes: true }, io);
+
+    expect(result.kind).toBe('ok');
+    expect(io.outText()).toContain('已复活');
+    expect(readConfig(root).constraints?.capability_sync).toBeUndefined();
+  });
+
+  it('--yes 直达无墓碑：明确提示 not_retired 语义', async () => {
+    const root = createProjectFixture({ name: 'harness-reactivate-test' });
+    writeProjectConfig(root, 'constraints:\n  capability_sync:\n    enabled: false\n');
+
+    const result = await constraintsReactivate('capability_sync', { projectPath: root, yes: true }, io);
+
+    expect(result.kind).toBe('skip');
+    expect(io.outText()).toContain('无 retired 墓碑');
+  });
+
+  it('缺 id：usage-error 提示用法', async () => {
+    const result = await constraintsReactivate(undefined, { yes: true }, io);
+    expect(result.kind).toBe('usage-error');
+    expect(io.errText()).toContain('用法');
+  });
+});
+
+describe('应用层约束复活（ADR-0033 块 3 子项 3）', () => {
+  const APP_YML = [
+    'constraints:',
+    '  - id: app_no_internal_url',
+    '    rule: Web code must not contain internal URLs',
+    '    checker: regex-scan',
+    '    params:',
+    "      pattern: 'https?://10\\.'",
+    '    severity: warning',
+    '',
+  ].join('\n');
+
+  function appFixture(): string {
+    return createProjectFixture({
+      name: 'harness-reactivate-test',
+      files: { [path.join('.harness', 'constraints.yml')]: APP_YML },
+    });
+  }
+
+  it('退休后可复活：删 config.yml 墓碑，约束回生效集（constraints.yml 条文一直在）', () => {
+    const root = appFixture();
+    retireConstraint(root, 'app_no_internal_url', { reason: '先退', now: FIXED_NOW });
+    expect(getEffectiveConstraints(root).some(c => c.id === 'app_no_internal_url')).toBe(false);
+
+    const result = reactivateConstraint(root, 'app_no_internal_url', { reason: '误退', now: REACTIVATE_NOW });
+
+    expect(result.status).toBe('reactivated');
+    expect(readConfig(root).constraints?.app_no_internal_url).toBeUndefined();
+    expect(getEffectiveConstraints(root).some(c => c.id === 'app_no_internal_url')).toBe(true);
+    // 复活沉淀照写
+    const store = new FileKnowledgeStore({ baseDir: process.env.KNOWLEDGE_BASE_DIR! });
+    expect(store.get('constraint-reactivated-app_no_internal_url')).toBeDefined();
+  });
+
+  it('应用层未退休（无墓碑）→ not_retired', () => {
+    const root = appFixture();
+    const result = reactivateConstraint(root, 'app_no_internal_url', { now: REACTIVATE_NOW });
+    expect(result.status).toBe('not_retired');
+  });
+});

package/src/cli/commands/__tests__/constraints-report-json-flag.test.ts

@@ -0,0 +1,101 @@
+/**
+ * constraints report --json-output 测试（E1 复盘修正 M3.1）
+ *
+ * 复现的 bug：父命令 constraints 与子命令 report 同名 --json 相撞
+ * （definitions.ts 两处注册），commander 把 flag 消费在父命令上，
+ * report 的 JSON 分支（constraints-report.ts）不可达——
+ * `constraints report --json` 输出的仍是文本格式。
+ *
+ * 修法（计划允许二选一）：子命令换名 --json-output。
+ * 理由：父命令 --json 有活跃消费者（studio-agent 取约束 hash），
+ * 删除会静默降级其取数；子命令 --json 因本 bug 从未可达、零消费者，
+ * 换名零破坏。
+ *
+ * 两层证据：
+ * 1. 定义表不变式（无 dist 依赖）：父子命令不得注册同名 option flag
+ *    （commander 会把子命令位置的同名 flag 消费在父命令上）；
+ * 2. 端到端 spawn bin/harness.js（dist 存在时）：--json-output 真实到达
+ *    report 的 JSON 分支，父命令 --json 行为不变。
+ */
+
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { spawnSync } from 'child_process';
+import { COMMAND_DEFINITIONS } from '../definitions';
+import { GATE_DEFINITIONS } from '../../../gates/definitions';
+
+/** 从 flags 串提取长选项名：'-p, --project-path <path>' → '--project-path' */
+function longFlags(flags: string): string[] {
+  return [...flags.matchAll(/--[a-z][a-z-]*/g)].map(m => m[0]);
+}
+
+describe('定义表不变式：父子命令不得注册同名 option flag', () => {
+  const defs = [
+    ...COMMAND_DEFINITIONS,
+    ...GATE_DEFINITIONS.filter(g => g.cli).map(g => g.cli!),
+  ];
+
+  it('constraints report 与父命令无同名 flag（M3.1 复现场景）', () => {
+    const constraints = defs.find(d => d.command === 'constraints')!;
+    const parentFlags = new Set((constraints.options ?? []).flatMap(o => longFlags(o.flags)));
+    for (const child of constraints.children ?? []) {
+      const childFlags = (child.options ?? []).flatMap(o => longFlags(o.flags));
+      const collisions = childFlags.filter(f => parentFlags.has(f));
+      expect(collisions).toEqual([]);
+    }
+  });
+
+  it('全表泛化：任何带 children 的命令都与子命令 flag 不相交', () => {
+    for (const def of defs) {
+      if (!def.children || def.children.length === 0) continue;
+      const parentFlags = new Set((def.options ?? []).flatMap(o => longFlags(o.flags)));
+      for (const child of def.children) {
+        const childFlags = (child.options ?? []).flatMap(o => longFlags(o.flags));
+        const collisions = childFlags.filter(f => parentFlags.has(f));
+        expect(collisions).toEqual([]);
+      }
+    }
+  });
+});
+
+// dist 缺失时显式失败而非静默 skip（同 bin-exit-mapping.test.ts 口径，harness#99）
+const repoRoot = path.join(__dirname, '..', '..', '..', '..');
+const distBin = path.join(repoRoot, 'bin', 'harness.js');
+const hasDist = fs.existsSync(path.join(repoRoot, 'dist', 'cli', 'commands'));
+
+if (!hasDist && process.env.CI) {
+  throw new Error('dist 未构建：bin 端到端 smoke 不得静默 skip —— CI 必须先 npm run build 再 npm test（harness#99）');
+}
+
+const smoke = hasDist ? describe : describe.skip;
+
+smoke('端到端：constraints report --json-output 到达 JSON 分支', () => {
+  const run = (argv: string[], cwd: string) => spawnSync(process.execPath, [distBin, ...argv], {
+    cwd,
+    encoding: 'utf-8',
+    timeout: 60000,
+  });
+
+  it('report --json-output → stdout 是报告 JSON（含 stats），退出码 0', () => {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'harness-m31-'));
+    try {
+      const r = run(['constraints', 'report', '--json-output'], dir);
+      expect(r.status).toBe(0);
+      const report = JSON.parse(r.stdout);
+      expect(Array.isArray(report.stats)).toBe(true);
+      expect(report.stats.length).toBeGreaterThan(0);
+      expect(Array.isArray(report.candidates)).toBe(true);
+    } finally {
+      fs.rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  it('父命令 constraints --json 行为不变（活跃消费者面）', () => {
+    const r = run(['constraints', '--json'], repoRoot);
+    expect(r.status).toBe(0);
+    const meta = JSON.parse(r.stdout);
+    expect(typeof meta.hash).toBe('string');
+    expect(meta.counts).toBeDefined();
+  });
+});