@dommaker/harness 1.11.0 → 1.12.0

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.test.ts

@@ -15,7 +15,9 @@ import {
   buildConstraintsUsageReport,
   diagnoseRetireCandidates,
   readProjectTraces,
+  WATCHLIST_PERIOD_DAYS,
 } from '../../../core/constraints/usage-report';
+import type { HarnessState, StateIO } from '../../state-io';
 import { constraintsReport, renderExportMarkdown } from '../constraints-report';
 import { createProjectFixture, writeProjectTraces } from '../../../test-setup/project-fixture';
 
@@ -126,13 +128,13 @@ describe('buildConstraintsUsageReport', () => {
     expect(noiseC?.kind).toBe('high_noise');
     expect(noiseC?.reason).toContain('83%');
 
-    // 零拦截
-    const zeroC = byId.get('no_hardcoded_credentials');
-    expect(zeroC?.kind).toBe('zero_intercept');
-    expect(zeroC?.reason).toContain('50 次评估');
+    // 零拦截：先进观察名单（ADR-0032 中间态），不直接进退役候选
+    expect(byId.get('no_hardcoded_credentials')).toBeUndefined();
+    const watched = report.watchlist.find(w => w.id === 'no_hardcoded_credentials');
+    expect(watched?.reason).toContain('50 次评估');
   });
 
