pan-wizard 2.9.1 → 3.4.1

package/pan-wizard-core/bin/lib/knowledge.cjs

@@ -0,0 +1,331 @@
+/**
+ * Knowledge — grounded Q&A, multi-turn discussion, playbook generation
+ * (Spec B v2 Y-3, v3.2).
+ *
+ * Three modes, one module:
+ *   - ask      — retrieve candidate files + format citation context for the agent
+ *   - discuss  — session state CRUD for multi-turn conversations on a phase
+ *   - playbook — read all agents' memory and cluster into sections
+ *
+ * All three leverage Spec A infrastructure:
+ *   - E-1 caching for stable input prefixes (ask, discuss)
+ *   - E-4 memory for playbook source + discuss state
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { output, error, safeReadFile, toPosix } = require('./core.cjs');
+const { PLANNING_DIR } = require('./constants.cjs');
+const { planningPath } = require('./utils.cjs');
+const { listMemoryAgents, readMemory } = require('./memory.cjs');
+
+const CONVERSATIONS_DIR = 'conversations';
+const PLAYBOOK_FILE = 'playbook.md';
+const DEFAULT_MAX_SOURCES = 20;
+
+// ─── Mode: ask — retrieval for grounded Q&A ────────────────────────────────
+
+/**
+ * Candidate source directories that pan-knowledge agent can cite.
+ */
+const CITATION_ROOTS = [
+  '.planning/project.md',
+  '.planning/requirements.md',
+  '.planning/roadmap.md',
+  '.planning/state.md',
+  '.planning/standards.md',
+  '.planning/patterns.md',
+  '.planning/phases',
+  '.planning/milestones',
+  '.planning/memory',
+  'docs',
+  'CHANGELOG.md',
+  'README.md',
+  'CLAUDE.md',
+];
+
+/**
+ * Score a candidate file by naive keyword matching against the question.
+ * Not a vector index — just a frequency-based ranker so the agent reads
+ * the most relevant files first.
+ */
+function scoreRelevance(question, content) {
+  if (!content) return 0;
+  const words = question.toLowerCase().split(/\W+/).filter(w => w.length >= 3);
+  if (words.length === 0) return 0;
+  const body = content.toLowerCase();
+  let score = 0;
+  for (const w of words) {
+    const count = (body.match(new RegExp(`\\b${w.replace(/[.*+?^${}()|[\\]\\\\]/g, '\\$&')}\\b`, 'g')) || []).length;
+    score += count;
+  }
+  return score;
+}
+
+/**
+ * Walk a path (file or directory, 1 level deep for .md files) and return
+ * {file, score} entries.
+ */
+function gatherCandidates(cwd, question) {
+  const candidates = [];
+  for (const rel of CITATION_ROOTS) {
+    const abs = path.join(cwd, rel);
+    let stat;
+    try { stat = fs.statSync(abs); } catch { continue; }
+    if (stat.isFile()) {
+      const content = safeReadFile(abs);
+      candidates.push({ file: toPosix(rel), score: scoreRelevance(question, content), bytes: Buffer.byteLength(content || '', 'utf-8') });
+    } else if (stat.isDirectory()) {
+      let entries = [];
+      try { entries = fs.readdirSync(abs); } catch { continue; }
+      for (const entry of entries) {
+        const entryAbs = path.join(abs, entry);
+        let entryStat;
+        try { entryStat = fs.statSync(entryAbs); } catch { continue; }
+        if (entryStat.isFile() && entry.endsWith('.md')) {
+          const entryRel = toPosix(path.join(rel, entry));
+          const content = safeReadFile(entryAbs);
+          candidates.push({ file: entryRel, score: scoreRelevance(question, content), bytes: Buffer.byteLength(content || '', 'utf-8') });
+        } else if (entryStat.isDirectory()) {
+          // One more level for phases/<NN>/ and milestones/
+          let sub = [];
+          try { sub = fs.readdirSync(entryAbs); } catch { continue; }
+          for (const s of sub) {
+            if (!s.endsWith('.md')) continue;
+            const subRel = toPosix(path.join(rel, entry, s));
+            const content = safeReadFile(path.join(entryAbs, s));
+            candidates.push({ file: subRel, score: scoreRelevance(question, content), bytes: Buffer.byteLength(content || '', 'utf-8') });
+          }
+        }
+      }
+    }
+  }
+  return candidates;
+}
+
+/**
+ * Retrieve ranked candidate sources for a question.
+ *
+ * @param {string} cwd - Project root
+ * @param {string} question - User's natural-language question
+ * @param {Object} [opts] - {max_sources}
+ * @returns {Object} {question, sources: Array<{file, score, bytes}>, total_candidates}
+ */
+function ask(cwd, question, opts) {
+  if (typeof question !== 'string' || !question.trim()) {
+    return { error: 'question must be a non-empty string' };
+  }
+  const max = Math.max(1, Math.min(100, Number(opts?.max_sources) || DEFAULT_MAX_SOURCES));
+  const all = gatherCandidates(cwd, question);
+  const ranked = all
+    .filter(c => c.score > 0 || c.file.endsWith('project.md') || c.file.endsWith('requirements.md'))
+    .sort((a, b) => b.score - a.score || a.file.localeCompare(b.file))
+    .slice(0, max);
+  return {
+    question,
+    sources: ranked,
+    total_candidates: all.length,
+    returned: ranked.length,
+  };
+}
+
+// ─── Mode: discuss — session state for multi-turn conversations ────────────
+
+function conversationsDir(cwd) {
+  return path.join(planningPath(cwd), CONVERSATIONS_DIR);
+}
+
+function sessionFile(cwd, phaseNum) {
+  return path.join(conversationsDir(cwd), String(phaseNum), 'session.json');
+}
+
+/**
+ * Read or initialize a discussion session for a phase.
+ */
+function loadSession(cwd, phaseNum) {
+  const file = sessionFile(cwd, phaseNum);
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf-8'));
+  } catch {
+    return { phase: String(phaseNum), turns: [], created: new Date().toISOString() };
+  }
+}
+
+/**
+ * Append a user question + agent response turn.
+ *
+ * @param {string} cwd
+ * @param {string} phaseNum
+ * @param {{role: 'user'|'agent', content: string, cites?: string[]}} turn
+ * @returns {{appended: true, turn_count: number, file: string}|{error: string}}
+ */
+function appendTurn(cwd, phaseNum, turn) {
+  if (!phaseNum) return { error: 'phaseNum required' };
+  if (!turn || !turn.role || !turn.content) return { error: 'turn requires role + content' };
+  if (turn.role !== 'user' && turn.role !== 'agent') {
+    return { error: 'turn.role must be "user" or "agent"' };
+  }
+
+  const session = loadSession(cwd, phaseNum);
+  session.turns.push({
+    ts: new Date().toISOString(),
+    role: turn.role,
+    content: turn.content,
+    cites: Array.isArray(turn.cites) ? turn.cites : [],
+  });
+  session.last_updated = session.turns[session.turns.length - 1].ts;
+
+  const file = sessionFile(cwd, phaseNum);
+  try {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, JSON.stringify(session, null, 2), 'utf-8');
+  } catch (e) {
+    return { error: `Failed to write session: ${e.message}` };
+  }
+
+  return { appended: true, turn_count: session.turns.length, file: toPosix(path.relative(cwd, file)) };
+}
+
+// ─── Mode: playbook — cluster agent memory into sections ───────────────────
+
+/**
+ * Category heuristics. Maps keyword patterns to playbook sections.
+ * Order matters — first match wins.
+ */
+const PLAYBOOK_CATEGORIES = [
+  { name: 'Conventions', pattern: /\b(convention|style|format|naming|prefer)\b/i },
+  { name: 'Gotchas', pattern: /\b(gotcha|pitfall|edge\s*case|surprise|careful)\b/i },
+  { name: 'Decisions', pattern: /\b(decision|decided|chose|picked|adopt)\b/i },
+  { name: 'Tool choices', pattern: /\b(library|package|framework|tool|alternative)\b/i },
+  { name: 'Anti-patterns', pattern: /\b(anti.?pattern|avoid|do not|don't|never)\b/i },
+  { name: 'Recurring gaps', pattern: /\brecurring\s+(gap|plan\s+gap|issue)\b/i },
+];
+
+function categorizeEntry(entry) {
+  for (const cat of PLAYBOOK_CATEGORIES) {
+    if (cat.pattern.test(entry)) return cat.name;
+  }
+  return 'General';
+}
+
+/**
+ * Generate a structured playbook from all agents' memory files.
+ *
+ * @param {string} cwd - Project root
+ * @returns {Object} {sections: {name: [{agent, entry}]}, agent_count, entry_count}
+ */
+function buildPlaybook(cwd) {
+  const { agents } = listMemoryAgents(cwd);
+  const sections = {};
+  let entryCount = 0;
+
+  for (const a of agents) {
+    const mem = readMemory(cwd, a.agent);
+    if (!mem) continue;
+    for (const entry of mem.entries) {
+      const cat = categorizeEntry(entry);
+      if (!sections[cat]) sections[cat] = [];
+      sections[cat].push({ agent: a.agent, entry });
+      entryCount += 1;
+    }
+  }
+
+  return {
+    sections,
+    agent_count: agents.length,
+    entry_count: entryCount,
+    generated: new Date().toISOString(),
+  };
+}
+
+/**
+ * Serialize the playbook object to markdown and write to `.planning/playbook.md`.
+ */
+function writePlaybook(cwd, playbook) {
+  const lines = [];
+  lines.push('---');
+  lines.push('type: playbook');
+  lines.push(`generated: ${playbook.generated}`);
+  lines.push(`source_agents: ${playbook.agent_count}`);
+  lines.push(`entries: ${playbook.entry_count}`);
+  lines.push('---');
+  lines.push('');
+  lines.push('# PAN Playbook');
+  lines.push('');
+  lines.push(`Accumulated lessons across ${playbook.agent_count} agents and ${playbook.entry_count} memory entries. Regenerated from \`.planning/memory/*.md\`.`);
+  lines.push('');
+
+  const sectionOrder = [
+    ...PLAYBOOK_CATEGORIES.map(c => c.name),
+    'General',
+  ];
+
+  for (const section of sectionOrder) {
+    const items = playbook.sections[section];
+    if (!items || items.length === 0) continue;
+    lines.push(`## ${section}`);
+    lines.push('');
+    for (const item of items) {
+      lines.push(`- ${item.entry} _— from \`${item.agent}\`_`);
+    }
+    lines.push('');
+  }
+
+  const file = path.join(planningPath(cwd), PLAYBOOK_FILE);
+  try {
+    fs.writeFileSync(file, lines.join('\n'), 'utf-8');
+  } catch (e) {
+    return { error: `Failed to write playbook: ${e.message}` };
+  }
+  return { written: true, file: toPosix(path.relative(cwd, file)) };
+}
+
+// ─── CLI wrappers ───────────────────────────────────────────────────────────
+
+function cmdKnowledgeAsk(cwd, question, opts, raw) {
+  if (!question) error('Usage: knowledge ask <question>');
+  output(ask(cwd, question, opts), raw);
+}
+
+function cmdKnowledgeDiscuss(cwd, phaseNum, opts, raw) {
+  const subcmd = opts?.subcmd;
+  if (subcmd === 'read') {
+    output(loadSession(cwd, phaseNum), raw);
+  } else if (subcmd === 'append') {
+    output(appendTurn(cwd, phaseNum, {
+      role: opts.role,
+      content: opts.content,
+      cites: opts.cites ? opts.cites.split(',') : [],
+    }), raw);
+  } else {
+    error('Usage: knowledge discuss <phase> --subcmd read|append [--role user|agent --content "..."]');
+  }
+}
+
+function cmdKnowledgePlaybook(cwd, opts, raw) {
+  const playbook = buildPlaybook(cwd);
+  if (opts?.preview) {
+    output(playbook, raw);
+    return;
+  }
+  const result = writePlaybook(cwd, playbook);
+  if (result.error) { output(result, raw); return; }
+  output({ ...result, agent_count: playbook.agent_count, entry_count: playbook.entry_count }, raw);
+}
+
+module.exports = {
+  ask,
+  loadSession,
+  appendTurn,
+  buildPlaybook,
+  writePlaybook,
+  scoreRelevance,
+  categorizeEntry,
+  cmdKnowledgeAsk,
+  cmdKnowledgeDiscuss,
+  cmdKnowledgePlaybook,
+  CITATION_ROOTS,
+  CONVERSATIONS_DIR,
+  PLAYBOOK_FILE,
+  PLAYBOOK_CATEGORIES,
+};

package/pan-wizard-core/bin/lib/memory.cjs

@@ -0,0 +1,252 @@
+/**
+ * Memory — cross-phase agent memory layer
+ *
+ * Each agent has an append-only memory log at `.planning/memory/<agent>.md`.
+ * Agents read their memory at start of each invocation and append lessons
+ * learned at end. Compaction keeps file size bounded.
+ *
+ * File format: a markdown file with a stable YAML frontmatter header and
+ * an append-only "## Entries" section containing one bullet per entry:
+ *
+ *   ---
+ *   agent: pan-planner
+ *   created: 2026-04-18
+ *   ---
+ *
+ *   ## Entries
+ *
+ *   - 2026-04-18: Prefer bulk writes over per-row commits for Postgres
+ *   - 2026-04-19: ...
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { output, error } = require('./core.cjs');
+const { PLANNING_DIR } = require('./constants.cjs');
+const { planningPath } = require('./utils.cjs');
+
+const MEMORY_DIR = 'memory';
+const DEFAULT_MAX_ENTRIES = 500;
+const AGENT_NAME_RE = /^[a-zA-Z0-9_-]+$/;
+
+function memoryDir(cwd) {
+  return path.join(planningPath(cwd), MEMORY_DIR);
+}
+
+function memoryFile(cwd, agent) {
+  return path.join(memoryDir(cwd), `${agent}.md`);
+}
+
+function validateAgentName(agent) {
+  if (typeof agent !== 'string' || !AGENT_NAME_RE.test(agent)) {
+    return `Invalid agent name: ${agent}. Must match ${AGENT_NAME_RE}`;
+  }
+  return null;
+}
+
+function today() {
+  return new Date().toISOString().slice(0, 10);
+}
+
+/**
+ * Read the memory file for an agent.
+ * @param {string} cwd - Project root
+ * @param {string} agent - Agent name
+ * @returns {{agent: string, entries: string[], raw: string}|null}
+ */
+function readMemory(cwd, agent) {
+  const err = validateAgentName(agent);
+  if (err) return null;
+  let raw;
+  try {
+    raw = fs.readFileSync(memoryFile(cwd, agent), 'utf-8');
+  } catch {
+    return null;
+  }
+  const entries = parseEntries(raw);
+  return { agent, entries, raw };
+}
+
+/**
+ * Parse bullet entries from a memory file's body.
+ * @param {string} raw - File contents
+ * @returns {string[]} ordered entries (oldest → newest, as stored)
+ */
+function parseEntries(raw) {
+  const entries = [];
+  const lines = raw.split(/\r?\n/);
+  let inEntries = false;
+  for (const line of lines) {
+    if (/^##\s+Entries\s*$/.test(line)) { inEntries = true; continue; }
+    if (inEntries && /^##\s+/.test(line)) break;
+    if (!inEntries) continue;
+    const match = line.match(/^-\s+(.+)$/);
+    if (match) entries.push(match[1]);
+  }
+  return entries;
+}
+
+/**
+ * Append a single entry to an agent's memory log. Creates file+dir if absent.
+ * Entries are prefixed with today's date automatically unless already prefixed.
+ * @param {string} cwd - Project root
+ * @param {string} agent - Agent name
+ * @param {string} entry - Single-line lesson (newlines will be collapsed)
+ * @returns {{appended: true, file: string, count: number}|{error: string}}
+ */
+function appendMemory(cwd, agent, entry) {
+  const err = validateAgentName(agent);
+  if (err) return { error: err };
+  if (typeof entry !== 'string' || !entry.trim()) {
+    return { error: 'entry must be a non-empty string' };
+  }
+
+  const cleaned = entry.replace(/\r?\n/g, ' ').trim();
+  const datePrefixed = /^\d{4}-\d{2}-\d{2}:/.test(cleaned);
+  const finalEntry = datePrefixed ? cleaned : `${today()}: ${cleaned}`;
+
+  try {
+    fs.mkdirSync(memoryDir(cwd), { recursive: true });
+  } catch (e) {
+    return { error: `Failed to create memory dir: ${e.message}` };
+  }
+
+  const file = memoryFile(cwd, agent);
+  let existing = '';
+  try {
+    existing = fs.readFileSync(file, 'utf-8');
+  } catch {
+    // new file
+  }
+
+  let contents;
+  if (!existing) {
+    contents = buildHeader(agent) + '\n\n## Entries\n\n- ' + finalEntry + '\n';
+  } else if (/##\s+Entries/.test(existing)) {
+    // Ensure file ends with newline, then append bullet.
+    const needsNl = !existing.endsWith('\n');
+    contents = existing + (needsNl ? '\n' : '') + `- ${finalEntry}\n`;
+  } else {
+    const needsNl = !existing.endsWith('\n');
+    contents = existing + (needsNl ? '\n' : '') + '\n## Entries\n\n- ' + finalEntry + '\n';
+  }
+
+  try {
+    fs.writeFileSync(file, contents, 'utf-8');
+  } catch (e) {
+    return { error: `Failed to write memory file: ${e.message}` };
+  }
+
+  const count = parseEntries(contents).length;
+  return { appended: true, file, count };
+}
+
+function buildHeader(agent) {
+  return `---\nagent: ${agent}\ncreated: ${today()}\n---`;
+}
+
+/**
+ * Trim a memory file to the last N entries. Preserves frontmatter header.
+ * @param {string} cwd - Project root
+ * @param {string} agent - Agent name
+ * @param {number} maxEntries - Keep this many most-recent entries
+ * @returns {{compacted: true, kept: number, removed: number}|{error: string}}
+ */
+function compactMemory(cwd, agent, maxEntries = DEFAULT_MAX_ENTRIES) {
+  const err = validateAgentName(agent);
+  if (err) return { error: err };
+  const max = Number(maxEntries);
+  if (!Number.isFinite(max) || max < 1) {
+    return { error: `maxEntries must be a positive integer, got ${maxEntries}` };
+  }
+
+  const file = memoryFile(cwd, agent);
+  let raw;
+  try {
+    raw = fs.readFileSync(file, 'utf-8');
+  } catch {
+    return { error: `No memory file for agent: ${agent}` };
+  }
+
+  const entries = parseEntries(raw);
+  if (entries.length <= max) {
+    return { compacted: true, kept: entries.length, removed: 0 };
+  }
+
+  const keep = entries.slice(-max);
+  const removed = entries.length - keep.length;
+
+  const headerMatch = raw.match(/^---[\s\S]*?---/);
+  const header = headerMatch ? headerMatch[0] : buildHeader(agent);
+  const body = '\n\n## Entries\n\n' + keep.map(e => `- ${e}`).join('\n') + '\n';
+  try {
+    fs.writeFileSync(file, header + body, 'utf-8');
+  } catch (e) {
+    return { error: `Failed to write memory file: ${e.message}` };
+  }
+  return { compacted: true, kept: keep.length, removed };
+}
+
+/**
+ * List all agents that have a memory file.
+ * @param {string} cwd - Project root
+ * @returns {{agents: Array<{agent: string, entries: number}>}}
+ */
+function listMemoryAgents(cwd) {
+  let files;
+  try {
+    files = fs.readdirSync(memoryDir(cwd));
+  } catch {
+    return { agents: [] };
+  }
+  const agents = [];
+  for (const f of files) {
+    if (!f.endsWith('.md')) continue;
+    const name = f.slice(0, -3);
+    if (!AGENT_NAME_RE.test(name)) continue;
+    const mem = readMemory(cwd, name);
+    agents.push({ agent: name, entries: mem ? mem.entries.length : 0 });
+  }
+  agents.sort((a, b) => a.agent.localeCompare(b.agent));
+  return { agents };
+}
+
+// ─── CLI command wrappers ────────────────────────────────────────────────────
+
+function cmdMemoryRead(cwd, agent, raw) {
+  if (!agent) { error('Usage: memory read <agent>'); }
+  const result = readMemory(cwd, agent);
+  if (!result) { output({ agent, entries: [], exists: false }, raw); return; }
+  output({ agent, entries: result.entries, exists: true }, raw);
+}
+
+function cmdMemoryAppend(cwd, agent, entry, raw) {
+  if (!agent || !entry) { error('Usage: memory append <agent> <entry>'); }
+  const result = appendMemory(cwd, agent, entry);
+  output(result, raw);
+}
+
+function cmdMemoryList(cwd, raw) {
+  output(listMemoryAgents(cwd), raw);
+}
+
+function cmdMemoryCompact(cwd, agent, maxEntries, raw) {
+  if (!agent) { error('Usage: memory compact <agent> [max]'); }
+  const result = compactMemory(cwd, agent, maxEntries || DEFAULT_MAX_ENTRIES);
+  output(result, raw);
+}
+
+module.exports = {
+  readMemory,
+  appendMemory,
+  compactMemory,
+  listMemoryAgents,
+  parseEntries,
+  validateAgentName,
+  cmdMemoryRead,
+  cmdMemoryAppend,
+  cmdMemoryList,
+  cmdMemoryCompact,
+  MEMORY_DIR,
+  DEFAULT_MAX_ENTRIES,
+};