@dommaker/harness 0.16.9 → 0.17.1

package/src/cli/commands/constraints-retire.ts

@@ -0,0 +1,443 @@
+/**
+ * harness constraints retire —— 约束退役（ADR-0001 决策 2/5）
+ *
+ * 建议层全自动（候选诊断复用 report 数据层），执行层保留一次人确认。
+ * 落盘形态 = config.yml `enabled: false` + `retired` 元数据（不发明第二套状态）：
+ *
+ *   constraints:
+ *     <id>:
+ *       enabled: false
+ *       retired: { at, reason, stats: { total, fail, failRate } }
+ *
+ * 每条同时写一条 KnowledgeStore 记录（consumptionMode: 'signal'），
+ * 并同步 CLAUDE.md 注入段（存在 HARNESS_CONSTRAINTS 标记时）。
+ *
+ * retire 不是删除——恢复方法：删除 config.yml 中 constraints.<id> 段。
+ *
+ * 交互与执行分离：retireConstraint 为纯执行逻辑（同步、可测），
+ * runRetireInteractive 只做 readline 交互，IO 流可注入。
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import * as readline from 'readline';
+import * as yaml from 'js-yaml';
+import chalk from 'chalk';
+import { getConstraint } from '../../core/constraints/definitions';
+import { renderConstraintsSection, CONSTRAINTS_START_MARKER, CONSTRAINTS_END_MARKER } from '../../core/constraints/injection-renderer';
+import { getEffectiveConstraints } from '../../core/effective-constraints';
+import { loadRawProjectConfig, ProjectConfigLoader } from '../../core/project-config-loader';
+import { FileKnowledgeStore } from '../../knowledge/store';
+import type { KnowledgeEntry } from '../../knowledge/types';
+import type { Constraint } from '../../types/constraint';
+import {
+  buildConstraintsUsageReport,
+  collectUsageByConstraint,
+  readProjectTraces,
+  type RetireCandidate,
+} from '../../core/constraints/usage-report';
+import { getConstraintsMeta } from './constraints';
+
+export interface RetireExecuteOptions {
+  /** 退役原因（可空） */
+  reason?: string;
+  /** 注入当前时间（测试用） */
+  now?: Date;
+}
+
+export type RetireStatus = 'retired' | 'already_retired' | 'unknown_id';
+
+export interface RetireResult {
+  id: string;
+  status: RetireStatus;
+  /** 是否 check 层 iron（交互模式据此追加确认） */
+  isIronLaw: boolean;
+  stats: { total: number; fail: number; failRate: number };
+  /** CLAUDE.md 注入段是否已同步 */
+  claudeMdSynced: boolean;
+  /** KnowledgeStore 条目 id（status='retired' 时存在） */
+  knowledgeEntryId?: string;
+}
+
+export interface ConstraintsRetireOptions {
+  projectPath?: string;
+  reason?: string;
+}
+
+interface RetireTargetInfo {
+  isIronLaw: boolean;
+  level: Constraint['level'];
+  description?: string;
+  rule?: string;
+  message?: string;
+  promptInjection?: string;
+}
+
+/**
+ * 查找约束定义（内置 definitions + 项目 custom-constraints）
+ */
+function findRetireTarget(projectRoot: string, id: string): RetireTargetInfo | undefined {
+  const builtIn = getConstraint(id);
+  if (builtIn) {
+    return {
+      isIronLaw: builtIn.kind === 'check' && builtIn.level === 'iron_law',
+      level: builtIn.level,
+      description: builtIn.description,
+      rule: builtIn.rule,
+      message: builtIn.message,
+      promptInjection: builtIn.promptInjection,
+    };
+  }
+
+  const loader = new ProjectConfigLoader(projectRoot);
+  loader.load();
+  const custom = loader.getCustomConstraints()[id];
+  if (custom) {
+    const level = custom.level || 'guideline';
+    return {
+      isIronLaw: false, // custom 约束统一 kind='prompt'（无 checker），不存在 check 层 iron
+      level,
+      description: custom.description,
+      rule: custom.rule,
+      message: custom.message,
+    };
+  }
+
+  return undefined;
+}
+
+/**
+ * 读取 harness 版本（与 init.ts 同路径策略）
+ */
+function getHarnessVersion(): string {
+  try {
+    const pkgPath = path.join(__dirname, '..', '..', '..', 'package.json');
+    return JSON.parse(fs.readFileSync(pkgPath, 'utf-8')).version ?? 'unknown';
+  } catch {
+    return 'unknown';
+  }
+}
+
+/**
+ * 写 config.yml 退役段（ADR-0001 决策 5）
+ *
+ * js-yaml 不保留注释：原文件含注释行时重写会丢失，console 说明。
+ */
+function writeRetireConfig(
+  projectRoot: string,
+  id: string,
+  retiredMeta: { at: string; reason: string; stats: { total: number; fail: number; failRate: number } }
+): void {
+  const configPath = path.join(projectRoot, '.harness', 'config.yml');
+
+  let raw: Record<string, unknown> = {};
+  let hadComments = false;
+  if (fs.existsSync(configPath)) {
+    const original = fs.readFileSync(configPath, 'utf-8');
+    hadComments = original.split('\n').some(l => l.trimStart().startsWith('#'));
+    raw = (yaml.load(original) as Record<string, unknown>) ?? {};
+  }
+
+  const constraints = (raw.constraints ?? {}) as Record<string, unknown>;
+  const prev = (constraints[id] ?? {}) as Record<string, unknown>;
+  constraints[id] = { ...prev, enabled: false, retired: retiredMeta };
+  raw.constraints = constraints;
+
+  fs.mkdirSync(path.dirname(configPath), { recursive: true });
+  fs.writeFileSync(configPath, yaml.dump(raw, { lineWidth: 120 }), 'utf-8');
+
+  if (hadComments) {
+    console.log(chalk.yellow('   ⚠️  config.yml 已重写：js-yaml 不保留原文件注释'));
+  }
+}
+
+/**
+ * 写 KnowledgeStore 退役记录（consumptionMode: 'signal'）
+ */
+function saveRetireKnowledge(
+  projectRoot: string,
+  id: string,
+  target: RetireTargetInfo,
+  reason: string,
+  stats: { total: number; fail: number; failRate: number },
+  iso: string
+): string {
+  const entryId = `constraint-retired-${id}`;
+  const contentLines = [
+    `# 约束退役：${id}`,
+    '',
+    '## 规则原文',
+    '',
+    target.description ? `description: ${target.description}` : undefined,
+    target.rule ? `rule: ${target.rule}` : undefined,
+    target.message ? `message: ${target.message}` : undefined,
+    target.promptInjection ? `promptInjection: ${target.promptInjection}` : undefined,
+    '',
+    '## 退役原因',
+    '',
+    reason || '（未填写）',
+    '',
+    '## 历史统计',
+    '',
+    `- total: ${stats.total}`,
+    `- fail: ${stats.fail}`,
+    `- failRate: ${Math.round(stats.failRate * 100)}%`,
+    '',
+    `退役日期: ${iso}`,
+  ].filter((l): l is string => l !== undefined);
+
+  const entry: KnowledgeEntry = {
+    id: entryId,
+    type: 'decision',
+    title: `约束退役：${id}`,
+    content: contentLines.join('\n'),
+    maturity: 'verified',
+    layer: 'project',
+    created: iso,
+    lastReferenced: iso,
+    contributors: [],
+    projects: [],
+    tags: ['constraint-retired', `constraint:${id}`, `level:${target.level}`],
+    applicablePhases: [],
+    sourceReferences: [{ timestamp: iso }],
+    referencedBy: [],
+    executionResults: [],
+    consumptionMode: 'signal',
+    origin: 'human',
+  };
+
+  const store = new FileKnowledgeStore({ baseDir: path.join(projectRoot, '.harness', 'knowledge') });
+  store.save(entry);
+  return entryId;
+}
+
+/**
+ * 同步 CLAUDE.md 注入段（存在 HARNESS_CONSTRAINTS 标记时）
+ *
+ * 复用 renderConstraintsSection（P3 导出纯函数）按退役后生效集重渲染。
+ * 无标记段不动（不追加——retire 不承担 init 职责）。
+ */
+function syncClaudeMdInjection(projectRoot: string): boolean {
+  const claudeMdPath = path.join(projectRoot, 'CLAUDE.md');
+  if (!fs.existsSync(claudeMdPath)) return false;
+
+  const content = fs.readFileSync(claudeMdPath, 'utf-8');
+  const startIdx = content.indexOf(CONSTRAINTS_START_MARKER);
+  const endIdx = content.indexOf(CONSTRAINTS_END_MARKER);
+  if (startIdx === -1 || endIdx === -1 || endIdx <= startIdx) return false;
+
+  const body = renderConstraintsSection(getEffectiveConstraints(projectRoot), getHarnessVersion());
+  const after = content.slice(endIdx + CONSTRAINTS_END_MARKER.length).replace(/^\n+/, '');
+  const newContent = content.slice(0, startIdx) + body + (after ? '\n' + after : '');
+  if (newContent !== content) {
+    fs.writeFileSync(claudeMdPath, newContent, 'utf-8');
+  }
+  return true;
+}
+
+/**
+ * 执行单条约束退役（纯执行逻辑，无交互）
+ *
+ * 不存在的 id / 已退役的 id 通过 status 返回，由调用方提示。
+ */
+export function retireConstraint(
+  projectRoot: string,
+  id: string,
+  options: RetireExecuteOptions = {}
+): RetireResult {
+  const now = options.now ?? new Date();
+  const iso = now.toISOString();
+  const reason = options.reason ?? '';
+
+  const target = findRetireTarget(projectRoot, id);
+  const emptyStats = { total: 0, fail: 0, failRate: 0 };
+  if (!target) {
+    return { id, status: 'unknown_id', isIronLaw: false, stats: emptyStats, claudeMdSynced: false };
+  }
+
+  // 已退役保护（config.yml constraints.<id>.enabled === false）
+  const rawConfig = loadRawProjectConfig(projectRoot);
+  const existing = (rawConfig?.constraints as Record<string, { enabled?: boolean; retired?: unknown }> | undefined)?.[id];
+  if (existing?.enabled === false) {
+    return { id, status: 'already_retired', isIronLaw: target.isIronLaw, stats: emptyStats, claudeMdSynced: false };
+  }
+
+  // 历史统计（来自 traces.log）
+  const usage = collectUsageByConstraint(readProjectTraces(projectRoot)).get(id);
+  const evaluated = usage ? usage.total - usage.skip : 0;
+  const stats = {
+    total: usage?.total ?? 0,
+    fail: usage?.fail ?? 0,
+    failRate: evaluated > 0 ? (usage!.fail / evaluated) : 0,
+  };
+
+  // 1. config.yml
+  writeRetireConfig(projectRoot, id, { at: iso, reason, stats });
+
+  // 2. KnowledgeStore
+  const knowledgeEntryId = saveRetireKnowledge(projectRoot, id, target, reason, stats, iso);
+
+  // 3. CLAUDE.md 注入段同步
+  const claudeMdSynced = syncClaudeMdInjection(projectRoot);
+
+  return { id, status: 'retired', isIronLaw: target.isIronLaw, stats, claudeMdSynced, knowledgeEntryId };
+}
+
+/**
+ * 打印单条退役结果（含回滚语义提示）
+ */
+export function printRetireResult(result: RetireResult): void {
+  switch (result.status) {
+    case 'unknown_id':
+      console.log(chalk.red(`❌ ${result.id}: 约束不存在（既非内置也非 custom-constraints），未做任何变更`));
+      return;
+    case 'already_retired':
+      console.log(chalk.yellow(`⚠️  ${result.id}: 已处于退役状态（config.yml 中 enabled: false），跳过`));
+      return;
+    case 'retired':
+      console.log(chalk.green(`✅ ${result.id}: 已退役`));
+      console.log(`   历史统计: total=${result.stats.total} fail=${result.stats.fail} fail率=${Math.round(result.stats.failRate * 100)}%`);
+      console.log(`   知识沉淀: ${result.knowledgeEntryId}（.harness/knowledge）`);
+      if (result.claudeMdSynced) {
+        console.log('   已同步 CLAUDE.md 注入段');
+      }
+      console.log(chalk.gray(`   retire 不是删除——恢复方法：删除 config.yml 中 constraints.${result.id} 段`));
+  }
+}
+
+// ========================================
+// 交互模式
+// ========================================
+
+interface RetireIO {
+  input: NodeJS.ReadableStream;
+  output: NodeJS.WritableStream;
+}
+
+function createAsk(io: RetireIO): { ask: (q: string) => Promise<string>; close: () => void } {
+  const rl = readline.createInterface({ input: io.input, output: io.output });
+  return {
+    ask: (q: string) => new Promise(resolve => rl.question(q, ans => resolve(ans.trim()))),
+    close: () => rl.close(),
+  };
+}
+
+const CANDIDATE_KIND_LABEL: Record<RetireCandidate['kind'], string> = {
+  zero_trigger: '零触发',
+  unevaluable: '不可评估',
+  high_noise: '高噪',
+  zero_intercept: '零拦截',
+};
+
+/**
+ * 交互式退役（候选列表 → 编号多选 → 摘要 → 确认 → 执行）
+ *
+ * IO 流可注入（测试用），默认 process.stdin/stdout。
+ */
+export async function runRetireInteractive(
+  projectRoot: string,
+  io: RetireIO = { input: process.stdin, output: process.stdout }
+): Promise<void> {
+  const report = buildConstraintsUsageReport(projectRoot);
+  const { ask, close } = createAsk(io);
+
+  try {
+    let selectedIds: string[] = [];
+
+    if (report.candidates.length === 0) {
+      console.log(chalk.green('✅ 当前没有退役候选（所有 check 约束信号正常）'));
+      const manual = await ask('可手动输入要退役的约束 id（留空取消）: ');
+      if (!manual) {
+        console.log('已取消');
+        return;
+      }
+      selectedIds = [manual];
+    } else {
+      console.log(chalk.bold(`退役候选（${report.candidates.length} 条）:`));
+      report.candidates.forEach((c, i) => {
+        console.log(`  ${i + 1}. [${CANDIDATE_KIND_LABEL[c.kind]}] ${c.id} — ${c.reason}`);
+      });
+      console.log();
+      const answer = await ask('输入编号（逗号分隔多选）或约束 id，留空取消: ');
+      if (!answer) {
+        console.log('已取消');
+        return;
+      }
+
+      for (const token of answer.split(',').map(s => s.trim()).filter(Boolean)) {
+        const idx = Number(token);
+        if (Number.isInteger(idx) && idx >= 1 && idx <= report.candidates.length) {
+          selectedIds.push(report.candidates[idx - 1].id);
+        } else {
+          selectedIds.push(token); // 视为手动输入的 id，由 retireConstraint 校验
+        }
+      }
+      selectedIds = [...new Set(selectedIds)];
+    }
+
+    // 逐条收集 reason + iron 二次确认
+    const plan: { id: string; reason: string }[] = [];
+    for (const id of selectedIds) {
+      const target = findRetireTarget(projectRoot, id);
+      if (!target) {
+        console.log(chalk.red(`❌ ${id}: 约束不存在，跳过`));
+        continue;
+      }
+      if (target.isIronLaw) {
+        const confirm = await ask(chalk.yellow(`⚠️  ${id} 是一条 Iron Law，确认退役？(y/N) `));
+        if (confirm.toLowerCase() !== 'y' && confirm.toLowerCase() !== 'yes') {
+          console.log(`   已跳过 ${id}`);
+          continue;
+        }
+      }
+      const reason = await ask(`退役原因（${id}，可留空）: `);
+      plan.push({ id, reason });
+    }
+
+    if (plan.length === 0) {
+      console.log('无可执行项，已取消');
+      return;
+    }
+
+    // 变更摘要 → 最终确认
+    console.log();
+    console.log(chalk.bold('将执行以下变更:'));
+    for (const p of plan) {
+      console.log(`  - config.yml: constraints.${p.id}.enabled=false + retired 元数据（原因: ${p.reason || '（空）'}）`);
+      console.log(`  - KnowledgeStore: 写入 constraint-retired-${p.id}`);
+    }
+    console.log('  - CLAUDE.md: 若含 HARNESS_CONSTRAINTS 标记段则同步重渲染');
+    const finalConfirm = await ask('确认执行？(y/N) ');
+    if (finalConfirm.toLowerCase() !== 'y' && finalConfirm.toLowerCase() !== 'yes') {
+      console.log('已取消');
+      return;
+    }
+
+    console.log();
+    for (const p of plan) {
+      const result = retireConstraint(projectRoot, p.id, { reason: p.reason });
+      printRetireResult(result);
+    }
+  } finally {
+    close();
+  }
+}
+
+/**
+ * CLI handler: harness constraints retire [id]
+ */
+export async function constraintsRetire(id?: string, options: ConstraintsRetireOptions = {}): Promise<void> {
+  const projectRoot = options.projectPath || process.cwd();
+
+  if (id) {
+    // 非交互直达
+    const result = retireConstraint(projectRoot, id, { reason: options.reason });
+    if (result.status === 'retired' && result.isIronLaw) {
+      console.log(chalk.yellow(`⚠️  ${id} 是一条 Iron Law，已通过命令行直接退役（交互模式会要求二次确认）`));
+    }
+    printRetireResult(result);
+    return;
+  }
+
+  await runRetireInteractive(projectRoot);
+}