-  it('阈值可配：放宽零拦截样本阈值后 10 次全 pass 也成为候选', () => {
+  it('阈值可配：放宽零拦截样本阈值后 10 次全 pass 进观察名单（不直接进候选）', () => {
     const root = createProjectFixture({
       name: 'harness-report-test',
       traces: tracesOf('no_hardcoded_credentials', 'pass', 10),
@@ -140,9 +142,11 @@ describe('buildConstraintsUsageReport', () => {
 
     const strict = buildConstraintsUsageReport(root);
     expect(strict.candidates.find(c => c.id === 'no_hardcoded_credentials')).toBeUndefined();
+    expect(strict.watchlist.find(w => w.id === 'no_hardcoded_credentials')).toBeUndefined();
 
     const relaxed = buildConstraintsUsageReport(root, { zeroInterceptMinEvaluated: 10 });
-    expect(relaxed.candidates.find(c => c.id === 'no_hardcoded_credentials')?.kind).toBe('zero_intercept');
+    expect(relaxed.candidates.find(c => c.id === 'no_hardcoded_credentials')).toBeUndefined();
+    expect(relaxed.watchlist.find(w => w.id === 'no_hardcoded_credentials')).toBeDefined();
   });
 
   it('diagnoseRetireCandidates 优先级：全 skip 不重复计入零拦截', () => {
@@ -286,3 +290,168 @@ describe('constraintsReport 坏行数透传（harness#100）', () => {
     expect(fs.readFileSync(path.join(clean, 'report.md'), 'utf-8')).not.toContain('损坏');
   });
 });
+
+describe('零拦截观察名单（ADR-0032，块 3 子项 4）', () => {
+  const DAY_MS = 24 * 60 * 60 * 1000;
+  // 固定时钟：观察期判定全靠注入 now，不在测试里等 90 天
+  const NOW = 1700100000000;
+  const NOW_ISO = new Date(NOW).toISOString();
+
+  /** 内存 StateIO 假件（与 status/check 测试同形） */
+  function memoryStateIO(initial: HarnessState = {}): StateIO & { snapshot(): HarnessState } {
+    let state = initial;
+    return {
+      read: () => state,
+      write: (s: HarnessState) => { state = s; },
+      snapshot: () => state,
+    };
+  }
+
+  /** 50 次全 pass 的零拦截 fixture 项目 */
+  function zeroInterceptProject(id = 'no_hardcoded_credentials', n = 50): string {
+    return createProjectFixture({
+      name: 'harness-watchlist-test',
+      traces: tracesOf(id, 'pass', n, NOW - 10 * DAY_MS),
+    });
+  }
+
+  it('命中且不在名单：列入观察名单（记列入时间），进 watchlist 分组不进退役候选', () => {
+    const root = zeroInterceptProject();
+    const report = buildConstraintsUsageReport(root, {}, { now: NOW });
+
+    expect(report.candidates.some(c => c.id === 'no_hardcoded_credentials')).toBe(false);
+    const w = report.watchlist.find(x => x.id === 'no_hardcoded_credentials');
+    expect(w).toBeDefined();
+    expect(w!.listedAt).toBe(NOW_ISO);
+    expect(w!.remainingDays).toBe(WATCHLIST_PERIOD_DAYS);
+    expect(w!.reason).toContain('50 次评估');
+    // 待写回状态只增不删
+    expect(report.nextWatchlist['no_hardcoded_credentials']).toEqual({ listedAt: NOW_ISO });
+  });
+
+  it('观察期未满：仍留名单不转候选，剩余观察期按天折算', () => {
+    const root = zeroInterceptProject();
+    const listedAt = new Date(NOW - 30 * DAY_MS).toISOString();
+    const report = buildConstraintsUsageReport(root, {}, {
+      watchlist: { no_hardcoded_credentials: { listedAt } },
+      now: NOW,
+    });
+
+    expect(report.candidates.some(c => c.id === 'no_hardcoded_credentials')).toBe(false);
+    const w = report.watchlist.find(x => x.id === 'no_hardcoded_credentials');
+    expect(w!.listedAt).toBe(listedAt);
+    expect(w!.remainingDays).toBe(WATCHLIST_PERIOD_DAYS - 30);
+    // 已列入不重复写
+    expect(report.nextWatchlist).toEqual({ no_hardcoded_credentials: { listedAt } });
+  });
+
+  it('期满且样本够：转正式 zero_intercept 退役候选', () => {
+    const root = zeroInterceptProject();
+    const listedAt = new Date(NOW - WATCHLIST_PERIOD_DAYS * DAY_MS).toISOString();
+    const report = buildConstraintsUsageReport(root, {}, {
+      watchlist: { no_hardcoded_credentials: { listedAt } },
+      now: NOW,
+    });
+
+    const c = report.candidates.find(x => x.id === 'no_hardcoded_credentials');
+    expect(c?.kind).toBe('zero_intercept');
+    expect(c?.reason).toContain('观察期满');
+    expect(report.watchlist.some(w => w.id === 'no_hardcoded_credentials')).toBe(false);
+  });
+
+  it('期满但样本不够（评估数跌破阈值）：不转候选', () => {
+    const root = zeroInterceptProject('no_hardcoded_credentials', 30);
+    const listedAt = new Date(NOW - 120 * DAY_MS).toISOString();
+    const report = buildConstraintsUsageReport(root, {}, {
+      watchlist: { no_hardcoded_credentials: { listedAt } },
+      now: NOW,
+    });
+
+    expect(report.candidates.some(c => c.id === 'no_hardcoded_credentials')).toBe(false);
+  });
+
+  it('其他三类候选不进观察名单（zero_trigger/unevaluable/high_noise 维持现状）', () => {
+    const root = createProjectFixture({ name: 'harness-watchlist-test' });
+    writeProjectTraces(root, [
+      ...tracesOf('capability_sync', 'skip', 5),                    // 不可评估
+      ...tracesOf('no_test_simplification', 'fail', 20),            // 高噪
+      ...tracesOf('no_test_simplification', 'pass', 4, 1700001000000),
+      // docs_freshness 等零触发
+    ]);
+    const report = buildConstraintsUsageReport(root, {}, { now: NOW });
+
+    expect(report.candidates.length).toBeGreaterThan(0);
+    expect(report.watchlist).toEqual([]);
+    expect(report.nextWatchlist).toEqual({});
+  });
+
+  it('diagnoseRetireCandidates 兼容签名：只回候选，观察期内的零拦截不出现', () => {
+    const stats = [{
+      id: 'x', severity: 'warning' as const,
+      total: 50, pass: 50, fail: 0, skip: 0,
+      evaluated: 50, failRate: 0,
+    }];
+    expect(diagnoseRetireCandidates(stats)).toEqual([]);
+    const listedAt = new Date(NOW - 100 * DAY_MS).toISOString();
+    const converted = diagnoseRetireCandidates(stats, {}, {
+      watchlist: { x: { listedAt } },
+      now: NOW,
+    });
+    expect(converted.map(c => c.kind)).toEqual(['zero_intercept']);
+  });
+
+  it('列入时间损坏按未列入处理：重新列入、时钟重启', () => {
+    const root = zeroInterceptProject();
+    const report = buildConstraintsUsageReport(root, {}, {
+      watchlist: { no_hardcoded_credentials: { listedAt: 'not-a-date' } },
+      now: NOW,
+    });
+
+    expect(report.candidates.some(c => c.id === 'no_hardcoded_credentials')).toBe(false);
+    expect(report.nextWatchlist['no_hardcoded_credentials']).toEqual({ listedAt: NOW_ISO });
+  });
+
+  it('CLI 级：report 经 StateIO 持久化列入，第二次运行读回仍在名单', async () => {
+    const root = zeroInterceptProject();
+    const stateIO = memoryStateIO();
+
+    await constraintsReport({ projectPath: root, stateIO, now: NOW }, io);
+    expect(stateIO.snapshot().constraintWatchlist?.['no_hardcoded_credentials']).toEqual({ listedAt: NOW_ISO });
+    expect(io.outText()).toContain('观察名单');
+    expect(io.outText()).toContain('no_hardcoded_credentials');
+
+    // 第二次：名单状态经注入面读回，不重复写、不进候选
+    const io2 = captureIO();
+    await constraintsReport({ projectPath: root, stateIO, now: NOW + 10 * DAY_MS }, io2);
+    expect(io2.outText()).toContain('剩余观察 80 天');
+    expect(io2.outText()).not.toContain('[零拦截] no_hardcoded_credentials');
+
+    // 期满：同一条转退役候选
+    const io3 = captureIO();
+    await constraintsReport({ projectPath: root, stateIO, now: NOW + WATCHLIST_PERIOD_DAYS * DAY_MS }, io3);
+    expect(io3.outText()).toContain('[零拦截] no_hardcoded_credentials');
+  });
+
+  it('StateIO 写回不动其他状态字段（读-改-写）', async () => {
+    const root = zeroInterceptProject();
+    const stateIO = memoryStateIO({ shownHints: ['trace_50'], lastStatusRun: '2026-09-01T00:00:00.000Z' });
+
+    await constraintsReport({ projectPath: root, stateIO, now: NOW }, captureIO());
+
+    const s = stateIO.snapshot();
+    expect(s.shownHints).toEqual(['trace_50']);
+    expect(s.lastStatusRun).toBe('2026-09-01T00:00:00.000Z');
+    expect(Object.keys(s.constraintWatchlist ?? {})).toEqual(['no_hardcoded_credentials']);
+  });
+
+  it('--export 脱敏摘要带观察名单分组（列入时间 + 剩余观察期）', async () => {
+    const root = zeroInterceptProject();
+    await constraintsReport({ projectPath: root, export: 'report.md', now: NOW }, captureIO());
+
+    const md = fs.readFileSync(path.join(root, 'report.md'), 'utf-8');
+    expect(md).toContain('## 观察名单');
+    expect(md).toContain('no_hardcoded_credentials');
+    expect(md).toContain(`剩余观察 ${WATCHLIST_PERIOD_DAYS} 天`);
+    expect(md).not.toContain(root);
+  });
+});