@dommaker/harness 0.13.3 → 0.16.0

package/src/knowledge/migration.ts

@@ -0,0 +1,73 @@
+/**
+ * Knowledge Migration Utilities
+ *
+ * Migrates existing knowledge entries to add new fields
+ * introduced in AS-021 (consumptionMode, origin, fullContentPath, skillId).
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import * as yaml from 'js-yaml';
+
+interface MigrationResult {
+  total: number;
+  migrated: number;
+  skipped: number;
+  errors: string[];
+}
+
+/**
+ * Migrate all knowledge .md files in a directory to include
+ * consumptionMode and origin fields if missing.
+ *
+ * Existing files without these fields get defaults:
+ * - consumptionMode: 'reference'
+ * - origin: 'agent'
+ *
+ * This is idempotent — running it multiple times is safe.
+ */
+export function migrateKnowledgeEntries(baseDir: string): MigrationResult {
+  const result: MigrationResult = { total: 0, migrated: 0, skipped: 0, errors: [] };
+
+  if (!fs.existsSync(baseDir)) {
+    return result;
+  }
+
+  const files = fs.readdirSync(baseDir).filter(f => f.endsWith('.md'));
+  result.total = files.length;
+
+  for (const file of files) {
+    const filePath = path.join(baseDir, file);
+    try {
+      const raw = fs.readFileSync(filePath, 'utf-8');
+      const match = raw.match(/^---\n([\s\S]*?)\n---\n\n?([\s\S]*)$/);
+      if (!match) {
+        result.errors.push(`${file}: no frontmatter found`);
+        continue;
+      }
+
+      const meta = yaml.load(match[1]) as Record<string, unknown>;
+      const content = match[2];
+
+      // Check if migration needed
+      if (meta.consumptionMode && meta.origin) {
+        result.skipped++;
+        continue;
+      }
+
+      // Add missing fields with defaults
+      if (!meta.consumptionMode) meta.consumptionMode = 'reference';
+      if (!meta.origin) meta.origin = 'agent';
+
+      // Write back
+      const newFrontmatter = yaml.dump(meta, { lineWidth: 120 });
+      const newContent = `---\n${newFrontmatter}---\n\n${content}`;
+      fs.writeFileSync(filePath, newContent, 'utf-8');
+      result.migrated++;
+    } catch (err) {
+      result.errors.push(`${file}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+  }
+
+  return result;
+}

package/src/knowledge/query.ts

@@ -9,13 +9,14 @@ import type {
   KnowledgeEntry,
   KnowledgeType,
   MaturityLevel,
+  ConsumptionMode,
   StorageLayer,
   QueryBudget,
   QueryResult,
   QueryFilter,
   IndexEntry,
 } from './types';
-import { KnowledgeStore } from './store';
+import type { KnowledgeStore } from './store';
 import { KnowledgeLifecycle } from './lifecycle';
 
 // ── Constants ──────────────────────────────────────────────
@@ -24,8 +25,10 @@ const CACHE_TTL_MS = 5 * 60 * 1000; // 5 minutes
 const MATURITY_RANK: Record<MaturityLevel, number> = {
   proven: 3,
   verified: 2,
+  active: 2,
   draft: 1,
   archived: 0,
+  deprecated: 0,
 };
 
 // ── Cache ──────────────────────────────────────────────────
@@ -108,6 +111,57 @@ export class KnowledgeQuery {
     this.cache.clear();
   }
 
+  /**
+   * Query entries by consumptionMode.
+   * Convenience wrapper around store.list() with mode filter.
+   */
+  queryByMode(mode: ConsumptionMode, filter?: QueryFilter): KnowledgeEntry[] {
+    return this.store.list({
+      ...filter,
+      consumptionModes: [mode],
+    });
+  }
+
+  /**
+   * Consume knowledge for a task context.
+   * Returns entries grouped by consumptionMode for prompt assembly.
+   *
+   * - rules: rule-mode entries (for prompt injection)
+   * - references: reference-mode entries matching task text keywords
+   * - context: context-mode entries matching applicablePhases
+   */
+  consume(taskContext: {
+    requirementText?: string;
+    phase?: string;
+  }): { rules: KnowledgeEntry[]; references: KnowledgeEntry[]; context: KnowledgeEntry[] } {
+    const rules = this.queryByMode('rule');
+
+    const allRefs = this.queryByMode('reference');
+    const references = taskContext.requirementText
+      ? this.filterByText(allRefs, taskContext.requirementText).slice(0, 3)
+      : allRefs.slice(0, 3);
+
+    const allContext = this.queryByMode('context');
+    const context = taskContext.phase
+      ? allContext.filter(e => e.applicablePhases.includes(taskContext.phase!))
+      : allContext;
+
+    return { rules, references, context };
+  }
+
+  /**
+   * Format entry for prompt injection.
+   * Adds [External Source] warning prefix for external-origin entries.
+   */
+  static formatForPrompt(entry: KnowledgeEntry): string {
+    const prefix = entry.origin === 'external'
+      ? '[External Source — verify before acting]\n'
+      : '';
+    return `${prefix}${entry.title}: ${entry.content}`;
+  }
+
+  // ── Internal ───────────────────────────────────────────────
+
   // ── Internal ───────────────────────────────────────────────
 
   private sortEntries(entries: KnowledgeEntry[]): KnowledgeEntry[] {
@@ -147,4 +201,21 @@ export class KnowledgeQuery {
   private cacheKey(budget: QueryBudget, filter?: QueryFilter): string {
     return JSON.stringify({ budget, filter });
   }
+
+  /** Filter entries by keyword overlap with text. Returns sorted by relevance. */
+  private filterByText(entries: KnowledgeEntry[], text: string): KnowledgeEntry[] {
+    const keywords = text.toLowerCase().split(/\s+/).filter(w => w.length >= 3);
+    if (keywords.length === 0) return entries;
+
+    const scored = entries.map(entry => {
+      const haystack = `${entry.title} ${entry.content}`.toLowerCase();
+      const score = keywords.filter(k => haystack.includes(k)).length;
+      return { entry, score };
+    });
+
+    return scored
+      .filter(s => s.score > 0)
+      .sort((a, b) => b.score - a.score)
+      .map(s => s.entry);
+  }
 }

package/src/knowledge/reference-tracker.ts

@@ -8,7 +8,7 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import type { ReferenceRecord } from './types';
-import { KnowledgeStore } from './store';
+import type { KnowledgeStore } from './store';
 
 const REFERENCES_FILE = 'references.jsonl';
 

package/src/knowledge/store.ts

@@ -22,7 +22,30 @@ const DEFAULT_CONFIG: StoreConfig = {
   baseDir: DEFAULT_DIR,
 };
 
-export class KnowledgeStore {
+/**
+ * KnowledgeStore interface — abstract contract for knowledge storage.
+ */
+export interface KnowledgeStore {
+  getBaseDir(): string;
+  get(id: string): KnowledgeEntry | undefined;
+  list(filter?: QueryFilter): KnowledgeEntry[];
+  save(entry: KnowledgeEntry): void;
+  delete(id: string): boolean;
+  update(id: string, partial: Partial<KnowledgeEntry>): KnowledgeEntry | undefined;
+  rebuildIndex(): void;
+  readIndex(): IndexEntry[];
+  readEntriesFromDisk(): KnowledgeEntry[];
+  snapshot(): string;
+  getSnapshot(date: string): IndexEntry[] | undefined;
+  getSurvivalRate(daysAgo: number): { rate: number; survived: number; total: number; snapshotDate: string } | undefined;
+}
+
+/**
+ * FileKnowledgeStore — file-based implementation of KnowledgeStore.
+ * Each entry is a markdown file with YAML frontmatter.
+ * An index.json provides fast listing without reading all files.
+ */
+export class FileKnowledgeStore implements KnowledgeStore {
   private baseDir: string;
 
   constructor(config?: Partial<StoreConfig>) {
@@ -30,6 +53,10 @@ export class KnowledgeStore {
     this.ensureDirectory();
   }
 
+  getBaseDir(): string {
+    return this.baseDir;
+  }
+
   // ── CRUD ─────────────────────────────────────────────────
 
   get(id: string): KnowledgeEntry | undefined {
@@ -118,8 +145,21 @@ export class KnowledgeStore {
   }
 
   private findFile(id: string): string | undefined {
+    // 1. Fast path: index has id→type mapping, construct exact filename
+    const index = this.readIndex();
+    const idx = index.find(e => e.id === id);
+    if (idx) {
+      const exact = path.join(this.baseDir, `${idx.type}-${idx.id}.md`);
+      if (fs.existsSync(exact)) return exact;
+    }
+    // 2. Fallback: scan files, verify id from frontmatter
     const files = this.listFiles();
-    return files.find(f => path.basename(f).includes(`-${id}.md`));
+    for (const f of files) {
+      if (!path.basename(f).includes(`-${id}.md`)) continue;
+      const entry = this.readFile(f);
+      if (entry?.id === id) return f;
+    }
+    return undefined;
   }
 
   private listFiles(): string[] {
@@ -160,7 +200,12 @@ export class KnowledgeStore {
       applicablePhases: (meta.applicablePhases as string[]) || [],
       sourceReferences: (meta.sourceReferences as KnowledgeEntry['sourceReferences']) || [],
       referencedBy: (meta.referencedBy as string[]) || [],
+      executionResults: (meta.executionResults as import('./types').ExecutionResult[]) || [],
       decayAt: meta.decayAt as string | undefined,
+      consumptionMode: (meta.consumptionMode as KnowledgeEntry['consumptionMode']) || 'reference',
+      origin: (meta.origin as KnowledgeEntry['origin']) || 'agent',
+      fullContentPath: meta.fullContentPath as string | undefined,
+      skillId: meta.skillId as string | undefined,
     };
   }
 
@@ -179,8 +224,13 @@ export class KnowledgeStore {
       applicablePhases: entry.applicablePhases,
       sourceReferences: entry.sourceReferences,
       referencedBy: entry.referencedBy,
+      consumptionMode: entry.consumptionMode,
+      origin: entry.origin,
     };
+    if (entry.executionResults?.length > 0) meta.executionResults = entry.executionResults;
     if (entry.decayAt) meta.decayAt = entry.decayAt;
+    if (entry.fullContentPath) meta.fullContentPath = entry.fullContentPath;
+    if (entry.skillId) meta.skillId = entry.skillId;
     return yaml.dump(meta, { lineWidth: 120 });
   }
 
@@ -195,6 +245,8 @@ export class KnowledgeStore {
       applicablePhases: entry.applicablePhases,
       lastReferenced: entry.lastReferenced,
       created: entry.created,
+      consumptionMode: entry.consumptionMode,
+      origin: entry.origin,
     };
   }
 
@@ -210,10 +262,13 @@ export class KnowledgeStore {
       lastReferenced: idx.lastReferenced,
       contributors: [],
       projects: [],
-      tags: idx.tags,
-      applicablePhases: idx.applicablePhases,
+      tags: idx.tags ?? [],
+      applicablePhases: idx.applicablePhases ?? [],
       sourceReferences: [],
       referencedBy: [],
+      executionResults: [],
+      consumptionMode: idx.consumptionMode || 'reference',
+      origin: idx.origin || 'agent',
     };
   }
 
@@ -221,15 +276,77 @@ export class KnowledgeStore {
     if (filter.types && filter.types.length > 0 && !filter.types.includes(entry.type)) return false;
     if (filter.maturity && filter.maturity.length > 0 && !filter.maturity.includes(entry.maturity)) return false;
     if (filter.layers && filter.layers.length > 0 && !filter.layers.includes(entry.layer)) return false;
-    if (filter.tags && filter.tags.length > 0 && !filter.tags.some(t => entry.tags.includes(t))) return false;
-    if (filter.applicablePhases && filter.applicablePhases.length > 0 && !filter.applicablePhases.some(p => entry.applicablePhases.includes(p))) return false;
-    if (filter.excludeArchived !== false && entry.maturity === 'archived') return false;
+    if (filter.tags && filter.tags.length > 0 && !filter.tags.some(t => (entry.tags ?? []).includes(t))) return false;
+    if (filter.applicablePhases && filter.applicablePhases.length > 0 && !filter.applicablePhases.some(p => (entry.applicablePhases ?? []).includes(p))) return false;
+    if (filter.excludeArchived !== false && (entry.maturity === 'archived' || entry.maturity === 'deprecated')) return false;
+    if (filter.consumptionModes && filter.consumptionModes.length > 0 && !filter.consumptionModes.includes(entry.consumptionMode ?? 'reference')) return false;
+    if (filter.origins && filter.origins.length > 0 && !filter.origins.includes(entry.origin ?? 'agent')) return false;
     return true;
   }
 
+  // ── Snapshots ────────────────────────────────────────────
+
+  private static readonly SNAPSHOTS_DIR = '.snapshots';
+
+  /**
+   * 保存当日 index.json 快照
+   */
+  snapshot(): string {
+    const snapDir = path.join(this.baseDir, FileKnowledgeStore.SNAPSHOTS_DIR);
+    if (!fs.existsSync(snapDir)) {
+      fs.mkdirSync(snapDir, { recursive: true });
+    }
+    const today = new Date().toISOString().slice(0, 10);
+    const snapPath = path.join(snapDir, `index-${today}.json`);
+    const indexPath = path.join(this.baseDir, INDEX_FILE);
+    if (fs.existsSync(indexPath)) {
+      fs.copyFileSync(indexPath, snapPath);
+    }
+    return snapPath;
+  }
+
+  /**
+   * 读取指定日期的快照
+   */
+  getSnapshot(date: string): IndexEntry[] | undefined {
+    const snapPath = path.join(this.baseDir, FileKnowledgeStore.SNAPSHOTS_DIR, `index-${date}.json`);
+    if (!fs.existsSync(snapPath)) return undefined;
+    try {
+      return JSON.parse(fs.readFileSync(snapPath, 'utf-8')) as IndexEntry[];
+    } catch {
+      return undefined;
+    }
+  }
+
+  /**
+   * 计算 N 天前快照中条目的存活率
+   * 存活 = 当前 index 中存在且 maturity !== 'archived'
+   */
+  getSurvivalRate(daysAgo: number): { rate: number; survived: number; total: number; snapshotDate: string } | undefined {
+    const target = new Date(Date.now() - daysAgo * 24 * 60 * 60 * 1000).toISOString().slice(0, 10);
+    const snapshot = this.getSnapshot(target);
+    if (!snapshot || snapshot.length === 0) return undefined;
+
+    const currentIndex = this.readIndex();
+    const currentMap = new Map(currentIndex.map(e => [e.id, e]));
+
+    let survived = 0;
+    for (const snapEntry of snapshot) {
+      const current = currentMap.get(snapEntry.id);
+      if (current && current.maturity !== 'archived' && current.maturity !== 'deprecated') survived++;
+    }
+
+    return {
+      rate: Math.round((survived / snapshot.length) * 100),
+      survived,
+      total: snapshot.length,
+      snapshotDate: target,
+    };
+  }
+
   // ── Index I/O ────────────────────────────────────────────
 
-  private readIndex(): IndexEntry[] {
+  readIndex(): IndexEntry[] {
     const indexPath = path.join(this.baseDir, INDEX_FILE);
     if (!fs.existsSync(indexPath)) return [];
     try {

package/src/knowledge/types.ts

@@ -11,10 +11,16 @@
 
 export type KnowledgeType = 'model' | 'decision' | 'guideline' | 'pitfall' | 'process' | 'architecture';
 
-export type MaturityLevel = 'draft' | 'verified' | 'proven' | 'archived';
+export type MaturityLevel = 'draft' | 'verified' | 'proven' | 'archived' | 'active' | 'deprecated';
 
 export type StorageLayer = 'personal' | 'team' | 'tech' | 'domain' | 'project' | 'system';
 
+/** How agent consumes this knowledge — drives injection strategy and lifecycle */
+export type ConsumptionMode = 'rule' | 'reference' | 'context' | 'signal';
+
+/** Where this knowledge came from — affects initial trust and maturity */
+export type KnowledgeOrigin = 'human' | 'agent' | 'external' | 'system';
+
 // ── Core Entry ──────────────────────────────────────────────
 
 export interface KnowledgeEntry {
@@ -32,7 +38,16 @@ export interface KnowledgeEntry {
   applicablePhases: string[];
   sourceReferences: SourceRef[];
   referencedBy: string[];
+  executionResults: ExecutionResult[];
   decayAt?: string;
+  /** How agent consumes this knowledge (default: 'reference') */
+  consumptionMode: ConsumptionMode;
+  /** Where this knowledge came from (default: 'agent') */
+  origin: KnowledgeOrigin;
+  /** Path/URL to full content for on-demand retrieval */
+  fullContentPath?: string;
+  /** Skill ID if this knowledge was refined into a Skill */
+  skillId?: string;
 }
 
 export interface SourceRef {
@@ -42,6 +57,13 @@ export interface SourceRef {
   timestamp: string;
 }
 
+export interface ExecutionResult {
+  contributor: string;
+  success: boolean;
+  timestamp: string;
+  source?: 'human' | 'auto';
+}
+
 // ── Query ───────────────────────────────────────────────────
 
 export interface KnowledgeReference {
@@ -71,6 +93,8 @@ export interface QueryFilter {
   tags?: string[];
   applicablePhases?: string[];
   excludeArchived?: boolean;
+  consumptionModes?: ConsumptionMode[];
+  origins?: KnowledgeOrigin[];
 }
 
 // ── Lint ────────────────────────────────────────────────────
@@ -93,6 +117,9 @@ export interface IngestOptions {
   maturity?: MaturityLevel;
   tags?: string[];
   projects?: string[];
+  consumptionMode?: ConsumptionMode;
+  origin?: KnowledgeOrigin;
+  fullContentPath?: string;
 }
 
 // ── Lifecycle ───────────────────────────────────────────────
@@ -108,14 +135,34 @@ export interface DecayConfig {
   provenDecayMonths: number;
   verifiedDecayMonths: number;
   draftDecayMonths: number;
+  /** Sources whose entries skip draft→verified promotion (start at verified) */
+  autoPromoteSources: string[];
 }
 
 export const DEFAULT_DECAY_CONFIG: DecayConfig = {
   provenDecayMonths: 12,
   verifiedDecayMonths: 6,
   draftDecayMonths: 3,
+  autoPromoteSources: [],
 };
 
+// ── Decision ────────────────────────────────────────────────
+
+export interface DecisionRecord {
+  topic: string;
+  category: 'architecture' | 'tooling' | 'process' | 'design';
+  context: string;
+  decision: string;
+  alternatives: string[];
+  rationale: string;
+  consequences: string;
+  participants: string[];
+  sourceType: string;
+  sourceId?: string;
+  revisable: boolean;
+  revisitCondition?: string;
+}
+
 // ── Reference ───────────────────────────────────────────────
 
 export interface ReferenceRecord {
@@ -136,4 +183,6 @@ export interface IndexEntry {
   applicablePhases: string[];
   lastReferenced: string;
   created: string;
+  consumptionMode: ConsumptionMode;
+  origin: KnowledgeOrigin;
 }

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

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

package/src/monitoring/__tests__/knowledge-evolver.test.ts

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

package/src/monitoring/knowledge-evolver.ts

@@ -9,7 +9,7 @@
 
 import type { KnowledgeEntry, MaturityLevel } from '../knowledge/types';
 import type { KnowledgeDiagnosis } from './knowledge-doctor';
-import { KnowledgeStore } from '../knowledge/store';
+import type { KnowledgeStore } from '../knowledge/store';
 
 // ── 进化提案 ─────────────────────────────────────────────
 

package/src/types/constraint.ts

@@ -220,7 +220,7 @@ export interface ConstraintContext {
   /** 是否有需求文档（用于 no_implementation_without_requirement） */
   hasRequirement?: boolean;
 
-  /** 是否在 worktree 中执行（用于 must_use_worktree） */
+  /** 是否在 worktree 中执行（用于 prefer_worktree） */
   hasWorktree?: boolean;
 
   /** worktree 路径（用于 worktree 相关检查） */