godpowers 0.15.0

package/lib/checkpoint.js

@@ -0,0 +1,390 @@
+/**
+ * Checkpoint Manager
+ *
+ * Maintains `.godpowers/CHECKPOINT.md`, a human-readable + agent-readable
+ * orientation file. Anyone (new chat session, new AI tool, returning user)
+ * can read this single file and know where the project is, what the last
+ * action was, and what comes next.
+ *
+ * Design intent (context-rot protection):
+ *   - Long sessions cause the AI's mental model to drift from disk.
+ *   - New sessions in any tool start with zero context.
+ *   - CHECKPOINT.md is the disk-authoritative "you are here" pin.
+ *   - It is updated after every significant action by the orchestrator.
+ *   - Reads are cheap; writes are append-aware (last 20 actions kept).
+ *
+ * Schema:
+ *   YAML frontmatter (machine-readable):
+ *     id: CHECKPOINT-{ISO8601}
+ *     project: {name}
+ *     mode: {A|B|C|E}
+ *     mode-d-suite: {bool}
+ *     lifecycle: {pre-init|in-arc|steady-state-active|...}
+ *     current-tier: {tier-N}
+ *     current-substep: {substep-key}
+ *     last-action: {action-name}
+ *     last-actor: {agent or user}
+ *     last-update: {ISO8601}
+ *     facts-hash: {sha256 of the held-facts section}
+ *   Markdown body (human-readable):
+ *     ## Where you are
+ *     ## Last 20 actions (most recent first)
+ *     ## Held facts (top 10 critical decisions)
+ *     ## Next suggested command
+ *     ## If you're a new session
+ *
+ * Public API:
+ *   path(projectRoot) -> string
+ *   read(projectRoot) -> { frontmatter, body, facts, actions } | null
+ *   write(projectRoot, state, opts) -> path
+ *   recordAction(projectRoot, action) -> updated checkpoint
+ *   recordFact(projectRoot, fact) -> updated checkpoint
+ *   diff(projectRoot, aiClaim) -> { drifts, matches } (for /god-context-scan)
+ */
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+
+const MAX_ACTIONS = 20;
+const MAX_FACTS = 10;
+
+function checkpointPath(projectRoot) {
+  return path.join(projectRoot, '.godpowers', 'CHECKPOINT.md');
+}
+
+function sha256(s) {
+  return crypto.createHash('sha256').update(s).digest('hex');
+}
+
+function nowIso() {
+  return new Date().toISOString();
+}
+
+/**
+ * Parse a CHECKPOINT.md file. Returns structured form or null if missing.
+ */
+function read(projectRoot) {
+  const file = checkpointPath(projectRoot);
+  if (!fs.existsSync(file)) return null;
+  const raw = fs.readFileSync(file, 'utf8');
+
+  // Frontmatter parse
+  let frontmatter = {};
+  let body = raw;
+  if (raw.startsWith('---')) {
+    const end = raw.indexOf('\n---', 3);
+    if (end > 0) {
+      const fmText = raw.slice(3, end).trim();
+      body = raw.slice(end + 4).trim();
+      for (const line of fmText.split('\n')) {
+        const m = line.match(/^([\w-]+):\s*(.*)$/);
+        if (m) {
+          let v = m[2].trim();
+          if (v === 'true') v = true;
+          else if (v === 'false') v = false;
+          frontmatter[m[1]] = v;
+        }
+      }
+    }
+  }
+
+  // Section parse for actions and facts
+  const actions = parseList(body, 'Last actions');
+  const facts = parseList(body, 'Held facts');
+
+  return { path: file, frontmatter, body, actions, facts };
+}
+
+function parseList(body, heading) {
+  const re = new RegExp(`##\\s+${heading}[^\\n]*\\n([\\s\\S]*?)(?:\\n##\\s|$)`, 'i');
+  const m = body.match(re);
+  if (!m) return [];
+  return m[1].split('\n')
+    .map(l => l.trim())
+    .filter(l => l.startsWith('- '))
+    .map(l => l.slice(2));
+}
+
+/**
+ * Write a fresh CHECKPOINT.md. Overwrites prior content.
+ *
+ * state shape:
+ *   { project, mode, modeDSuite, lifecycle, currentTier, currentSubstep,
+ *     lastAction, lastActor, actions: [...], facts: [...], nextCommand,
+ *     nextReason }
+ */
+function write(projectRoot, state) {
+  const file = checkpointPath(projectRoot);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+
+  const ts = nowIso();
+  const id = `CHECKPOINT-${ts.replace(/[:.]/g, '-')}`;
+  const actions = (state.actions || []).slice(0, MAX_ACTIONS);
+  const facts = (state.facts || []).slice(0, MAX_FACTS);
+  const factsHash = sha256(JSON.stringify(facts));
+
+  const fm = [
+    '---',
+    `id: ${id}`,
+    `project: ${state.project || 'unnamed'}`,
+    `mode: ${state.mode || '?'}`,
+    `mode-d-suite: ${state.modeDSuite ? 'true' : 'false'}`,
+    `lifecycle: ${state.lifecycle || 'in-arc'}`,
+    `current-tier: ${state.currentTier || 'tier-0'}`,
+    `current-substep: ${state.currentSubstep || 'orchestration'}`,
+    `last-action: ${state.lastAction || 'unknown'}`,
+    `last-actor: ${state.lastActor || 'unknown'}`,
+    `last-update: ${ts}`,
+    `facts-hash: sha256:${factsHash}`,
+    '---',
+    ''
+  ].join('\n');
+
+  const body = [
+    '# Checkpoint',
+    '',
+    '> **For a new chat session or new AI tool**: read this file first.',
+    '> It is the authoritative "where you are" pin for this Godpowers project.',
+    '> Disk state always wins over conversation memory.',
+    '',
+    '## Where you are',
+    '',
+    `- Project: **${state.project || 'unnamed'}**`,
+    `- Mode: **${state.mode || '?'}**${state.modeDSuite ? ' (in multi-repo suite)' : ''}`,
+    `- Lifecycle phase: **${state.lifecycle || 'in-arc'}**`,
+    `- Current tier: **${state.currentTier || 'tier-0'}** / **${state.currentSubstep || 'orchestration'}**`,
+    `- Last action: \`${state.lastAction || 'unknown'}\` by ${state.lastActor || 'unknown'} at ${ts}`,
+    '',
+    '## Next suggested command',
+    '',
+    state.nextCommand
+      ? `\`${state.nextCommand}\` - ${state.nextReason || 'no reason given'}`
+      : 'Run `/god-next` to see the next command based on disk state.',
+    '',
+    `## Last actions (most recent first, max ${MAX_ACTIONS})`,
+    '',
+    actions.length === 0
+      ? '_(no actions recorded yet)_'
+      : actions.map(a => `- ${a}`).join('\n'),
+    '',
+    `## Held facts (top ${MAX_FACTS} critical decisions)`,
+    '',
+    facts.length === 0
+      ? '_(no facts recorded yet)_'
+      : facts.map(f => `- ${f}`).join('\n'),
+    '',
+    '## If you are a new session',
+    '',
+    '1. Read this whole file.',
+    '2. Run `/god-locate` for a full orientation including state.json',
+    '   diff and recent events.',
+    '3. Run `/god-status` to verify disk reality.',
+    '4. Run `/god-next` for the next suggested command.',
+    '5. If anything in this file feels inconsistent with what you',
+    '   know, run `/god-context-scan` to surface drift.',
+    '',
+    '## Provenance',
+    '',
+    `- Generated: ${ts}`,
+    `- Schema version: 1.0`,
+    `- Authoritative state: \`.godpowers/state.json\``,
+    `- Authoritative history: \`.godpowers/runs/<id>/events.jsonl\` + \`.godpowers/log\``,
+    ''
+  ].join('\n');
+
+  fs.writeFileSync(file, fm + body);
+  return file;
+}
+
+/**
+ * Append a new action to the checkpoint. Trims to MAX_ACTIONS.
+ *
+ * action shape: { ts, actor, name, details? }
+ */
+function recordAction(projectRoot, action) {
+  const existing = read(projectRoot);
+  const actions = existing ? existing.actions.slice() : [];
+  const line = `[${action.ts || nowIso()}] ${action.actor || 'unknown'}: ${action.name}${action.details ? ' - ' + action.details : ''}`;
+  actions.unshift(line);
+
+  const state = existing ? frontmatterToState(existing.frontmatter, existing.facts) : {};
+  state.actions = actions;
+  state.lastAction = action.name;
+  state.lastActor = action.actor;
+  return write(projectRoot, state);
+}
+
+/**
+ * Append a new held fact. Trims to MAX_FACTS (LRU style by reorder).
+ */
+function recordFact(projectRoot, fact) {
+  const existing = read(projectRoot);
+  const facts = existing ? existing.facts.slice() : [];
+  // Dedupe
+  const f = typeof fact === 'string' ? fact : `${fact.label}: ${fact.value}`;
+  const i = facts.indexOf(f);
+  if (i >= 0) facts.splice(i, 1);
+  facts.unshift(f);
+
+  const state = existing ? frontmatterToState(existing.frontmatter, facts) : { facts };
+  state.facts = facts;
+  return write(projectRoot, state);
+}
+
+function frontmatterToState(fm, facts) {
+  return {
+    project: fm.project,
+    mode: fm.mode,
+    modeDSuite: fm['mode-d-suite'] === true || fm['mode-d-suite'] === 'true',
+    lifecycle: fm.lifecycle,
+    currentTier: fm['current-tier'],
+    currentSubstep: fm['current-substep'],
+    lastAction: fm['last-action'],
+    lastActor: fm['last-actor'],
+    facts: facts || []
+  };
+}
+
+/**
+ * Compare the AI's claim about state with disk.
+ *
+ * aiClaim shape: { project, mode, lifecycle, currentTier, currentSubstep, lastAction }
+ *
+ * Returns { drifts: [...], matches: [...] }.
+ * Each drift: { field, claimed, actual }.
+ */
+function diff(projectRoot, aiClaim) {
+  const cp = read(projectRoot);
+  if (!cp) return { drifts: [{ field: 'checkpoint', claimed: aiClaim, actual: 'no checkpoint file' }], matches: [] };
+
+  const drifts = [];
+  const matches = [];
+  const state = cp.frontmatter;
+  for (const [k, claim] of Object.entries(aiClaim || {})) {
+    const mapped = {
+      project: state.project,
+      mode: state.mode,
+      modeDSuite: state['mode-d-suite'],
+      lifecycle: state.lifecycle,
+      currentTier: state['current-tier'],
+      currentSubstep: state['current-substep'],
+      lastAction: state['last-action']
+    }[k];
+    if (String(claim) === String(mapped)) {
+      matches.push({ field: k, value: claim });
+    } else {
+      drifts.push({ field: k, claimed: claim, actual: mapped });
+    }
+  }
+  return { drifts, matches };
+}
+
+/**
+ * Reconstruct the checkpoint from current disk state.
+ * Use when the orchestrator finishes a sub-step and wants to refresh
+ * the pin in one call instead of fine-grained recordAction calls.
+ *
+ * Reads .godpowers/state.json and .godpowers/runs/<latest>/events.jsonl
+ * to derive: project, mode, lifecycle, current tier/substep, last action,
+ * and the most recent action stream.
+ *
+ * opts:
+ *   extraFacts: string[] - facts to also record (prepended)
+ *   nextCommand: string  - next suggested command
+ *   nextReason: string   - reason for the suggestion
+ *
+ * Returns the path to the written checkpoint.
+ */
+function syncFromState(projectRoot, opts = {}) {
+  // Defer the requires so checkpoint.js stays a leaf module
+  const state = require('./state');
+  const events = require('./events');
+
+  const s = state.read(projectRoot);
+  if (!s) throw new Error('state.json not initialized');
+
+  // Find the current tier + sub-step: first one with status in-flight,
+  // else last one done, else tier-0/orchestration.
+  let currentTier = 'tier-0';
+  let currentSubstep = 'orchestration';
+  let lastAction = 'init';
+  let lastUpdate = null;
+  let lastActor = 'unknown';
+  if (s.tiers) {
+    outer: for (const tierKey of Object.keys(s.tiers).sort()) {
+      for (const [substepKey, sub] of Object.entries(s.tiers[tierKey])) {
+        if (sub.status === 'in-flight') {
+          currentTier = tierKey;
+          currentSubstep = substepKey;
+          break outer;
+        }
+        if (sub.status === 'done' && sub.updated) {
+          if (!lastUpdate || sub.updated > lastUpdate) {
+            lastUpdate = sub.updated;
+            currentTier = tierKey;
+            currentSubstep = substepKey;
+            lastAction = `${tierKey}.${substepKey} done`;
+          }
+        }
+      }
+    }
+  }
+
+  // Pull last 20 actions from events tail
+  const runs = events.listRuns(projectRoot);
+  const actions = [];
+  if (runs.length > 0) {
+    const latest = runs[runs.length - 1];
+    const all = events.readRun(projectRoot, latest);
+    // Walk backward; emit lines for human-significant events
+    const significant = ['agent.end', 'agent.pause', 'gate.fail', 'gate.pass',
+                         'tier.skip', 'state.repair', 'state.rollback',
+                         'extension.install', 'error'];
+    for (let i = all.length - 1; i >= 0 && actions.length < MAX_ACTIONS; i--) {
+      const e = all[i];
+      if (!significant.includes(e.name)) continue;
+      const tier = (e.attrs && e.attrs.tier) ? `[${e.attrs.tier}] ` : '';
+      const agent = (e.attrs && e.attrs.agent) ? e.attrs.agent + ': ' : '';
+      actions.push(`[${e.ts}] ${tier}${agent}${e.name}`);
+      if (i === all.length - 1) {
+        lastAction = e.name;
+        lastActor = (e.attrs && e.attrs.agent) || 'system';
+      }
+    }
+  }
+
+  // Carry forward existing facts; prepend new ones from opts
+  const existing = read(projectRoot);
+  const facts = (opts.extraFacts || []).concat(
+    existing ? existing.facts : []
+  ).slice(0, MAX_FACTS);
+
+  return write(projectRoot, {
+    project: s.project && s.project.name,
+    mode: s.mode,
+    modeDSuite: !!s['mode-d-suite'],
+    lifecycle: s['lifecycle-phase'] || 'in-arc',
+    currentTier,
+    currentSubstep,
+    lastAction,
+    lastActor,
+    actions,
+    facts,
+    nextCommand: opts.nextCommand,
+    nextReason: opts.nextReason
+  });
+}
+
+module.exports = {
+  checkpointPath,
+  path: checkpointPath,
+  read,
+  write,
+  recordAction,
+  recordFact,
+  syncFromState,
+  diff,
+  MAX_ACTIONS,
+  MAX_FACTS
+};

