hivemind-context-governance 1.3.0

package/src/lib/complexity.ts

@@ -0,0 +1,96 @@
+/**
+ * Complexity Detection Module
+ *
+ * Detects when sessions get complex based on:
+ *   - Files touched count (unique file paths)
+ *   - Turn count (total tool calls since last declare_intent)
+ *
+ * Configurable thresholds (default: 3 files OR 5 turns)
+ */
+
+import type { BrainState } from "../schemas/brain-state.js";
+
+export interface ComplexityThreshold {
+  maxFiles: number;
+  maxTurns: number;
+}
+
+export interface ComplexityCheckResult {
+  isComplex: boolean;
+  filesCount: number;
+  turnsCount: number;
+  threshold: ComplexityThreshold;
+  message: string;
+}
+
+/** Default complexity threshold */
+export const DEFAULT_COMPLEXITY_THRESHOLD: ComplexityThreshold = {
+  maxFiles: 3,
+  maxTurns: 5,
+};
+
+/**
+ * Check if current session complexity exceeds thresholds
+ */
+export function checkComplexity(
+  state: BrainState,
+  threshold: ComplexityThreshold = DEFAULT_COMPLEXITY_THRESHOLD
+): ComplexityCheckResult {
+  const filesCount = state.metrics.files_touched.length;
+  const turnsCount = state.metrics.turn_count;
+  
+  const filesExceeded = filesCount >= threshold.maxFiles;
+  const turnsExceeded = turnsCount >= threshold.maxTurns;
+  const isComplex = filesExceeded || turnsExceeded;
+  
+  let message = "Complexity normal";
+  if (isComplex) {
+    const reasons: string[] = [];
+    if (filesExceeded) reasons.push(`${filesCount} files touched`);
+    if (turnsExceeded) reasons.push(`${turnsCount} turns`);
+    message = `Complexity rising (${reasons.join(", ")}). Consider declare_intent.`;
+  }
+  
+  return {
+    isComplex,
+    filesCount,
+    turnsCount,
+    threshold,
+    message,
+  };
+}
+
+/**
+ * Check if nudge should be shown (only once per session)
+ */
+export function shouldShowComplexityNudge(
+  state: BrainState,
+  nudgeShown: boolean
+): boolean {
+  if (nudgeShown) return false;
+  
+  const check = checkComplexity(state);
+  return check.isComplex;
+}
+
+/**
+ * Format complexity for display
+ */
+export function formatComplexity(state: BrainState): string {
+  const check = checkComplexity(state);
+  return `${check.filesCount} files, ${check.turnsCount} turns`;
+}
+
+/**
+ * Get complexity percentage (0-100)
+ * Based on how close to thresholds
+ */
+export function getComplexityPercentage(
+  state: BrainState,
+  threshold: ComplexityThreshold = DEFAULT_COMPLEXITY_THRESHOLD
+): number {
+  const filesRatio = state.metrics.files_touched.length / threshold.maxFiles;
+  const turnsRatio = state.metrics.turn_count / threshold.maxTurns;
+  const maxRatio = Math.max(filesRatio, turnsRatio);
+  return Math.min(100, Math.round(maxRatio * 100));
+}

package/src/lib/context-refresh.ts

