@dommaker/harness 0.14.0 → 0.16.1

package/src/cli/commands/spec-baseline-check.ts

@@ -0,0 +1,384 @@
+/**
+ * harness spec-baseline-check 命令
+ *
+ * 验证 spec 文件的前置条件（Baseline / 前置条件）是否满足。
+ * 纯代码操作，零 LLM 调用。
+ */
+
+import chalk from 'chalk';
+import * as fs from 'fs';
+import * as path from 'path';
+
+export interface SpecBaselineCheckOptions {
+  /** 项目路径 */
+  projectPath?: string;
+  /** 输出 JSON 格式 */
+  json?: boolean;
+}
+
+/** 前置条件验证结果 */
+export interface PrerequisiteResult {
+  /** 前置条件描述 */
+  prerequisite: string;
+  /** 是否满足 */
+  satisfied: boolean;
+  /** 证据 */
+  evidence: string;
+}
+
+// ============================================
+// 解析器
+// ============================================
+
+/**
+ * 从 spec 内容中提取 Baseline/前置条件 section
+ */
+export function extractBaselineSection(content: string): string[] {
+  const lines = content.split('\n');
+  const prerequisites: string[] = [];
+
+  // 查找 ## Baseline 或 ## 前置条件 section
+  let inSection = false;
+  let sectionLevel = 0;
+
+  for (const line of lines) {
+    const headerMatch = line.match(/^(#{1,6})\s+(.+)/);
+
+    if (headerMatch) {
+      const level = headerMatch[1].length;
+      const title = headerMatch[2].trim();
+
+      // 检查是否是目标 section
+      if (/^(Baseline|前置条件|Prerequisites|Prereqs)$/i.test(title)) {
+        inSection = true;
+        sectionLevel = level;
+        continue;
+      }
+
+      // 同级或更高级的标题结束 section
+      if (inSection && level <= sectionLevel) {
+        inSection = false;
+        continue;
+      }
+    }
+
+    // 在 section 中提取列表项
+    if (inSection) {
+      const listMatch = line.match(/^\s*[-*+]\s+(.+)/);
+      if (listMatch) {
+        prerequisites.push(listMatch[1].trim());
+      }
+      // 也支持编号列表
+      const numberedMatch = line.match(/^\s*\d+\.\s+(.+)/);
+      if (numberedMatch) {
+        prerequisites.push(numberedMatch[1].trim());
+      }
+    }
+  }
+
+  return prerequisites;
+}
+
+// ============================================
+// 验证器
+// ============================================
+
+/**
+ * 检查文件/目录是否存在
+ */
+function checkFileExists(pattern: string, projectPath: string): { exists: boolean; evidence: string } {
+  // 提取路径引用（反引号中的路径、引号中的路径、或直接的路径模式）
+  const pathPatterns = [
+    /`([^`]+\.[a-z]+)`/g,           // `src/foo.ts`
+    /["']([^"']+\.[a-z]+)["']/g,    // "src/foo.ts"
+    /`([^`]+\/)`/g,                  // `src/foo/`
+    /(\S+\/\S+\.[a-z]+)/g,          // src/foo.ts
+  ];
+
+  const paths: string[] = [];
+  for (const p of pathPatterns) {
+    p.lastIndex = 0;
+    let m;
+    while ((m = p.exec(pattern)) !== null) {
+      paths.push(m[1]);
+    }
+  }
+
+  if (paths.length === 0) {
+    return { exists: false, evidence: '无法从描述中提取路径' };
+  }
+
+  const found: string[] = [];
+  const missing: string[] = [];
+
+  for (const p of paths) {
+    const fullPath = path.resolve(projectPath, p);
+    if (fs.existsSync(fullPath)) {
+      found.push(p);
+    } else {
+      missing.push(p);
+    }
+  }
+
+  if (missing.length === 0 && found.length > 0) {
+    return { exists: true, evidence: `文件存在: ${found.join(', ')}` };
+  }
+  if (found.length > 0) {
+    return { exists: false, evidence: `部分存在: ${found.join(', ')}; 缺失: ${missing.join(', ')}` };
+  }
+  return { exists: false, evidence: `文件不存在: ${missing.join(', ')}` };
+}
+
+/**
+ * 检查代码中是否存在特定模式
+ */
+function checkCodePattern(pattern: string, projectPath: string): { exists: boolean; evidence: string } {
+  // 从描述中提取关键词
+  const keywords: string[] = [];
+
+  // 提取反引号中的代码
+  const codePatterns = pattern.match(/`([^`]+)`/g);
+  if (codePatterns) {
+    for (const cp of codePatterns) {
+      const inner = cp.slice(1, -1);
+      if (inner.length >= 2) {
+        keywords.push(inner);
+      }
+    }
+  }
+
+  // 提取 "implemented" / "exists" / "已实现" 等关键词后的内容
+  const implMatch = pattern.match(/(?:implemented|exists|已实现|已完成|已存在)[\s:：]+(.+)/i);
+  if (implMatch) {
+    keywords.push(implMatch[1].trim());
+  }
+
+  if (keywords.length === 0) {
+    return { exists: false, evidence: '无法从描述中提取搜索关键词' };
+  }
+
+  const found: string[] = [];
+  const notFound: string[] = [];
+
+  for (const kw of keywords) {
+    let count = 0;
+    function walkDir(dir: string) {
+      let entries: fs.Dirent[];
+      try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+      } catch {
+        return;
+      }
+      for (const entry of entries) {
+        if (entry.name.startsWith('.') || entry.name === 'node_modules' || entry.name === 'dist') continue;
+        const fullPath = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+          walkDir(fullPath);
+        } else if (entry.isFile() && (fullPath.endsWith('.ts') || fullPath.endsWith('.js'))) {
+          try {
+            const content = fs.readFileSync(fullPath, 'utf-8');
+            if (content.includes(kw)) count++;
+          } catch { /* skip */ }
+        }
+      }
+    }
+    walkDir(projectPath);
+    if (count > 0) {
+      found.push(`${kw} (${count} files)`);
+    } else {
+      notFound.push(kw);
+    }
+  }
+
+  if (notFound.length === 0 && found.length > 0) {
+    return { exists: true, evidence: `代码中找到: ${found.join(', ')}` };
+  }
+  if (found.length > 0) {
+    return { exists: false, evidence: `找到: ${found.join(', ')}; 未找到: ${notFound.join(', ')}` };
+  }
+  return { exists: false, evidence: `代码中未找到: ${notFound.join(', ')}` };
+}
+
+/**
+ * 检查包依赖是否安装
+ */
+function checkDependency(pattern: string, projectPath: string): { exists: boolean; evidence: string } {
+  // 提取包名
+  const pkgPatterns = [
+    /`(@?[\w-]+\/[\w-]+)`/g,      // `@scope/pkg` or `pkg-name`
+    /`([\w-]+)`/g,                  // `pkg`
+    /install(?:ed)?\s+(\S+)/gi,    // installed pkg-name
+  ];
+
+  const packages: string[] = [];
+  for (const p of pkgPatterns) {
+    p.lastIndex = 0;
+    let m;
+    while ((m = p.exec(pattern)) !== null) {
+      const pkg = m[1];
+      if (pkg.length >= 2 && !pkg.includes('/') && !pkg.includes('.')) {
+        packages.push(pkg);
+      }
+    }
+  }
+
+  if (packages.length === 0) {
+    return { exists: false, evidence: '无法从描述中提取包名' };
+  }
+
+  const found: string[] = [];
+  const missing: string[] = [];
+
+  const pkgJsonPath = path.join(projectPath, 'package.json');
+  let deps: Record<string, string> = {};
+
+  try {
+    const pkgJson = JSON.parse(fs.readFileSync(pkgJsonPath, 'utf-8'));
+    deps = { ...pkgJson.dependencies, ...pkgJson.devDependencies };
+  } catch {
+    return { exists: false, evidence: '无法读取 package.json' };
+  }
+
+  for (const pkg of packages) {
+    if (deps[pkg] || deps[`@types/${pkg}`]) {
+      found.push(pkg);
+    } else {
+      // 检查 node_modules
+      const nmPath = path.join(projectPath, 'node_modules', pkg);
+      if (fs.existsSync(nmPath)) {
+        found.push(pkg);
+      } else {
+        missing.push(pkg);
+      }
+    }
+  }
+
+  if (missing.length === 0 && found.length > 0) {
+    return { exists: true, evidence: `依赖已安装: ${found.join(', ')}` };
+  }
+  if (found.length > 0) {
+    return { exists: false, evidence: `已安装: ${found.join(', ')}; 缺失: ${missing.join(', ')}` };
+  }
+  return { exists: false, evidence: `依赖缺失: ${missing.join(', ')}` };
+}
+
+/**
+ * 综合验证一条前置条件
+ */
+function verifyPrerequisite(prereq: string, projectPath: string): PrerequisiteResult {
+  const lower = prereq.toLowerCase();
+
+  // 路径/文件存在性检查
+  if (lower.includes('文件') || lower.includes('file') || lower.includes('目录') || lower.includes('directory')
+    || /`[^`]+\.[a-z]+`/.test(prereq) || /\//.test(prereq)) {
+    const { exists, evidence } = checkFileExists(prereq, projectPath);
+    if (exists || evidence.includes('文件不存在')) {
+      return { prerequisite: prereq, satisfied: exists, evidence };
+    }
+  }
+
+  // 依赖检查
+  if (lower.includes('依赖') || lower.includes('install') || lower.includes('package') || lower.includes('npm')) {
+    const { exists, evidence } = checkDependency(prereq, projectPath);
+    return { prerequisite: prereq, satisfied: exists, evidence };
+  }
+
+  // 代码模式检查
+  if (lower.includes('实现') || lower.includes('implement') || lower.includes('exist')
+    || lower.includes('已') || lower.includes('必须')
+    || /`[^`]+`/.test(prereq)) {
+    const { exists, evidence } = checkCodePattern(prereq, projectPath);
+    return { prerequisite: prereq, satisfied: exists, evidence };
+  }
+
+  // 默认：无法自动验证
+  return {
+    prerequisite: prereq,
+    satisfied: true,
+    evidence: '无法自动验证（需人工确认）',
+  };
+}
+
+// ============================================
+// 输出格式化
+// ============================================
+
+function formatTable(results: PrerequisiteResult[]): string {
+  if (results.length === 0) return chalk.yellow('未找到 Baseline / 前置条件 section');
+
+  const lines: string[] = [];
+  lines.push(chalk.blue(`前置条件检查 (${results.length} 条)\n`));
+
+  const satisfied = results.filter(r => r.satisfied).length;
+  const failed = results.filter(r => !r.satisfied);
+
+  lines.push(chalk.bold(`  满足: ${satisfied}/${results.length}`));
+  if (failed.length > 0) {
+    lines.push(chalk.red(`  未满足: ${failed.length}\n`));
+  } else {
+    lines.push(chalk.green('  全部满足\n'));
+  }
+
+  for (const r of results) {
+    const icon = r.satisfied ? chalk.green('✓') : chalk.red('✗');
+    lines.push(`  ${icon} ${r.prerequisite}`);
+    if (!r.satisfied) {
+      lines.push(`    ${chalk.yellow(r.evidence)}`);
+    }
+  }
+
+  return lines.join('\n');
+}
+
+// ============================================
+// 主入口
+// ============================================
+
+/**
+ * spec-baseline-check CLI 命令
+ */
+export async function specBaselineCheck(
+  specPath: string,
+  options: SpecBaselineCheckOptions = {},
+): Promise<void> {
+  // 验证文件存在
+  const resolvedPath = path.resolve(specPath);
+  if (!fs.existsSync(resolvedPath)) {
+    console.error(chalk.red(`文件不存在: ${resolvedPath}`));
+    process.exitCode = 1;
+    return;
+  }
+
+  const projectPath = options.projectPath || path.dirname(resolvedPath);
+
+  // 读取 spec
+  const content = fs.readFileSync(resolvedPath, 'utf-8');
+
+  // 提取前置条件
+  const prerequisites = extractBaselineSection(content);
+
+  if (prerequisites.length === 0) {
+    if (options.json) {
+      console.log(JSON.stringify({ prerequisites: [], message: '未找到 Baseline / 前置条件 section' }, null, 2));
+    } else {
+      console.log(chalk.yellow('未找到 ## Baseline 或 ## 前置条件 section'));
+    }
+    return;
+  }
+
+  // 验证每条前置条件
+  const results = prerequisites.map(p => verifyPrerequisite(p, projectPath));
+
+  // 输出
+  if (options.json) {
+    console.log(JSON.stringify(results, null, 2));
+  } else {
+    console.log(formatTable(results));
+  }
+
+  // 有未满足的前置条件时 exit 1
+  const failed = results.filter(r => !r.satisfied);
+  if (failed.length > 0) {
+    process.exitCode = 1;
+  }
+}

package/src/context/__tests__/knowledge-injector.test.ts

@@ -4,7 +4,7 @@
 
 import { KnowledgeInjector } from '../knowledge-injector';
 import { KnowledgeQuery } from '../../knowledge/query';
-import { KnowledgeStore } from '../../knowledge/store';
+import { FileKnowledgeStore as KnowledgeStore } from '../../knowledge/store';
 import * as fs from 'fs';
 import * as path from 'path';
 import * as os from 'os';

package/src/core/constraints/checker.ts

@@ -256,7 +256,7 @@ export class ConstraintChecker {
         // 检查是否有需求文档
         return context.hasRequirement === true;
 
-      case 'must_use_worktree':
+      case 'prefer_worktree':
         // 检查是否在 worktree 中执行
         return context.hasWorktree === true;
 

package/src/core/constraints/definitions.ts

@@ -238,31 +238,6 @@ https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agent
     promptInjection: '开始编写代码前，必须确认：需求来源明确（Spec/Issue/Roadmap/用户指令）、验收标准(AC)已定义、边界情况已明确。不要凭假设或猜测开始实现。',
   },
 
-  /**
-   * 必须在 worktree 中开发
-   * 原因：隔离工作区，安全回滚，并行开发
-   * 来源：Superpowers must_use_worktree
-   */
-  must_use_worktree: {
-    id: 'must_use_worktree',
-    rule: 'CODE CHANGES MUST BE ISOLATED IN A WORKTREE',
-    message: '代码开发必须在隔离的 worktree 中进行',
-    level: 'iron_law',
-    trigger: ['code_implementation'],
-    enforcement: 'check-worktree',
-    description: `所有代码修改必须在隔离的 worktree 中进行，不要在原始仓库目录直接编辑。
-
-【原因】
-- 隔离风险：worktree 中的改动不会影响主工作区
-- 安全回滚：删除 worktree 即可放弃改动
-- 并行开发：多个任务可同时在不同 worktree 中进行
-
-【禁止】
-- 在原始仓库目录直接编辑文件
-- 跳过 worktree 创建直接执行 Agent`,
-    promptInjection: '所有代码修改必须在隔离的 worktree 中进行。不要在原始仓库目录直接编辑文件。worktree 提供了安全回滚和并行开发能力。如果你发现不在 worktree 中，立即停止并要求创建 worktree。',
-  },
-
   /**
    * 禁止模糊完成声明
    * 原因：质量底线，必须有可量化证据
@@ -371,6 +346,37 @@ https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agent
 // ========================================
 
 export const GUIDELINES: Record<string, Constraint> = {
+  /**
+   * 高风险改动优先使用 worktree
+   * 原因：隔离工作区，安全回滚，并行开发
+   * 来源：Superpowers prefer_worktree
+   */
+  prefer_worktree: {
+    id: 'prefer_worktree',
+    rule: 'USE WORKTREE FOR HIGH-RISK CHANGES',
+    message: '高风险改动应在 worktree 中进行',
+    level: 'guideline',
+    trigger: ['code_implementation'],
+    enforcement: 'check-worktree',
+    description: `高风险改动应在隔离的 worktree 中进行。
+
+【何时需要 worktree】
+- 新功能开发（新增模块/API）
+- 跨模块改动（>3 文件）
+- 基础设施变更（CI/CD、依赖）
+
+【何时不需要】
+- 配置文件修改
+- 单文件 bug fix
+- 外科手术式修复（typo、missing import）
+
+【原因】
+- 隔离风险：worktree 中的改动不会影响主工作区
+- 安全回滚：删除 worktree 即可放弃改动
+- 并行开发：多个任务可同时在不同 worktree 中进行`,
+    promptInjection: '高风险改动（新功能、跨模块、基础设施）应在 worktree 中进行。配置修改、单文件 fix 可直接编辑。',
+  },
+
   /**
    * 禁止无调查修复 bug
    * 例外：简单 typo、配置错误

package/src/knowledge/__tests__/audit.test.ts

@@ -14,7 +14,7 @@ import * as fs from 'fs';
 import * as path from 'path';
 import * as os from 'os';
 import { KnowledgeAudit } from '../audit';
-import { KnowledgeStore } from '../store';
+import { FileKnowledgeStore as KnowledgeStore } from '../store';
 import type { KnowledgeEntry } from '../types';
 
 function makeTmpDir(): string {
@@ -558,6 +558,62 @@ describe('auto-fix', () => {
   });
 });
 
+// ── D2b: deprecated-domain ──────────────────────────────
+
+describe('D2b: deprecated-domain', () => {
+  it('flags entry with "pipeline" tag', () => {
+    const dir = makeTmpDir();
+    const audit = new KnowledgeAudit({ baseDir: dir });
+    const entry = makeEntry({ tags: ['pipeline', 'deployment'] });
+    const issues = audit.validate(entry);
+    const dd = issues.filter(i => i.rule === 'deprecated-domain');
+    expect(dd.length).toBe(1);
+    expect(dd[0].action).toBe('archive');
+    expect(dd[0].severity).toBe('high');
+    fs.rmSync(dir, { recursive: true });
+  });
+
+  it('flags entry with "pipeline" in title', () => {
+    const dir = makeTmpDir();
+    const audit = new KnowledgeAudit({ baseDir: dir });
+    const entry = makeEntry({ title: 'Pipeline 工作单元不可见导致协作效率低' });
+    const issues = audit.validate(entry);
+    const dd = issues.filter(i => i.rule === 'deprecated-domain');
+    expect(dd.length).toBe(1);
+    fs.rmSync(dir, { recursive: true });
+  });
+
+  it('flags entry with "管线" in title', () => {
+    const dir = makeTmpDir();
+    const audit = new KnowledgeAudit({ baseDir: dir });
+    const entry = makeEntry({ title: 'B51 管线端到端验证常量与测试' });
+    const issues = audit.validate(entry);
+    const dd = issues.filter(i => i.rule === 'deprecated-domain');
+    expect(dd.length).toBe(1);
+    fs.rmSync(dir, { recursive: true });
+  });
+
+  it('does not flag entry without deprecated domain references', () => {
+    const dir = makeTmpDir();
+    const audit = new KnowledgeAudit({ baseDir: dir });
+    const entry = makeEntry({ title: 'Agent Network 核心概念', tags: ['agent', 'architecture'] });
+    const issues = audit.validate(entry);
+    const dd = issues.filter(i => i.rule === 'deprecated-domain');
+    expect(dd.length).toBe(0);
+    fs.rmSync(dir, { recursive: true });
+  });
+
+  it('skips already archived entries', () => {
+    const dir = makeTmpDir();
+    const audit = new KnowledgeAudit({ baseDir: dir });
+    const entry = makeEntry({ title: 'Pipeline legacy entry', maturity: 'archived', tags: ['pipeline'] });
+    const issues = audit.validate(entry);
+    const dd = issues.filter(i => i.rule === 'deprecated-domain');
+    expect(dd.length).toBe(0);
+    fs.rmSync(dir, { recursive: true });
+  });
+});
+
 // ── run() report structure ─────────────────────────────
 
 describe('run() report', () => {

package/src/knowledge/__tests__/doctor.test.ts

@@ -4,7 +4,7 @@
 
 import * as fs from 'fs';
 import * as path from 'path';
-import { KnowledgeStore } from '../store';
+import { FileKnowledgeStore as KnowledgeStore } from '../store';
 import { KnowledgeLinter, type LintReport } from '../lint';
 import { ReferenceTracker } from '../reference-tracker';
 import { KnowledgeHealthScorer } from '../doctor';

package/src/knowledge/__tests__/import.test.ts

@@ -3,7 +3,7 @@
  */
 
 import { ColdStartImporter } from '../import';
-import { KnowledgeStore } from '../store';
+import { FileKnowledgeStore as KnowledgeStore } from '../store';
 import * as fs from 'fs';
 import * as path from 'path';
 import * as os from 'os';