@fermindi/pwn-cli 0.1.1 → 0.2.0

package/cli/knowledge.js

@@ -1,531 +1,531 @@
-import { existsSync } from 'fs';
-import { join } from 'path';
-import {
-  initKnowledgeRegistry,
-  syncKnowledge,
-  getKnowledgeStats,
-  getAllKnowledge,
-  getKnowledgeItem,
-  recordAccess,
-  recordApplication,
-  changeStatus
-} from '../src/knowledge/lifecycle.js';
-import {
-  updateReferences,
-  addReference,
-  findBrokenReferences,
-  getReferenceStats
-} from '../src/knowledge/references.js';
-import {
-  dryRunGC,
-  executeGC,
-  getGCStats,
-  getArchivalCandidates,
-  restoreFromArchive
-} from '../src/knowledge/gc.js';
-import {
-  checkPromotionEligibility,
-  getPromotionCandidates,
-  promoteToPattern,
-  getPromotionStats,
-  suggestPromotion
-} from '../src/knowledge/promote.js';
-
-const cwd = process.cwd();
-
-export default async function knowledge(args) {
-  const subcommand = args[0];
-
-  // Check for PWN workspace
-  if (!existsSync(join(cwd, '.ai'))) {
-    console.log('No PWN workspace found in current directory.');
-    console.log('Run: pwn inject');
-    process.exit(1);
-  }
-
-  switch (subcommand) {
-    case 'status':
-      await showStatus();
-      break;
-
-    case 'sync':
-      await runSync();
-      break;
-
-    case 'check':
-      await checkReferences();
-      break;
-
-    case 'gc':
-      await runGC(args.slice(1));
-      break;
-
-    case 'promote':
-      await runPromote(args.slice(1));
-      break;
-
-    case 'link':
-      await runLink(args.slice(1));
-      break;
-
-    case 'show':
-      await showItem(args[1]);
-      break;
-
-    case 'access':
-      await recordItemAccess(args[1]);
-      break;
-
-    case 'apply':
-      await recordItemApplication(args[1], args[2]);
-      break;
-
-    case 'restore':
-      await runRestore(args[1]);
-      break;
-
-    default:
-      showHelp();
-  }
-}
-
-function showHelp() {
-  console.log(`
-PWN Knowledge Lifecycle
-
-Usage: pwn knowledge <command> [options]
-
-Commands:
-  status              Show knowledge system status
-  sync                Sync registry with markdown files
-  check               Find broken references
-  gc                  Garbage collection (dry-run)
-  gc --apply          Execute garbage collection
-  gc --no-archive     Delete instead of archive
-  promote <id>        Promote decision to pattern
-  promote --list      List promotion candidates
-  link <id> <target>  Add reference link
-  show <id>           Show knowledge item details
-  access <id>         Record an access to item
-  apply <id> <ctx>    Record application in context
-  restore <id>        Restore archived item
-
-Examples:
-  pwn knowledge status
-  pwn knowledge sync
-  pwn knowledge gc
-  pwn knowledge gc --apply
-  pwn knowledge promote DEC-005
-  pwn knowledge link DEC-001 src/auth/login.ts
-  pwn knowledge show DEC-001
-`);
-}
-
-async function showStatus() {
-  // Initialize if needed
-  initKnowledgeRegistry(cwd);
-
-  const stats = getKnowledgeStats(cwd);
-  const refStats = getReferenceStats(cwd);
-  const gcStats = getGCStats(cwd);
-  const promoStats = getPromotionStats(cwd);
-
-  console.log('\n PWN Knowledge Lifecycle Status\n');
-
-  console.log('Knowledge Items:');
-  console.log(`  Total:      ${stats.total}`);
-  console.log(`  Decisions:  ${stats.decisions}`);
-  console.log(`  Dead-ends:  ${stats.deadends}`);
-  console.log(`  Active:     ${stats.active}`);
-  console.log(`  Candidates: ${stats.candidatePatterns}`);
-  console.log(`  Archived:   ${stats.archived}`);
-  console.log(`  Garbage:    ${stats.garbage}`);
-
-  console.log('\nReferences:');
-  console.log(`  Total refs:      ${refStats.totalRefs}`);
-  console.log(`  Avg per item:    ${refStats.avgRefsPerItem}`);
-  console.log(`  Orphaned items:  ${refStats.orphaned}`);
-
-  if (refStats.mostReferenced.length > 0) {
-    console.log('\n  Most Referenced:');
-    for (const item of refStats.mostReferenced.slice(0, 3)) {
-      console.log(`    ${item.id}: ${item.count} refs - ${item.title.substring(0, 40)}`);
-    }
-  }
-
-  console.log('\nGarbage Collection:');
-  console.log(`  Last GC:          ${gcStats.lastGC}`);
-  console.log(`  Ready for GC:     ${gcStats.garbageCount}`);
-  console.log(`  Archive candidates: ${gcStats.archivalCandidates}`);
-  console.log(`  Broken refs:      ${gcStats.brokenReferences}`);
-
-  console.log('\nPattern Promotion:');
-  console.log(`  Promoted:    ${promoStats.promotedCount}`);
-  console.log(`  Candidates:  ${promoStats.candidateCount}`);
-  console.log(`  Eligible:    ${promoStats.eligibleCount}`);
-
-  const suggestion = suggestPromotion(cwd);
-  if (suggestion) {
-    console.log(`\n  Suggestion: ${suggestion.message}`);
-  }
-
-  console.log(`\nLast Sync: ${stats.lastSync || 'Never'}`);
-  console.log('');
-}
-
-async function runSync() {
-  console.log('Syncing knowledge registry with markdown files...\n');
-
-  const result = syncKnowledge(cwd);
-
-  if (result.added.length > 0) {
-    console.log(`Added ${result.added.length} items:`);
-    for (const id of result.added) {
-      console.log(`  + ${id}`);
-    }
-  }
-
-  if (result.updated.length > 0) {
-    console.log(`Updated ${result.updated.length} items`);
-  }
-
-  if (result.removed.length > 0) {
-    console.log(`Marked ${result.removed.length} items as garbage:`);
-    for (const id of result.removed) {
-      console.log(`  - ${id}`);
-    }
-  }
-
-  // Also update file references
-  console.log('\nScanning for file references...');
-  const refResult = updateReferences(cwd);
-
-  if (refResult.error) {
-    console.log(`  Error: ${refResult.error}`);
-  } else {
-    console.log(`  Updated: ${refResult.updated.length} items`);
-    console.log(`  Orphaned: ${refResult.orphaned.length} items`);
-    if (refResult.newRefs.length > 0) {
-      console.log(`  New references found: ${refResult.newRefs.length}`);
-    }
-  }
-
-  console.log('\nSync complete.');
-}
-
-async function checkReferences() {
-  console.log('Checking for broken references...\n');
-
-  const broken = findBrokenReferences(cwd);
-
-  if (broken.length === 0) {
-    console.log('No broken references found.');
-    return;
-  }
-
-  console.log(`Found ${broken.length} items with broken references:\n`);
-
-  for (const item of broken) {
-    console.log(`${item.id}:`);
-    if (item.brokenFiles.length > 0) {
-      console.log('  Missing files:');
-      for (const file of item.brokenFiles) {
-        console.log(`    - ${file}`);
-      }
-    }
-    if (item.brokenDecisions.length > 0) {
-      console.log('  Missing decisions:');
-      for (const dec of item.brokenDecisions) {
-        console.log(`    - ${dec}`);
-      }
-    }
-  }
-
-  console.log('\nRun `pwn knowledge gc --apply` to clean broken references.');
-}
-
-async function runGC(args) {
-  const apply = args.includes('--apply');
-  const archive = !args.includes('--no-archive');
-
-  if (!apply) {
-    console.log('Garbage Collection (Dry Run)\n');
-    const result = dryRunGC(cwd);
-
-    if (result.marked.length === 0 && result.cleaned.length === 0) {
-      console.log('Nothing to collect. Knowledge base is clean.');
-      return;
-    }
-
-    if (result.marked.length > 0) {
-      console.log(`Items to be ${archive ? 'archived' : 'deleted'}:`);
-      for (const item of result.details.garbage) {
-        console.log(`  ${item.id}: ${item.reason} - ${item.title}`);
-      }
-    }
-
-    if (result.cleaned.length > 0) {
-      console.log(`\nBroken references to clean: ${result.cleaned.length}`);
-    }
-
-    console.log('\nRun with --apply to execute.');
-    return;
-  }
-
-  console.log(`Executing Garbage Collection (${archive ? 'archive' : 'delete'} mode)...\n`);
-
-  const result = executeGC({ archive, cleanBroken: true }, cwd);
-
-  if (result.archived.length > 0) {
-    console.log(`Archived ${result.archived.length} items:`);
-    for (const id of result.archived) {
-      console.log(`  ${id}`);
-    }
-  }
-
-  if (result.deleted.length > 0) {
-    console.log(`Deleted ${result.deleted.length} items:`);
-    for (const id of result.deleted) {
-      console.log(`  ${id}`);
-    }
-  }
-
-  if (result.cleaned.length > 0) {
-    console.log(`Cleaned references in ${result.cleaned.length} items`);
-  }
-
-  if (result.marked.length === 0 && result.cleaned.length === 0) {
-    console.log('Nothing to collect.');
-  }
-
-  console.log('\nGarbage collection complete.');
-}
-
-async function runPromote(args) {
-  if (args.includes('--list')) {
-    const candidates = getPromotionCandidates(cwd);
-
-    if (candidates.length === 0) {
-      console.log('No promotion candidates found.');
-      console.log('Decisions become candidates after being applied 3+ times in 2+ contexts.');
-      return;
-    }
-
-    console.log('Promotion Candidates:\n');
-    for (const c of candidates) {
-      const status = c.isEligible ? '[READY]' : '[pending]';
-      console.log(`${status} ${c.id}: ${c.title}`);
-      console.log(`   Applied: ${c.eligibility.appliedCount.current}/${c.eligibility.appliedCount.required}`);
-      console.log(`   Contexts: ${c.eligibility.appliedContexts.current}/${c.eligibility.appliedContexts.required}`);
-      console.log(`   Accessed: ${c.eligibility.accessCount.current}/${c.eligibility.accessCount.required}`);
-      console.log('');
-    }
-    return;
-  }
-
-  const id = args[0];
-  if (!id) {
-    console.log('Usage: pwn knowledge promote <id>');
-    console.log('       pwn knowledge promote --list');
-    return;
-  }
-
-  // Check eligibility
-  const eligibility = checkPromotionEligibility(id, cwd);
-
-  if (!eligibility.eligible) {
-    console.log(`${id} is not eligible for promotion.\n`);
-    console.log('Criteria:');
-    for (const [key, val] of Object.entries(eligibility.criteria)) {
-      const status = val.met ? '[x]' : '[ ]';
-      console.log(`  ${status} ${key}: ${val.current}/${val.required}`);
-    }
-
-    if (args.includes('--force')) {
-      console.log('\n--force flag detected. Proceeding anyway...');
-    } else {
-      console.log('\nUse --force to promote anyway.');
-      return;
-    }
-  }
-
-  // Get category
-  const categoryArg = args.find(a => a.startsWith('--category='));
-  const category = categoryArg ? categoryArg.split('=')[1] : undefined;
-
-  const result = promoteToPattern(id, {
-    category,
-    force: args.includes('--force')
-  }, cwd);
-
-  if (result.success) {
-    console.log(`Promoted ${id} to pattern!`);
-    console.log(`  File: .ai/${result.patternFile}`);
-    console.log(`  Category: ${result.category}`);
-    console.log('\nEdit the pattern file to add details and examples.');
-  } else {
-    console.log(`Failed to promote: ${result.error}`);
-  }
-}
-
-async function runLink(args) {
-  const [id, target, typeArg] = args;
-
-  if (!id || !target) {
-    console.log('Usage: pwn knowledge link <id> <target> [--type=file|decision|task]');
-    console.log('');
-    console.log('Examples:');
-    console.log('  pwn knowledge link DEC-001 src/auth/login.ts');
-    console.log('  pwn knowledge link DEC-001 DEC-002 --type=decision');
-    console.log('  pwn knowledge link DEC-001 TASK-005 --type=task');
-    return;
-  }
-
-  // Infer type if not provided
-  let targetType = 'file';
-  if (typeArg?.startsWith('--type=')) {
-    targetType = typeArg.split('=')[1];
-  } else if (target.startsWith('DEC-') || target.startsWith('DE-')) {
-    targetType = 'decision';
-  } else if (target.startsWith('TASK-')) {
-    targetType = 'task';
-  }
-
-  const result = addReference(id, target, targetType, cwd);
-
-  if (!result) {
-    console.log(`Failed to add link. Item ${id} not found.`);
-    return;
-  }
-
-  console.log(`Linked ${id} -> ${target} (${targetType})`);
-}
-
-async function showItem(id) {
-  if (!id) {
-    console.log('Usage: pwn knowledge show <id>');
-    return;
-  }
-
-  const item = getKnowledgeItem(id, cwd);
-
-  if (!item) {
-    console.log(`Item ${id} not found.`);
-    return;
-  }
-
-  console.log(`\n${item.id}: ${item.title}\n`);
-  console.log(`Type:           ${item.type}`);
-  console.log(`Status:         ${item.status}`);
-  console.log(`Created:        ${item.createdAt || 'Unknown'}`);
-  console.log(`Last Accessed:  ${item.lastAccessed || 'Never'}`);
-  console.log(`Access Count:   ${item.accessCount || 0}`);
-  console.log(`Applied Count:  ${item.appliedCount || 0}`);
-
-  if (item.relatedFiles?.length > 0) {
-    console.log(`\nRelated Files (${item.relatedFiles.length}):`);
-    for (const file of item.relatedFiles) {
-      console.log(`  - ${file}`);
-    }
-  }
-
-  if (item.relatedDecisions?.length > 0) {
-    console.log(`\nRelated Decisions (${item.relatedDecisions.length}):`);
-    for (const dec of item.relatedDecisions) {
-      console.log(`  - ${dec}`);
-    }
-  }
-
-  if (item.relatedTasks?.length > 0) {
-    console.log(`\nRelated Tasks (${item.relatedTasks.length}):`);
-    for (const task of item.relatedTasks) {
-      console.log(`  - ${task}`);
-    }
-  }
-
-  if (item.appliedContexts?.length > 0) {
-    console.log(`\nApplied Contexts (${item.appliedContexts.length}):`);
-    for (const ctx of item.appliedContexts) {
-      console.log(`  - ${ctx}`);
-    }
-  }
-
-  // Check promotion eligibility for decisions
-  if (item.type === 'decision' && item.status === 'active') {
-    const elig = checkPromotionEligibility(id, cwd);
-    console.log(`\nPromotion Status: ${elig.eligible ? 'ELIGIBLE' : 'Not eligible'}`);
-    if (!elig.eligible) {
-      for (const [key, val] of Object.entries(elig.criteria)) {
-        if (!val.met) {
-          console.log(`  - Need ${val.required - val.current} more ${key}`);
-        }
-      }
-    }
-  }
-
-  console.log('');
-}
-
-async function recordItemAccess(id) {
-  if (!id) {
-    console.log('Usage: pwn knowledge access <id>');
-    return;
-  }
-
-  const result = recordAccess(id, cwd);
-
-  if (!result) {
-    console.log(`Item ${id} not found.`);
-    return;
-  }
-
-  console.log(`Recorded access to ${id} (total: ${result.accessCount})`);
-}
-
-async function recordItemApplication(id, context) {
-  if (!id || !context) {
-    console.log('Usage: pwn knowledge apply <id> <context>');
-    console.log('');
-    console.log('Example:');
-    console.log('  pwn knowledge apply DEC-001 "user-auth-feature"');
-    return;
-  }
-
-  const result = recordApplication(id, context, cwd);
-
-  if (!result) {
-    console.log(`Item ${id} not found.`);
-    return;
-  }
-
-  console.log(`Recorded application of ${id} in "${context}"`);
-  console.log(`  Applied: ${result.appliedCount} times`);
-  console.log(`  Contexts: ${result.appliedContexts.length}`);
-
-  if (result.status === 'candidate_pattern') {
-    console.log(`\n${id} is now a candidate for promotion to pattern!`);
-    console.log('Run: pwn knowledge promote --list');
-  }
-}
-
-async function runRestore(id) {
-  if (!id) {
-    console.log('Usage: pwn knowledge restore <id>');
-    return;
-  }
-
-  const result = restoreFromArchive(id, cwd);
-
-  if (!result) {
-    console.log(`Item ${id} not found.`);
-    return;
-  }
-
-  if (result.error) {
-    console.log(`Error: ${result.error}`);
-    return;
-  }
-
-  console.log(`Restored ${id} from archive.`);
-  console.log(`Status: ${result.status}`);
-}
+import { existsSync } from 'fs';
+import { join } from 'path';
+import {
+  initKnowledgeRegistry,
+  syncKnowledge,
+  getKnowledgeStats,
+  getAllKnowledge,
+  getKnowledgeItem,
+  recordAccess,
+  recordApplication,
+  changeStatus
+} from '../src/knowledge/lifecycle.js';
+import {
+  updateReferences,
+  addReference,
+  findBrokenReferences,
+  getReferenceStats
+} from '../src/knowledge/references.js';
+import {
+  dryRunGC,
+  executeGC,
+  getGCStats,
+  getArchivalCandidates,
+  restoreFromArchive
+} from '../src/knowledge/gc.js';
+import {
+  checkPromotionEligibility,
+  getPromotionCandidates,
+  promoteToPattern,
+  getPromotionStats,
+  suggestPromotion
+} from '../src/knowledge/promote.js';
+
+const cwd = process.cwd();
+
+export default async function knowledge(args) {
+  const subcommand = args[0];
+
+  // Check for PWN workspace
+  if (!existsSync(join(cwd, '.ai'))) {
+    console.log('No PWN workspace found in current directory.');
+    console.log('Run: pwn inject');
+    process.exit(1);
+  }
+
+  switch (subcommand) {
+    case 'status':
+      await showStatus();
+      break;
+
+    case 'sync':
+      await runSync();
+      break;
+
+    case 'check':
+      await checkReferences();
+      break;
+
+    case 'gc':
+      await runGC(args.slice(1));
+      break;
+
+    case 'promote':
+      await runPromote(args.slice(1));
+      break;
+
+    case 'link':
+      await runLink(args.slice(1));
+      break;
+
+    case 'show':
+      await showItem(args[1]);
+      break;
+
+    case 'access':
+      await recordItemAccess(args[1]);
+      break;
+
+    case 'apply':
+      await recordItemApplication(args[1], args[2]);
+      break;
+
+    case 'restore':
+      await runRestore(args[1]);
+      break;
+
+    default:
+      showHelp();
+  }
+}
+
+function showHelp() {
+  console.log(`
+PWN Knowledge Lifecycle
+
+Usage: pwn knowledge <command> [options]
+
+Commands:
+  status              Show knowledge system status
+  sync                Sync registry with markdown files
+  check               Find broken references
+  gc                  Garbage collection (dry-run)
+  gc --apply          Execute garbage collection
+  gc --no-archive     Delete instead of archive
+  promote <id>        Promote decision to pattern
+  promote --list      List promotion candidates
+  link <id> <target>  Add reference link
+  show <id>           Show knowledge item details
+  access <id>         Record an access to item
+  apply <id> <ctx>    Record application in context
+  restore <id>        Restore archived item
+
+Examples:
+  pwn knowledge status
+  pwn knowledge sync
+  pwn knowledge gc
+  pwn knowledge gc --apply
+  pwn knowledge promote DEC-005
+  pwn knowledge link DEC-001 src/auth/login.ts
+  pwn knowledge show DEC-001
+`);
+}
+
+async function showStatus() {
+  // Initialize if needed
+  initKnowledgeRegistry(cwd);
+
+  const stats = getKnowledgeStats(cwd);
+  const refStats = getReferenceStats(cwd);
+  const gcStats = getGCStats(cwd);
+  const promoStats = getPromotionStats(cwd);
+
+  console.log('\n PWN Knowledge Lifecycle Status\n');
+
+  console.log('Knowledge Items:');
+  console.log(`  Total:      ${stats.total}`);
+  console.log(`  Decisions:  ${stats.decisions}`);
+  console.log(`  Dead-ends:  ${stats.deadends}`);
+  console.log(`  Active:     ${stats.active}`);
+  console.log(`  Candidates: ${stats.candidatePatterns}`);
+  console.log(`  Archived:   ${stats.archived}`);
+  console.log(`  Garbage:    ${stats.garbage}`);
+
+  console.log('\nReferences:');
+  console.log(`  Total refs:      ${refStats.totalRefs}`);
+  console.log(`  Avg per item:    ${refStats.avgRefsPerItem}`);
+  console.log(`  Orphaned items:  ${refStats.orphaned}`);
+
+  if (refStats.mostReferenced.length > 0) {
+    console.log('\n  Most Referenced:');
+    for (const item of refStats.mostReferenced.slice(0, 3)) {
+      console.log(`    ${item.id}: ${item.count} refs - ${item.title.substring(0, 40)}`);
+    }
+  }
+
+  console.log('\nGarbage Collection:');
+  console.log(`  Last GC:          ${gcStats.lastGC}`);
+  console.log(`  Ready for GC:     ${gcStats.garbageCount}`);
+  console.log(`  Archive candidates: ${gcStats.archivalCandidates}`);
+  console.log(`  Broken refs:      ${gcStats.brokenReferences}`);
+
+  console.log('\nPattern Promotion:');
+  console.log(`  Promoted:    ${promoStats.promotedCount}`);
+  console.log(`  Candidates:  ${promoStats.candidateCount}`);
+  console.log(`  Eligible:    ${promoStats.eligibleCount}`);
+
+  const suggestion = suggestPromotion(cwd);
+  if (suggestion) {
+    console.log(`\n  Suggestion: ${suggestion.message}`);
+  }
+
+  console.log(`\nLast Sync: ${stats.lastSync || 'Never'}`);
+  console.log('');
+}
+
+async function runSync() {
+  console.log('Syncing knowledge registry with markdown files...\n');
+
+  const result = syncKnowledge(cwd);
+
+  if (result.added.length > 0) {
+    console.log(`Added ${result.added.length} items:`);
+    for (const id of result.added) {
+      console.log(`  + ${id}`);
+    }
+  }
+
+  if (result.updated.length > 0) {
+    console.log(`Updated ${result.updated.length} items`);
+  }
+
+  if (result.removed.length > 0) {
+    console.log(`Marked ${result.removed.length} items as garbage:`);
+    for (const id of result.removed) {
+      console.log(`  - ${id}`);
+    }
+  }
+
+  // Also update file references
+  console.log('\nScanning for file references...');
+  const refResult = updateReferences(cwd);
+
+  if (refResult.error) {
+    console.log(`  Error: ${refResult.error}`);
+  } else {
+    console.log(`  Updated: ${refResult.updated.length} items`);
+    console.log(`  Orphaned: ${refResult.orphaned.length} items`);
+    if (refResult.newRefs.length > 0) {
+      console.log(`  New references found: ${refResult.newRefs.length}`);
+    }
+  }
+
+  console.log('\nSync complete.');
+}
+
+async function checkReferences() {
+  console.log('Checking for broken references...\n');
+
+  const broken = findBrokenReferences(cwd);
+
+  if (broken.length === 0) {
+    console.log('No broken references found.');
+    return;
+  }
+
+  console.log(`Found ${broken.length} items with broken references:\n`);
+
+  for (const item of broken) {
+    console.log(`${item.id}:`);
+    if (item.brokenFiles.length > 0) {
+      console.log('  Missing files:');
+      for (const file of item.brokenFiles) {
+        console.log(`    - ${file}`);
+      }
+    }
+    if (item.brokenDecisions.length > 0) {
+      console.log('  Missing decisions:');
+      for (const dec of item.brokenDecisions) {
+        console.log(`    - ${dec}`);
+      }
+    }
+  }
+
+  console.log('\nRun `pwn knowledge gc --apply` to clean broken references.');
+}
+
+async function runGC(args) {
+  const apply = args.includes('--apply');
+  const archive = !args.includes('--no-archive');
+
+  if (!apply) {
+    console.log('Garbage Collection (Dry Run)\n');
+    const result = dryRunGC(cwd);
+
+    if (result.marked.length === 0 && result.cleaned.length === 0) {
+      console.log('Nothing to collect. Knowledge base is clean.');
+      return;
+    }
+
+    if (result.marked.length > 0) {
+      console.log(`Items to be ${archive ? 'archived' : 'deleted'}:`);
+      for (const item of result.details.garbage) {
+        console.log(`  ${item.id}: ${item.reason} - ${item.title}`);
+      }
+    }
+
+    if (result.cleaned.length > 0) {
+      console.log(`\nBroken references to clean: ${result.cleaned.length}`);
+    }
+
+    console.log('\nRun with --apply to execute.');
+    return;
+  }
+
+  console.log(`Executing Garbage Collection (${archive ? 'archive' : 'delete'} mode)...\n`);
+
+  const result = executeGC({ archive, cleanBroken: true }, cwd);
+
+  if (result.archived.length > 0) {
+    console.log(`Archived ${result.archived.length} items:`);
+    for (const id of result.archived) {
+      console.log(`  ${id}`);
+    }
+  }
+
+  if (result.deleted.length > 0) {
+    console.log(`Deleted ${result.deleted.length} items:`);
+    for (const id of result.deleted) {
+      console.log(`  ${id}`);
+    }
+  }
+
+  if (result.cleaned.length > 0) {
+    console.log(`Cleaned references in ${result.cleaned.length} items`);
+  }
+
+  if (result.marked.length === 0 && result.cleaned.length === 0) {
+    console.log('Nothing to collect.');
+  }
+
+  console.log('\nGarbage collection complete.');
+}
+
+async function runPromote(args) {
+  if (args.includes('--list')) {
+    const candidates = getPromotionCandidates(cwd);
+
+    if (candidates.length === 0) {
+      console.log('No promotion candidates found.');
+      console.log('Decisions become candidates after being applied 3+ times in 2+ contexts.');
+      return;
+    }
+
+    console.log('Promotion Candidates:\n');
+    for (const c of candidates) {
+      const status = c.isEligible ? '[READY]' : '[pending]';
+      console.log(`${status} ${c.id}: ${c.title}`);
+      console.log(`   Applied: ${c.eligibility.appliedCount.current}/${c.eligibility.appliedCount.required}`);
+      console.log(`   Contexts: ${c.eligibility.appliedContexts.current}/${c.eligibility.appliedContexts.required}`);
+      console.log(`   Accessed: ${c.eligibility.accessCount.current}/${c.eligibility.accessCount.required}`);
+      console.log('');
+    }
+    return;
+  }
+
+  const id = args[0];
+  if (!id) {
+    console.log('Usage: pwn knowledge promote <id>');
+    console.log('       pwn knowledge promote --list');
+    return;
+  }
+
+  // Check eligibility
+  const eligibility = checkPromotionEligibility(id, cwd);
+
+  if (!eligibility.eligible) {
+    console.log(`${id} is not eligible for promotion.\n`);
+    console.log('Criteria:');
+    for (const [key, val] of Object.entries(eligibility.criteria)) {
+      const status = val.met ? '[x]' : '[ ]';
+      console.log(`  ${status} ${key}: ${val.current}/${val.required}`);
+    }
+
+    if (args.includes('--force')) {
+      console.log('\n--force flag detected. Proceeding anyway...');
+    } else {
+      console.log('\nUse --force to promote anyway.');
+      return;
+    }
+  }
+
+  // Get category
+  const categoryArg = args.find(a => a.startsWith('--category='));
+  const category = categoryArg ? categoryArg.split('=')[1] : undefined;
+
+  const result = promoteToPattern(id, {
+    category,
+    force: args.includes('--force')
+  }, cwd);
+
+  if (result.success) {
+    console.log(`Promoted ${id} to pattern!`);
+    console.log(`  File: .ai/${result.patternFile}`);
+    console.log(`  Category: ${result.category}`);
+    console.log('\nEdit the pattern file to add details and examples.');
+  } else {
+    console.log(`Failed to promote: ${result.error}`);
+  }
+}
+
+async function runLink(args) {
+  const [id, target, typeArg] = args;
+
+  if (!id || !target) {
+    console.log('Usage: pwn knowledge link <id> <target> [--type=file|decision|task]');
+    console.log('');
+    console.log('Examples:');
+    console.log('  pwn knowledge link DEC-001 src/auth/login.ts');
+    console.log('  pwn knowledge link DEC-001 DEC-002 --type=decision');
+    console.log('  pwn knowledge link DEC-001 TASK-005 --type=task');
+    return;
+  }
+
+  // Infer type if not provided
+  let targetType = 'file';
+  if (typeArg?.startsWith('--type=')) {
+    targetType = typeArg.split('=')[1];
+  } else if (target.startsWith('DEC-') || target.startsWith('DE-')) {
+    targetType = 'decision';
+  } else if (target.startsWith('TASK-')) {
+    targetType = 'task';
+  }
+
+  const result = addReference(id, target, targetType, cwd);
+
+  if (!result) {
+    console.log(`Failed to add link. Item ${id} not found.`);
+    return;
+  }
+
+  console.log(`Linked ${id} -> ${target} (${targetType})`);
+}
+
+async function showItem(id) {
+  if (!id) {
+    console.log('Usage: pwn knowledge show <id>');
+    return;
+  }
+
+  const item = getKnowledgeItem(id, cwd);
+
+  if (!item) {
+    console.log(`Item ${id} not found.`);
+    return;
+  }
+
+  console.log(`\n${item.id}: ${item.title}\n`);
+  console.log(`Type:           ${item.type}`);
+  console.log(`Status:         ${item.status}`);
+  console.log(`Created:        ${item.createdAt || 'Unknown'}`);
+  console.log(`Last Accessed:  ${item.lastAccessed || 'Never'}`);
+  console.log(`Access Count:   ${item.accessCount || 0}`);
+  console.log(`Applied Count:  ${item.appliedCount || 0}`);
+
+  if (item.relatedFiles?.length > 0) {
+    console.log(`\nRelated Files (${item.relatedFiles.length}):`);
+    for (const file of item.relatedFiles) {
+      console.log(`  - ${file}`);
+    }
+  }
+
+  if (item.relatedDecisions?.length > 0) {
+    console.log(`\nRelated Decisions (${item.relatedDecisions.length}):`);
+    for (const dec of item.relatedDecisions) {
+      console.log(`  - ${dec}`);
+    }
+  }
+
+  if (item.relatedTasks?.length > 0) {
+    console.log(`\nRelated Tasks (${item.relatedTasks.length}):`);
+    for (const task of item.relatedTasks) {
+      console.log(`  - ${task}`);
+    }
+  }
+
+  if (item.appliedContexts?.length > 0) {
+    console.log(`\nApplied Contexts (${item.appliedContexts.length}):`);
+    for (const ctx of item.appliedContexts) {
+      console.log(`  - ${ctx}`);
+    }
+  }
+
+  // Check promotion eligibility for decisions
+  if (item.type === 'decision' && item.status === 'active') {
+    const elig = checkPromotionEligibility(id, cwd);
+    console.log(`\nPromotion Status: ${elig.eligible ? 'ELIGIBLE' : 'Not eligible'}`);
+    if (!elig.eligible) {
+      for (const [key, val] of Object.entries(elig.criteria)) {
+        if (!val.met) {
+          console.log(`  - Need ${val.required - val.current} more ${key}`);
+        }
+      }
+    }
+  }
+
+  console.log('');
+}
+
+async function recordItemAccess(id) {
+  if (!id) {
+    console.log('Usage: pwn knowledge access <id>');
+    return;
+  }
+
+  const result = recordAccess(id, cwd);
+
+  if (!result) {
+    console.log(`Item ${id} not found.`);
+    return;
+  }
+
+  console.log(`Recorded access to ${id} (total: ${result.accessCount})`);
+}
+
+async function recordItemApplication(id, context) {
+  if (!id || !context) {
+    console.log('Usage: pwn knowledge apply <id> <context>');
+    console.log('');
+    console.log('Example:');
+    console.log('  pwn knowledge apply DEC-001 "user-auth-feature"');
+    return;
+  }
+
+  const result = recordApplication(id, context, cwd);
+
+  if (!result) {
+    console.log(`Item ${id} not found.`);
+    return;
+  }
+
+  console.log(`Recorded application of ${id} in "${context}"`);
+  console.log(`  Applied: ${result.appliedCount} times`);
+  console.log(`  Contexts: ${result.appliedContexts.length}`);
+
+  if (result.status === 'candidate_pattern') {
+    console.log(`\n${id} is now a candidate for promotion to pattern!`);
+    console.log('Run: pwn knowledge promote --list');
+  }
+}
+
+async function runRestore(id) {
+  if (!id) {
+    console.log('Usage: pwn knowledge restore <id>');
+    return;
+  }
+
+  const result = restoreFromArchive(id, cwd);
+
+  if (!result) {
+    console.log(`Item ${id} not found.`);
+    return;
+  }
+
+  if (result.error) {
+    console.log(`Error: ${result.error}`);
+    return;
+  }
+
+  console.log(`Restored ${id} from archive.`);
+  console.log(`Status: ${result.status}`);
+}