@@ -0,0 +1,107 @@
+/**
+ * Context Refresh Trigger Module
+ *
+ * Triggers context refresh recommendations when negative sentiment
+ * signals exceed thresholds.
+ *
+ * Threshold: 2 negative signals within 5 turns triggers refresh warning
+ */
+
+import type { BrainState } from "../schemas/brain-state.js";
+import type { SentimentSignal } from "./sentiment.js";
+
+export interface RefreshTriggerResult {
+  shouldRefresh: boolean;
+  signalCount: number;
+  windowSize: number;
+  message: string;
+}
+
+/** Default threshold configuration */
+export const DEFAULT_REFRESH_THRESHOLD = {
+  signalCount: 2,
+  windowSize: 5, // turns
+};
+
+/**
+ * Check if context refresh should be triggered
+ * Based on signal count within recent turn window
+ */
+export function checkRefreshTrigger(
+  state: BrainState,
+  threshold = DEFAULT_REFRESH_THRESHOLD
+): RefreshTriggerResult {
+  const currentTurn = state.metrics.turn_count;
+  const windowStart = Math.max(0, currentTurn - threshold.windowSize);
+  
+  // Count signals within the window
+  const recentSignals = state.sentiment_signals.filter(
+    (signal) => signal.turn_number >= windowStart && signal.turn_number <= currentTurn
+  );
+  
+  const shouldRefresh = recentSignals.length >= threshold.signalCount;
+  
+  return {
+    shouldRefresh,
+    signalCount: recentSignals.length,
+    windowSize: threshold.windowSize,
+    message: shouldRefresh
+      ? `[ContextRefresh] Drift detected (${recentSignals.length} negative signals in last ${threshold.windowSize} turns). Consider compact_session.`
+      : `Context stable (${recentSignals.length} signals in last ${threshold.windowSize} turns)`,
+  };
+}
+
+/**
+ * Get recent signals for display
+ */
+export function getRecentSignals(
+  state: BrainState,
+  windowSize: number = 5
+): SentimentSignal[] {
+  const currentTurn = state.metrics.turn_count;
+  const windowStart = Math.max(0, currentTurn - windowSize);
+  
+  return state.sentiment_signals.filter(
+    (signal) => signal.turn_number >= windowStart && signal.turn_number <= currentTurn
+  );
+}
+
+/**
+ * Format signals for logging
+ */
+export function formatSignalsForLog(signals: SentimentSignal[]): string {
+  if (signals.length === 0) return "No recent signals";
+  
+  return signals
+    .map((s) => `[Turn ${s.turn_number}] ${s.type}: "${s.matched_text}"`)
+    .join("\n  ");
+}
+
+/**
+ * Check if drift warning should be added to active.md
+ */
+export function shouldAddDriftWarning(state: BrainState): boolean {
+  const result = checkRefreshTrigger(state);
+  return result.shouldRefresh;
+}
+
+/**
+ * Generate drift warning content for active.md
+ */
+export function generateDriftWarning(state: BrainState): string {
+  const recentSignals = getRecentSignals(state);
+  
+  return [
+    "",
+    "## ⚠️ Drift Warning",
+    "",
+    `**Detected**: ${recentSignals.length} negative signals in recent turns`,
+    "",
+    "**Recommendation**: Consider using `compact_session` to reset context,",
+    "or `map_context` to refocus on current objectives.",
+    "",
+    "**Recent Signals**:",
+    ...recentSignals.map((s) => `- Turn ${s.turn_number}: ${s.type} (${s.matched_text})`),
+    "",
+  ].join("\n");
+}

package/src/lib/index.ts

@@ -0,0 +1,10 @@
+/**
+ * Lib barrel exports
+ */
+
+export * from "./logging.js";
+export * from "./persistence.js";
+export * from "./planning-fs.js";
+export * from "./sentiment.js";
+export * from "./context-refresh.js";
+export * from "./complexity.js";

package/src/lib/logging.ts

@@ -0,0 +1,53 @@
+/**
+ * TUI-safe logging
+ * File-based logging only - never use console.log
+ */
+
+import { appendFile, mkdir } from "fs/promises";
+import { dirname } from "path";
+
+export interface Logger {
+  debug: (message: string) => Promise<void>;
+  info: (message: string) => Promise<void>;
+  warn: (message: string) => Promise<void>;
+  error: (message: string) => Promise<void>;
+}
+
+export async function createLogger(
+  logDir: string,
+  service: string
+): Promise<Logger> {
+  const logFile = `${logDir}/${service}.log`;
+  
+  // Ensure log directory exists
+  try {
+    await mkdir(dirname(logFile), { recursive: true });
+  } catch {
+    // Directory may already exist
+  }
+  
+  async function log(level: string, message: string): Promise<void> {
+    const timestamp = new Date().toISOString();
+    const line = `[${timestamp}] [${level.toUpperCase()}] ${message}\n`;
+    try {
+      await appendFile(logFile, line);
+    } catch {
+      // Fail silently - logging should never break the application
+    }
+  }
+  
+  return {
+    debug: (msg) => log("debug", msg),
+    info: (msg) => log("info", msg),
+    warn: (msg) => log("warn", msg),
+    error: (msg) => log("error", msg),
+  };
+}
+
+// No-op logger for when logging is disabled
+export const noopLogger: Logger = {
+  debug: async () => {},
+  info: async () => {},
+  warn: async () => {},
+  error: async () => {},
+};

