pan-wizard 3.5.1 → 3.7.10

package/pan-wizard-core/bin/lib/learn-index.cjs

@@ -0,0 +1,235 @@
+/**
+ * Learn-Index — Build a topic→agent-relevance index for the learnings store.
+ *
+ * Solves the P-RES-002 anti-pattern PAN currently ships: workflow files say
+ * "Also see learnings/universal/" and the agent skim-loads ~25 files into
+ * context every plan/exec turn. Distractor density (per Chroma 2025) degrades
+ * agent performance even at modest token counts.
+ *
+ * The index lets agents load only the topics relevant to their role at the
+ * current phase, with token budgets visible.
+ *
+ * Generated by: `pan-tools learn build-index`
+ * Read by:      `pan-tools learn topics-for --agent <name>`
+ * Stored at:    pan-wizard-core/learnings/index.json
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { collectAllPatterns } = require('./learn-lint.cjs');
+
+const CHARS_PER_TOKEN = 4;
+
+const INDEX_PATH_REL = path.join('pan-wizard-core', 'learnings', 'index.json');
+
+/**
+ * Static topic→agent-role relevance table. Curated, not heuristic — these
+ * judgments come from "what does each agent role NEED to know to do its job
+ * well?" (per the agent definitions in agents/pan-{planner,executor,verifier,
+ * reviewer,plan-checker}.md).
+ *
+ * Values: 'high' = always load; 'medium' = load when relevant phase domain
+ * matches; 'low' = load only when explicitly cited.
+ *
+ * If a topic is missing from the table, default is medium for executor and
+ * low for the others (assumes new topics are mostly executor-side patterns
+ * unless tagged otherwise).
+ */
+const RELEVANCE = {
+  // Planning-time concerns
+  'design-process':       { planner: 'high',   executor: 'low',    verifier: 'low',    reviewer: 'medium' },
+  'schema-design':        { planner: 'high',   executor: 'medium', verifier: 'medium', reviewer: 'medium' },
+  'composition':          { planner: 'high',   executor: 'medium', verifier: 'low',    reviewer: 'medium' },
+  'dag-scheduler':        { planner: 'high',   executor: 'medium', verifier: 'low',    reviewer: 'medium' },
+  'data-driven-design':   { planner: 'high',   executor: 'medium', verifier: 'low',    reviewer: 'medium' },
+  'vendor-pattern':       { planner: 'medium', executor: 'low',    verifier: 'low',    reviewer: 'medium' },
+  'phase-locking':        { planner: 'high',   executor: 'low',    verifier: 'low',    reviewer: 'low' },
+
+  // Execution-time concerns
+  'atomic-state':         { planner: 'medium', executor: 'high',   verifier: 'high',   reviewer: 'medium' },
+  'binary-io':            { planner: 'low',    executor: 'high',   verifier: 'medium', reviewer: 'low' },
+  'concurrency':          { planner: 'medium', executor: 'high',   verifier: 'high',   reviewer: 'medium' },
+  'streaming-io':         { planner: 'low',    executor: 'high',   verifier: 'medium', reviewer: 'low' },
+  'io-patterns':          { planner: 'low',    executor: 'high',   verifier: 'medium', reviewer: 'low' },
+  'parser-design':        { planner: 'medium', executor: 'high',   verifier: 'medium', reviewer: 'medium' },
+  'error-handling':       { planner: 'medium', executor: 'high',   verifier: 'high',   reviewer: 'high' },
+  'error-paths':          { planner: 'low',    executor: 'high',   verifier: 'high',   reviewer: 'high' },
+  'invariants':           { planner: 'medium', executor: 'high',   verifier: 'high',   reviewer: 'high' },
+  'numeric-edge-cases':   { planner: 'low',    executor: 'high',   verifier: 'high',   reviewer: 'medium' },
+  'unicode':              { planner: 'low',    executor: 'high',   verifier: 'medium', reviewer: 'low' },
+  'glob-semantics':       { planner: 'low',    executor: 'medium', verifier: 'medium', reviewer: 'low' },
+  'comment-syntax':       { planner: 'low',    executor: 'medium', verifier: 'low',    reviewer: 'medium' },
+  'output-conventions':   { planner: 'low',    executor: 'high',   verifier: 'medium', reviewer: 'low' },
+  'pipe-friendly-cli':    { planner: 'medium', executor: 'high',   verifier: 'low',    reviewer: 'low' },
+  'empirical-spike':      { planner: 'high',   executor: 'medium', verifier: 'low',    reviewer: 'medium' },
+  'idempotency':          { planner: 'high',   executor: 'high',   verifier: 'high',   reviewer: 'high' },
+  'secret-handling':      { planner: 'medium', executor: 'high',   verifier: 'high',   reviewer: 'high' },
+
+  // Verification-time concerns
+  'test-patterns':        { planner: 'medium', executor: 'high',   verifier: 'high',   reviewer: 'high' },
+  'test-strategy':        { planner: 'high',   executor: 'medium', verifier: 'high',   reviewer: 'high' },
+
+  // PAN-internal (loaded only by PAN's own dev sessions)
+  'experiment-runner':    { planner: 'low',    executor: 'low',    verifier: 'low',    reviewer: 'low' },
+  'external-research':    { planner: 'medium', executor: 'low',    verifier: 'low',    reviewer: 'medium' },
+  'pan-dev-bugs':         { planner: 'low',    executor: 'low',    verifier: 'low',    reviewer: 'low' },
+  'loop-design':          { planner: 'medium', executor: 'low',    verifier: 'low',    reviewer: 'low' },
+};
+
+/**
+ * Build the index from the on-disk learnings store.
+ */
+function buildIndex(sourceRoot) {
+  const all = collectAllPatterns(sourceRoot);
+  const byTopic = new Map();
+  for (const p of all) {
+    const key = `${p.scope}/${p.topic}`;
+    if (!byTopic.has(key)) {
+      byTopic.set(key, {
+        name: p.topic,
+        scope: p.scope,
+        file: path.relative(sourceRoot, p.file).replace(/\\/g, '/'),
+        patterns: [],
+        size_bytes: 0,
+        size_tokens_est: 0,
+      });
+    }
+    const entry = byTopic.get(key);
+    entry.patterns.push(p.id);
+  }
+
+  for (const [, entry] of byTopic) {
+    const abs = path.join(sourceRoot, entry.file);
+    try {
+      const stat = fs.statSync(abs);
+      entry.size_bytes = stat.size;
+      entry.size_tokens_est = Math.ceil(stat.size / CHARS_PER_TOKEN);
+    } catch {
+      entry.size_bytes = 0;
+      entry.size_tokens_est = 0;
+    }
+    const rel = RELEVANCE[entry.name] || { planner: 'low', executor: 'medium', verifier: 'low', reviewer: 'low' };
+    entry.agent_relevance = rel;
+  }
+
+  const topics = [...byTopic.values()].sort((a, b) => {
+    if (a.scope !== b.scope) return a.scope.localeCompare(b.scope);
+    return a.name.localeCompare(b.name);
+  });
+
+  return {
+    schema_version: 1,
+    generated_at: new Date().toISOString(),
+    topics,
+    totals: {
+      topics: topics.length,
+      patterns: topics.reduce((s, t) => s + t.patterns.length, 0),
+      size_bytes: topics.reduce((s, t) => s + t.size_bytes, 0),
+      size_tokens_est: topics.reduce((s, t) => s + t.size_tokens_est, 0),
+    },
+  };
+}
+
+/**
+ * Write the index to disk.
+ */
+function writeIndex(sourceRoot, index) {
+  const filePath = path.join(sourceRoot, INDEX_PATH_REL);
+  fs.writeFileSync(filePath, JSON.stringify(index, null, 2) + '\n');
+  return filePath;
+}
+
+/**
+ * Read the index from disk; build it if missing.
+ */
+function readIndex(sourceRoot) {
+  const filePath = path.join(sourceRoot, INDEX_PATH_REL);
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+  } catch {
+    return buildIndex(sourceRoot);
+  }
+}
+
+/**
+ * Query: what topics should agent X load at this point?
+ *
+ * @param {object} index - the index object
+ * @param {object} opts
+ * @param {string} opts.agent - 'planner' | 'executor' | 'verifier' | 'reviewer'
+ * @param {string} [opts.minRelevance] - 'high' | 'medium' | 'low' (default 'medium')
+ * @param {number} [opts.tokenBudget] - max tokens to fit (default 5000)
+ * @returns {object} { topics: [{name, scope, file, tokens, relevance}], total_tokens, dropped: [...] }
+ */
+function topicsForAgent(index, opts) {
+  const agent = opts.agent;
+  const minLevel = opts.minRelevance || 'medium';
+  const budget = opts.tokenBudget || 5000;
+  const ranks = { high: 3, medium: 2, low: 1 };
+  const minRank = ranks[minLevel] || 2;
+
+  const ranked = [];
+  for (const t of index.topics) {
+    const rel = (t.agent_relevance || {})[agent] || 'low';
+    const rank = ranks[rel] || 1;
+    if (rank < minRank) continue;
+    ranked.push({ ...t, _relevance: rel, _rank: rank });
+  }
+  ranked.sort((a, b) => b._rank - a._rank || a.size_tokens_est - b.size_tokens_est);
+
+  const selected = [];
+  const dropped = [];
+  let total = 0;
+  for (const t of ranked) {
+    if (total + t.size_tokens_est > budget) {
+      dropped.push({ name: t.name, scope: t.scope, tokens: t.size_tokens_est, relevance: t._relevance });
+      continue;
+    }
+    selected.push({
+      name: t.name,
+      scope: t.scope,
+      file: t.file,
+      tokens: t.size_tokens_est,
+      relevance: t._relevance,
+      patterns: t.patterns,
+    });
+    total += t.size_tokens_est;
+  }
+
+  return {
+    agent,
+    min_relevance: minLevel,
+    token_budget: budget,
+    selected,
+    dropped,
+    total_tokens: total,
+  };
+}
+
+function cmdBuildIndex(sourceRoot) {
+  const index = buildIndex(sourceRoot);
+  const filePath = writeIndex(sourceRoot, index);
+  return {
+    written_to: filePath,
+    topics: index.totals.topics,
+    patterns: index.totals.patterns,
+    total_tokens_est: index.totals.size_tokens_est,
+    schema_version: index.schema_version,
+  };
+}
+
+function cmdTopicsFor(sourceRoot, opts) {
+  const index = readIndex(sourceRoot);
+  return topicsForAgent(index, opts);
+}
+
+module.exports = {
+  buildIndex,
+  writeIndex,
+  readIndex,
+  topicsForAgent,
+  cmdBuildIndex,
+  cmdTopicsFor,
+  INDEX_PATH_REL,
+  RELEVANCE,
+};

