@dommaker/harness 1.11.0 → 1.12.0

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

@@ -14,6 +14,7 @@
 
 import * as fs from 'fs';
 import { captureIO, type CapturingIO } from '../../command-contract';
+import * as os from 'os';
 import * as path from 'path';
 import { PassThrough, Writable } from 'stream';
 import * as yaml from 'js-yaml';
@@ -21,6 +22,7 @@ import { getConstraint } from '../../../core/constraints/definitions';
 import { getEffectiveConstraints } from '../../../core/effective-constraints';
 import { FileKnowledgeStore } from '../../../knowledge/store';
 import { retireConstraint, constraintsRetire, runRetireInteractive, printRetireResult } from '../constraints-retire';
+import { openKnowledgeStore } from '../knowledge-view';
 import { createProjectFixture, writeProjectTraces } from '../../../test-setup/project-fixture';
 
 const FIXED_NOW = new Date('2026-08-08T12:00:00.000Z');
@@ -32,6 +34,12 @@ function readConfig(root: string): any {
 let io: CapturingIO;
 beforeEach(() => {
   io = captureIO();
+  // retire 的 KnowledgeStore 写口走统一解析点（harness#177）：不隔离会写进真实用户主目录
+  process.env.KNOWLEDGE_BASE_DIR = fs.mkdtempSync(path.join(os.tmpdir(), 'harness-retire-kb-'));
+});
+afterEach(() => {
+  fs.rmSync(process.env.KNOWLEDGE_BASE_DIR!, { recursive: true, force: true });
+  delete process.env.KNOWLEDGE_BASE_DIR;
 });
 
 describe('retireConstraint 执行逻辑', () => {
@@ -49,7 +57,7 @@ describe('retireConstraint 执行逻辑', () => {
     });
 
     expect(result.status).toBe('retired');
-    expect(result.isError).toBe(false);
+    expect(result.isError).toBe(true);
     expect(result.stats).toEqual({ total: 3, fail: 1, failRate: 1 / 3 });
 
     const config = readConfig(root);
@@ -77,7 +85,7 @@ describe('retireConstraint 执行逻辑', () => {
     expect(config.constraints.capability_sync.retired.reason).toBe('');
   });
 
-  it('KnowledgeStore 写入退役记录：规则原文 + 原因 + 统计 + signal 模式', () => {
+  it('KnowledgeStore 写入退役记录：规则原文 + 原因 + 统计 + signal 模式，落点为 knowledge 读口同一解析根（harness#177）', () => {
     const root = createProjectFixture({
       name: 'harness-retire-test',
       traces: [{ constraintId: 'no_completion_without_verification', result: 'fail' }],
@@ -86,8 +94,12 @@ describe('retireConstraint 执行逻辑', () => {
     const result = retireConstraint(root, 'no_completion_without_verification', { reason: '流程已内置门禁', now: FIXED_NOW });
     expect(result.status).toBe('retired');
     expect(result.knowledgeEntryId).toBe('constraint-retired-no_completion_without_verification');
+    // 写口与读口同一解析点：KNOWLEDGE_BASE_DIR 覆盖对写口同步生效
+    expect(result.knowledgeBaseDir).toBe(process.env.KNOWLEDGE_BASE_DIR);
+    // 缺省解析（无 -p/--dir）构造的 store 直接可读——修复前写口硬编码 projectRoot，此处读不到
+    expect(openKnowledgeStore({}, io).get('constraint-retired-no_completion_without_verification')).toBeDefined();
 
-    const store = new FileKnowledgeStore({ baseDir: path.join(root, '.harness', 'knowledge') });
+    const store = new FileKnowledgeStore({ baseDir: process.env.KNOWLEDGE_BASE_DIR! });
     const entry = store.get('constraint-retired-no_completion_without_verification');
     expect(entry).toBeDefined();
     expect(entry!.consumptionMode).toBe('signal');
@@ -104,7 +116,7 @@ describe('retireConstraint 执行逻辑', () => {
     expect(entry!.content).toContain(FIXED_NOW.toISOString());
   });
 
-  it('退役结果打印含回滚语义提示（恢复 = 删 config.yml 段）', () => {
+  it('退役结果打印含回滚语义提示（恢复 = constraints reactivate 命令）', () => {
     const root = createProjectFixture({ name: 'harness-retire-test' });
     const result = retireConstraint(root, 'capability_sync', { now: FIXED_NOW });
     expect(result.status).toBe('retired');
@@ -112,7 +124,38 @@ describe('retireConstraint 执行逻辑', () => {
     printRetireResult(result, io);
     const output = io.outText();
     expect(output).toContain('恢复方法');
-    expect(output).toContain('constraints.capability_sync');
+    expect(output).toContain('harness constraints reactivate capability_sync');
+  });
+
+  it('退役结果打印：git 仓内附 commit 提示，非 git 目录不提示（票 02 断点 4）', () => {
+    const gitRoot = createProjectFixture({ name: 'harness-retire-test', files: { '.git/HEAD': 'ref: refs/heads/master\n' } });
+    const inGit = retireConstraint(gitRoot, 'capability_sync', { now: FIXED_NOW });
+    printRetireResult(inGit, io, gitRoot);
+    expect(io.outText()).toContain('git add .harness/config.yml');
+
+    const plainRoot = createProjectFixture({ name: 'harness-retire-test' });
+    const plainIo = captureIO();
+    const notInGit = retireConstraint(plainRoot, 'capability_sync', { now: FIXED_NOW });
+    printRetireResult(notInGit, plainIo, plainRoot);
+    expect(plainIo.outText()).not.toContain('git add');
+  });
+
+  it('裸 disable 不吞退休：enabled:false 无墓碑时 retire 照常落墓碑 + 沉淀（ADR-0032 决策 6.6，票 02 断点 6）', () => {
+    const root = createProjectFixture({
+      name: 'harness-retire-test',
+      config: 'constraints:\n  capability_sync:\n    enabled: false\n',
+    });
+
+    const result = retireConstraint(root, 'capability_sync', { reason: '升级裸 disable 为退休', now: FIXED_NOW });
+
+    expect(result.status).toBe('retired');
+    const config = readConfig(root);
+    expect(config.constraints.capability_sync.enabled).toBe(false);
+    expect(config.constraints.capability_sync.retired.at).toBe(FIXED_NOW.toISOString());
+    expect(config.constraints.capability_sync.retired.reason).toBe('升级裸 disable 为退休');
+    // 沉淀照写，不被裸 disable 吞掉
+    const store = new FileKnowledgeStore({ baseDir: process.env.KNOWLEDGE_BASE_DIR! });
+    expect(store.get('constraint-retired-capability_sync')).toBeDefined();
   });
 
   it('重复 retire：already_retired，不覆盖原 retired 元数据', () => {
@@ -229,14 +272,14 @@ describe('constraintsRetire 非交互直达', () => {
 
   it('--yes 直达 warning 级退役：不打印 error 级警示并落盘', async () => {
     const root = createProjectFixture({ name: 'harness-retire-test' });
-    await constraintsRetire('no_hardcoded_credentials', { projectPath: root, reason: '直接退役', yes: true }, io);
+    await constraintsRetire('capability_sync', { projectPath: root, reason: '直接退役', yes: true }, io);
 
     const output = io.outText();
     expect(output).not.toContain('是一条 error 级约束');
     expect(output).toContain('已退役');
 
     const config = readConfig(root);
-    expect(config.constraints.no_hardcoded_credentials.enabled).toBe(false);
+    expect(config.constraints.capability_sync.enabled).toBe(false);
   });
 
   it('--yes 直达未知 id：明确提示', async () => {
@@ -305,7 +348,7 @@ describe('runRetireInteractive 交互流程（注入 IO 流）', () => {
       ]);
     writeProjectTraces(root, healthy);
 
-    const streams = makeIo(['no_hardcoded_credentials', '误报太多', 'y']);
+    const streams = makeIo(['capability_sync', '误报太多', 'y']);
     const printed = captureLog();
     await runRetireInteractive(root, streams);
     streams.done();
@@ -316,8 +359,8 @@ describe('runRetireInteractive 交互流程（注入 IO 流）', () => {
     expect(output).toContain('已退役');
 
     const config = readConfig(root);
-    expect(config.constraints.no_hardcoded_credentials.enabled).toBe(false);
-    expect(config.constraints.no_hardcoded_credentials.retired.reason).toBe('误报太多');
+    expect(config.constraints.capability_sync.enabled).toBe(false);
+    expect(config.constraints.capability_sync.retired.reason).toBe('误报太多');
   });
 
   it('坏行 fixture：候选列表前告知损坏行数（决策依据不完整不静默，harness#100）', async () => {
@@ -403,3 +446,85 @@ describe('runRetireInteractive 交互流程（注入 IO 流）', () => {
     expect(fs.existsSync(path.join(root, '.harness', 'config.yml'))).toBe(false);
   });
 });
+
+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',
+    '    message: 检测到内网地址',
+    '',
+  ].join('\n');
+
+  function appFixture(configYml?: string): string {
+    return createProjectFixture({
+      name: 'harness-retire-test',
+      config: configYml,
+      files: { [path.join('.harness', 'constraints.yml')]: APP_YML },
+    });
+  }
+
+  it('墓碑写 config.yml 与内置同形（enabled:false + retired），constraints.yml 条文保留不删', () => {
+    const root = appFixture();
+    const ymlBefore = fs.readFileSync(path.join(root, '.harness', 'constraints.yml'), 'utf-8');
+
+    const result = retireConstraint(root, 'app_no_internal_url', { reason: '网关统一拦截', now: FIXED_NOW });
+
+    expect(result.status).toBe('retired');
+    expect(result.isError).toBe(false); // 应用层 severity=warning
+    const config = readConfig(root);
+    const entry = config.constraints.app_no_internal_url;
+    expect(entry.enabled).toBe(false);
+    expect(entry.retired.at).toBe(FIXED_NOW.toISOString());
+    expect(entry.retired.reason).toBe('网关统一拦截');
+    // 退休=停用不是删除：定义正本逐字节不动
+    expect(fs.readFileSync(path.join(root, '.harness', 'constraints.yml'), 'utf-8')).toBe(ymlBefore);
+    // 生效集排除
+    expect(getEffectiveConstraints(root).some(c => c.id === 'app_no_internal_url')).toBe(false);
+  });
+
+  it('沉淀条目复用 saveRetireKnowledge，tags 加 source:app', () => {
+    const root = appFixture();
+    const result = retireConstraint(root, 'app_no_internal_url', { now: FIXED_NOW });
+
+    expect(result.status).toBe('retired');
+    expect(result.knowledgeEntryId).toBe('constraint-retired-app_no_internal_url');
+    const store = new FileKnowledgeStore({ baseDir: process.env.KNOWLEDGE_BASE_DIR! });
+    const entry = store.get('constraint-retired-app_no_internal_url');
+    expect(entry).toBeDefined();
+    expect(entry!.tags).toContain('constraint-retired');
+    expect(entry!.tags).toContain('constraint:app_no_internal_url');
+    expect(entry!.tags).toContain('source:app');
+    expect(entry!.content).toContain('Web code must not contain internal URLs');
+  });
+
+  it('内置退休沉淀不带 source:app（tags 形状不漂移）', () => {
+    const root = createProjectFixture({ name: 'harness-retire-test' });
+    retireConstraint(root, 'capability_sync', { now: FIXED_NOW });
+    const store = new FileKnowledgeStore({ baseDir: process.env.KNOWLEDGE_BASE_DIR! });
+    expect(store.get('constraint-retired-capability_sync')!.tags).not.toContain('source:app');
+  });
+
+  it('重复退休应用层：already_retired 幂等，不覆盖原墓碑', () => {
+    const root = appFixture();
+    retireConstraint(root, 'app_no_internal_url', { reason: '第一次', now: FIXED_NOW });
+
+    const second = retireConstraint(root, 'app_no_internal_url', {
+      reason: '第二次',
+      now: new Date('2026-08-09T00:00:00.000Z'),
+    });
+    expect(second.status).toBe('already_retired');
+    expect(readConfig(root).constraints.app_no_internal_url.retired.reason).toBe('第一次');
+  });
+
+  it('constraints.yml 里的 id 与内置都找不到 → unknown_id', () => {
+    const root = appFixture();
+    const result = retireConstraint(root, 'app_ghost', { now: FIXED_NOW });
+    expect(result.status).toBe('unknown_id');
+    expect(fs.existsSync(path.join(root, '.harness', 'config.yml'))).toBe(false);
+  });
+});

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

@@ -85,7 +85,8 @@ beforeEach(() => {
 });
 
 // 解析函数本体自 #133 起住 knowledge-view.ts（resolveKnowledgeBaseDir），行为面不变：
-// 这里经 knowledgeStats 观测 `-p` / KNOWLEDGE_BASE_DIR / 旧目录兜底三条路径的解析结果
+// 这里经 knowledgeStats 观测 `-p` / KNOWLEDGE_BASE_DIR / 缺省目录三条路径的解析结果
+// （ADR-0034：旧 ~/.studio/knowledge 兼容沿用已退役，不再属观测面）
 describe('getKnowledgeDir', () => {
   const fs = require('fs');
   const os = require('os');
@@ -119,34 +120,23 @@ describe('getKnowledgeDir', () => {
     }));
   });
 
-  it('should default to ~/.harness/knowledge when no env var and no legacy data', async () => {
+  it('should default to ~/.harness/knowledge when no env var', async () => {
     await knowledgeStats({ json: true }, io);
     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 () => {
+  it('should NOT fall back to legacy ~/.studio/knowledge even when it has data (ADR-0034 目录收编：兼容沿用已退役)', 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 }, io);
-    expect(storeCtorSpy).toHaveBeenCalledWith(expect.objectContaining({
-      baseDir: legacyDir,
-    }));
-    expect(io.errText()).toContain('旧目录');
-    // 闩锁：同进程重复解析只提示一次
-    await knowledgeStats({ json: true }, io);
-    const notices = io.errLines().filter(line => line.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 }, io);
+    // 旧目录有数据也不再沿用：落缺省 ~/.harness/knowledge，无兼容提示
     expect(storeCtorSpy).toHaveBeenCalledWith(expect.objectContaining({
       baseDir: path.join(tmpHome, '.harness', 'knowledge'),
     }));
+    expect(io.errText()).not.toContain('旧目录');
   });
 
   it('should use projectPath when provided', async () => {

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

@@ -0,0 +1,67 @@
+/**
+ * report 命令生效集口径（ADR-0033 块 3 子项 3）
+ *
+ * 缺口修复回归：report 此前跑内置全集（CONSTRAINTS），config.yml 禁用与
+ * 应用层约束（.harness/constraints.yml）都进不了报告面。修复后 collectConstraints
+ * 传 merged config（与 check.ts 同一 getMergedConstraintsConfig 入口），
+ * 应用层条目进总数、违规如实上报。
+ */
+
+import { describe, it, expect } from '@jest/globals';
+import * as path from 'path';
+import { report } from '../report';
+import { captureIO } from '../../command-contract';
+import { CONSTRAINTS } from '../../../core/constraints/definitions';
+import { createProjectFixture } from '../../../test-setup/project-fixture';
+
+const BUILTIN_TOTAL = Object.keys(CONSTRAINTS).length;
+
+/** 应用层约束：file-exists 指向一个不存在的文件（warning 级，必违规） */
+const APP_YML = [
+  'constraints:',
+  '  - id: app_required_readme',
+  '    rule: Project must keep README.app.md',
+  '    checker: file-exists',
+  '    params:',
+  '      path: README.app.md',
+  '    severity: warning',
+  '    message: 缺少 README.app.md',
+  '',
+].join('\n');
+
+function parseJsonReport(output: string) {
+  const start = output.indexOf('{');
+  const end = output.lastIndexOf('}');
+  return JSON.parse(output.slice(start, end + 1));
+}
+
+describe('report 生效集口径（含应用层）', () => {
+  it('应用层约束进报告：总数 +1，违规进 violations', async () => {
+    const root = createProjectFixture({
+      name: 'report-app-effective',
+      files: { [path.join('.harness', 'constraints.yml')]: APP_YML },
+    });
+    const io = captureIO();
+
+    await report({ format: 'json', projectPath: root }, io);
+
+    const data = parseJsonReport(io.outText());
+    expect(data.constraints.total).toBe(BUILTIN_TOTAL + 1);
+    const ids = data.constraints.violations.map((v: { id: string }) => v.id);
+    expect(ids).toContain('app_required_readme');
+    expect(data.constraints.warningViolations).toBeGreaterThanOrEqual(1);
+  });
+
+  it('config.yml 禁用内置约束后总数随生效集收窄（不再报内置全集）', async () => {
+    const root = createProjectFixture({
+      name: 'report-app-effective',
+      config: 'constraints:\n  capability_sync:\n    enabled: false\n',
+    });
+    const io = captureIO();
+
+    await report({ format: 'json', projectPath: root }, io);
+
+    const data = parseJsonReport(io.outText());
+    expect(data.constraints.total).toBe(BUILTIN_TOTAL - 1);
+  });
+});

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

@@ -0,0 +1,172 @@
+/**
+ * harness constraints pack-proposal <id> —— 升级提案材料打包（ADR-0033 决策 4，块 3 子项 5）
+ *
+ * 升级通道链路：studio 审卡发起/初审 → approve 后由本命令打包脱敏材料 →
+ * 人拿材料去 harness 仓开 issue（github 操作留给人，本命令不触网）。
+ *
+ * 材料内容：条文 + severity + checker 模板与参数 + traces.log 使用统计（只有计数）
+ * + 升级理由留白段。
+ *
+ * 脱敏口径（工具做路径脱敏，内容脱敏归人）：
+ * - 项目根绝对路径一律替换为 `<repoRoot>`；
+ * - 统计只有计数与首末次日期，不带样本内容；
+ * - 应用层约束的 params（正则/glob）**原文带出**并标注"请人工确认无应用内部信息"——
+ *   打包工具是质量前置，不是保密闸门。
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import * as yaml from 'js-yaml';
+import chalk from 'chalk';
+import { getConstraint } from '../../core/constraints/definitions';
+import { loadAppConstraints } from '../../core/app-constraints-loader';
+import { collectUsageByConstraint, readProjectTraces } from '../../core/constraints/usage-report';
+import type { Constraint } from '../../types/constraint';
+import { log, logError, processIO, type CommandIO, type CommandResult } from '../command-contract';
+
+export interface PackProposalOptions {
+  projectPath?: string;
+  /** 打印到 stdout 而不落盘 */
+  stdout?: boolean;
+  /** 日期注入（测试用；缺省真实时钟） */
+  now?: Date;
+}
+
+/** 提案材料的输入（查找结果 + 使用统计聚合） */
+export interface ProposalMaterial {
+  constraint: Constraint;
+  stats: {
+    total: number;
+    pass: number;
+    fail: number;
+    skip: number;
+    evaluated: number;
+    firstAt?: number;
+    lastAt?: number;
+  };
+}
+
+/**
+ * 查找约束定义（内置 + 应用层，与 findRetireTarget 同口径但带全量字段——
+ * checker/params 是提案材料的核心内容，RetireTargetInfo 不带）
+ */
+function findProposalTarget(id: string, projectRoot: string): Constraint | undefined {
+  const builtIn = getConstraint(id);
+  if (builtIn) return builtIn;
+  return loadAppConstraints(projectRoot).find(c => c.id === id);
+}
+
+function formatDate(ts: number | undefined): string {
+  return ts === undefined ? '（无记录）' : new Date(ts).toISOString().slice(0, 10);
+}
+
+/**
+ * 渲染脱敏提案材料 markdown（纯函数，导出供测试）
+ *
+ * @param projectRoot 用于路径脱敏（材料中出现的项目根绝对路径替换为 `<repoRoot>`）
+ */
+export function renderProposalMarkdown(
+  material: ProposalMaterial,
+  projectRoot: string,
+  now: Date = new Date()
+): string {
+  const c = material.constraint;
+  const s = material.stats;
+  const isApp = c.source === 'app';
+
+  const lines: string[] = [];
+  lines.push(`# 约束升级提案材料：${c.id}`);
+  lines.push('');
+  lines.push(`- 生成日期: ${now.toISOString().slice(0, 10)}`);
+  lines.push(`- 来源: ${isApp ? '应用层（.harness/constraints.yml）' : '内置'}`);
+  lines.push(`- severity: ${c.severity}`);
+  lines.push('');
+
+  lines.push('## 条文');
+  lines.push('');
+  lines.push(`rule: ${c.rule}`);
+  if (c.message && c.message !== c.rule) lines.push(`message: ${c.message}`);
+  if (c.description) lines.push(`description: ${c.description}`);
+  lines.push('');
+
+  lines.push('## checker');
+  lines.push('');
+  if (isApp) {
+    lines.push(`模板: \`${c.checker}\``);
+    lines.push('');
+    lines.push('参数（原文带出，**请人工确认无应用内部信息**——工具只做路径脱敏，内容脱敏归人）:');
+    lines.push('');
+    lines.push('```yaml');
+    lines.push(yaml.dump(c.params ?? {}, { lineWidth: 120 }).trimEnd());
+    lines.push('```');
+  } else {
+    lines.push('内置定制 checker（按约束 id 注册，非参数化模板）。升级到通用层前需评审：');
+    lines.push('改写为模板 + 参数，或作为通用规则保留定制实现。');
+  }
+  lines.push('');
+
+  lines.push('## 使用统计（traces.log 聚合，只有计数）');
+  lines.push('');
+  lines.push(`- total: ${s.total}`);
+  lines.push(`- evaluated: ${s.evaluated}（pass ${s.pass} / fail ${s.fail} / skip ${s.skip}）`);
+  lines.push(`- 首次触发: ${formatDate(s.firstAt)}`);
+  lines.push(`- 最近触发: ${formatDate(s.lastAt)}`);
+  lines.push('');
+
+  lines.push('## 升级理由');
+  lines.push('');
+  lines.push('> （请在此填写：为什么这条约束该进通用层——适用面、证据、与其他仓的相关性）');
+  lines.push('');
+
+  // 路径脱敏：项目根绝对路径一律替换
+  return lines.join('\n').split(projectRoot).join('<repoRoot>');
+}
+
+/**
+ * CLI handler: harness constraints pack-proposal <id>
+ */
+export async function constraintsPackProposal(
+  id: string | undefined,
+  options: PackProposalOptions = {},
+  io: CommandIO = processIO
+): Promise<CommandResult> {
+  const projectRoot = options.projectPath || process.cwd();
+
+  if (!id) {
+    logError(io, '❌ 缺少约束 id：harness constraints pack-proposal <id>');
+    return { kind: 'usage-error', reason: '缺少约束 id' };
+  }
+
+  const constraint = findProposalTarget(id, projectRoot);
+  if (!constraint) {
+    logError(io, `❌ 未知约束 id: ${id}（内置与应用层 constraints.yml 均未找到），未做任何变更`);
+    return { kind: 'usage-error', reason: `未知约束 id: ${id}` };
+  }
+
+  const usage = collectUsageByConstraint(readProjectTraces(projectRoot)).get(id);
+  const stats = {
+    total: usage?.total ?? 0,
+    pass: usage?.pass ?? 0,
+    fail: usage?.fail ?? 0,
+    skip: usage?.skip ?? 0,
+    evaluated: (usage?.total ?? 0) - (usage?.skip ?? 0),
+    firstAt: usage?.firstAt,
+    lastAt: usage?.lastAt,
+  };
+
+  const now = options.now ?? new Date();
+  const markdown = renderProposalMarkdown({ constraint, stats }, projectRoot, now);
+
+  if (options.stdout) {
+    log(io, markdown);
+    return { kind: 'ok' };
+  }
+
+  const date = now.toISOString().slice(0, 10).replace(/-/g, '');
+  const outPath = path.join(projectRoot, '.harness', 'reports', `proposal-${id}-${date}.md`);
+  fs.mkdirSync(path.dirname(outPath), { recursive: true });
+  fs.writeFileSync(outPath, markdown, 'utf-8');
+  log(io, chalk.green(`✅ 提案材料已生成: ${outPath}`));
+  log(io, chalk.gray('   下一步：人工确认 params 无应用内部信息后，拿材料去 harness 仓开 issue（不自动开）'));
+  return { kind: 'ok' };
+}