forge-workflow 0.1.0-beta.4 → 0.1.0-beta.6

package/lib/insights.js

@@ -3,10 +3,76 @@
 const fs = require('node:fs');
 const path = require('node:path');
 const typedMemory = require('./memory/typed-api');
+const { runIssueOperation: defaultRunIssueOperation } = require('./forge-issues');
+const { buildMigratedKernelIssueDeps } = require('./kernel/cli-broker-factory');
 
 const ISSUE_REFS = ['forge-besw.12', 'forge-1gry', 'forge-5q7s'];
 const DEFAULT_MIN_COUNT = 5;
 const DEFAULT_LIMIT = 10;
+// Upper bound on kernel_events scanned for interaction patterns — a spot-read, not a
+// full history walk. Newest-first, so recent activity dominates the signal.
+const EVENT_READ_LIMIT = 2000;
+
+// Default kernel activity read for `forge insights` (Slice C2). Builds a short-lived
+// migrated broker, reads recent kernel_events, and ALWAYS closes the driver (Windows
+// CI fails on a leaked handle). Injectable via analyzeInsights options for tests.
+async function defaultListRecentEvents(projectRoot, { since = null, limit = null } = {}) {
+  let deps;
+  try {
+    deps = await buildMigratedKernelIssueDeps({ projectRoot });
+  } catch {
+    return [];
+  }
+  try {
+    return await deps.kernelBroker.listRecentEvents({ since, limit });
+  } catch {
+    return [];
+  } finally {
+    if (deps.kernelDriver && typeof deps.kernelDriver.close === 'function') {
+      deps.kernelDriver.close();
+    }
+  }
+}
+
+// Map a kernel_events row back to the interaction shape insights consumes. Imported beads
+// interactions carry event_type `beads.interaction.<kind>` and payload_json `{ kind, ...extra }`
+// where field/new_value/reason live at the top level alongside kind (see beads-kernel-compat
+// mapBeadsInteractionToKernel). Native kernel events fall back to their event_type as the kind.
+function eventToInteraction(row) {
+  if (!row || typeof row !== 'object') return null;
+  let parsed;
+  try {
+    parsed = row.payload_json ? JSON.parse(row.payload_json) : row.payload;
+  } catch {
+    parsed = null;
+  }
+  // A scalar or array payload carries no interaction fields — treat it as empty.
+  const payload = parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : {};
+  const kind = payload.kind
+    || String(row.event_type || '').replace(/^beads\.interaction\./, '')
+    || 'interaction';
+  return {
+    kind,
+    id: row.id,
+    issue_id: row.entity_id || null,
+    created_at: row.created_at || null,
+    extra: payload,
+  };
+}
+
+// Read all issues from the Kernel (the sole issue-state authority) for theme mining.
+// Resilient: any read failure degrades to empty issue evidence rather than throwing.
+async function listKernelIssues(projectRoot, runIssueOperation, env) {
+  try {
+    const result = await runIssueOperation('list', [], projectRoot, { issueBackend: 'kernel', env });
+    if (result && result.ok && result.data && Array.isArray(result.data.issues)) {
+      return result.data.issues;
+    }
+  } catch {
+    // best-effort: insights never crashes on a kernel read failure
+  }
+  return [];
+}
 const STOP_WORDS = new Set([
   'after',
   'against',
@@ -108,10 +174,15 @@ function addPattern(map, key, patch) {
   map.set(key, existing);
 }
 
-function interactionPatterns(projectRoot, options, map) {
-  const rows = readJsonl(path.join(projectRoot, '.beads', 'interactions.jsonl'));
-  for (const row of rows) {
-    if (!row || typeof row !== 'object' || row._parseError || !isSince(row.created_at, options.since)) continue;
+async function interactionPatterns(projectRoot, options, map) {
+  const listRecentEvents = options.listRecentEvents || defaultListRecentEvents;
+  const since = options.since ? options.since.toISOString() : null;
+  const rawEvents = await listRecentEvents(projectRoot, { since, limit: EVENT_READ_LIMIT, env: options.env });
+  const interactions = (Array.isArray(rawEvents) ? rawEvents : [])
+    .map(eventToInteraction)
+    .filter(Boolean);
+  for (const row of interactions) {
+    if (!isSince(row.created_at, options.since)) continue;
     const extra = row.extra && typeof row.extra === 'object' ? row.extra : {};
     if (row.kind === 'field_change' && extra.field) {
       const family = reasonFamily(extra.reason);
@@ -120,7 +191,7 @@ function interactionPatterns(projectRoot, options, map) {
         kind: 'interaction',
         title: `${extra.field} changed to ${extra.new_value || 'changed'} (${family})`,
         evidence: row.issue_id || row.id,
-        source: '.beads/interactions.jsonl',
+        source: 'kernel_events',
         lastSeen: row.created_at,
       });
     } else if (row.kind) {
@@ -128,12 +199,12 @@ function interactionPatterns(projectRoot, options, map) {
         kind: 'interaction',
         title: `Interaction event: ${row.kind}`,
         evidence: row.issue_id || row.id,
-        source: '.beads/interactions.jsonl',
+        source: 'kernel_events',
         lastSeen: row.created_at,
       });
     }
   }
-  return rows;
+  return interactions;
 }
 
 function words(value) {
@@ -153,9 +224,9 @@ function words(value) {
   return tokens;
 }
 
-function issuePatterns(projectRoot, options, map) {
-  const rows = readJsonl(path.join(projectRoot, '.beads', 'issues.jsonl'))
-    .filter(row => row && !row._parseError && row._type === 'issue');
+async function issuePatterns(projectRoot, options, map) {
+  const runIssueOperation = options.runIssueOperation || defaultRunIssueOperation;
+  const rows = await listKernelIssues(projectRoot, runIssueOperation, options.env);
   const perWord = new Map();
   for (const issue of rows) {
     if (!isSince(issue.updated_at || issue.closed_at || issue.created_at, options.since)) continue;
@@ -173,7 +244,7 @@ function issuePatterns(projectRoot, options, map) {
       title: `Recurring issue theme: ${word}`,
       count: issues.length,
       evidence: issues.slice(0, 5).map(issue => issue.id).join(', '),
-      source: '.beads/issues.jsonl',
+      source: 'kernel',
       lastSeen: issues.map(issue => asDate(issue.updated_at || issue.closed_at || issue.created_at))
         .filter(Boolean)
         .sort((a, b) => b - a)[0],
@@ -244,11 +315,19 @@ function candidateFromPattern(pattern) {
   };
 }
 
-function analyzeInsights(projectRoot, options = {}) {
+async function analyzeInsights(projectRoot, options = {}) {
   const normalized = normalizeOptions(options);
+  // Read options carry the normalized thresholds PLUS the injectable kernel seams
+  // (defaulted to the real cli-broker-factory-backed reads) so tests can supply fakes.
+  const readOptions = {
+    ...normalized,
+    runIssueOperation: options.runIssueOperation,
+    listRecentEvents: options.listRecentEvents,
+    env: options.env,
+  };
   const map = new Map();
-  const interactions = interactionPatterns(projectRoot, normalized, map);
-  const issues = issuePatterns(projectRoot, normalized, map);
+  const interactions = await interactionPatterns(projectRoot, readOptions, map);
+  const issues = await issuePatterns(projectRoot, readOptions, map);
   const audit = auditPatterns(projectRoot, normalized, map);
   const patterns = toPatternList(map, normalized);
   const candidates = patterns.map(candidateFromPattern);
@@ -267,7 +346,7 @@ function analyzeInsights(projectRoot, options = {}) {
     candidates,
     limitations: [
       'Insights are local workflow signals, not proof of correctness.',
-      'Sparse Beads interactions or missing audit logs reduce confidence.',
+      'Sparse kernel events or missing audit logs reduce confidence.',
       'Accepting a suggestion records a decision; it does not install trusted executable code.',
     ],
   };
@@ -314,6 +393,8 @@ function recordInsightDecision(projectRoot, candidateId, status, options = {}) {
   }, {
     memory: options.memory,
     tags: ['insights', status],
+    // `beadsRefs` is a persisted typed-memory field name kept for data-shape compat
+    // (imported/legacy memories carry it); the values are historical issue references.
     beadsRefs: ISSUE_REFS,
     provenance: {
       actor: 'forge insights',
@@ -323,75 +404,10 @@ function recordInsightDecision(projectRoot, candidateId, status, options = {}) {
   });
 }
 
-function issueSummary(issues) {
-  return issues.reduce((summary, issue) => {
-    summary.total += 1;
-    if (issue.status === 'closed') summary.closed += 1;
-    else summary.open += 1;
-    return summary;
-  }, { total: 0, open: 0, closed: 0 });
-}
-
-function buildRecap(projectRoot, options = {}) {
-  const normalized = normalizeOptions(options);
-  const insights = analyzeInsights(projectRoot, options);
-  const issues = readJsonl(path.join(projectRoot, '.beads', 'issues.jsonl'))
-    .filter(row => row && !row._parseError && row._type === 'issue')
-    .filter(issue => isSince(issue.updated_at || issue.closed_at || issue.created_at, normalized.since));
-  const interactions = readJsonl(path.join(projectRoot, '.beads', 'interactions.jsonl'))
-    .filter(row => row && typeof row === 'object' && !row._parseError)
-    .filter(row => isSince(row.created_at, normalized.since));
-  const reviewOutcomes = interactions.filter(row => {
-    const reason = row.extra?.reason || '';
-    return reasonFamily(reason) === 'merged-and-verified' || String(reason).toLowerCase().includes('review');
-  }).length;
-  const recentIssues = [...issues]
-    .sort((a, b) => String(b.updated_at || b.closed_at || b.created_at || '').localeCompare(String(a.updated_at || a.closed_at || a.created_at || '')))
-    .slice(0, normalized.limit)
-    .map(issue => ({
-      id: issue.id,
-      title: issue.title,
-      status: issue.status,
-    }));
-
-  return {
-    generatedAt: new Date().toISOString(),
-    issueSummary: issueSummary(issues),
-    reviewOutcomes,
-    recentIssues,
-    insights,
-  };
-}
-
-function formatRecapText(recap) {
-  const lines = [
-    'Forge recap',
-    `Issues: ${recap.issueSummary.total} total, ${recap.issueSummary.open} open, ${recap.issueSummary.closed} closed`,
-    `Review outcomes found: ${recap.reviewOutcomes}`,
-    'Recent work:',
-  ];
-  for (const issue of recap.recentIssues) {
-    lines.push(`- ${issue.id}: ${issue.title} [${issue.status || 'unknown'}]`);
-  }
-  lines.push('Insight candidates:');
-  if (recap.insights.candidates.length === 0) {
-    lines.push('- No strong recurring patterns found.');
-  } else {
-    for (const candidate of recap.insights.candidates) {
-      lines.push(`- ${candidate.id}: ${candidate.title}`);
-    }
-  }
-  lines.push('Limitations:');
-  for (const limitation of recap.insights.limitations) lines.push(`- ${limitation}`);
-  return `${lines.join('\n')}\n`;
-}
-
 module.exports = {
   ISSUE_REFS,
   analyzeInsights,
-  buildRecap,
   formatInsightsText,
-  formatRecapText,
   readJsonl,
   recordInsightDecision,
 };

package/lib/issue-render.js

@@ -114,6 +114,19 @@ function pushSection(lines, label, text) {
   lines.push('', `${label}:`, text);
 }
 
+function renderReadinessReason(reason) {
+	if (!reason || typeof reason !== 'object') return String(reason ?? 'unknown');
+	const detail = reason.field || reason.issue_id || reason.gate || reason.actor || reason.status;
+	const parts = [];
+	if (detail) parts.push(String(detail));
+	if (reason.expected !== undefined) parts.push(`expected ${JSON.stringify(reason.expected)}`);
+	if (reason.actual !== undefined) parts.push(`actual ${JSON.stringify(reason.actual)}`);
+	if (reason.declared !== undefined) parts.push(`declared ${JSON.stringify(reason.declared)}`);
+	return parts.length > 0
+		? `${reason.code} (${parts.join(', ')})`
+		: String(reason.code || 'unknown');
+}
+
 // forge show: the full detail view. This is the surface that prints the FULL id
 // (list/ready show only the 8-char prefix), so every field a script or human
 // needs to act on the issue is reachable without --json.
@@ -135,6 +148,12 @@ function renderIssueShow(envelope) {
   pushField(lines, 'Claimed by', issue.claimed_by);
   pushField(lines, 'Parent', shortId(issue.parent_id ?? null) || null);
   pushField(lines, 'Blocked by', Array.isArray(issue.blocked_by) ? issue.blocked_by.map(shortId) : null);
+	pushField(lines, 'Readiness', issue.readiness_state);
+	pushField(
+		lines,
+		'Readiness reasons',
+		Array.isArray(issue.readiness_reasons) ? issue.readiness_reasons.map(renderReadinessReason) : null,
+	);
   pushField(lines, 'Dependencies', Array.isArray(issue.dependencies) ? issue.dependencies.map(shortId) : null);
   pushField(lines, 'Dependents', Array.isArray(issue.dependents) ? issue.dependents.map(shortId) : null);
   pushField(lines, 'Created', issue.created_at);

package/lib/kernel/backing-issue.js

@@ -39,7 +39,14 @@ const DEFAULT_IGNORE_GLOBS = Object.freeze(['tmp/*', 'spike/*', 'wip/*', 'throwa
 const AUTO_STUB_LABEL = 'auto-stub';
 // Branch prefixes stripped before deriving a title / probing for an encoded issue id.
 const BRANCH_PREFIX = /^(feat|feature|fix|bugfix|hotfix|chore|refactor|docs|test|spike|wip)\//i;
-// An issue key encoded in a branch slug, e.g. `feat/kap-7-foo` -> `kap-7`.
+// A full Kernel issue id (UUID) named anywhere in the branch, e.g.
+// `feat/18f1988e-...-close-on-merge`. Kernel ids ARE UUIDs, so this is the shape a
+// real branch->issue reference actually takes; kept identical to the UUID_RE that
+// resolveActiveIssueId (lib/workflow/enforce-stage.js) matches, so every resolver
+// agrees on which issue a branch names.
+const ENCODED_UUID = /[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/i;
+// Legacy Beads-era issue key encoded in a branch slug, e.g. `feat/kap-7-foo` -> `kap-7`.
+// Still honored for stores imported via `forge migrate --from beads`.
 const ENCODED_ISSUE_ID = /^([a-z][a-z0-9]*-\d+)\b/i;
 // Regex metacharacters escaped when compiling an ignore glob.
 const GLOB_METACHARS = '.+^${}()|[]\\';
@@ -145,12 +152,17 @@ function deriveTitle(branch) {
 }
 
 /**
- * Extract an issue id encoded in the branch name (e.g. `feat/kap-7-foo` -> `kap-7`).
+ * Extract an issue id named in the branch: a Kernel UUID anywhere in the name
+ * (`feat/18f1988e-...-foo`), else a legacy Beads key at the head of the slug
+ * (`feat/kap-7-foo` -> `kap-7`). The caller VERIFIES the id exists before linking,
+ * so a branch that merely looks like an id never binds to a phantom issue.
  *
  * @param {string} branch
  * @returns {string|null}
  */
 function extractEncodedIssueId(branch) {
+  const uuid = ENCODED_UUID.exec(String(branch));
+  if (uuid) return uuid[0];
   const match = ENCODED_ISSUE_ID.exec(stripPrefix(branch));
   return match ? match[1] : null;
 }