@dommaker/harness 1.10.0 → 1.12.0

package/src/core/constraints/checkers/index.ts

@@ -1,13 +1,19 @@
 /**
- * 约束检查器注册表（工单 21）
+ * 约束检查器注册表（工单 21；ADR-0033 拆两层）
  *
- * checker.ts 编排层通过 getConstraintCheck(id) 查找实现。
+ * checker.ts 编排层通过 getConstraintCheck() 查找实现。
  *
- * 注册表闭环（ADR-0001）：模块加载时校验全部 kind='check' 的内置约束
- * 都有已注册 checker，且注册表中没有无对应 check 定义的孤儿实现；
- * 任一不满足即抛错（加载期失败，不许静默 pass）。
+ * 两层注册表：
+ * - 内置 checker（registry，按约束 id）：模块加载时校验全部 kind='check' 的内置约束
+ *   都有已注册 checker，且注册表中没有无对应 check 定义的孤儿实现；
+ *   任一不满足即抛错（加载期失败，不许静默 pass，ADR-0001）。
+ * - 模板 checker（TEMPLATES，按模板 id）：填空式参数化模板，供应用层约束
+ *   （source='app'，`.harness/constraints.yml`）按 checker + params 实例化。
+ *   闭环语义扩展而非开口：应用层约束在加载期（app-constraints-loader）校验
+ *   模板 id 存在 + validateParams 通过；getConstraintCheck 对未注册模板 id 抛错。
  */
 
+import type { Constraint } from '../../../types/constraint';
 import type { ConstraintCheck } from './types';
 import { getAllConstraints } from '../definitions';
 
@@ -20,14 +26,15 @@ import { contextDocSync } from './context-doc-sync';
 import { docsFreshness } from './docs-freshness';
 import { noHardcodedCredentials } from './no-hardcoded-credentials';
 import { governancePresence } from './governance-presence';