package/pan-wizard-core/bin/lib/learn-lint.cjs

@@ -0,0 +1,292 @@
+/**
+ * Learn-Lint — Validate the learnings system itself.
+ *
+ * Catches integrity violations that erode trust in the learnings PAN ships
+ * to executor / planner / verifier agents:
+ *
+ *  - L-001: Duplicate pattern IDs across files (silent contract collision)
+ *  - L-002: Dangling pattern reference (body cites P-XXXX that doesn't exist)
+ *  - L-003: Empty source_experiments while evidence prose names a known experiment
+ *  - L-004: Universal-scope rule prose mentions PAN-internal terms
+ *           (candidate for internal/ scope rather than universal/)
+ *  - L-005: Revision marker (rN) appended in body but no supersession field
+ *
+ * These are not patterns themselves — they're integrity checks for the
+ * pattern store. Wired to `pan-tools learn lint`.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const VALID_SCOPES = ['universal', 'internal'];
+
+function getLearningsDir(sourceRoot, scope) {
+  return path.join(sourceRoot, 'pan-wizard-core', 'learnings', scope);
+}
+
+function readTopicFile(filePath) {
+  const content = fs.readFileSync(filePath, 'utf-8');
+  const fmMatch = content.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
+  if (!fmMatch) return { frontmatter: { patterns: [] }, body: content };
+  const fmText = fmMatch[1];
+  const body = fmMatch[2];
+  const fm = parseFrontmatter(fmText);
+  return { frontmatter: fm, body };
+}
+
+function parseFrontmatter(text) {
+  const out = { topic: '', last_updated: '', patterns: [] };
+  const lines = text.split('\n');
+  let inPatterns = false;
+  let current = null;
+  for (const line of lines) {
+    if (line === 'patterns:') { inPatterns = true; continue; }
+    if (!inPatterns) {
+      const m = line.match(/^([a-z_]+):\s*(.*)$/);
+      if (m) out[m[1]] = m[2].trim();
+      continue;
+    }
+    if (line.startsWith('  - id:')) {
+      if (current) out.patterns.push(current);
+      current = { id: line.replace(/^\s*- id:\s*/, '').trim() };
+    } else if (current) {
+      const m = line.match(/^\s+([a-z_]+):\s*(.*)$/);
+      if (m) {
+        const key = m[1];
+        let val = m[2].trim();
+        if (val.startsWith('[') && val.endsWith(']')) {
+          val = val.slice(1, -1).split(',').map(s => s.trim()).filter(Boolean);
+        }
+        current[key] = val;
+      }
+    }
+  }
+  if (current) out.patterns.push(current);
+  return out;
+}
+
+/**
+ * Walk both scopes and collect every pattern with full body context.
+ */
+function collectAllPatterns(sourceRoot) {
+  const all = [];
+  for (const scope of VALID_SCOPES) {
+    const dir = getLearningsDir(sourceRoot, scope);
+    let files;
+    try {
+      files = fs.readdirSync(dir).filter(f => f.endsWith('.md') && f !== 'README.md');
+    } catch {
+      continue;
+    }
+    for (const file of files) {
+      const filePath = path.join(dir, file);
+      const { frontmatter, body } = readTopicFile(filePath);
+      const topic = file.replace(/\.md$/, '');
+      for (const p of frontmatter.patterns) {
+        const patternBody = extractPatternBody(body, p.id);
+        all.push({
+          id: p.id,
+          scope,
+          topic,
+          file: filePath,
+          summary: p.summary || '',
+          source_experiments: Array.isArray(p.source_experiments) ? p.source_experiments : [],
+          superseded_by: p.superseded_by || null,
+          superseded_id: p.superseded_id || null,
+          body: patternBody,
+        });
+      }
+    }
+  }
+  return all;
+}
+
+/**
+ * Find a pattern's narrative body (the section between `## P-XXX —` and the
+ * next `## ` or end of file).
+ */
+function extractPatternBody(fileBody, patternId) {
+  const escaped = patternId.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const re = new RegExp(`(^|\\n)## ${escaped}[\\s\\S]*?(?=\\n## [A-Z]|$)`, 'i');
+  const m = fileBody.match(re);
+  return m ? m[0] : '';
+}
+
+/**
+ * Extract a single named bold-field section from a pattern body.
+ * Returns text between `**Field:**` and the next `**Other:**` block.
+ */
+function extractFieldSection(body, field) {
+  const re = new RegExp(`\\*\\*${field}:\\*\\*([\\s\\S]*?)(?=\\n\\*\\*[A-Z]|$)`, 'i');
+  const m = body.match(re);
+  return m ? m[1].trim() : '';
+}
+
+const KNOWN_EXPERIMENT_TOKENS = [
+  'notepadrs',
+  'whoolog', 'whoocache', 'whooflow', 'whooschema', 'whoodb',
+  'whoorun', 'whoograph', 'whoocsv', 'whoodag', 'whoodiff',
+  'whooemoji', 'whoohash', 'whoolen', 'whoosort', 'whooo',
+  'panloop', 'panloop2', 'panmd2', 'panmd3', 'panrhi',
+];
+
+const PAN_INTERNAL_TERMS = [
+  /\bPAN(?:'s)?\b/,
+  /\bv3\.\d+(\.\d+)?/,
+  /\bpan-wizard-core\b/,
+  /\bpan-tools\b/,
+  /\b\.planning\//,
+  /\bpan-(?:planner|executor|verifier|reviewer)\b/,
+];
+
+const PATTERN_REF_RE = /\bP-(?:[A-Z]+-)?\d+(?:-r\d+)?\b/g;
+
+/**
+ * Run all integrity checks on the collected patterns.
+ *
+ * Returns:
+ *   {
+ *     violations: [{ code, severity, pattern_id, file, message, ... }],
+ *     pattern_count, file_count, scopes
+ *   }
+ */
+function lintPatterns(patterns) {
+  const violations = [];
+
+  const idIndex = new Map(); // id -> [{scope, topic, file}, ...]
+  for (const p of patterns) {
+    if (!idIndex.has(p.id)) idIndex.set(p.id, []);
+    idIndex.get(p.id).push({ scope: p.scope, topic: p.topic, file: p.file });
+  }
+
+  for (const [id, locations] of idIndex.entries()) {
+    if (locations.length > 1) {
+      violations.push({
+        code: 'L-001',
+        severity: 'error',
+        pattern_id: id,
+        message: `Pattern ID "${id}" defined in ${locations.length} places`,
+        locations,
+      });
+    }
+  }
+
+  const knownIds = new Set(idIndex.keys());
+
+  for (const p of patterns) {
+    const refs = (p.body.match(PATTERN_REF_RE) || []).filter(r => r !== p.id);
+    const dangling = [...new Set(refs)].filter(r => !knownIds.has(r));
+    for (const ref of dangling) {
+      violations.push({
+        code: 'L-002',
+        severity: 'error',
+        pattern_id: p.id,
+        file: p.file,
+        message: `Pattern "${p.id}" references "${ref}" which is not defined in any topic file`,
+        dangling_ref: ref,
+      });
+    }
+  }
+
+  for (const p of patterns) {
+    if (p.source_experiments.length > 0) continue;
+    const lower = p.body.toLowerCase();
+    const cited = KNOWN_EXPERIMENT_TOKENS.filter(t => lower.includes(t.toLowerCase()));
+    if (cited.length > 0) {
+      violations.push({
+        code: 'L-003',
+        severity: 'warning',
+        pattern_id: p.id,
+        file: p.file,
+        message: `Pattern "${p.id}" cites experiment(s) ${JSON.stringify(cited)} in evidence prose but source_experiments frontmatter is empty`,
+        cited_experiments: cited,
+      });
+    }
+  }
+
+  for (const p of patterns) {
+    if (p.scope !== 'universal') continue;
+    const ruleSection = extractFieldSection(p.body, 'Rule');
+    const headingMatch = p.body.match(/^\s*##\s+([^\n]+)/m);
+    const heading = headingMatch ? headingMatch[1] : '';
+    const scanText = `${heading}\n${ruleSection}`;
+    const matches = [];
+    for (const re of PAN_INTERNAL_TERMS) {
+      const m = scanText.match(re);
+      if (m) matches.push(m[0]);
+    }
+    if (matches.length > 0) {
+      violations.push({
+        code: 'L-004',
+        severity: 'warning',
+        pattern_id: p.id,
+        file: p.file,
+        message: `Universal-scope pattern "${p.id}" mentions PAN-internal terms ${JSON.stringify([...new Set(matches)])} in heading or Rule section — candidate for internal/ scope`,
+        terms: [...new Set(matches)],
+      });
+    }
+  }
+
+  for (const p of patterns) {
+    const revMatch = p.id.match(/^(P-[A-Z0-9]+(?:-[A-Z0-9]+)?)-r(\d+)$/);
+    if (!revMatch) continue;
+    const baseId = revMatch[1];
+    const revNum = revMatch[2];
+    const basePattern = patterns.find(x => x.file === p.file && x.id === baseId);
+    if (!basePattern) continue;
+    const hasSupersession = basePattern.superseded_by || basePattern.superseded_id || /supersed/i.test(basePattern.body);
+    if (!hasSupersession) {
+      violations.push({
+        code: 'L-005',
+        severity: 'warning',
+        pattern_id: p.id,
+        file: p.file,
+        message: `Revision pattern "${p.id}" exists but base "${baseId}" has no superseded_by field in frontmatter`,
+        base_id: baseId,
+        revision: revNum,
+      });
+    }
+  }
+
+  return {
+    violations,
+    pattern_count: patterns.length,
+    file_count: new Set(patterns.map(p => p.file)).size,
+    scopes: VALID_SCOPES,
+  };
+}
+
+/**
+ * CLI entry: lint the learnings store.
+ *
+ * @param {string} sourceRoot
+ * @param {object} opts - { scope?: 'universal'|'internal', strict?: boolean }
+ */
+function cmdLearnLint(sourceRoot, opts = {}) {
+  const all = collectAllPatterns(sourceRoot);
+  const filtered = opts.scope
+    ? all.filter(p => p.scope === opts.scope)
+    : all;
+  const result = lintPatterns(filtered);
+
+  const errors = result.violations.filter(v => v.severity === 'error').length;
+  const warnings = result.violations.filter(v => v.severity === 'warning').length;
+
+  result.summary = {
+    total_violations: result.violations.length,
+    errors,
+    warnings,
+    status: errors > 0 || (opts.strict && warnings > 0) ? 'fail' : 'pass',
+  };
+
+  return result;
+}
+
+module.exports = {
+  cmdLearnLint,
+  collectAllPatterns,
+  lintPatterns,
+  extractPatternBody,
+  extractFieldSection,
+  KNOWN_EXPERIMENT_TOKENS,
+};