package/src/cli/commands/constraints.ts

@@ -13,7 +13,7 @@ import { getAllConstraints } from '../../core/constraints/definitions';
 export interface ConstraintsMeta {
   version: string;
   hash: string;
-  counts: { ironLaws: number; guidelines: number; tips: number };
+  counts: { ironLaws: number; guidelines: number; prompts: number };
   textSize: { total: number; perConstraint: number };
 }
 
@@ -40,7 +40,7 @@ export function getConstraintsMeta(): ConstraintsMeta {
 
   const ironLaws = constraints.filter(c => c.level === 'iron_law');
   const guidelines = constraints.filter(c => c.level === 'guideline');
-  const tips = constraints.filter(c => c.level === 'tip');
+  const prompts = constraints.filter(c => c.level === 'prompt');
 
   // 计算总 promptInjection 文本长度（字符数，可估算 token）
   const totalTextSize = constraints
@@ -51,7 +51,7 @@ export function getConstraintsMeta(): ConstraintsMeta {
   const hashInput = JSON.stringify({
     ironLaws: ironLaws.map(c => ({ id: c.id, promptInjection: c.promptInjection })),
     guidelines: guidelines.map(c => ({ id: c.id, promptInjection: c.promptInjection })),
-    tips: tips.map(c => ({ id: c.id, promptInjection: c.promptInjection })),
+    prompts: prompts.map(c => ({ id: c.id, promptInjection: c.promptInjection })),
   });
   const hash = createHash('sha256').update(hashInput).digest('hex');
 
@@ -61,7 +61,7 @@ export function getConstraintsMeta(): ConstraintsMeta {
     counts: {
       ironLaws: ironLaws.length,
       guidelines: guidelines.length,
-      tips: tips.length,
+      prompts: prompts.length,
     },
     textSize: {
       total: totalTextSize,
@@ -80,7 +80,7 @@ export async function constraints(options: { json?: boolean }): Promise<void> {
   } else {
     console.log(`version: ${meta.version}`);
     console.log(`hash: ${meta.hash}`);
-    console.log(`ironLaws: ${meta.counts.ironLaws}, guidelines: ${meta.counts.guidelines}, tips: ${meta.counts.tips}`);
+    console.log(`ironLaws: ${meta.counts.ironLaws}, guidelines: ${meta.counts.guidelines}, prompts: ${meta.counts.prompts}`);
     console.log(`textSize: ${meta.textSize.total} chars total, ~${meta.textSize.perConstraint} chars/constraint`);
   }
 }

package/src/cli/commands/index.ts

@@ -8,7 +8,6 @@ export { runPassesGate, checkCoverage, type PassesGateOptions } from './passes-g
 export { init, type InitOptions } from './init';
 export { report, type ReportOptions } from './report';
 export { status, type StatusOptions } from './status';
-export { flow, type FlowOptions } from './flow';
 export { specValidate, listSpecTypes, type SpecValidateOptions } from './spec';
 export { acceptance, listAcceptanceCriteria, type AcceptanceOptions } from './acceptance';
 export { performance, type PerformanceOptions } from './performance';
@@ -24,6 +23,8 @@ export { release, type ReleaseOptions } from './release';
 export { analyzeSessions, type AnalyzeSessionsOptions } from './analyze-sessions';
 export { updateUserModel, type UpdateUserModelOptions } from './update-user-model';
 export { constraints, getConstraintsMeta, type ConstraintsMeta } from './constraints';
+export { constraintsReport, renderExportMarkdown, type ConstraintsReportOptions } from './constraints-report';
+export { constraintsRetire, retireConstraint, runRetireInteractive, printRetireResult, type ConstraintsRetireOptions, type RetireResult, type RetireStatus } from './constraints-retire';
 export { docFreshnessCheck, extractClaims, verifyClaims, type DocFreshnessCheckOptions, type ClaimResult, type ClaimType } from './doc-freshness-check';
 export { specBaselineCheck, extractBaselineSection, type SpecBaselineCheckOptions, type PrerequisiteResult } from './spec-baseline-check';
 export { sddIndex, type SDDOptions } from './sdd';