@dommaker/harness 0.17.0 → 0.18.0

package/src/cli/commands/__tests__/sync-docs.test.ts

@@ -406,6 +406,96 @@ describe('sync-docs command', () => {
       fs.rmSync(testDir, { recursive: true, force: true });
     });
 
+    it('.tsx 登记行指向真实文件时不得误判为已删除（#33），--check 收敛', async () => {
+      const testDir = path.join(tempDir, 'tsx-row');
+      const srcDir = path.join(testDir, 'src', 'components');
+      fs.mkdirSync(srcDir, { recursive: true });
+      // 复刻 studio 场景：同目录混合 .ts 与 .tsx
+      fs.writeFileSync(path.join(srcDir, 'statusClasses.ts'), 'export const statuses = {};');
+      fs.writeFileSync(
+        path.join(srcDir, 'DistillProposalCard.tsx'),
+        'export const DistillProposalCard = () => null;'
+      );
+
+      // 手工登记一行 .tsx 模块（表格格式承诺支持 ts|tsx|js|jsx）
+      fs.writeFileSync(
+        path.join(testDir, 'CAPABILITIES.md'),
+        [
+          '# CAPABILITIES.md', '',
+          '> 最后更新: 2026-01-01', '',
+          '| 模块 | 文件 | 说明 |', '|------|------|------|',
+          '| statusClasses | src/components/statusClasses.ts | 状态类 |',
+          '| DistillProposalCard | src/components/DistillProposalCard.tsx | 人审卡 |',
+          '',
+        ].join('\n')
+      );
+
+      await syncDocs({ projectPath: testDir });
+      const content = fs.readFileSync(path.join(testDir, 'CAPABILITIES.md'), 'utf-8');
+      expect(content).toContain('DistillProposalCard.tsx');
+
+      // 修复前：--check 每跑必报「包含已删除的模块」不收敛
+      consoleSpy.mockClear();
+      const check = await syncDocs({ projectPath: testDir, check: true });
+      expect(check).toBe(true);
+
+      fs.rmSync(testDir, { recursive: true, force: true });
+    });
+
+    it('未登记的 .tsx 源文件应进入 added，写入模式生成表格行', async () => {
+      const testDir = path.join(tempDir, 'tsx-added');
+      const srcDir = path.join(testDir, 'src');
+      fs.mkdirSync(srcDir, { recursive: true });
+      fs.writeFileSync(path.join(srcDir, 'util.ts'), 'export const util = 1;');
+      fs.writeFileSync(path.join(srcDir, 'Card.tsx'), 'export const Card = () => null;');
+
+      fs.writeFileSync(
+        path.join(testDir, 'CAPABILITIES.md'),
+        '# Capabilities\n\n| 模块 | 文件 | 说明 |\n|------|------|------|\n| util | src/util.ts | util |'
+      );
+
+      const check = await syncDocs({ projectPath: testDir, check: true });
+      expect(check).toBe(false);
+      expect(consoleSpy).toHaveBeenCalledWith(expect.stringContaining('Card.tsx'));
+
+      await syncDocs({ projectPath: testDir });
+      const content = fs.readFileSync(path.join(testDir, 'CAPABILITIES.md'), 'utf-8');
+      expect(content).toContain('Card.tsx');
+
+      fs.rmSync(testDir, { recursive: true, force: true });
+    });
+
+    it('真实存在的非扫描扩展名登记行（.js/.jsx）也不得误删（存在性过滤兜底）', async () => {
+      const testDir = path.join(tempDir, 'js-row');
+      const srcDir = path.join(testDir, 'src');
+      fs.mkdirSync(srcDir, { recursive: true });
+      fs.writeFileSync(path.join(srcDir, 'helper.js'), 'module.exports = {};');
+      fs.writeFileSync(path.join(srcDir, 'Helper.jsx'), 'export default () => null;');
+
+      fs.writeFileSync(
+        path.join(testDir, 'CAPABILITIES.md'),
+        [
+          '# CAPABILITIES.md', '',
+          '> 最后更新: 2026-01-01', '',
+          '| 模块 | 文件 | 说明 |', '|------|------|------|',
+          '| helper | src/helper.js | 手工登记 |',
+          '| Helper | src/Helper.jsx | 手工登记 |',
+          '',
+        ].join('\n')
+      );
+
+      await syncDocs({ projectPath: testDir });
+      const content = fs.readFileSync(path.join(testDir, 'CAPABILITIES.md'), 'utf-8');
+      expect(content).toContain('src/helper.js');
+      expect(content).toContain('src/Helper.jsx');
+
+      consoleSpy.mockClear();
+      const check = await syncDocs({ projectPath: testDir, check: true });
+      expect(check).toBe(true);
+
+      fs.rmSync(testDir, { recursive: true, force: true });
+    });
+
     it('basename 碰撞的幽灵条目（文件已删但同名文件存在）也应被移除', async () => {
       const testDir = path.join(tempDir, 'ghost-basename-collision');
       const srcA = path.join(testDir, 'src', 'a');

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

@@ -118,9 +118,9 @@ export function renderExportMarkdown(
 export function renderInjectionDriftLines(drift: InjectionDrift): string[] {
   const lines: string[] = [];
   if (drift.notInjected) {
-    lines.push('  CLAUDE.md 无约束注入标记段（未注入，不算漂移）；可运行 npx harness init 注入');
+    lines.push('  CLAUDE.md 无约束注入标记段（未注入，不算漂移）；可运行 npx @dommaker/harness init 注入');
     if (drift.duplicateHeading) {
-      lines.push('  另检测到多个 "## Governance Rules" 标题（历史遗留重复章节），建议手工清理后重跑 npx harness init');
+      lines.push('  另检测到多个 "## Governance Rules" 标题（历史遗留重复章节），建议手工清理后重跑 npx @dommaker/harness init');
     }
     return lines;
   }

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

@@ -2,17 +2,28 @@
  * harness constraints retire —— 约束退役（ADR-0001 决策 2/5）
  *
  * 建议层全自动（候选诊断复用 report 数据层），执行层保留一次人确认。
- * 落盘形态 = config.yml `enabled: false` + `retired` 元数据（不发明第二套状态）：
+ * 落盘形态（#82 D6 一处真相）：
  *
- *   constraints:
- *     <id>:
- *       enabled: false
- *       retired: { at, reason, stats: { total, fail, failRate } }
+ * - 内置约束 → config.yml `enabled: false` + `retired` 元数据：
+ *
+ *     constraints:
+ *       <id>:
+ *         enabled: false
+ *         retired: { at, reason, stats: { total, fail, failRate } }
+ *
+ * - custom 约束 → custom-constraints.yml 条目内 `retired` 元数据段
+ *   （不拆 config.yml 第二处）：
+ *
+ *     custom_constraints:
+ *       <id>:
+ *         rule: ...
+ *         retired: { at, reason, stats: { total, fail, failRate } }
  *
  * 每条同时写一条 KnowledgeStore 记录（consumptionMode: 'signal'），
  * 并同步 CLAUDE.md 注入段（存在 HARNESS_CONSTRAINTS 标记时）。
  *
- * retire 不是删除——恢复方法：删除 config.yml 中 constraints.<id> 段。
+ * retire 不是删除——恢复方法：内置删 config.yml 中 constraints.<id> 段；
+ * custom 删 custom-constraints.yml 中 custom_constraints.<id>.retired 段。
  *
  * 交互与执行分离：retireConstraint 为纯执行逻辑（同步、可测），
  * runRetireInteractive 只做 readline 交互，IO 流可注入。
@@ -36,7 +47,6 @@ import {
   readProjectTraces,
   type RetireCandidate,
 } from '../../core/constraints/usage-report';
-import { getConstraintsMeta } from './constraints';
 
 export interface RetireExecuteOptions {
   /** 退役原因（可空） */
@@ -52,6 +62,8 @@ export interface RetireResult {
   status: RetireStatus;
   /** 是否 check 层 iron（交互模式据此追加确认） */
   isIronLaw: boolean;
+  /** 退役落点：custom 约束落 custom-constraints.yml（#82 D6），内置落 config.yml */
+  landing: 'config.yml' | 'custom-constraints.yml';
   stats: { total: number; fail: number; failRate: number };
   /** CLAUDE.md 注入段是否已同步 */
   claudeMdSynced: boolean;
@@ -62,9 +74,12 @@ export interface RetireResult {
 export interface ConstraintsRetireOptions {
   projectPath?: string;
   reason?: string;
+  /** 直达模式显式确认（--yes）：ADR-0001 决策 2 人确认闸门，无此 flag 直达拒绝执行 */
+  yes?: boolean;
 }
 
 interface RetireTargetInfo {
+  source: 'builtin' | 'custom';
   isIronLaw: boolean;
   level: Constraint['level'];
   description?: string;
@@ -80,6 +95,7 @@ function findRetireTarget(projectRoot: string, id: string): RetireTargetInfo | u
   const builtIn = getConstraint(id);
   if (builtIn) {
     return {
+      source: 'builtin',
       isIronLaw: builtIn.kind === 'check' && builtIn.level === 'iron_law',
       level: builtIn.level,
       description: builtIn.description,
@@ -95,11 +111,13 @@ function findRetireTarget(projectRoot: string, id: string): RetireTargetInfo | u
   if (custom) {
     const level = custom.level || 'guideline';
     return {
+      source: 'custom',
       isIronLaw: false, // custom 约束统一 kind='prompt'（无 checker），不存在 check 层 iron
       level,
       description: custom.description,
       rule: custom.rule,
       message: custom.message,
+      promptInjection: custom.promptInjection,
     };
   }
 
@@ -151,6 +169,41 @@ function writeRetireConfig(
   }
 }
 
+/**
+ * 写 custom-constraints.yml 退役段（#82 D6 统一落点）
+ *
+ * 在 custom_constraints.<id> 条目内追加 retired 元数据，保留规则原文。
+ * js-yaml 不保留注释：原文件含注释行时重写会丢失，console 说明。
+ */
+function writeCustomRetireYml(
+  projectRoot: string,
+  fileName: string,
+  id: string,
+  retiredMeta: { at: string; reason: string; stats: { total: number; fail: number; failRate: number } }
+): void {
+  const filePath = path.join(projectRoot, '.harness', fileName);
+
+  let raw: Record<string, unknown> = {};
+  let hadComments = false;
+  if (fs.existsSync(filePath)) {
+    const original = fs.readFileSync(filePath, 'utf-8');
+    hadComments = original.split('\n').some(l => l.trimStart().startsWith('#'));
+    raw = (yaml.load(original) as Record<string, unknown>) ?? {};
+  }
+
+  const customs = (raw.custom_constraints ?? {}) as Record<string, Record<string, unknown>>;
+  const prev = customs[id] ?? {};
+  customs[id] = { ...prev, retired: retiredMeta };
+  raw.custom_constraints = customs;
+
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, yaml.dump(raw, { lineWidth: 120 }), 'utf-8');
+
+  if (hadComments) {
+    console.log(chalk.yellow('   ⚠️  custom-constraints.yml 已重写：js-yaml 不保留原文件注释'));
+  }
+}
+
 /**
  * 写 KnowledgeStore 退役记录（consumptionMode: 'signal'）
  */
@@ -251,15 +304,24 @@ export function retireConstraint(
 
   const target = findRetireTarget(projectRoot, id);
   const emptyStats = { total: 0, fail: 0, failRate: 0 };
+  const landing: RetireResult['landing'] =
+    target?.source === 'custom' ? 'custom-constraints.yml' : 'config.yml';
   if (!target) {
-    return { id, status: 'unknown_id', isIronLaw: false, stats: emptyStats, claudeMdSynced: false };
+    return { id, status: 'unknown_id', isIronLaw: false, landing, stats: emptyStats, claudeMdSynced: false };
   }
 
-  // 已退役保护（config.yml constraints.<id>.enabled === false）
+  // 已退役保护：内置看 config.yml constraints.<id>.enabled === false；
+  // custom 看 yml 条目 retired 元数据（历史落点 config.yml 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 };
+  if (target.source === 'custom') {
+    const loader = new ProjectConfigLoader(projectRoot);
+    loader.load();
+    if (loader.getCustomConstraints()[id]?.retired || existing?.enabled === false) {
+      return { id, status: 'already_retired', isIronLaw: target.isIronLaw, landing, stats: emptyStats, claudeMdSynced: false };
+    }
+  } else if (existing?.enabled === false) {
+    return { id, status: 'already_retired', isIronLaw: target.isIronLaw, landing, stats: emptyStats, claudeMdSynced: false };
   }
 
   // 历史统计（来自 traces.log）
@@ -271,8 +333,15 @@ export function retireConstraint(
     failRate: evaluated > 0 ? (usage!.fail / evaluated) : 0,
   };
 
-  // 1. config.yml
-  writeRetireConfig(projectRoot, id, { at: iso, reason, stats });
+  // 1. 落盘退役（custom → yml 条目 retired 段；内置 → config.yml，原文均保留）
+  if (target.source === 'custom') {
+    const loader = new ProjectConfigLoader(projectRoot);
+    loader.load();
+    const customFile = loader.getConfig().custom_constraints_file ?? 'custom-constraints.yml';
+    writeCustomRetireYml(projectRoot, customFile, id, { at: iso, reason, stats });
+  } else {
+    writeRetireConfig(projectRoot, id, { at: iso, reason, stats });
+  }
 
   // 2. KnowledgeStore
   const knowledgeEntryId = saveRetireKnowledge(projectRoot, id, target, reason, stats, iso);
@@ -280,7 +349,7 @@ export function retireConstraint(
   // 3. CLAUDE.md 注入段同步
   const claudeMdSynced = syncClaudeMdInjection(projectRoot);
 
-  return { id, status: 'retired', isIronLaw: target.isIronLaw, stats, claudeMdSynced, knowledgeEntryId };
+  return { id, status: 'retired', isIronLaw: target.isIronLaw, landing, stats, claudeMdSynced, knowledgeEntryId };
 }
 
 /**
@@ -294,14 +363,20 @@ export function printRetireResult(result: RetireResult): void {
     case 'already_retired':
       console.log(chalk.yellow(`⚠️  ${result.id}: 已处于退役状态（config.yml 中 enabled: false），跳过`));
       return;
-    case 'retired':
+    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} 段`));
+      const recovery =
+        result.landing === 'custom-constraints.yml'
+          ? `删除 custom-constraints.yml 中 custom_constraints.${result.id}.retired 段`
+          : `删除 config.yml 中 constraints.${result.id} 段`;
+      console.log(chalk.gray(`   retire 不是删除——恢复方法：${recovery}`));
+      break;
+    }
   }
 }
 
@@ -376,7 +451,7 @@ export async function runRetireInteractive(
     }
 
     // 逐条收集 reason + iron 二次确认
-    const plan: { id: string; reason: string }[] = [];
+    const plan: { id: string; reason: string; source: RetireTargetInfo['source'] }[] = [];
     for (const id of selectedIds) {
       const target = findRetireTarget(projectRoot, id);
       if (!target) {
@@ -391,7 +466,7 @@ export async function runRetireInteractive(
         }
       }
       const reason = await ask(`退役原因（${id}，可留空）: `);
-      plan.push({ id, reason });
+      plan.push({ id, reason, source: target.source });
     }
 
     if (plan.length === 0) {
@@ -403,7 +478,11 @@ export async function runRetireInteractive(
     console.log();
     console.log(chalk.bold('将执行以下变更:'));
     for (const p of plan) {
-      console.log(`  - config.yml: constraints.${p.id}.enabled=false + retired 元数据（原因: ${p.reason || '（空）'}）`);
+      if (p.source === 'custom') {
+        console.log(`  - custom-constraints.yml: custom_constraints.${p.id}.retired 元数据（原因: ${p.reason || '（空）'}）`);
+      } else {
+        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 标记段则同步重渲染');
@@ -425,15 +504,29 @@ export async function runRetireInteractive(
 
 /**
  * CLI handler: harness constraints retire [id]
+ *
+ * 人确认闸门（#24，ADR-0001 决策 2）：带 id 的直达路径必须显式 `--yes`，
+ * 无 `--yes` 报错 + 非零退出码，提示改用 `--yes` 或交互模式；不落盘任何文件。
  */
 export async function constraintsRetire(id?: string, options: ConstraintsRetireOptions = {}): Promise<void> {
   const projectRoot = options.projectPath || process.cwd();
 
   if (id) {
-    // 非交互直达
+    // 非交互直达：执行层人确认对所有入口成立（含程序化调用方）
+    if (!options.yes) {
+      console.error(
+        chalk.red(`❌ 直达退役需要显式人确认（ADR-0001 决策 2：执行层保留一次人确认），未做任何变更\n`) +
+          `   带 --yes 显式确认直达：harness constraints retire ${id} --yes` +
+          `${options.reason ? ` --reason "${options.reason}"` : ''}\n` +
+          `   或去掉 id 走交互确认：harness constraints retire`
+      );
+      process.exitCode = 1;
+      return;
+    }
+
     const result = retireConstraint(projectRoot, id, { reason: options.reason });
     if (result.status === 'retired' && result.isIronLaw) {
-      console.log(chalk.yellow(`⚠️  ${id} 是一条 Iron Law，已通过命令行直接退役（交互模式会要求二次确认）`));
+      console.log(chalk.yellow(`⚠️  ${id} 是一条 Iron Law，已通过 --yes 直达退役（交互模式会要求二次确认）`));
     }
     printRetireResult(result);
     return;

package/src/cli/commands/doc-freshness-check.ts

@@ -358,7 +358,7 @@ export async function docFreshnessCheck(
   const content = fs.readFileSync(resolvedPath, 'utf-8');
 
   // 提取声明
-  let claims = extractClaims(content, resolvedPath);
+  const claims = extractClaims(content, resolvedPath);
 
   // 如果指定了变更文件，只验证与变更文件相关的声明
   if (options.changedFiles) {

package/src/cli/commands/init.ts

@@ -256,7 +256,7 @@ function printSnippets(): void {
   console.log();
   console.log(chalk.cyan(GITHUB_ACTIONS_SNIPPET));
   
-  console.log(chalk.blue('💡 提示: 运行 harness init 自动创建配置文件'));
+  console.log(chalk.blue('💡 提示: 运行 npx @dommaker/harness init 自动创建配置文件'));
 }
 
 /**
@@ -264,7 +264,7 @@ function printSnippets(): void {
  */
 const PRE_COMMIT_SNIPPET = `
 # Harness 约束检查
-npx harness check --staged
+npx @dommaker/harness check --staged
 if [ $? -ne 0 ]; then
   echo "❌ Iron law check failed"
   exit 1
@@ -273,11 +273,11 @@ fi
 # Plan coverage check (via PostEval)
 STAGED=$(git diff --cached --name-only --diff-filter=ACMR 2>/dev/null || true)
 if command -v npx > /dev/null 2>&1; then
-  PLAN_FILES=$(echo "$STAGED" | grep -E 'plans/.*\.md$|\.plan\.md$' || true)
+  PLAN_FILES=$(echo "$STAGED" | grep -E 'plans/.*\\.md$|\\.plan\\.md$' || true)
   if [ -n "$PLAN_FILES" ]; then
     echo "📋 Checking plan coverage..."
     for plan in $PLAN_FILES; do
-      npx harness posteval-plan "$plan" || {
+      npx @dommaker/harness posteval-plan "$plan" || {
         echo "🛑 Plan coverage incomplete. See above for missed items."
         exit 1
       }
@@ -298,7 +298,7 @@ const GITHUB_ACTIONS_SNIPPET = `
         with:
           node-version: '20'
       - run: npm ci
-      - run: npx harness check
+      - run: npx @dommaker/harness check
 `;
 
 /**
@@ -313,7 +313,7 @@ async function setupGitHooks(projectPath: string): Promise<void> {
     await fs.access(gitDir);
   } catch {
     console.log(chalk.yellow('⚠️  未检测到 Git 仓库，跳过 Git hooks'));
-    console.log(chalk.gray('💡 初始化 Git 后可运行 harness init --print-snippets 查看配置'));
+    console.log(chalk.gray('💡 初始化 Git 后可运行 npx @dommaker/harness init --print-snippets 查看配置'));
     return;
   }
 
@@ -337,7 +337,7 @@ echo "🔍 Running harness checks..."
 STAGED=$(git diff --cached --name-only --diff-filter=ACMR 2>/dev/null || true)
 
 # 铁律检查
-npx harness check --staged
+npx @dommaker/harness check --staged
 if [ $? -ne 0 ]; then
   echo "❌ Iron law check failed"
   exit 1
@@ -349,7 +349,7 @@ if command -v npx > /dev/null 2>&1; then
   if [ -n "$PLAN_FILES" ]; then
     echo "📋 Checking plan coverage..."
     for plan in $PLAN_FILES; do
-      npx harness posteval-plan "$plan" || {
+      npx @dommaker/harness posteval-plan "$plan" || {
         echo "🛑 Plan coverage incomplete. See above for missed items."
         exit 1
       }
@@ -413,13 +413,13 @@ jobs:
         run: npm ci
 
       - name: Run harness check
-        run: npx harness check
+        run: npx @dommaker/harness check
 
       - name: Run harness validate
-        run: npx harness validate
+        run: npx @dommaker/harness validate
 
       - name: Run harness passes-gate
-        run: npx harness passes-gate
+        run: npx @dommaker/harness passes-gate
 `;
 
   await fs.writeFile(workflowPath, workflowContent, 'utf-8');
@@ -820,7 +820,7 @@ async function setupGovernanceWorkflow(projectPath: string, level: string): Prom
   const docsCheckStep = level !== 'minimal'
     ? `
       - name: Check docs freshness
-        run: npx harness sync-docs --check
+        run: npx @dommaker/harness sync-docs --check
         continue-on-error: true`
     : '';
 
@@ -848,10 +848,10 @@ jobs:
         run: npm ci
 
       - name: Constraint check
-        run: npx harness check
+        run: npx @dommaker/harness check
 
       - name: Quality gate
-        run: npx harness passes-gate
+        run: npx @dommaker/harness passes-gate
 ${docsCheckStep}
 `;
 

package/src/cli/commands/sync-docs/index.ts

@@ -93,7 +93,7 @@ export async function syncDocs(options: SyncDocsOptions): Promise<boolean> {
 
   // 1. 扫描源码模块（从 governance config 读取目录列表，默认 src/）
   const srcDirs = await getSourceDirs(projectPath);
-  let currentModules: ModuleInfo[] = [];
+  const currentModules: ModuleInfo[] = [];
   for (const srcDir of srcDirs) {
     try {
       const modules = await scanSourceModules(path.join(projectPath, srcDir), projectPath);
@@ -166,17 +166,30 @@ export async function syncDocs(options: SyncDocsOptions): Promise<boolean> {
         )
         .map(m => getBasename(m.file));
     }
-    result.removed = existingFileNames.filter(f => !currentBasenames.includes(f));
+    // removed：basename 对比 + 全路径存在性兜底（#33）。
+    // 表格格式承诺 ts|tsx|js|jsx，但扫描只覆盖 .ts/.tsx——
+    // 指向真实存在文件的登记行（.js/.jsx 等扫描盲区）不得误判为「已删除」。
+    // 兜底按 basename 豁免；路径不存在的幽灵行进不了豁免，由下方清扫按完整路径补入 removed。
+    const sourceRoots = detectSourceRoots(projectPath);
+    const entryExists = (entry: string): boolean =>
+      existsSync(path.join(projectPath, entry)) ||
+      sourceRoots.some(root => existsSync(path.join(projectPath, root, entry)));
+
+    const registeredEntries = readCapabilitiesEntries(capabilitiesPath);
+    const livePathBasenames = new Set(
+      registeredEntries
+        .filter(e => !e.endsWith('/') && e.includes('/') && entryExists(e))
+        .map(getBasename)
+    );
+    result.removed = existingFileNames.filter(
+      f => !currentBasenames.includes(f) && !livePathBasenames.has(f)
+    );
 
     // 幽灵条目清扫（2026-08-08 studio CI 4 连红事故）：上方按 basename 对比，
     // 同名碰撞时幽灵不可见（如 agent-configs/routes.ts 已删但 agents/routes.ts 仍存在，
     // basename routes.ts 仍在扫描结果中，永远不会被判 removed）。
     // 这里按完整路径直接判存在性（与 docs_freshness 检查器同语义：项目根 + 源码根前缀）。
-    const sourceRoots = detectSourceRoots(projectPath);
-    const entryExists = (entry: string): boolean =>
-      existsSync(path.join(projectPath, entry)) ||
-      sourceRoots.some(root => existsSync(path.join(projectPath, root, entry)));
-    for (const entry of readCapabilitiesEntries(capabilitiesPath)) {
+    for (const entry of registeredEntries) {
       // 纯文件名条目（无路径）无法用存在性判定，交由上方 basename 对比
       if (!entry.includes('/') || entryExists(entry)) continue;
       const basename = entry.split('/').pop()!;

package/src/cli/commands/sync-docs/project-reader.ts

@@ -7,7 +7,7 @@ import { existsSync } from 'fs';
 import * as path from 'path';
 import { loadRawProjectConfig } from '../../../core/project-config-loader';
 import { detectSourceRoots } from '../../../utils/detect-source-roots';
-import { findTsSourceFiles } from '../../../utils/file-walk';
+import { findTsSourceFiles, isTsSourceFile } from '../../../utils/file-walk';
 
 export interface ModuleInfo {
   name: string;
@@ -115,18 +115,20 @@ export async function scanSourceModules(srcDir: string, projectPath: string): Pr
     const stat = await fs.stat(entryPath);
 
     if (stat.isDirectory()) {
-      // 子目录：递归扫描 .ts 文件（不报告目录条目本身）
-      const subFiles = findTsSourceFiles(entryPath, { skipIndex: true });
+      // 子目录：递归扫描 .ts/.tsx 文件（不报告目录条目本身）
+      // includeTsx 开启后，历史项目未登记过的 .tsx 会首次批量进入 added（#33 已知连带，
+      // 与 .ts 同口径属预期，一次性补登记即可）
+      const subFiles = findTsSourceFiles(entryPath, { skipIndex: true, includeTsx: true });
       for (const f of subFiles) {
         modules.push({
-          name: path.basename(f, '.ts'),
+          name: path.basename(f, path.extname(f)),
           file: path.relative(projectPath, f),
           description: await extractFileDescription(f),
         });
       }
-    } else if (entry.endsWith('.ts') && !entry.endsWith('.d.ts') && entry !== 'index.ts') {
+    } else if (isTsSourceFile(entry, { skipIndex: true, includeTsx: true })) {
       modules.push({
-        name: path.basename(entry, '.ts'),
+        name: path.basename(entry, path.extname(entry)),
         file: path.relative(projectPath, entryPath),
         description: await extractFileDescription(entryPath),
       });
@@ -142,9 +144,9 @@ export async function scanSourceModules(srcDir: string, projectPath: string): Pr
 async function extractFileDescription(filePath: string): Promise<string> {
   try {
     const content = await fs.readFile(filePath, 'utf-8');
-    return extractFirstComment(content) || path.basename(filePath, '.ts');
+    return extractFirstComment(content) || path.basename(filePath, path.extname(filePath));
   } catch {
-    return path.basename(filePath, '.ts');
+    return path.basename(filePath, path.extname(filePath));
   }
 }
 

package/src/cli/commands/validate.ts

@@ -165,15 +165,15 @@ export async function createExampleCheckpoint(projectPath: string): Promise<void
 const DEFAULT_RESOLUTIONS = {
   no_fuzzy_completion_claim: {
     title: 'commit message 缺少验证证据',
-    fix: '在 commit message body 中附上验证输出:\n`npx harness check --staged` | `npx harness validate` | `npm test -- --coverage`\n确认全部通过后重新 commit。',
+    fix: '在 commit message body 中附上验证输出:\n`npx @dommaker/harness check --staged` | `npx @dommaker/harness validate` | `npm test -- --coverage`\n确认全部通过后重新 commit。',
   },
   capability_sync: {
     title: '缺少 CAPABILITIES.md',
-    fix: '在项目根目录创建 CAPABILITIES.md，列出所有模块能力清单。运行 `npx harness sync-docs` 可自动生成模板。',
+    fix: '在项目根目录创建 CAPABILITIES.md，列出所有模块能力清单。运行 `npx @dommaker/harness sync-docs` 可自动生成模板。',
   },
   context_doc_sync: {
     title: '关键目录缺少 CONTEXT.md',
-    fix: '在 required_dirs 目录下创建 CONTEXT.md。运行 `npx harness sync-docs` 可自动生成模板。',
+    fix: '在 required_dirs 目录下创建 CONTEXT.md。运行 `npx @dommaker/harness sync-docs` 可自动生成模板。',
   },
 };
 

package/src/cli/session-mining/text.ts

@@ -99,7 +99,7 @@ export function stripCodeBlocks(text: string): string {
 
 /** 是否纯标点/空白 */
 export function isPunctuation(str: string): boolean {
-  return /^[，。！？、；：""''（）\[\]【】「」『』《》〈〉\s]+$/.test(str);
+  return /^[，。！？、；：""''（）[\]【】「」『』《》〈〉\s]+$/.test(str);
 }
 
 /** 是否含语义内容（汉字，或 ≥7 字符的合法英文标识词） */

package/src/context/__tests__/progressive-loader.test.ts

@@ -18,7 +18,7 @@ describe('ProgressiveLoader', () => {
 
       await loader.loadInChunks(items, {
         chunkSize: 20,
-        onChunk: (chunk, index) => { chunks.push(chunk); },
+        onChunk: (chunk) => { chunks.push(chunk); },
       });
 
       expect(chunks.length).toBe(5);
@@ -45,7 +45,7 @@ describe('ProgressiveLoader', () => {
       await loader.loadInChunks(items, {
         chunkSize: 5,
         parallel: true,
-        onChunk: (chunk, index) => { chunks.push(chunk); },
+        onChunk: (chunk) => { chunks.push(chunk); },
       });
 
       expect(chunks.length).toBe(4);
@@ -78,7 +78,7 @@ describe('ProgressiveLoader', () => {
 
       await loader.loadInChunks(items, {
         chunkSize: 10,
-        onChunk: (chunk, index) => { chunks.push(chunk); },
+        onChunk: (chunk) => { chunks.push(chunk); },
       });
 
       expect(chunks.length).toBe(3);
@@ -171,7 +171,7 @@ describe('ProgressiveLoader', () => {
     it('should handle empty items', async () => {
       const result = await loader.loadWithBudget([], {
         budget: 100,
-        estimator: (item) => 0,
+        estimator: () => 0,
       });
 
       expect(result.items.length).toBe(0);
@@ -241,7 +241,7 @@ describe('ProgressiveLoader', () => {
         return n * 2;
       };
 
-      const results = await loader.processBatch(items, processor, 1);
+      await loader.processBatch(items, processor, 1);
 
       // Check that all items were processed
       expect(processed.sort()).toEqual([1, 2, 3]);
@@ -256,7 +256,7 @@ describe('progressiveLoader (default instance)', () => {
 
     await progressiveLoader.loadInChunks(items, {
       chunkSize: 1,
-      onChunk: (chunk, index) => { chunks.push(chunk); return undefined; },
+      onChunk: (chunk) => { chunks.push(chunk); return undefined; },
     });
 
     expect(chunks.length).toBe(3);