scoops 0.1.0

package/src/commands/prune.js

@@ -0,0 +1,107 @@
+'use strict';
+
+const { parseArgs } = require('node:util');
+const readline = require('node:readline');
+const { readKnowledge, writeKnowledge, TYPES } = require('../lib/memory');
+const { rebuildIndex } = require('../lib/index');
+
+const { values } = parseArgs({
+  options: {
+    keep:     { type: 'string' },
+    before:   { type: 'string' },
+    tag:      { type: 'string' },
+    type:     { type: 'string', short: 't' },
+    'dry-run':{ type: 'boolean', default: false },
+    yes:      { type: 'boolean', short: 'y', default: false },
+  },
+  strict: false,
+});
+
+const cwd = process.cwd();
+const dryRun = values['dry-run'];
+const keepN = values.keep ? parseInt(values.keep, 10) : null;
+const beforeDate = values.before ? new Date(values.before) : null;
+const tagFilter = values.tag;
+const typeFilter = values.type;
+
+if (!keepN && !beforeDate && !tagFilter) {
+  console.error('Specify at least one filter: --keep N, --before DATE, or --tag TAG');
+  console.error('Example: ascr prune --keep 50');
+  process.exit(1);
+}
+
+const typesToPrune = typeFilter ? [typeFilter] : TYPES;
+const removals = {};
+let totalRemoved = 0;
+
+for (const type of typesToPrune) {
+  const entries = readKnowledge(cwd, type);
+  let toRemove = [];
+
+  if (tagFilter) {
+    toRemove = entries.filter(e => (e.tags || []).includes(tagFilter));
+  }
+  if (beforeDate) {
+    const byDate = entries.filter(e => e.date && new Date(e.date) < beforeDate);
+    toRemove = [...new Set([...toRemove, ...byDate])];
+  }
+  if (keepN !== null) {
+    const excess = entries.length - keepN;
+    if (excess > 0) {
+      const byAge = entries.slice(0, excess);
+      toRemove = [...new Set([...toRemove, ...byAge])];
+    }
+  }
+
+  if (toRemove.length > 0) {
+    removals[type] = { entries, toRemove };
+    totalRemoved += toRemove.length;
+  }
+}
+
+if (totalRemoved === 0) {
+  console.log('\nNothing to prune with the given filters.\n');
+  process.exit(0);
+}
+
+// Show what will be removed
+console.log(`\nWill remove ${totalRemoved} entr${totalRemoved === 1 ? 'y' : 'ies'}:\n`);
+for (const [type, { toRemove }] of Object.entries(removals)) {
+  console.log(`  ${type}:`);
+  for (const e of toRemove) {
+    const label = e.decision || e.component || e.thread || e.warning || e.id;
+    console.log(`    - [${e.id || '?'}] ${label}`);
+  }
+}
+console.log('');
+
+if (dryRun) {
+  console.log('Dry run — nothing removed. Remove --dry-run to apply.\n');
+  process.exit(0);
+}
+
+// Confirm unless --yes
+function doRemoval() {
+  for (const [type, { entries, toRemove }] of Object.entries(removals)) {
+    const removeIds = new Set(toRemove.map(e => e.id));
+    const remaining = entries.filter(e => !removeIds.has(e.id));
+    writeKnowledge(cwd, type, remaining);
+  }
+  rebuildIndex(cwd);
+  console.log(`Removed ${totalRemoved} entr${totalRemoved === 1 ? 'y' : 'ies'} and rebuilt index.\n`);
+}
+
+if (values.yes) {
+  doRemoval();
+  process.exit(0);
+}
+
+const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+rl.question('Proceed? [y/N] ', (answer) => {
+  rl.close();
+  if (answer.toLowerCase() === 'y') {
+    doRemoval();
+  } else {
+    console.log('Aborted.\n');
+  }
+});

package/src/commands/status.js

