@dommaker/harness 0.13.3 → 0.16.0

package/src/cli/commands/release.ts

@@ -44,7 +44,26 @@ export async function release(options: ReleaseOptions): Promise<void> {
   console.log(chalk.cyan(`📦 ${pkgName}@${oldVersion}`));
   console.log(chalk.cyan(`   bump: ${bumpType}${dryRun ? ' (dry-run)' : ''}`));
 
-  // ── 2. Check clean working tree ──
+  // ── 2. Check branch (must be on master/main) ──
+  const branchResult = await run('git rev-parse --abbrev-ref HEAD', pkgPath);
+  const currentBranch = branchResult.stdout.trim();
+  if (currentBranch !== 'master' && currentBranch !== 'main') {
+    console.error(chalk.red(`❌ Must be on master or main branch to release. Currently on: ${currentBranch}`));
+    console.error(chalk.gray('   Run: git checkout master && git merge ' + currentBranch));
+    process.exit(1);
+  }
+  console.log(chalk.green(`✅ git: on ${currentBranch}`));
+
+  // ── 2b. Check remote sync ──
+  await run('git fetch origin', pkgPath, 15_000);
+  const behind = await run(`git rev-list --count HEAD..origin/${currentBranch}`, pkgPath);
+  if (behind.stdout.trim() !== '0') {
+    console.error(chalk.red(`❌ Local ${currentBranch} is ${behind.stdout.trim()} commits behind origin/${currentBranch}. Pull first.`));
+    process.exit(1);
+  }
+  console.log(chalk.green('✅ git: synced with remote'));
+
+  // ── 2c. Check clean working tree ──
   const stat = await run('git status --porcelain -uno', pkgPath);
   if (stat.stdout.length > 0) {
     console.error(chalk.red('❌ Uncommitted changes. Commit or stash before releasing.'));
@@ -98,6 +117,18 @@ export async function release(options: ReleaseOptions): Promise<void> {
   // ── 5. Bump version (npm version creates git commit + tag atomically,
   //     including package-lock.json — no desync possible) ──
   console.log(chalk.cyan('🔢 Bumping version...'));
+  const [major, minor, patch] = oldVersion.split('.').map(Number);
+  let expectedNew: string;
+  if (bumpType === 'major') expectedNew = `${major + 1}.0.0`;
+  else if (bumpType === 'minor') expectedNew = `${major}.${minor + 1}.0`;
+  else expectedNew = `${major}.${minor}.${patch + 1}`;
+  const expectedTag = `v${expectedNew}`;
+  const tagExists = await run(`git tag -l "${expectedTag}"`, pkgPath);
+  if (tagExists.stdout.trim() === expectedTag) {
+    console.error(chalk.red(`❌ Tag ${expectedTag} already exists. Version may have been released already.`));
+    process.exit(1);
+  }
+
   const bump = await run(`npm version ${bumpType} -m "release: %s"`, pkgPath);
   if (bump.stderr && !bump.stdout) {
     console.error(chalk.red('❌ npm version failed:'), bump.stderr);
@@ -107,10 +138,9 @@ export async function release(options: ReleaseOptions): Promise<void> {
   const tag = `v${newVersion}`;
   console.log(chalk.green(`✅ version: ${oldVersion} → ${newVersion} (committed + tagged)`));
 
-  // ── 7. Push ──
+  // ── 6. Push ──
   console.log(chalk.cyan('⬆️  Pushing...'));
-  const branch = await run('git rev-parse --abbrev-ref HEAD', pkgPath);
-  const push = await run(`git push origin ${branch.stdout}`, pkgPath, 30_000);
+  const push = await run(`git push origin ${currentBranch}`, pkgPath, 30_000);
   if (push.stderr && push.stderr.includes('error')) {
     console.error(chalk.red('❌ git push failed:'), push.stderr.slice(0, 500));
     process.exit(1);
@@ -118,7 +148,15 @@ export async function release(options: ReleaseOptions): Promise<void> {
   await run(`git push origin ${tag}`, pkgPath, 30_000);
   console.log(chalk.green('✅ git: pushed'));
 
-  // ── 8. npm publish ──
+  // ── 8. Check private flag ──
+  if (pkgJson.private) {
+    console.error(chalk.red('❌ package.json has "private": true. Remove it before publishing.'));
+    console.error(chalk.gray('   The release tool will NOT auto-remove private flag.'));
+    process.exit(1);
+  }
+  console.log(chalk.green('✅ package: not private'));
+
+  // ── 7. npm publish ──
   // Switch to npmjs.org for publishing (npmmirror is read-only mirror)
   const origRegistry = await run('npm config get registry', pkgPath);
   await run('npm config set registry https://registry.npmjs.org/', pkgPath);
@@ -136,7 +174,7 @@ export async function release(options: ReleaseOptions): Promise<void> {
     process.exit(1);
   }
 
-  // ── 9. GitHub Release ──
+  // ── 8. GitHub Release ──
   console.log(chalk.cyan('🐙 Creating GitHub Release...'));
   const gh = await run(`gh release create ${tag} --generate-notes`, pkgPath, 30_000);
   if (gh.stderr && gh.stderr.includes('already exists')) {

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';
@@ -42,6 +42,9 @@ describe('KnowledgeInjector', () => {
       applicablePhases: [],
       sourceReferences: [],
       referencedBy: [],
+      executionResults: [],
+      consumptionMode: 'reference',
+      origin: 'agent',
       ...overrides,
     });
   }

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、配置错误
@@ -813,8 +819,10 @@ export const GUIDELINES: Record<string, Constraint> = {
     description: `删除任何代码（包/模块/文件）前，必须：
 1. 查设计文档（CLAUDE.md / roadmap / specs）
 2. 分析是否有可吸收的功能
-3. 记录分析结论（有/无吸收价值，原因）`,
-    promptInjection: '删除任何代码包或模块前，必须先查 CLAUDE.md 和相关设计文档，分析是否有可吸收的功能，并记录分析结论。',
+3. 查替代函数是否丢失了关键设计模式（零引用≠无价值）
+4. 分类：未接线（应接线）/ 被替代但有可吸收设计 / 真正无用
+5. 记录分析结论（有/无吸收价值，原因）`,
+    promptInjection: '删除任何代码前，先查设计意图（JSDoc/commit/spec），分析被替代的函数是否有丢失的关键模式。零引用≠无价值。分类：未接线→接线，被替代→吸收模式，真正无用→才删。',
   },
 
   /**

package/src/dashboard/__tests__/data.test.ts

@@ -22,6 +22,9 @@ function makeEntry(overrides: Partial<KnowledgeEntry> = {}): KnowledgeEntry {
     applicablePhases: [],
     sourceReferences: [],
     referencedBy: [],
+    executionResults: [],
+    consumptionMode: 'reference',
+    origin: 'agent',
     ...overrides,
   };
 }

package/src/dashboard/__tests__/stats.test.ts

@@ -21,6 +21,9 @@ function makeEntry(overrides: Partial<KnowledgeEntry> = {}): KnowledgeEntry {
     applicablePhases: [],
     sourceReferences: [],
     referencedBy: [],
+    executionResults: [],
+    consumptionMode: 'reference',
+    origin: 'agent',
     ...overrides,
   };
 }

package/src/index.ts

@@ -76,7 +76,9 @@ export * from './verification';
 // ========================================
 // 约束分层导出
 // ========================================
-export * from './constraints';
+export * from './constraints/types';
+export { ConstraintRegistry } from './constraints/registry';
+export { ConstraintLifecycleRunner } from './constraints/lifecycle-runner';
 
 // ========================================
 // Dashboard 数据导出

package/src/knowledge/CONTEXT.md

@@ -1,29 +1,51 @@
 # knowledge/
 
 ## 职责
-知识引擎：知识存储(CRUD)、语义查询、引用追踪、质量检查(Linter)、生命周期管理、冷启动导入、健康评分。
+知识引擎：知识存储(CRUD)、语义查询、引用追踪、质量审计(Audit)、质量检查(Linter)、生命周期管理、冷启动导入、健康评分、外部内容摄入。
+
+## 三维分类体系 (AS-021)
+知识由三个正交维度定义：
+- **Topic** — 开放集，用 `tags: string[]` 描述
+- **ConsumptionMode** — 闭集 (rule/reference/context/signal)，驱动注入策略和生命周期
+- **Origin** — 闭集 (human/agent/external/system)，影响信任度和 maturity 起点
+
+## 生命周期按模式分化
+- `rule`: draft → active → deprecated (1 次成功激活, 失败率>=50% 降级)
+- `reference`: draft → verified → proven → archived (现有逻辑)
+- `context`: draft → active → archived (1 次引用激活, 3 个月未引用归档)
+- `signal`: active → archived (消费饱和: ref>=3 + 有更新同标签条目)
+- 所有模式支持 `decayAt` 硬过期
 
 ## 核心导出
 - `KnowledgeStore` — 知识条目 CRUD + 结构化存储
-- `KnowledgeQuery` — 语义搜索 + 类型/标签过滤
-- `KnowledgeLifecycle` — 知识生命周期: draft → candidate → validated → canonical → archived
-- `KnowledgeIngest` — 知识摄取引擎
+- `KnowledgeQuery` — 语义搜索 + 类型/标签过滤 + `queryByMode()` + `consume(taskContext)`
+- `KnowledgeLifecycle` — per-mode 生命周期管理
+- `KnowledgeIngest` — 知识摄取引擎（含 ingest gate 质量门）+ `ingestExternal()` 外部内容摄入
+- `sanitizeExternalContent` — 外部内容安全清洗（过滤注入模式 + 长度限制）
+- `migrateKnowledgeEntries` — AS-021 迁移工具（为现有条目添加 consumptionMode/origin）
+- `KnowledgeAudit` — 6 维度质量审计引擎
 - `ReferenceTracker` — 知识引用关系图谱
 - `KnowledgeLinter` — 知识质量检查(完整性/一致性/时效性)
 - `ColdStartImporter` — 冷启动知识导入
-- `KnowledgeHealthScorer` — 知识健康评分
+- `KnowledgeHealthScorer` — 知识健康评分（doctor.ts）
 - `KnowledgeLifecycleHooks` — 生命周期 hook
 
 ## 依赖关系
 - 依赖 `src/types/` 知识相关类型
 - 依赖 `src/monitoring/` KnowledgeDoctor / KnowledgeEvolver
-- 被 `src/cli/commands/knowledge.ts` CLI 消费
+- 被 `src/cli/commands/knowledge.ts` CLI 消费（含 `migrate` 子命令）
 
 ## 约定
-- 知识条目有明确的生命周期状态
+- 知识条目有明确的生命周期状态（按 consumptionMode 分化）
 - 约束退化时自动写入 KnowledgeStore
 - Linter 检查完整性/一致性/时效性三个维度
+- Audit 6 维度评分：D1结构 D2内容 D3去重 D4成熟度 D5新鲜度 D6飞轮
+- Ingest gate: ingestEntry() 先经 audit.validate() 检查，reject 不入库
+- 外部内容三层防御：ingest sanitization + retrieval marking + prompt constraint
+- 消费饱和度替代固定 TTL 用于 signal 过期判断
 
 ## 注意事项
 - Phase 1+4 实现的知识引擎核心
 - 约束"退化不删除"——降级时保留规则原文 + 退化原因 + 历史数据
+- `MaturityLevel` 包含 6 个值: draft/verified/proven/archived/active/deprecated
+- `excludeArchived` 同时排除 archived 和 deprecated