package/src/lib/persistence.ts

@@ -0,0 +1,83 @@
+/**
+ * StateManager - Disk persistence for brain state
+ */
+
+import { readFile, writeFile, mkdir } from "fs/promises";
+import { existsSync } from "fs";
+import { dirname, join } from "path";
+import type { BrainState } from "../schemas/brain-state.js";
+import type { HiveMindConfig } from "../schemas/config.js";
+import { createBrainState } from "../schemas/brain-state.js";
+import { createConfig } from "../schemas/config.js";
+
+export interface StateManager {
+  load(): Promise<BrainState | null>;
+  save(state: BrainState): Promise<void>;
+  initialize(sessionId: string, config: HiveMindConfig): Promise<BrainState>;
+  exists(): boolean;
+}
+
+export function createStateManager(projectRoot: string): StateManager {
+  const brainPath = join(projectRoot, ".opencode", "planning", "brain.json");
+  
+  return {
+    async load(): Promise<BrainState | null> {
+      try {
+        if (!existsSync(brainPath)) {
+          return null;
+        }
+        const data = await readFile(brainPath, "utf-8");
+        return JSON.parse(data) as BrainState;
+      } catch {
+        return null;
+      }
+    },
+    
+    async save(state: BrainState): Promise<void> {
+      try {
+        await mkdir(dirname(brainPath), { recursive: true });
+        await writeFile(brainPath, JSON.stringify(state, null, 2));
+      } catch (error) {
+        throw new Error(`Failed to save brain state: ${error}`);
+      }
+    },
+    
+    async initialize(
+      sessionId: string,
+      config: HiveMindConfig
+    ): Promise<BrainState> {
+      const state = createBrainState(sessionId, config);
+      await this.save(state);
+      return state;
+    },
+    
+    exists(): boolean {
+      return existsSync(brainPath);
+    },
+  };
+}
+
+export async function loadConfig(projectRoot: string): Promise<HiveMindConfig> {
+  const configPath = join(projectRoot, ".opencode", "planning", "config.json");
+  
+  try {
+    if (existsSync(configPath)) {
+      const data = await readFile(configPath, "utf-8");
+      const parsed = JSON.parse(data);
+      return createConfig(parsed);
+    }
+  } catch {
+    // Fall through to default
+  }
+  
+  return createConfig();
+}
+
+export async function saveConfig(
+  projectRoot: string,
+  config: HiveMindConfig
+): Promise<void> {
+  const configPath = join(projectRoot, ".opencode", "planning", "config.json");
+  await mkdir(dirname(configPath), { recursive: true });
+  await writeFile(configPath, JSON.stringify(config, null, 2));
+}

package/src/lib/planning-fs.ts