package/lib/code-scanner.js

@@ -0,0 +1,262 @@
+/**
+ * Code Scanner
+ *
+ * Scans a codebase for linkage signals between code and artifact IDs.
+ *
+ * Discovery mechanisms:
+ *   1. Comment annotations: // Implements: P-MUST-01, // ADR-007, // Token: {colors.primary}
+ *   2. Filename heuristics: src/components/Button.tsx -> D-button-primary; src/auth/ -> C-auth-service
+ *   3. Import analysis: importing a STACK dep links to its decision ID
+ *   4. Style-system parsing: tokens used in CSS / styled-components / Tailwind
+ *   5. Test descriptions: describe('P-MUST-01: user can log in') -> link
+ *
+ * Returns structured links: [{ artifactId, file, source, line? }]
+ *
+ * Public API:
+ *   scan(projectRoot, opts) -> { links, stats }
+ *   scanFile(filePath, opts) -> [...links from this file]
+ *   parseAnnotation(line) -> [...] // exposed for testing
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const linkage = require('./linkage');
+
+// ============================================================================
+// Annotation patterns (across languages, comment styles)
+// ============================================================================
+
+// Match: `// Implements: P-MUST-01` or `# Implements: P-MUST-01` etc.
+const ANNOTATION_PATTERNS = [
+  // Implements: <id>
+  /(?:\/\/|\/\*|\*|#|--|<!--)\s*Implements?\s*:\s*([A-Za-z][\w.-]*(?:,\s*[A-Za-z][\w.-]*)*)/i,
+  // Fixes: P-MUST-NN  or  Fixes: incident-001
+  /(?:\/\/|\/\*|\*|#|--|<!--)\s*Fixes?\s*:\s*([A-Za-z][\w.-]*)/i,
+  // ADR-007 mentioned anywhere in a comment line
+  /(?:\/\/|\/\*|\*|#|--|<!--)[^\n]*\b(ADR-\d+)\b/i,
+  // Token: {colors.primary}
+  /(?:\/\/|\/\*|\*|#|--|<!--)\s*Token\s*:\s*\{([\w.-]+)\}/i,
+  // Pattern: ADR-007 or Source: C-auth-service
+  /(?:\/\/|\/\*|\*|#|--|<!--)\s*(?:Pattern|Source|Container)\s*:\s*([A-Za-z][\w.-]+)/i,
+  // Implements: D-button-primary (design component)
+  /(?:\/\/|\/\*|\*|#|--|<!--)\s*Implements?\s*:\s*(D-[\w-]+)/i
+];
+
+const SCAN_EXTENSIONS = new Set([
+  '.js', '.jsx', '.ts', '.tsx', '.mjs', '.cjs',
+  '.py', '.go', '.rb', '.rs', '.java', '.kt', '.swift',
+  '.css', '.scss', '.less', '.styl',
+  '.html', '.vue', '.svelte', '.astro',
+  '.md', '.mdx',
+  '.yml', '.yaml',
+  '.sh', '.bash'
+]);
+
+const IGNORE_DIRS = new Set([
+  'node_modules', '.git', '.next', 'dist', 'build', 'out',
+  '.cache', '.parcel-cache', '.turbo', 'target', '__pycache__',
+  '.pytest_cache', '.venv', 'venv', '.tox', '.idea', '.vscode',
+  'coverage', '.nyc_output', '.svelte-kit', '.vercel',
+  '.godpowers'
+]);
+
+/**
+ * Parse a single line of source for annotations. Returns array of artifact IDs.
+ */
+function parseAnnotation(line) {
+  const ids = [];
+  for (const pattern of ANNOTATION_PATTERNS) {
+    const m = line.match(pattern);
+    if (m && m[1]) {
+      // Comma-separated list support: "P-MUST-01, P-MUST-02"
+      const tokens = m[1].split(',').map(t => t.trim()).filter(Boolean);
+      ids.push(...tokens);
+    }
+  }
+  return [...new Set(ids)];
+}
+
+/**
+ * Scan a single file and return all annotation-based links.
+ */
+function scanFile(filePath, opts = {}) {
+  const links = [];
+  if (!fs.existsSync(filePath)) return links;
+
+  const ext = path.extname(filePath);
+  if (!SCAN_EXTENSIONS.has(ext)) return links;
+
+  const content = fs.readFileSync(filePath, 'utf8');
+  const lines = content.split('\n');
+  for (let i = 0; i < lines.length; i++) {
+    const ids = parseAnnotation(lines[i]);
+    for (const id of ids) {
+      links.push({
+        artifactId: id,
+        file: filePath,
+        source: 'annotation',
+        line: i + 1
+      });
+    }
+  }
+  return links;
+}
+
+/**
+ * Filename heuristic: src/components/Button.tsx -> [D-button]
+ */
+function filenameHeuristic(filePath, projectRoot) {
+  const links = [];
+  const rel = path.relative(projectRoot, filePath);
+
+  // src/components/Button.tsx -> D-button
+  const compMatch = rel.match(/components?\/([\w-]+)\.(tsx?|jsx?|vue|svelte)$/i);
+  if (compMatch) {
+    const slug = kebab(compMatch[1]);
+    links.push({ artifactId: `D-${slug}`, file: filePath, source: 'filename' });
+  }
+
+  // src/auth/foo.ts -> C-auth-service (if matches container slug pattern)
+  const containerMatch = rel.match(/^(?:src|lib|app|services?)\/([a-z][\w-]*)/);
+  if (containerMatch) {
+    const slug = containerMatch[1];
+    // Heuristic: only treat as container if the slug looks service-y
+    if (/service|server|api|db|auth|core/i.test(slug)) {
+      links.push({ artifactId: `C-${slug}`, file: filePath, source: 'filename' });
+    }
+  }
+  return links;
+}
+
+/**
+ * Style-system: scan CSS/JSX for token references like var(--colors-primary)
+ * or Tailwind class fragments that look like our tokens.
+ */
+function styleSystemScan(filePath, opts = {}) {
+  const links = [];
+  const ext = path.extname(filePath);
+  if (!['.css', '.scss', '.less', '.styl', '.tsx', '.jsx', '.vue', '.svelte', '.html'].includes(ext)) {
+    return links;
+  }
+  if (!fs.existsSync(filePath)) return links;
+  const content = fs.readFileSync(filePath, 'utf8');
+
+  // CSS variables: var(--colors-primary) or var(--token-name)
+  // Tokens like `colors.primary` get translated to CSS vars `--colors-primary`
+  const cssVarRegex = /var\(--([a-z][\w-]*)\)/g;
+  let m;
+  while ((m = cssVarRegex.exec(content)) !== null) {
+    const cssName = m[1]; // e.g., "colors-primary"
+    // Convert back to token path: colors-primary -> colors.primary (heuristic)
+    const tokenPath = cssName.replace(/-/g, '.');
+    if (linkage.classifyId(tokenPath) === 'token') {
+      links.push({ artifactId: tokenPath, file: filePath, source: 'css-var' });
+    }
+  }
+
+  // Direct {token.path} references in styled-components or Tailwind config
+  const tokenRefRegex = /\{(colors|typography|spacing|rounded)\.([\w-]+)\}/g;
+  while ((m = tokenRefRegex.exec(content)) !== null) {
+    const tokenPath = `${m[1]}.${m[2]}`;
+    links.push({ artifactId: tokenPath, file: filePath, source: 'token-ref' });
+  }
+
+  return links;
+}
+
+/**
+ * Top-level scan: walks the project tree, applies all discovery mechanisms.
+ */
+function scan(projectRoot, opts = {}) {
+  const root = path.resolve(projectRoot);
+  const links = [];
+  const stats = {
+    filesScanned: 0,
+    filesWithLinks: 0,
+    annotationLinks: 0,
+    filenameLinks: 0,
+    styleLinks: 0
+  };
+
+  function walk(dir) {
+    if (!fs.existsSync(dir)) return;
+    let entries;
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch (e) {
+      return;
+    }
+    for (const e of entries) {
+      const full = path.join(dir, e.name);
+      if (e.isDirectory()) {
+        if (IGNORE_DIRS.has(e.name)) continue;
+        walk(full);
+      } else if (e.isFile()) {
+        const ext = path.extname(e.name);
+        if (!SCAN_EXTENSIONS.has(ext)) continue;
+
+        stats.filesScanned++;
+        const before = links.length;
+
+        // 1. Annotation scan
+        const annLinks = scanFile(full);
+        links.push(...annLinks);
+        stats.annotationLinks += annLinks.length;
+
+        // 2. Filename heuristic
+        const fnLinks = filenameHeuristic(full, root);
+        links.push(...fnLinks);
+        stats.filenameLinks += fnLinks.length;
+
+        // 3. Style-system scan
+        if (opts.skipStyleScan !== true) {
+          const styleLinks = styleSystemScan(full);
+          links.push(...styleLinks);
+          stats.styleLinks += styleLinks.length;
+        }
+
+        if (links.length > before) stats.filesWithLinks++;
+      }
+    }
+  }
+
+  walk(root);
+  return { links, stats };
+}
+
+/**
+ * Apply scan results to linkage map. Returns counts of additions.
+ */
+function applyScan(projectRoot, scanResult, opts = {}) {
+  const { links } = scanResult;
+  let added = 0;
+  for (const l of links) {
+    const r = linkage.addLink(projectRoot, l.artifactId, l.file, { source: l.source });
+    if (r.added) added++;
+  }
+  return { totalLinks: links.length, added };
+}
+
+// ============================================================================
+// Helpers
+// ============================================================================
+
+function kebab(s) {
+  return s
+    .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
+    .replace(/[\s_]+/g, '-')
+    .toLowerCase();
+}
+
+module.exports = {
+  parseAnnotation,
+  scanFile,
+  filenameHeuristic,
+  styleSystemScan,
+  scan,
+  applyScan,
+  ANNOTATION_PATTERNS,
+  SCAN_EXTENSIONS,
+  IGNORE_DIRS
+};