@@ -0,0 +1,62 @@
+'use strict';
+
+const fs = require('node:fs');
+const paths = require('../lib/paths');
+const { getAscrHookEvents } = require('../lib/merge-settings');
+const { countAll } = require('../lib/memory');
+
+const cwd = process.cwd();
+let allOk = true;
+
+function check(label, ok, detail = '') {
+  const icon = ok ? 'OK  ' : 'FAIL';
+  console.log(`  [${icon}] ${label}${detail ? '  — ' + detail : ''}`);
+  if (!ok) allOk = false;
+}
+
+console.log('\nASCR Status\n───────────');
+
+// Knowledge files
+const knowledgeOk = fs.existsSync(paths.decisionsFile(cwd));
+check('.ascr/ directory', knowledgeOk, knowledgeOk ? '' : 'Run `ascr init`');
+
+if (knowledgeOk) {
+  const counts = countAll(cwd);
+  const summary = Object.entries(counts).map(([t, n]) => `${n} ${t}`).join(', ');
+  check('Knowledge files', true, summary);
+
+  const indexOk = fs.existsSync(paths.indexFile(cwd));
+  check('Index file (.ascr/index.json)', indexOk, indexOk ? '' : 'Run `ascr init --force`');
+}
+
+// Hook scripts
+const hooksOk = fs.existsSync(paths.hooksDir(cwd));
+const sessionStartOk = fs.existsSync(require('node:path').join(paths.hooksDir(cwd), 'session-start.js'));
+const retrieverOk    = fs.existsSync(require('node:path').join(paths.hooksDir(cwd), 'prompt-retriever.js'));
+const stopGateOk     = fs.existsSync(require('node:path').join(paths.hooksDir(cwd), 'stop-gate.js'));
+check('Hook: session-start.js',    sessionStartOk, sessionStartOk ? '' : 'Run `ascr init`');
+check('Hook: prompt-retriever.js', retrieverOk,    retrieverOk    ? '' : 'Run `ascr init`');
+check('Hook: stop-gate.js',        stopGateOk,     stopGateOk     ? '' : 'Run `ascr init`');
+
+// Settings registration
+const settingsPath = paths.settingsFile(cwd);
+const settingsExist = fs.existsSync(settingsPath);
+check('.claude/settings.json exists', settingsExist, settingsExist ? '' : 'Run `ascr init`');
+
+if (settingsExist) {
+  let settings = {};
+  try { settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8')); } catch { /* ignore */ }
+  const registered = getAscrHookEvents(settings);
+  const expectedEvents = ['SessionStart', 'UserPromptSubmit', 'Stop'];
+  for (const event of expectedEvents) {
+    check(`Hook registered: ${event}`, registered.includes(event), registered.includes(event) ? '' : 'Run `ascr init`');
+  }
+}
+
+console.log('');
+if (allOk) {
+  console.log('Everything looks good. Start a Claude Code session to activate ASCR.');
+} else {
+  console.log('Some checks failed. Run `ascr init` to fix.');
+}
+console.log('');

package/src/hooks/prompt-retriever.js

@@ -0,0 +1,147 @@
+#!/usr/bin/env node
+'use strict';
+
+// ASCR UserPromptSubmit Hook — standalone, no external dependencies
+// Extracts keywords from the user's prompt, scores against .ascr/index.json,
+// pulls top matching entries, and outputs them to stdout for context injection.
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const STOP_WORDS = new Set([
+  'a','an','the','and','or','but','in','on','at','to','for','of','with',
+  'by','from','is','it','its','be','as','are','was','were','been','has',
+  'have','had','do','does','did','will','would','could','should','may',
+  'might','can','i','we','you','he','she','they','this','that','these',
+  'those','what','how','why','when','where','which','who','not','no','so',
+  'if','then','my','our','your','their','me','us','add','make','create',
+  'update','get','set','use','using','want','need','please','help','let',
+  'just','also','now','like','new','old','all','some','any','into','out',
+]);
+
+function extractKeywords(prompt) {
+  return prompt
+    .toLowerCase()
+    .replace(/[^a-z0-9\s\-_]/g, ' ')
+    .split(/[\s\-_]+/)
+    .map(w => w.trim())
+    .filter(w => w.length >= 3 && !STOP_WORDS.has(w))
+    .filter((w, i, arr) => arr.indexOf(w) === i);
+}
+
+function scoreIndex(index, keywords) {
+  const results = [];
+  const typePriority = { threads: 4, architecture: 3, decisions: 2, warnings: 1 };
+  for (const [type, entries] of Object.entries(index)) {
+    for (const entry of (entries || [])) {
+      let score = 0;
+      const tags = (entry.tags || []).map(t => t.toLowerCase());
+      const key = (entry.key || '').toLowerCase();
+      for (const kw of keywords) {
+        if (tags.includes(kw))                            score += 2;
+        else if (tags.some(t => t.includes(kw) || kw.includes(t))) score += 1;
+        if (key.includes(kw))                             score += 1;
+      }
+      // Boost in-progress threads ONLY if there's already a keyword match
+      if (score > 0 && type === 'threads' && entry.status === 'in_progress') score += 1;
+      if (score > 0) results.push({ type, id: entry.id, score, priority: typePriority[type] || 0 });
+    }
+  }
+  return results.sort((a, b) => b.score !== a.score ? b.score - a.score : b.priority - a.priority);
+}
+
+function formatEntry(type, entry) {
+  const lines = [];
+  switch (type) {
+    case 'decisions':
+      lines.push(`[Decision] ${entry.decision}`);
+      if (entry.why) lines.push(`  Why: ${entry.why}`);
+      if (entry.alternatives_rejected?.length) lines.push(`  Rejected: ${entry.alternatives_rejected.join(', ')}`);
+      if (entry.affects?.length) lines.push(`  Affects: ${entry.affects.join(', ')}`);
+      break;
+    case 'architecture':
+      lines.push(`[Architecture] ${entry.component}${entry.location ? ` (${entry.location})` : ''}`);
+      if (entry.does) lines.push(`  ${entry.does}`);
+      if (entry.depends_on?.length) lines.push(`  Depends on: ${entry.depends_on.join(', ')}`);
+      if (entry.depended_by?.length) lines.push(`  Used by: ${entry.depended_by.join(', ')}`);
+      if (entry.gotchas?.length) lines.push(`  Gotcha: ${entry.gotchas.join(' | ')}`);
+      break;
+    case 'threads':
+      lines.push(`[Thread] ${entry.thread} — ${(entry.status || 'unknown').toUpperCase()}`);
+      if (entry.done?.length) lines.push(`  Done: ${entry.done.join(', ')}`);
+      if (entry.remaining?.length) lines.push(`  Remaining: ${entry.remaining.join(', ')}`);
+      if (entry.blocked_by) lines.push(`  Blocked by: ${entry.blocked_by}`);
+      break;
+    case 'warnings':
+      lines.push(`[Warning] ${entry.warning}`);
+      if (entry.context) lines.push(`  Context: ${entry.context}`);
+      if (entry.avoid) lines.push(`  Avoid: ${entry.avoid}`);
+      break;
+    default:
+      lines.push(JSON.stringify(entry));
+  }
+  return lines.join('\n');
+}
+
+function readJson(file) {
+  try { return JSON.parse(fs.readFileSync(file, 'utf8')); } catch { return null; }
+}
+
+function getFullEntry(ascrDir, type, id) {
+  const typeFiles = {
+    decisions:    'decisions.json',
+    architecture: 'architecture.json',
+    threads:      'threads.json',
+    warnings:     'warnings.json',
+  };
+  const file = path.join(ascrDir, typeFiles[type]);
+  const entries = readJson(file);
+  if (!Array.isArray(entries)) return null;
+  return entries.find(e => e.id === id) || null;
+}
+
+let input = '';
+process.stdin.on('data', chunk => { input += chunk; });
+process.stdin.on('end', () => {
+  try {
+    const data = JSON.parse(input || '{}');
+    const cwd = data.cwd || process.cwd();
+    const prompt = data.prompt || '';
+    const ascrDir = path.join(cwd, '.ascr');
+
+    // Skip if not initialized or prompt is empty
+    if (!fs.existsSync(ascrDir) || !prompt.trim()) process.exit(0);
+
+    const indexFile = path.join(ascrDir, 'index.json');
+    if (!fs.existsSync(indexFile)) process.exit(0);
+
+    const index = readJson(indexFile);
+    if (!index) process.exit(0);
+
+    const keywords = extractKeywords(prompt);
+    if (keywords.length === 0) process.exit(0);
+
+    const scored = scoreIndex(index, keywords);
+    if (scored.length === 0) process.exit(0);
+
+    // Pull top 3 full entries
+    const TOP_N = 3;
+    const topMatches = scored.slice(0, TOP_N);
+    const formatted = [];
+    for (const match of topMatches) {
+      const entry = getFullEntry(ascrDir, match.type, match.id);
+      if (entry) formatted.push(formatEntry(match.type, entry));
+    }
+
+    if (formatted.length === 0) process.exit(0);
+
+    // Output — injected into agent's context alongside the prompt
+    console.log('\n=== ASCR Context ===');
+    console.log(formatted.join('\n\n'));
+    console.log('=== End ASCR Context ===\n');
+
+    process.exit(0);
+  } catch {
+    process.exit(0);
+  }
+});

package/src/hooks/session-start.js

@@ -0,0 +1,82 @@
+#!/usr/bin/env node
+'use strict';
+
+// ASCR SessionStart Hook — standalone, no external dependencies
+// Announces ASCR is active and snapshots knowledge base hashes.
+// Stdout is injected into the agent's context by Claude Code.
+
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+
+let input = '';
+process.stdin.on('data', chunk => { input += chunk; });
+process.stdin.on('end', () => {
+  try {
+    const data = JSON.parse(input || '{}');
+    const cwd = data.cwd || process.cwd();
+    const sessionId = data.session_id || 'default';
+    const ascrDir = path.join(cwd, '.ascr');
+
+    if (!fs.existsSync(ascrDir)) process.exit(0);
+
+    const files = {
+      decisions:    path.join(ascrDir, 'decisions.json'),
+      architecture: path.join(ascrDir, 'architecture.json'),
+      threads:      path.join(ascrDir, 'threads.json'),
+      warnings:     path.join(ascrDir, 'warnings.json'),
+      index:        path.join(ascrDir, 'index.json'),
+    };
+
+    // Count entries and build hashes for stop gate
+    const counts = {};
+    const hashes = {};
+    for (const [type, file] of Object.entries(files)) {
+      const content = fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : '[]';
+      hashes[type] = crypto.createHash('sha256').update(content).digest('hex');
+      if (type !== 'index') {
+        try { counts[type] = JSON.parse(content).length; } catch { counts[type] = 0; }
+      }
+    }
+
+    // Write session hash snapshot for stop gate
+    const hashFile = path.join(ascrDir, `.session-hash-${sessionId}`);
+    fs.writeFileSync(hashFile, JSON.stringify(hashes), 'utf8');
+
+    // Clean up stale hash files older than 24 hours
+    try {
+      const entries = fs.readdirSync(ascrDir);
+      const cutoff = Date.now() - 24 * 60 * 60 * 1000;
+      for (const entry of entries) {
+        if (entry.startsWith('.session-hash-')) {
+          const fullPath = path.join(ascrDir, entry);
+          if (fs.statSync(fullPath).mtimeMs < cutoff) fs.unlinkSync(fullPath);
+        }
+      }
+    } catch { /* ignore cleanup errors */ }
+
+    // Build announcement output (injected into agent context)
+    const total = Object.values(counts).reduce((a, b) => a + b, 0);
+    const parts = Object.entries(counts)
+      .filter(([, n]) => n > 0)
+      .map(([type, n]) => `${n} ${type}`);
+
+    const summary = parts.length > 0
+      ? `Knowledge base: ${parts.join(', ')}`
+      : 'Knowledge base: empty (no entries yet)';
+
+    console.log(`=== ASCR Active ===`);
+    console.log(summary);
+    if (total > 0) {
+      console.log(`Context injected automatically per prompt. For deep search, read .ascr/ files directly.`);
+    } else {
+      console.log(`First session — update .ascr/ files when you finish work to build memory.`);
+    }
+    console.log(`===`);
+
+    process.exit(0);
+  } catch (err) {
+    // Never crash — just exit cleanly
+    process.exit(0);
+  }
+});

package/src/hooks/stop-gate.js

@@ -0,0 +1,124 @@
+#!/usr/bin/env node
+'use strict';
+
+// ASCR Stop Hook — standalone, no external dependencies
+// Blocks the agent from stopping if it made code changes but didn't update the knowledge base.
+// Uses a hash snapshot (written by session-start) to detect knowledge base changes.
+// Uses git diff to detect code changes (falls back to hash-only if not a git repo).
+
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const { execSync } = require('node:child_process');
+
+const BLOCK_MESSAGE = `ASCR: You made changes to the project but did not update the knowledge base.
+Update the relevant .ascr/ files before ending:
+
+  .ascr/decisions.json    — if you made or changed an architectural decision
+  .ascr/architecture.json — if you created or modified components/files
+  .ascr/threads.json      — if work is in progress or was completed
+  .ascr/warnings.json     — if you hit dead ends or gotchas to avoid
+
+Also update .ascr/index.json with tags for any new or modified entries.
+
+Schema reference:
+  decisions:    { id, decision, why, alternatives_rejected, tags, affects, date }
+  architecture: { id, component, location, does, depends_on, depended_by, tags, gotchas }
+  threads:      { id, thread, status, done, remaining, tags, blocked_by, updated }
+  warnings:     { id, warning, context, avoid, tags, date }
+
+Generate id: first 8 chars of sha256(key + timestamp). Example:
+  echo -n "jose-over-jsonwebtoken2026-03-27" | sha256sum | cut -c1-8`;
+
+function hashFile(file) {
+  try {
+    const content = fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : '[]';
+    return crypto.createHash('sha256').update(content).digest('hex');
+  } catch {
+    return null;
+  }
+}
+
+function codeFilesChanged(cwd) {
+  try {
+    // Check for any changes: staged, unstaged, or untracked (new files)
+    const staged   = execSync('git diff --cached --name-only', { cwd, encoding: 'utf8', stdio: ['pipe','pipe','pipe'] }).trim();
+    const unstaged = execSync('git diff --name-only', { cwd, encoding: 'utf8', stdio: ['pipe','pipe','pipe'] }).trim();
+    // Exclude .ascr/ changes from the check — those are memory, not code
+    const allChanges = [...staged.split('\n'), ...unstaged.split('\n')]
+      .filter(f => f && !f.startsWith('.ascr/'));
+    return allChanges.length > 0;
+  } catch {
+    // Not a git repo or git not available — skip this check
+    return null; // null = unknown
+  }
+}
+
+function knowledgeBaseChanged(ascrDir, sessionId, savedHashes) {
+  const files = {
+    decisions:    path.join(ascrDir, 'decisions.json'),
+    architecture: path.join(ascrDir, 'architecture.json'),
+    threads:      path.join(ascrDir, 'threads.json'),
+    warnings:     path.join(ascrDir, 'warnings.json'),
+    index:        path.join(ascrDir, 'index.json'),
+  };
+  for (const [type, file] of Object.entries(files)) {
+    const currentHash = hashFile(file);
+    if (currentHash && savedHashes[type] && currentHash !== savedHashes[type]) {
+      return true;
+    }
+  }
+  return false;
+}
+
+let input = '';
+process.stdin.on('data', chunk => { input += chunk; });
+process.stdin.on('end', () => {
+  try {
+    const data = JSON.parse(input || '{}');
+    const cwd = data.cwd || process.cwd();
+    const sessionId = data.session_id || 'default';
+
+    // 1. Loop guard — if stop_hook_active, allow unconditionally
+    if (data.stop_hook_active) process.exit(0);
+
+    const ascrDir = path.join(cwd, '.ascr');
+
+    // 2. If ASCR not initialized, skip enforcement
+    if (!fs.existsSync(ascrDir)) process.exit(0);
+
+    // 3. Read saved hash snapshot from session start
+    const hashFile = path.join(ascrDir, `.session-hash-${sessionId}`);
+    if (!fs.existsSync(hashFile)) process.exit(0); // no snapshot = can't enforce
+
+    let savedHashes;
+    try {
+      savedHashes = JSON.parse(fs.readFileSync(hashFile, 'utf8'));
+    } catch {
+      process.exit(0); // malformed hash file = skip
+    }
+
+    // 4. Smart trigger: check if code files actually changed
+    const codeChanged = codeFilesChanged(cwd);
+    if (codeChanged === false) {
+      // Git confirms no code changes outside .ascr/ — Q&A turn, no enforcement
+      process.exit(0);
+    }
+    // codeChanged === null means git unavailable — fall through to hash check
+
+    // 5. Check if knowledge base was updated
+    if (knowledgeBaseChanged(ascrDir, sessionId, savedHashes)) {
+      // Agent already updated memory — clean up hash file and allow
+      try { fs.unlinkSync(hashFile); } catch { /* ignore */ }
+      process.exit(0);
+    }
+
+    // 6. Code changed but knowledge base didn't — block
+    process.stderr.write(BLOCK_MESSAGE);
+    process.exit(2);
+
+  } catch {
+    // Never crash — always allow on unexpected error
+    process.exit(0);
+  }
+});

package/src/lib/index.js

@@ -0,0 +1,65 @@
+'use strict';
+
+const { readFileSync, writeFileSync, existsSync } = require('node:fs');
+const paths = require('./paths');
+const { readKnowledge, TYPES } = require('./memory');
+
+function readIndex(cwd) {
+  const file = paths.indexFile(cwd);
+  if (!existsSync(file)) return { decisions: [], architecture: [], threads: [], warnings: [] };
+  try {
+    return JSON.parse(readFileSync(file, 'utf8'));
+  } catch {
+    return { decisions: [], architecture: [], threads: [], warnings: [] };
+  }
+}
+
+function writeIndex(cwd, index) {
+  writeFileSync(paths.indexFile(cwd), JSON.stringify(index, null, 2) + '\n', 'utf8');
+}
+
+// Rebuild the full index from knowledge files
+function rebuildIndex(cwd) {
+  const index = {};
+  for (const type of TYPES) {
+    const entries = readKnowledge(cwd, type);
+    index[type] = entries.map(e => {
+      const entry = { id: e.id, key: e.key || e.decision || e.component || e.thread || e.warning || e.id, tags: e.tags || [] };
+      if (type === 'threads' && e.status) entry.status = e.status;
+      return entry;
+    });
+  }
+  writeIndex(cwd, index);
+  return index;
+}
+
+// Score index entries against a set of keywords
+// Returns sorted array of { type, id, score }
+function scoreIndex(index, keywords) {
+  const results = [];
+  for (const type of TYPES) {
+    const entries = index[type] || [];
+    for (const entry of entries) {
+      let score = 0;
+      const tags = (entry.tags || []).map(t => t.toLowerCase());
+      const key = (entry.key || '').toLowerCase();
+      for (const kw of keywords) {
+        if (tags.includes(kw)) score += 2;
+        else if (tags.some(t => t.includes(kw) || kw.includes(t))) score += 1;
+        if (key.includes(kw)) score += 1;
+      }
+      // Boost in-progress threads ONLY if there's already a keyword match
+      if (score > 0 && type === 'threads' && entry.status === 'in_progress') score += 1;
+      if (score > 0) results.push({ type, id: entry.id, score });
+    }
+  }
+  // Sort by score desc, then prefer threads > architecture > decisions > warnings
+  const typePriority = { threads: 4, architecture: 3, decisions: 2, warnings: 1 };
+  results.sort((a, b) => {
+    if (b.score !== a.score) return b.score - a.score;
+    return (typePriority[b.type] || 0) - (typePriority[a.type] || 0);
+  });
+  return results;
+}
+
+module.exports = { readIndex, writeIndex, rebuildIndex, scoreIndex };

package/src/lib/memory.js

@@ -0,0 +1,49 @@
+'use strict';
+
+const { readFileSync, writeFileSync, existsSync } = require('node:fs');
+const paths = require('./paths');
+
+const TYPES = ['decisions', 'architecture', 'threads', 'warnings'];
+
+function readKnowledge(cwd, type) {
+  const file = paths.KNOWLEDGE_FILES(cwd)[type];
+  if (!existsSync(file)) return [];
+  try {
+    const raw = readFileSync(file, 'utf8').trim();
+    if (!raw || raw === '') return [];
+    return JSON.parse(raw);
+  } catch {
+    return [];
+  }
+}
+
+function writeKnowledge(cwd, type, entries) {
+  const file = paths.KNOWLEDGE_FILES(cwd)[type];
+  writeFileSync(file, JSON.stringify(entries, null, 2) + '\n', 'utf8');
+}
+
+function readAllKnowledge(cwd) {
+  const result = {};
+  for (const type of TYPES) {
+    result[type] = readKnowledge(cwd, type);
+  }
+  return result;
+}
+
+function filterEntries(entries, { tag, status } = {}) {
+  return entries.filter(e => {
+    if (tag && !(e.tags || []).includes(tag)) return false;
+    if (status && e.status !== status) return false;
+    return true;
+  });
+}
+
+function countAll(cwd) {
+  const counts = {};
+  for (const type of TYPES) {
+    counts[type] = readKnowledge(cwd, type).length;
+  }
+  return counts;
+}
+
+module.exports = { TYPES, readKnowledge, writeKnowledge, readAllKnowledge, filterEntries, countAll };