@@ -0,0 +1,187 @@
+/**
+ * Planning File System
+ * Manages .opencode/planning/ directory structure
+ */
+
+import { readFile, writeFile, mkdir, readdir } from "fs/promises";
+import { existsSync } from "fs";
+import { join } from "path";
+import { parse, stringify } from "yaml";
+
+export interface PlanningPaths {
+  projectRoot: string;
+  planningDir: string;
+  indexPath: string;
+  activePath: string;
+  archiveDir: string;
+  brainPath: string;
+}
+
+export function getPlanningPaths(projectRoot: string): PlanningPaths {
+  const planningDir = join(projectRoot, ".opencode", "planning");
+  return {
+    projectRoot,
+    planningDir,
+    indexPath: join(planningDir, "index.md"),
+    activePath: join(planningDir, "active.md"),
+    archiveDir: join(planningDir, "archive"),
+    brainPath: join(planningDir, "brain.json"),
+  };
+}
+
+export interface ActiveMdContent {
+  frontmatter: {
+    session_id?: string;
+    mode?: string;
+    governance_status?: string;
+    start_time?: number;
+    last_updated?: number;
+  };
+  body: string;
+}
+
+export async function initializePlanningDirectory(
+  projectRoot: string
+): Promise<PlanningPaths> {
+  const paths = getPlanningPaths(projectRoot);
+  
+  // Create directories
+  await mkdir(paths.planningDir, { recursive: true });
+  await mkdir(paths.archiveDir, { recursive: true });
+  
+  // Create index.md if not exists
+  if (!existsSync(paths.indexPath)) {
+    await writeFile(paths.indexPath, generateIndexTemplate());
+  }
+  
+  // Create active.md if not exists
+  if (!existsSync(paths.activePath)) {
+    await writeFile(paths.activePath, generateActiveTemplate());
+  }
+  
+  return paths;
+}
+
+export async function readActiveMd(
+  projectRoot: string
+): Promise<ActiveMdContent> {
+  const paths = getPlanningPaths(projectRoot);
+  
+  try {
+    const content = await readFile(paths.activePath, "utf-8");
+    return parseActiveMd(content);
+  } catch {
+    return { frontmatter: {}, body: "" };
+  }
+}
+
+export function parseActiveMd(content: string): ActiveMdContent {
+  const yamlMatch = content.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
+  
+  if (yamlMatch) {
+    try {
+      const frontmatter = parse(yamlMatch[1]) || {};
+      const body = yamlMatch[2].trim();
+      return { frontmatter, body };
+    } catch {
+      // Fall through to default
+    }
+  }
+  
+  return { frontmatter: {}, body: content.trim() };
+}
+
+export async function writeActiveMd(
+  projectRoot: string,
+  content: ActiveMdContent
+): Promise<void> {
+  const paths = getPlanningPaths(projectRoot);
+  const yamlContent = stringify(content.frontmatter);
+  const fullContent = `---\n${yamlContent}---\n\n${content.body}`;
+  await writeFile(paths.activePath, fullContent);
+}
+
+export async function archiveSession(
+  projectRoot: string,
+  sessionId: string,
+  content: string
+): Promise<void> {
+  const paths = getPlanningPaths(projectRoot);
+  const timestamp = new Date().toISOString().split("T")[0];
+  const archiveFile = join(paths.archiveDir, `session_${timestamp}_${sessionId}.md`);
+  await writeFile(archiveFile, content);
+}
+
+export async function updateIndexMd(
+  projectRoot: string,
+  summaryLine: string
+): Promise<void> {
+  const paths = getPlanningPaths(projectRoot);
+  
+  try {
+    const content = await readFile(paths.indexPath, "utf-8");
+    const timestamp = new Date().toISOString().split("T")[0];
+    const entry = `- ${timestamp}: ${summaryLine}\n`;
+    const updated = content + entry;
+    await writeFile(paths.indexPath, updated);
+  } catch {
+    // If index doesn't exist, create it
+    await writeFile(paths.indexPath, generateIndexTemplate() + summaryLine + "\n");
+  }
+}
+
+export async function listArchives(projectRoot: string): Promise<string[]> {
+  const paths = getPlanningPaths(projectRoot);
+  
+  try {
+    const files = await readdir(paths.archiveDir);
+    return files.filter((f) => f.endsWith(".md")).sort();
+  } catch {
+    return [];
+  }
+}
+
+export function generateIndexTemplate(): string {
+  return `# Project Trajectory
+
+## Goals
+<!-- High-level goals only -->
+- 
+
+## Constraints
+<!-- Project-wide constraints -->
+- 
+
+## Session History
+<!-- Auto-updated by compact_session -->
+`;
+}
+
+export function generateActiveTemplate(): string {
+  return `---
+session_id: ""
+mode: ""
+governance_status: "LOCKED"
+start_time: 0
+last_updated: 0
+---
+
+# Active Session
+
+## Current Focus
+<!-- Updated via map_context -->
+
+## Completed
+<!-- Items marked [x] get archived -->
+
+## Notes
+<!-- Scratchpad - anything goes -->
+`;
+}
+
+export async function resetActiveMd(projectRoot: string): Promise<void> {
+  await writeFile(
+    getPlanningPaths(projectRoot).activePath,
+    generateActiveTemplate()
+  );
+}