@fermindi/pwn-cli 0.1.0 → 0.2.0

package/src/knowledge/lifecycle.js

@@ -1,401 +1,401 @@
-import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'fs';
-import { join } from 'path';
-
-/**
- * Knowledge Item Status
- * @typedef {'active' | 'candidate_pattern' | 'archived' | 'garbage'} KnowledgeStatus
- */
-
-/**
- * Knowledge Item
- * @typedef {Object} KnowledgeItem
- * @property {string} id - Item ID (DEC-001, DE-001)
- * @property {string} type - 'decision' | 'deadend'
- * @property {string} title - Item title
- * @property {string} status - Current status
- * @property {string[]} relatedFiles - Code files that reference this
- * @property {string[]} relatedDecisions - Other decisions that reference
- * @property {string[]} relatedTasks - Tasks that depend on this
- * @property {number} accessCount - Times consulted
- * @property {number} appliedCount - Times applied in code
- * @property {string[]} appliedContexts - Different contexts applied
- * @property {string} createdAt - ISO date string
- * @property {string} lastAccessed - ISO date string
- */
-
-/**
- * Get the path to knowledge.json registry
- * @param {string} cwd - Working directory
- * @returns {string}
- */
-export function getKnowledgePath(cwd = process.cwd()) {
-  return join(cwd, '.ai', 'config', 'knowledge.json');
-}
-
-/**
- * Initialize knowledge registry if it doesn't exist
- * @param {string} cwd - Working directory
- * @returns {Object} Knowledge registry
- */
-export function initKnowledgeRegistry(cwd = process.cwd()) {
-  const knowledgePath = getKnowledgePath(cwd);
-  const configDir = join(cwd, '.ai', 'config');
-
-  if (!existsSync(configDir)) {
-    mkdirSync(configDir, { recursive: true });
-  }
-
-  if (!existsSync(knowledgePath)) {
-    const initial = {
-      version: '1.0.0',
-      items: {},
-      lastGC: null,
-      lastSync: new Date().toISOString()
-    };
-    writeFileSync(knowledgePath, JSON.stringify(initial, null, 2));
-    return initial;
-  }
-
-  return JSON.parse(readFileSync(knowledgePath, 'utf8'));
-}
-
-/**
- * Get knowledge registry
- * @param {string} cwd - Working directory
- * @returns {Object|null}
- */
-export function getKnowledgeRegistry(cwd = process.cwd()) {
-  const knowledgePath = getKnowledgePath(cwd);
-
-  if (!existsSync(knowledgePath)) {
-    return null;
-  }
-
-  try {
-    return JSON.parse(readFileSync(knowledgePath, 'utf8'));
-  } catch {
-    return null;
-  }
-}
-
-/**
- * Save knowledge registry
- * @param {Object} registry - Registry to save
- * @param {string} cwd - Working directory
- */
-export function saveKnowledgeRegistry(registry, cwd = process.cwd()) {
-  const knowledgePath = getKnowledgePath(cwd);
-  registry.lastSync = new Date().toISOString();
-  writeFileSync(knowledgePath, JSON.stringify(registry, null, 2));
-}
-
-/**
- * Parse decisions.md to extract decision items
- * @param {string} cwd - Working directory
- * @returns {KnowledgeItem[]}
- */
-export function parseDecisions(cwd = process.cwd()) {
-  const decisionsPath = join(cwd, '.ai', 'memory', 'decisions.md');
-
-  if (!existsSync(decisionsPath)) {
-    return [];
-  }
-
-  const content = readFileSync(decisionsPath, 'utf8');
-  const items = [];
-
-  // Match pattern: ## DEC-XXX: Title
-  const decisionRegex = /^## (DEC-\d+): (.+)$/gm;
-  let match;
-
-  while ((match = decisionRegex.exec(content)) !== null) {
-    const id = match[1];
-    const title = match[2];
-
-    // Extract status from the block
-    const blockStart = match.index;
-    const nextMatch = content.indexOf('\n## ', blockStart + 1);
-    const blockEnd = nextMatch === -1 ? content.length : nextMatch;
-    const block = content.substring(blockStart, blockEnd);
-
-    const statusMatch = block.match(/\*\*Status:\*\* (\w+)/);
-    const dateMatch = block.match(/\*\*Date:\*\* ([\d-]+)/);
-
-    items.push({
-      id,
-      type: 'decision',
-      title,
-      status: statusMatch ? statusMatch[1].toLowerCase() : 'active',
-      relatedFiles: [],
-      relatedDecisions: [],
-      relatedTasks: [],
-      accessCount: 0,
-      appliedCount: 0,
-      appliedContexts: [],
-      createdAt: dateMatch ? dateMatch[1] : null,
-      lastAccessed: null
-    });
-  }
-
-  return items;
-}
-
-/**
- * Parse deadends.md to extract dead-end items
- * @param {string} cwd - Working directory
- * @returns {KnowledgeItem[]}
- */
-export function parseDeadends(cwd = process.cwd()) {
-  const deadendsPath = join(cwd, '.ai', 'memory', 'deadends.md');
-
-  if (!existsSync(deadendsPath)) {
-    return [];
-  }
-
-  const content = readFileSync(deadendsPath, 'utf8');
-  const items = [];
-
-  // Match pattern: ## DE-XXX: Title
-  const deadendRegex = /^## (DE-\d+): (.+)$/gm;
-  let match;
-
-  while ((match = deadendRegex.exec(content)) !== null) {
-    const id = match[1];
-    const title = match[2];
-
-    // Extract date from the block
-    const blockStart = match.index;
-    const nextMatch = content.indexOf('\n## ', blockStart + 1);
-    const blockEnd = nextMatch === -1 ? content.length : nextMatch;
-    const block = content.substring(blockStart, blockEnd);
-
-    const dateMatch = block.match(/\*\*Date:\*\* ([\d-]+)/);
-
-    items.push({
-      id,
-      type: 'deadend',
-      title,
-      status: 'active',
-      relatedFiles: [],
-      relatedDecisions: [],
-      relatedTasks: [],
-      accessCount: 0,
-      appliedCount: 0,
-      appliedContexts: [],
-      createdAt: dateMatch ? dateMatch[1] : null,
-      lastAccessed: null
-    });
-  }
-
-  return items;
-}
-
-/**
- * Sync knowledge registry with markdown files
- * Discovers new items and preserves existing metadata
- * @param {string} cwd - Working directory
- * @returns {Object} Sync result
- */
-export function syncKnowledge(cwd = process.cwd()) {
-  const registry = initKnowledgeRegistry(cwd);
-  const decisions = parseDecisions(cwd);
-  const deadends = parseDeadends(cwd);
-
-  const allItems = [...decisions, ...deadends];
-  const result = { added: [], updated: [], removed: [] };
-
-  // Track existing IDs
-  const existingIds = new Set(Object.keys(registry.items));
-  const currentIds = new Set(allItems.map(item => item.id));
-
-  // Add or update items
-  for (const item of allItems) {
-    if (registry.items[item.id]) {
-      // Preserve existing metadata, update title
-      registry.items[item.id].title = item.title;
-      if (item.createdAt && !registry.items[item.id].createdAt) {
-        registry.items[item.id].createdAt = item.createdAt;
-      }
-      result.updated.push(item.id);
-    } else {
-      // New item
-      registry.items[item.id] = {
-        ...item,
-        lastAccessed: new Date().toISOString()
-      };
-      result.added.push(item.id);
-    }
-  }
-
-  // Mark removed items
-  for (const id of existingIds) {
-    if (!currentIds.has(id)) {
-      // Item was removed from markdown
-      result.removed.push(id);
-      // Don't delete, mark for GC
-      registry.items[id].status = 'garbage';
-    }
-  }
-
-  saveKnowledgeRegistry(registry, cwd);
-  return result;
-}
-
-/**
- * Get a knowledge item
- * @param {string} id - Item ID
- * @param {string} cwd - Working directory
- * @returns {KnowledgeItem|null}
- */
-export function getKnowledgeItem(id, cwd = process.cwd()) {
-  const registry = getKnowledgeRegistry(cwd);
-  if (!registry) return null;
-  return registry.items[id] || null;
-}
-
-/**
- * Update a knowledge item
- * @param {string} id - Item ID
- * @param {Object} updates - Fields to update
- * @param {string} cwd - Working directory
- * @returns {KnowledgeItem|null}
- */
-export function updateKnowledgeItem(id, updates, cwd = process.cwd()) {
-  const registry = getKnowledgeRegistry(cwd);
-  if (!registry || !registry.items[id]) return null;
-
-  registry.items[id] = {
-    ...registry.items[id],
-    ...updates
-  };
-
-  saveKnowledgeRegistry(registry, cwd);
-  return registry.items[id];
-}
-
-/**
- * Record an access to a knowledge item
- * @param {string} id - Item ID
- * @param {string} cwd - Working directory
- * @returns {KnowledgeItem|null}
- */
-export function recordAccess(id, cwd = process.cwd()) {
-  const registry = getKnowledgeRegistry(cwd);
-  if (!registry || !registry.items[id]) return null;
-
-  registry.items[id].accessCount = (registry.items[id].accessCount || 0) + 1;
-  registry.items[id].lastAccessed = new Date().toISOString();
-
-  saveKnowledgeRegistry(registry, cwd);
-  return registry.items[id];
-}
-
-/**
- * Record that a knowledge item was applied in a context
- * @param {string} id - Item ID
- * @param {string} context - Context description (e.g., file path, feature name)
- * @param {string} cwd - Working directory
- * @returns {KnowledgeItem|null}
- */
-export function recordApplication(id, context, cwd = process.cwd()) {
-  const registry = getKnowledgeRegistry(cwd);
-  if (!registry || !registry.items[id]) return null;
-
-  const item = registry.items[id];
-  item.appliedCount = (item.appliedCount || 0) + 1;
-  item.appliedContexts = item.appliedContexts || [];
-
-  if (!item.appliedContexts.includes(context)) {
-    item.appliedContexts.push(context);
-  }
-
-  item.lastAccessed = new Date().toISOString();
-
-  // Check for promotion candidate
-  if (item.type === 'decision' &&
-      item.appliedCount >= 3 &&
-      item.appliedContexts.length >= 2 &&
-      item.status === 'active') {
-    item.status = 'candidate_pattern';
-  }
-
-  saveKnowledgeRegistry(registry, cwd);
-  return item;
-}
-
-/**
- * Get all knowledge items
- * @param {Object} options - Filter options
- * @param {string} options.type - Filter by type
- * @param {string} options.status - Filter by status
- * @param {string} cwd - Working directory
- * @returns {KnowledgeItem[]}
- */
-export function getAllKnowledge(options = {}, cwd = process.cwd()) {
-  const registry = getKnowledgeRegistry(cwd);
-  if (!registry) return [];
-
-  let items = Object.values(registry.items);
-
-  if (options.type) {
-    items = items.filter(item => item.type === options.type);
-  }
-
-  if (options.status) {
-    items = items.filter(item => item.status === options.status);
-  }
-
-  return items;
-}
-
-/**
- * Get knowledge statistics
- * @param {string} cwd - Working directory
- * @returns {Object}
- */
-export function getKnowledgeStats(cwd = process.cwd()) {
-  const registry = getKnowledgeRegistry(cwd);
-  if (!registry) {
-    return {
-      total: 0,
-      decisions: 0,
-      deadends: 0,
-      active: 0,
-      candidatePatterns: 0,
-      archived: 0,
-      garbage: 0,
-      lastSync: null,
-      lastGC: null
-    };
-  }
-
-  const items = Object.values(registry.items);
-
-  return {
-    total: items.length,
-    decisions: items.filter(i => i.type === 'decision').length,
-    deadends: items.filter(i => i.type === 'deadend').length,
-    active: items.filter(i => i.status === 'active').length,
-    candidatePatterns: items.filter(i => i.status === 'candidate_pattern').length,
-    archived: items.filter(i => i.status === 'archived').length,
-    garbage: items.filter(i => i.status === 'garbage').length,
-    lastSync: registry.lastSync,
-    lastGC: registry.lastGC
-  };
-}
-
-/**
- * Change status of a knowledge item
- * @param {string} id - Item ID
- * @param {KnowledgeStatus} newStatus - New status
- * @param {string} cwd - Working directory
- * @returns {KnowledgeItem|null}
- */
-export function changeStatus(id, newStatus, cwd = process.cwd()) {
-  const validStatuses = ['active', 'candidate_pattern', 'archived', 'garbage'];
-  if (!validStatuses.includes(newStatus)) {
-    throw new Error(`Invalid status: ${newStatus}. Valid: ${validStatuses.join(', ')}`);
-  }
-
-  return updateKnowledgeItem(id, { status: newStatus }, cwd);
-}
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'fs';
+import { join } from 'path';
+
+/**
+ * Knowledge Item Status
+ * @typedef {'active' | 'candidate_pattern' | 'archived' | 'garbage'} KnowledgeStatus
+ */
+
+/**
+ * Knowledge Item
+ * @typedef {Object} KnowledgeItem
+ * @property {string} id - Item ID (DEC-001, DE-001)
+ * @property {string} type - 'decision' | 'deadend'
+ * @property {string} title - Item title
+ * @property {string} status - Current status
+ * @property {string[]} relatedFiles - Code files that reference this
+ * @property {string[]} relatedDecisions - Other decisions that reference
+ * @property {string[]} relatedTasks - Tasks that depend on this
+ * @property {number} accessCount - Times consulted
+ * @property {number} appliedCount - Times applied in code
+ * @property {string[]} appliedContexts - Different contexts applied
+ * @property {string} createdAt - ISO date string
+ * @property {string} lastAccessed - ISO date string
+ */
+
+/**
+ * Get the path to knowledge.json registry
+ * @param {string} cwd - Working directory
+ * @returns {string}
+ */
+export function getKnowledgePath(cwd = process.cwd()) {
+  return join(cwd, '.ai', 'config', 'knowledge.json');
+}
+
+/**
+ * Initialize knowledge registry if it doesn't exist
+ * @param {string} cwd - Working directory
+ * @returns {Object} Knowledge registry
+ */
+export function initKnowledgeRegistry(cwd = process.cwd()) {
+  const knowledgePath = getKnowledgePath(cwd);
+  const configDir = join(cwd, '.ai', 'config');
+
+  if (!existsSync(configDir)) {
+    mkdirSync(configDir, { recursive: true });
+  }
+
+  if (!existsSync(knowledgePath)) {
+    const initial = {
+      version: '1.0.0',
+      items: {},
+      lastGC: null,
+      lastSync: new Date().toISOString()
+    };
+    writeFileSync(knowledgePath, JSON.stringify(initial, null, 2));
+    return initial;
+  }
+
+  return JSON.parse(readFileSync(knowledgePath, 'utf8'));
+}
+
+/**
+ * Get knowledge registry
+ * @param {string} cwd - Working directory
+ * @returns {Object|null}
+ */
+export function getKnowledgeRegistry(cwd = process.cwd()) {
+  const knowledgePath = getKnowledgePath(cwd);
+
+  if (!existsSync(knowledgePath)) {
+    return null;
+  }
+
+  try {
+    return JSON.parse(readFileSync(knowledgePath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Save knowledge registry
+ * @param {Object} registry - Registry to save
+ * @param {string} cwd - Working directory
+ */
+export function saveKnowledgeRegistry(registry, cwd = process.cwd()) {
+  const knowledgePath = getKnowledgePath(cwd);
+  registry.lastSync = new Date().toISOString();
+  writeFileSync(knowledgePath, JSON.stringify(registry, null, 2));
+}
+
+/**
+ * Parse decisions.md to extract decision items
+ * @param {string} cwd - Working directory
+ * @returns {KnowledgeItem[]}
+ */
+export function parseDecisions(cwd = process.cwd()) {
+  const decisionsPath = join(cwd, '.ai', 'memory', 'decisions.md');
+
+  if (!existsSync(decisionsPath)) {
+    return [];
+  }
+
+  const content = readFileSync(decisionsPath, 'utf8');
+  const items = [];
+
+  // Match pattern: ## DEC-XXX: Title
+  const decisionRegex = /^## (DEC-\d+): (.+)$/gm;
+  let match;
+
+  while ((match = decisionRegex.exec(content)) !== null) {
+    const id = match[1];
+    const title = match[2];
+
+    // Extract status from the block
+    const blockStart = match.index;
+    const nextMatch = content.indexOf('\n## ', blockStart + 1);
+    const blockEnd = nextMatch === -1 ? content.length : nextMatch;
+    const block = content.substring(blockStart, blockEnd);
+
+    const statusMatch = block.match(/\*\*Status:\*\* (\w+)/);
+    const dateMatch = block.match(/\*\*Date:\*\* ([\d-]+)/);
+
+    items.push({
+      id,
+      type: 'decision',
+      title,
+      status: statusMatch ? statusMatch[1].toLowerCase() : 'active',
+      relatedFiles: [],
+      relatedDecisions: [],
+      relatedTasks: [],
+      accessCount: 0,
+      appliedCount: 0,
+      appliedContexts: [],
+      createdAt: dateMatch ? dateMatch[1] : null,
+      lastAccessed: null
+    });
+  }
+
+  return items;
+}
+
+/**
+ * Parse deadends.md to extract dead-end items
+ * @param {string} cwd - Working directory
+ * @returns {KnowledgeItem[]}
+ */
+export function parseDeadends(cwd = process.cwd()) {
+  const deadendsPath = join(cwd, '.ai', 'memory', 'deadends.md');
+
+  if (!existsSync(deadendsPath)) {
+    return [];
+  }
+
+  const content = readFileSync(deadendsPath, 'utf8');
+  const items = [];
+
+  // Match pattern: ## DE-XXX: Title
+  const deadendRegex = /^## (DE-\d+): (.+)$/gm;
+  let match;
+
+  while ((match = deadendRegex.exec(content)) !== null) {
+    const id = match[1];
+    const title = match[2];
+
+    // Extract date from the block
+    const blockStart = match.index;
+    const nextMatch = content.indexOf('\n## ', blockStart + 1);
+    const blockEnd = nextMatch === -1 ? content.length : nextMatch;
+    const block = content.substring(blockStart, blockEnd);
+
+    const dateMatch = block.match(/\*\*Date:\*\* ([\d-]+)/);
+
+    items.push({
+      id,
+      type: 'deadend',
+      title,
+      status: 'active',
+      relatedFiles: [],
+      relatedDecisions: [],
+      relatedTasks: [],
+      accessCount: 0,
+      appliedCount: 0,
+      appliedContexts: [],
+      createdAt: dateMatch ? dateMatch[1] : null,
+      lastAccessed: null
+    });
+  }
+
+  return items;
+}
+
+/**
+ * Sync knowledge registry with markdown files
+ * Discovers new items and preserves existing metadata
+ * @param {string} cwd - Working directory
+ * @returns {Object} Sync result
+ */
+export function syncKnowledge(cwd = process.cwd()) {
+  const registry = initKnowledgeRegistry(cwd);
+  const decisions = parseDecisions(cwd);
+  const deadends = parseDeadends(cwd);
+
+  const allItems = [...decisions, ...deadends];
+  const result = { added: [], updated: [], removed: [] };
+
+  // Track existing IDs
+  const existingIds = new Set(Object.keys(registry.items));
+  const currentIds = new Set(allItems.map(item => item.id));
+
+  // Add or update items
+  for (const item of allItems) {
+    if (registry.items[item.id]) {
+      // Preserve existing metadata, update title
+      registry.items[item.id].title = item.title;
+      if (item.createdAt && !registry.items[item.id].createdAt) {
+        registry.items[item.id].createdAt = item.createdAt;
+      }
+      result.updated.push(item.id);
+    } else {
+      // New item
+      registry.items[item.id] = {
+        ...item,
+        lastAccessed: new Date().toISOString()
+      };
+      result.added.push(item.id);
+    }
+  }
+
+  // Mark removed items
+  for (const id of existingIds) {
+    if (!currentIds.has(id)) {
+      // Item was removed from markdown
+      result.removed.push(id);
+      // Don't delete, mark for GC
+      registry.items[id].status = 'garbage';
+    }
+  }
+
+  saveKnowledgeRegistry(registry, cwd);
+  return result;
+}
+
+/**
+ * Get a knowledge item
+ * @param {string} id - Item ID
+ * @param {string} cwd - Working directory
+ * @returns {KnowledgeItem|null}
+ */
+export function getKnowledgeItem(id, cwd = process.cwd()) {
+  const registry = getKnowledgeRegistry(cwd);
+  if (!registry) return null;
+  return registry.items[id] || null;
+}
+
+/**
+ * Update a knowledge item
+ * @param {string} id - Item ID
+ * @param {Object} updates - Fields to update
+ * @param {string} cwd - Working directory
+ * @returns {KnowledgeItem|null}
+ */
+export function updateKnowledgeItem(id, updates, cwd = process.cwd()) {
+  const registry = getKnowledgeRegistry(cwd);
+  if (!registry || !registry.items[id]) return null;
+
+  registry.items[id] = {
+    ...registry.items[id],
+    ...updates
+  };
+
+  saveKnowledgeRegistry(registry, cwd);
+  return registry.items[id];
+}
+
+/**
+ * Record an access to a knowledge item
+ * @param {string} id - Item ID
+ * @param {string} cwd - Working directory
+ * @returns {KnowledgeItem|null}
+ */
+export function recordAccess(id, cwd = process.cwd()) {
+  const registry = getKnowledgeRegistry(cwd);
+  if (!registry || !registry.items[id]) return null;
+
+  registry.items[id].accessCount = (registry.items[id].accessCount || 0) + 1;
+  registry.items[id].lastAccessed = new Date().toISOString();
+
+  saveKnowledgeRegistry(registry, cwd);
+  return registry.items[id];
+}
+
+/**
+ * Record that a knowledge item was applied in a context
+ * @param {string} id - Item ID
+ * @param {string} context - Context description (e.g., file path, feature name)
+ * @param {string} cwd - Working directory
+ * @returns {KnowledgeItem|null}
+ */
+export function recordApplication(id, context, cwd = process.cwd()) {
+  const registry = getKnowledgeRegistry(cwd);
+  if (!registry || !registry.items[id]) return null;
+
+  const item = registry.items[id];
+  item.appliedCount = (item.appliedCount || 0) + 1;
+  item.appliedContexts = item.appliedContexts || [];
+
+  if (!item.appliedContexts.includes(context)) {
+    item.appliedContexts.push(context);
+  }
+
+  item.lastAccessed = new Date().toISOString();
+
+  // Check for promotion candidate
+  if (item.type === 'decision' &&
+      item.appliedCount >= 3 &&
+      item.appliedContexts.length >= 2 &&
+      item.status === 'active') {
+    item.status = 'candidate_pattern';
+  }
+
+  saveKnowledgeRegistry(registry, cwd);
+  return item;
+}
+
+/**
+ * Get all knowledge items
+ * @param {Object} options - Filter options
+ * @param {string} options.type - Filter by type
+ * @param {string} options.status - Filter by status
+ * @param {string} cwd - Working directory
+ * @returns {KnowledgeItem[]}
+ */
+export function getAllKnowledge(options = {}, cwd = process.cwd()) {
+  const registry = getKnowledgeRegistry(cwd);
+  if (!registry) return [];
+
+  let items = Object.values(registry.items);
+
+  if (options.type) {
+    items = items.filter(item => item.type === options.type);
+  }
+
+  if (options.status) {
+    items = items.filter(item => item.status === options.status);
+  }
+
+  return items;
+}
+
+/**
+ * Get knowledge statistics
+ * @param {string} cwd - Working directory
+ * @returns {Object}
+ */
+export function getKnowledgeStats(cwd = process.cwd()) {
+  const registry = getKnowledgeRegistry(cwd);
+  if (!registry) {
+    return {
+      total: 0,
+      decisions: 0,
+      deadends: 0,
+      active: 0,
+      candidatePatterns: 0,
+      archived: 0,
+      garbage: 0,
+      lastSync: null,
+      lastGC: null
+    };
+  }
+
+  const items = Object.values(registry.items);
+
+  return {
+    total: items.length,
+    decisions: items.filter(i => i.type === 'decision').length,
+    deadends: items.filter(i => i.type === 'deadend').length,
+    active: items.filter(i => i.status === 'active').length,
+    candidatePatterns: items.filter(i => i.status === 'candidate_pattern').length,
+    archived: items.filter(i => i.status === 'archived').length,
+    garbage: items.filter(i => i.status === 'garbage').length,
+    lastSync: registry.lastSync,
+    lastGC: registry.lastGC
+  };
+}
+
+/**
+ * Change status of a knowledge item
+ * @param {string} id - Item ID
+ * @param {KnowledgeStatus} newStatus - New status
+ * @param {string} cwd - Working directory
+ * @returns {KnowledgeItem|null}
+ */
+export function changeStatus(id, newStatus, cwd = process.cwd()) {
+  const validStatuses = ['active', 'candidate_pattern', 'archived', 'garbage'];
+  if (!validStatuses.includes(newStatus)) {
+    throw new Error(`Invalid status: ${newStatus}. Valid: ${validStatuses.join(', ')}`);
+  }
+
+  return updateKnowledgeItem(id, { status: newStatus }, cwd);
+}