+import { TEMPLATES } from './templates-registry';
 
 const CHECKS: ConstraintCheck[] = [
   // severity='error'
   noCompletionWithoutVerification,
   noTestSimplification,
   docsFreshness,
-  // severity='warning'
   noHardcodedCredentials,
+  // severity='warning'
   capabilitySync,
   contextDocSync,
   governancePresence,
@@ -35,6 +42,14 @@ const CHECKS: ConstraintCheck[] = [
 
 const registry = new Map<string, ConstraintCheck>(CHECKS.map(c => [c.id, c]));
 
+// ========================================
+// 模板注册表（ADR-0033，应用层约束用）
+// ========================================
+
+// TEMPLATES 住在 ./templates-registry（独立模块防值级循环，见该文件头注释）；
+// 此处 re-export 供编排层与测试单口取数
+export { TEMPLATES } from './templates-registry';
+
 // ========================================
 // 注册表闭环校验（加载期）
 // ========================================
@@ -60,11 +75,29 @@ for (const id of registry.keys()) {
 }
 
 /**
- * 按约束 ID 查找检查实现；未注册返回 undefined
- * （编排层对 kind='check' 未注册的情况抛错）
+ * 查找检查实现
+ *
+ * - 传字符串 id 或内置约束：按 id 查内置注册表，未注册返回 undefined
+ *   （编排层对 kind='check' 未注册的情况抛错）
+ * - 传 source='app' 的约束：按 checker 模板 id + params 实例化；
+ *   模板 id 未注册 → 抛错（闭环保留，不许静默 pass）
  */
-export function getConstraintCheck(id: string): ConstraintCheck | undefined {
-  return registry.get(id);
+export function getConstraintCheck(idOrConstraint: string | Constraint): ConstraintCheck | undefined {
+  if (typeof idOrConstraint === 'string') {
+    return registry.get(idOrConstraint);
+  }
+  if (idOrConstraint.source === 'app') {
+    const templateId = idOrConstraint.checker;
+    const factory = templateId ? TEMPLATES.get(templateId) : undefined;
+    if (!factory) {
+      throw new Error(
+        `[harness] 约束注册表闭环校验失败：应用层约束 "${idOrConstraint.id}" 引用的 checker 模板 ` +
+        `"${templateId ?? '（未填写）'}" 未注册。请在 checkers/templated/ 中实现并注册。`
+      );
+    }
+    return factory.create(idOrConstraint.id, idOrConstraint.params ?? {});
+  }
+  return registry.get(idOrConstraint.id);
 }
 
 /**
@@ -77,6 +110,7 @@ export function registeredCheckCount(): number {
 export { buildCheckEnv, normalizeCheckOutcome } from './types';
 export type {
   ConstraintCheck,
+  TemplatedCheckerFactory,
   CheckEnv,
   CheckOutcome,
   CheckDetail,

package/src/core/constraints/checkers/templated/file-exists.ts

@@ -0,0 +1,75 @@
+/**
+ * file-exists 模板：文件存在性约束（ADR-0033，块 3 子项 2）
+ *
+ * 形态参照 context-doc-sync：存在性判定 + 证据行（fail 必须可归因，harness#119）。
+ * 与 context-doc-sync 的差别：目标由参数显式给出（加载期已校验），
+ * 无「约定未采用」三态，故永不 skip。
+ *
+ * 参数：
+ * - path（可选）：相对项目根的单文件路径
+ * - glob（可选）：文件集 glob（fast-glob 口径，dot: true 以覆盖 .harness 等点目录）
+ * - mustExist（可选，缺省 true）：true = 必须存在；false = 必须不存在
+ * path 与 glob 至少填一个；都填 = 两者都要满足。
+ */
+
+import { existsSync } from 'fs';
+import { join } from 'path';
+import * as glob from 'fast-glob';
+import { formatEvidence, type ConstraintCheck, type TemplatedCheckerFactory } from '../types';
+
+export const fileExists: TemplatedCheckerFactory = {
+  validateParams(params) {
+    const errors: string[] = [];
+    if (params.path !== undefined && typeof params.path !== 'string') {
+      errors.push('path 必须是字符串');
+    }
+    if (params.glob !== undefined && typeof params.glob !== 'string') {
+      errors.push('glob 必须是字符串');
+    }
+    const hasPath = typeof params.path === 'string' && params.path.length > 0;
+    const hasGlob = typeof params.glob === 'string' && params.glob.length > 0;
+    if (!hasPath && !hasGlob) {
+      errors.push('path 或 glob 至少填一个');
+    }
+    if (params.mustExist !== undefined && typeof params.mustExist !== 'boolean') {
+      errors.push('mustExist 必须是布尔值');
+    }
+    return errors;
+  },
+
+  create(id, params): ConstraintCheck {
+    const rel = params.path as string | undefined;
+    const globPattern = params.glob as string | undefined;
+    const mustExist = params.mustExist !== false;
+
+    return {
+      id,
+      evaluate(env) {
+        const pathHit = rel !== undefined && existsSync(join(env.projectPath, rel));
+        const globHits = globPattern !== undefined
+          ? glob.sync(globPattern, { cwd: env.projectPath, dot: true, onlyFiles: false })
+          : [];
+
+        if (mustExist) {
+          const missing: string[] = [];
+          if (rel !== undefined && !pathHit) missing.push(rel);
+          if (globPattern !== undefined && globHits.length === 0) missing.push(`${globPattern}（无匹配文件）`);
+          if (missing.length > 0) {
+            return { pass: false, evidence: formatEvidence('必需文件不存在', missing) };
+          }
+          return true;
+        }
+
+        // mustExist=false：任何目标存在即违规
+        const present: string[] = [
+          ...(pathHit ? [rel!] : []),
+          ...globHits,
+        ];
+        if (present.length > 0) {
+          return { pass: false, evidence: formatEvidence('禁存文件存在', present) };
+        }
+        return true;
+      },
+    };
+  },
+};

package/src/core/constraints/checkers/templated/glob.ts

@@ -0,0 +1,46 @@
+/**
+ * 模板侧轻量 glob 匹配（支持 `**`、`*`、`?`，纯字符串判定，不碰文件系统）
+ *
+ * 与 completion-checkers/glob-match 同一匹配语义；此处另写一份是因为分层
+ * （harness#88 参数化守卫）不许 core 值导入同层领域模块——约束域的模板
+ * 参数匹配不住 completion-checkers 的 commits 分类模块。
+ */
+
+function escapeRegExp(s: string): string {
+  return s.replace(/[.+^${}()|[\]\\]/g, '\\$&');
+}
+
+/** glob → 锚定正则。前缀 `**` + `/` 匹配零或多段路径；`*` 不跨 `/`；`?` 匹配单个非 `/` 字符 */
+function globToRegExp(glob: string): RegExp {
+  let re = '';
+  let i = 0;
+  while (i < glob.length) {
+    const c = glob[i];
+    if (c === '*') {
+      if (glob[i + 1] === '*') {
+        if (glob[i + 2] === '/') {
+          re += '(?:[^/]+/)*';
+          i += 3;
+        } else {
+          re += '.*';
+          i += 2;
+        }
+      } else {
+        re += '[^/]*';
+        i += 1;
+      }
+    } else if (c === '?') {
+      re += '[^/]';
+      i += 1;
+    } else {
+      re += escapeRegExp(c);
+      i += 1;
+    }
+  }
+  return new RegExp('^' + re + '$');
+}
+
+/** 单 glob 匹配（相对路径正斜杠口径） */
+export function matchGlob(file: string, glob: string): boolean {
+  return globToRegExp(glob).test(file);
+}

package/src/core/constraints/checkers/templated/index.ts

@@ -0,0 +1,12 @@
+/**
+ * 填空式 checker 模板（ADR-0033 两层约束模型，块 3 子项 2）
+ *
+ * 每个模板 = TemplatedCheckerFactory（validateParams + create），注册进
+ * checkers/index.ts 的 TEMPLATES 供应用层约束（`.harness/constraints.yml`）
+ * 按 checker + params 实例化。
+ *
+ * 模板只认参数不认应用语义（harness 零业务逻辑）：约束条文、文案归应用仓。
+ */
+
+export { regexScan } from './regex-scan';
+export { fileExists } from './file-exists';

package/src/core/constraints/checkers/templated/regex-scan.ts

@@ -0,0 +1,132 @@
+/**
+ * regex-scan 模板：正则扫描约束（ADR-0033，块 3 子项 2）
+ *
+ * 形态参照 no-hardcoded-credentials：scope='diff'（缺省）扫 staged diff 新增行，
+ * diff 为空/不可用时退化为变更文件内容扫描；scope='content' 直接扫变更文件内容。
+ * 命中即违规，证据行点名文件与命中行（harness#119：fail 必须可归因）。
+ *
+ * 参数：
+ * - pattern（必填）：正则字符串
+ * - glob（可选）：限定文件集（相对路径，支持 `**`/`*`/`?`）
+ * - scope（可选）：'diff' | 'content'，缺省 'diff'
+ */
+
+import { readFileSync } from 'fs';
+import { join } from 'path';
+import { formatEvidence, type CheckDetail, type CheckEnv, type ConstraintCheck, type TemplatedCheckerFactory } from '../types';
+import { matchGlob } from './glob';
+
+/** 证据行单行长度上限（命中行可能是整行配置/长文本） */
+const MAX_LINE = 120;
+
+interface AddedLine {
+  file: string;
+  line: string;
+}
+
+/** 从 unified diff 中取新增行（按 +++ b/<path> 归属文件，glob 过滤文件集） */
+function collectAddedLines(diff: string, inScope: (file: string) => boolean): AddedLine[] {
+  const out: AddedLine[] = [];
+  let file = '';
+  for (const raw of diff.split('\n')) {
+    if (raw.startsWith('+++ b/')) {
+      file = raw.slice('+++ b/'.length);
+      continue;
+    }
+    if (raw.startsWith('+++') || raw.startsWith('diff --git')) {
+      if (raw.startsWith('diff --git')) file = '';
+      continue;
+    }
+    if (raw.startsWith('+') && file && inScope(file)) {
+      out.push({ file, line: raw.slice(1) });
+    }
+  }
+  return out;
+}
+
+function hitEvidence(pattern: RegExp, hits: string[]): CheckDetail {
+  return {
+    pass: false,
+    evidence: formatEvidence(`命中禁用模式 /${pattern.source}/`, hits),
+  };
+}
+
+function clip(line: string): string {
+  const t = line.trim();
+  return t.length > MAX_LINE ? `${t.slice(0, MAX_LINE)}…` : t;
+}
+
+export const regexScan: TemplatedCheckerFactory = {
+  validateParams(params) {
+    const errors: string[] = [];
+    const pattern = params.pattern;
+    if (typeof pattern !== 'string' || pattern.length === 0) {
+      errors.push('pattern 必填（正则字符串）');
+    } else {
+      try {
+        new RegExp(pattern);
+      } catch (err) {
+        errors.push(`pattern 不是合法正则：${err instanceof Error ? err.message : String(err)}`);
+      }
+    }
+    if (params.glob !== undefined && typeof params.glob !== 'string') {
+      errors.push('glob 必须是字符串');
+    }
+    if (params.scope !== undefined && params.scope !== 'diff' && params.scope !== 'content') {
+      errors.push("scope 必须是 'diff' 或 'content'");
+    }
+    return errors;
+  },
+
+  create(id, params): ConstraintCheck {
+    const pattern = new RegExp(params.pattern as string);
+    const glob = params.glob as string | undefined;
+    const scope = (params.scope as 'diff' | 'content' | undefined) ?? 'diff';
+    const inScope = (file: string) => !glob || matchGlob(file, glob);
+
+    const scanChangedFiles = (env: CheckEnv): string[] => {
+      const hits: string[] = [];
+      for (const file of (env.context.changedFiles ?? []).filter(inScope)) {
+        let content: string;
+        try {
+          content = readFileSync(join(env.projectPath, file), 'utf-8');
+        } catch {
+          continue; // 文件不可读（已删除/二进制）→ 跳过
+        }
+        for (const line of content.split('\n')) {
+          if (pattern.test(line)) hits.push(`${file}: ${clip(line)}`);
+        }
+      }
+      return hits;
+    };
+
+    return {
+      id,
+      async evaluate(env) {
+        if (scope === 'content') {
+          const hits = scanChangedFiles(env);
+          return hits.length > 0 ? hitEvidence(pattern, hits) : true;
+        }
+
+        // scope='diff'：staged diff 新增行；diff 为空/不可用 → 退化变更文件内容扫描
+        let scanned = false;
+        try {
+          const diff = await env.stagedDiff();
+          const added = collectAddedLines(diff, inScope);
+          if (added.length > 0) {
+            scanned = true;
+            const hits = added.filter(a => pattern.test(a.line)).map(a => `${a.file}: ${clip(a.line)}`);
+            if (hits.length > 0) return hitEvidence(pattern, hits);
+          }
+        } catch {
+          // diff 不可用 → 退化为文件内容扫描
+        }
+        if (!scanned) {
+          const hits = scanChangedFiles(env);
+          if (hits.length > 0) return hitEvidence(pattern, hits);
+        }
+        return true;
+      },
+    };
+  },
+};

package/src/core/constraints/checkers/templates-registry.ts

@@ -0,0 +1,22 @@
+/**
+ * 填空式 checker 模板注册表（ADR-0033 两层约束模型）
+ *
+ * 独立成模块而非住在 checkers/index.ts：应用层加载器（core/app-constraints-loader）
+ * 要做加载期模板校验，若直接引 checkers/index.ts 会经 project-config-loader →
+ * 本注册表 → 内置 checker → project-config-loader 形成值级循环（checker 初始化时
+ * 拿到 undefined）。本模块不引内置 checker，无环。
+ *
+ * 闭环语义：模板 id 未注册即不可用——加载期由 app-constraints-loader 校验，
+ * 运行期由 checkers/index.ts 的 getConstraintCheck 抛错兜底。
+ *
+ * 首批模板：regex-scan（正则扫描）/ file-exists（文件存在性），块 3 子项 2。
+ */
+
+import type { TemplatedCheckerFactory } from './types';
+import { regexScan, fileExists } from './templated';
+
+/** 模板注册表（模板 id → 工厂）；测试可注册替身模板，用后须注销 */
+export const TEMPLATES = new Map<string, TemplatedCheckerFactory>([
+  ['regex-scan', regexScan],
+  ['file-exists', fileExists],
+]);

package/src/core/constraints/checkers/types.ts

@@ -148,6 +148,21 @@ export interface ConstraintCheck {
   evaluate(env: CheckEnv): Promise<CheckOutcome> | CheckOutcome;
 }
 
+/**
+ * 填空式 checker 模板工厂（ADR-0033 两层约束模型）
+ *
+ * 每个模板 = validateParams + create：参数坏在加载期早报（validateParams），
+ * create 只在参数已校验后调用。注册点 = checkers/index.ts 的 TEMPLATES。
+ * 类型住在 types.ts（而非 index.ts）是为了模板实现文件只依赖本模块，
+ * 不与注册表形成值级循环导入。
+ */
+export interface TemplatedCheckerFactory {
+  /** 参数校验：返回错误清单，空数组 = 通过（加载期跑，参数坏早报） */
+  validateParams(params: Record<string, unknown>): string[];
+  /** 按约束 id + 已校验参数实例化 checker */
+  create(id: string, params: Record<string, unknown>): ConstraintCheck;
+}
+
 /**
  * 构造纯上下文标志检查（无 I/O 的轻量约束）
  */

package/src/core/constraints/definitions/guidelines.ts

@@ -10,21 +10,6 @@
 import type { Constraint } from '../../../types/constraint';
 
 export const WARNING_CONSTRAINTS: Record<string, Constraint> = {
-  /**
-   * 禁止硬编码凭证
-   * 原因：密码/token/密钥泄露是最严重的安全漏洞，一旦提交到版本控制即不可逆
-   */
-  no_hardcoded_credentials: {
-    id: 'no_hardcoded_credentials',
-    kind: 'check',
-    rule: 'NO HARDCODED PASSWORDS, TOKENS, SECRETS, OR CREDENTIALS IN ANY SOURCE FILE',
-    message: '禁止在代码/文档/配置文件中硬编码密码、token、密钥、API key',
-    severity: 'warning',
-    trigger: ['code_implementation', 'doc_update', 'config_change', 'commit'],
-    enforcement: 'credential-scan',
-    description: `凭证（密码/token/密钥/API key）必须从环境变量或加密配置读取，严禁以明文形式出现在任何源代码文件中。包括但不限于：源码、Markdown 文档、YAML/JSON 配置、脚本文件。模板文件（.example/.sample/.template）允许占位符但不得包含真实值。建议配合 pre-commit hook 做自动扫描。`,
-  },
-
   /**
    * 功能清单同步
    * 例外：内部重构、bug fix

package/src/core/constraints/definitions/iron-laws.ts

@@ -25,6 +25,22 @@ export const ERROR_CONSTRAINTS: Record<string, Constraint> = {
     description: '在声明任何任务完成之前，必须运行新鲜的验证命令（项目声明的测试 + type check），以新鲜输出作为完成证据。验证命令集由项目自行声明，全量验证留给 CI 流程。',
   },
 
+  /**
+   * 禁止硬编码凭证
+   * 原因：密码/token/密钥泄露是最严重的安全漏洞，一旦提交到版本控制即不可逆。
+   * ADR-0032：安全底线类约束，warning 不阻断等于没有——升级为 error（违规即阻断）。
+   */
+  no_hardcoded_credentials: {
+    id: 'no_hardcoded_credentials',
+    kind: 'check',
+    rule: 'NO HARDCODED PASSWORDS, TOKENS, SECRETS, OR CREDENTIALS IN ANY SOURCE FILE',
+    message: '禁止在代码/文档/配置文件中硬编码密码、token、密钥、API key',
+    severity: 'error',
+    trigger: ['code_implementation', 'doc_update', 'config_change', 'commit'],
+    enforcement: 'credential-scan',
+    description: `凭证（密码/token/密钥/API key）必须从环境变量或加密配置读取，严禁以明文形式出现在任何源代码文件中。包括但不限于：源码、Markdown 文档、YAML/JSON 配置、脚本文件。模板文件（.example/.sample/.template）允许占位符但不得包含真实值。建议配合 pre-commit hook 做自动扫描。`,
+  },
+
   /**
    * 禁止简化测试
    * 原因：质量底线，测试困难必须解决

package/src/core/constraints/usage-report.ts

@@ -3,9 +3,11 @@
  *
  * `harness constraints report` 与 `harness constraints retire`（交互模式）共用的
  * 数据层：读取项目 traces.log，与生效集（getEffectiveConstraints）对齐，
- * 产出 check 约束统计表与四类退役候选诊断。
+ * 产出 check 约束统计表、四类退役候选诊断与零拦截观察名单（ADR-0032/0033 块 3 子项 4：
+ * 零拦截先进观察名单挂一个季度，期满且样本足才转正式退役候选）。
  *
- * 只读：不创建目录、不写任何文件。
+ * 只读：不创建目录、不写任何文件。观察名单状态以快照入参进来、以 `nextWatchlist`
+ * 产物出去，持久化（`.harness/.state.json` 经 StateIO 接缝）是 cli 层调用方的职责。
  */
 
 import * as fs from 'fs';
@@ -92,6 +94,52 @@ export const DEFAULT_DIAGNOSE_THRESHOLDS: DiagnoseThresholds = {
   highNoiseMinEvaluated: 20,
 };
 
+/**
+ * 观察名单状态条目（ADR-0032 口径，块 3 子项 4）
+ *
+ * 持久化在 `.harness/.state.json` 的 `constraintWatchlist` 段（StateIO 接缝，
+ * cli 层读-改-写）；本层只认快照，不碰 fs。
+ */
+export interface WatchlistStateEntry {
+  /** 列入观察名单时刻（ISO 串，与 HarnessState 其余时间字段同形） */
+  listedAt: string;
+}
+
+/** 观察名单状态（constraintId → 条目） */
+export type ConstraintWatchlistState = Record<string, WatchlistStateEntry>;
+
+/** 观察期时长（天）：满一个季度且样本仍达标，零拦截才转正式退役候选 */
+export const WATCHLIST_PERIOD_DAYS = 90;
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+
+/**
+ * report 里单独分组展示的观察名单条目
+ *
+ * 列入即进 report（告知面），但不进退役候选；观察期内再次出现 fail / 样本
+ * 跌破阈值时条目自然消失（状态段里的列入记录保留，时钟不回拨）。
+ */
+export interface WatchlistEntry {
+  id: string;
+  stats: ConstraintUsageStats;
+  /** 列入时刻（ISO 串） */
+  listedAt: string;
+  /** 剩余观察天数（观察期未满恒 > 0） */
+  remainingDays: number;
+  /** 人类可读的诊断说明（带证据数字） */
+  reason: string;
+}
+
+/**
+ * 候选诊断的观察名单上下文（不传 = 空名单 + 真实时钟）
+ */
+export interface DiagnoseWatchOptions {
+  /** 观察名单状态快照（来自 `.harness/.state.json`，缺省空） */
+  watchlist?: ConstraintWatchlistState;
+  /** 当前时刻（Unix ms），测试注入用——别在测试里等 90 天 */
+  now?: number;
+}
+
 /**
  * report 数据模型
  */
@@ -100,6 +148,13 @@ export interface ConstraintsUsageReport {
   stats: ConstraintUsageStats[];
   /** 退役候选诊断（按 zero_trigger → unevaluable → high_noise → zero_intercept 排序） */
   candidates: RetireCandidate[];
+  /** 零拦截观察名单（进 report 但不进退役候选；期满且样本足才转候选） */
+  watchlist: WatchlistEntry[];
+  /**
+   * 观察名单读-改-写产物：入参快照 + 本次新列入（只增不删）。
+   * 与入参快照键数不同（有新增）时，调用方应经 StateIO 写回 `.harness/.state.json`。
+   */
+  nextWatchlist: ConstraintWatchlistState;
   /** 配置健康诊断（unknownIds 等） */
   lint: EffectiveConfigLint;
   /** trace 文件是否存在 */
@@ -117,7 +172,7 @@ export interface ConstraintsUsageReport {
  *
  * 坏行策略：skip（原语义不变——report 只读，不因单行损坏失败）；
  * 计数去向：透传——`skippedLines` 随本方法返回，进 `ConstraintsUsageReport.skippedLines`，
- * 消费面为 `constraints report` 的文本行 / `--json` 字段 / `--export` 摘要。
+ * 消费面为 `constraints report` 的文本行 / `--json-output` 字段 / `--export` 摘要。
  */
 export function readProjectTracesReport(projectRoot: string): { traces: ExecutionTrace[]; skippedLines: number } {
   const { records, skippedLines } = readJsonl<ExecutionTrace>(
@@ -176,18 +231,33 @@ function toStats(id: string, severity: Constraint['severity'], agg: { total: num
   };
 }
 
+/** 诊断完整产物（candidates + watchlist + 待写回的状态） */
+interface DiagnoseOutcome {
+  candidates: RetireCandidate[];
+  watchlist: WatchlistEntry[];
+  nextWatchlist: ConstraintWatchlistState;
+}
+
 /**
  * 退役候选诊断（纯函数）
  *
  * 每条约束最多归入一个类别，优先级：
  * zero_trigger → unevaluable → high_noise → zero_intercept
+ *
+ * zero_intercept 走观察名单中间态（ADR-0032）：命中且样本够 → 不在名单则列入
+ * （listedAt = now），进 watchlist 不进 candidates；已在名单且满 WATCHLIST_PERIOD_DAYS
+ * 且当前样本仍达标 → 转正式 zero_intercept 退役候选。其他三类不进观察名单。
  */
-export function diagnoseRetireCandidates(
+function diagnose(
   stats: ConstraintUsageStats[],
-  thresholds: Partial<DiagnoseThresholds> = {}
-): RetireCandidate[] {
-  const t = { ...DEFAULT_DIAGNOSE_THRESHOLDS, ...thresholds };
+  t: DiagnoseThresholds,
+  watch: DiagnoseWatchOptions
+): DiagnoseOutcome {
+  const now = watch.now ?? Date.now();
+  const watchlistState = watch.watchlist ?? {};
+  const nextWatchlist: ConstraintWatchlistState = { ...watchlistState };
   const candidates: RetireCandidate[] = [];
+  const watchlistEntries: WatchlistEntry[] = [];
 
   for (const s of stats) {
     if (s.total === 0) {
@@ -224,24 +294,66 @@ export function diagnoseRetireCandidates(
     }
 
     if (s.fail === 0 && s.evaluated >= t.zeroInterceptMinEvaluated) {
-      candidates.push({
+      const listed = watchlistState[s.id];
+      const listedAtMs = listed ? Date.parse(listed.listedAt) : NaN;
+      // 列入时间损坏按未列入处理：重新列入、时钟重启（状态文件是人可手改的，不静默信脏值）
+      const isListed = listed !== undefined && Number.isFinite(listedAtMs);
+
+      if (isListed && now - listedAtMs >= WATCHLIST_PERIOD_DAYS * DAY_MS) {
+        candidates.push({
+          id: s.id,
+          kind: 'zero_intercept',
+          stats: s,
+          reason: `零拦截：观察期满（${listed.listedAt.slice(0, 10)} 列入，已满 ${WATCHLIST_PERIOD_DAYS} 天），${s.evaluated} 次评估从未 fail`,
+        });
+        continue;
+      }
+
+      const listedAt = isListed ? listed.listedAt : new Date(now).toISOString();
+      if (!isListed) {
+        nextWatchlist[s.id] = { listedAt };
+      }
+      watchlistEntries.push({
         id: s.id,
-        kind: 'zero_intercept',
         stats: s,
+        listedAt,
+        remainingDays: isListed
+          ? Math.max(0, Math.ceil((listedAtMs + WATCHLIST_PERIOD_DAYS * DAY_MS - now) / DAY_MS))
+          : WATCHLIST_PERIOD_DAYS,
         reason: `零拦截：${s.evaluated} 次评估从未 fail`,
       });
     }
   }
 
-  return candidates;
+  return { candidates, watchlist: watchlistEntries, nextWatchlist };
 }
 
 /**
- * 构建 report 数据模型（只读）
+ * 退役候选诊断（纯函数）——观察名单兼容包装
+ *
+ * 每条约束最多归入一个类别，优先级：
+ * zero_trigger → unevaluable → high_noise → zero_intercept
+ *
+ * 只返回退役候选；观察名单分组与待写回状态走 `buildConstraintsUsageReport`
+ * 的 `watchlist` / `nextWatchlist` 字段。zero_intercept 仅在观察期满且样本足时
+ * 才出现在本返回值里（ADR-0032），未期满的命中不再直接列候选。
+ */
+export function diagnoseRetireCandidates(
+  stats: ConstraintUsageStats[],
+  thresholds: Partial<DiagnoseThresholds> = {},
+  watch: DiagnoseWatchOptions = {}
+): RetireCandidate[] {
+  const t = { ...DEFAULT_DIAGNOSE_THRESHOLDS, ...thresholds };
+  return diagnose(stats, t, watch).candidates;
+}
+
+/**
+ * 构建 report 数据模型（只读；观察名单状态以快照入、以 nextWatchlist 出，不写盘）
  */
 export function buildConstraintsUsageReport(
   projectRoot: string = process.cwd(),
-  thresholds: Partial<DiagnoseThresholds> = {}
+  thresholds: Partial<DiagnoseThresholds> = {},
+  watch: DiagnoseWatchOptions = {}
 ): ConstraintsUsageReport {
   const effective = getEffectiveConstraints(projectRoot);
 
@@ -250,12 +362,15 @@ export function buildConstraintsUsageReport(
   const usage = collectUsageByConstraint(traces);
 
   const stats = effective.map(c => toStats(c.id, c.severity, usage.get(c.id)));
-  const candidates = diagnoseRetireCandidates(stats, thresholds);
+  const t = { ...DEFAULT_DIAGNOSE_THRESHOLDS, ...thresholds };
+  const outcome = diagnose(stats, t, watch);
   const lint = lintEffectiveConfig(projectRoot);
 
   return {
     stats,
-    candidates,
+    candidates: outcome.candidates,
+    watchlist: outcome.watchlist,
+    nextWatchlist: outcome.nextWatchlist,
     lint,
     traceFileExists: fs.existsSync(tracePath),
     skippedLines,