hivemind-context-governance 1.3.0

package/src/lib/sentiment.ts

@@ -0,0 +1,183 @@
+/**
+ * Sentiment Detection Module
+ *
+ * Detects negative signals in agent/user communication to trigger
+ * context refresh when drift is detected.
+ *
+ * Signals:
+ *   - Negative keywords: stop, wrong, no, bad, incorrect, confused
+ *   - Agent failure phrases: "I apologize", "you are right", "I was wrong"
+ *   - Cancellation patterns: "cancel", "abort", "start over"
+ */
+
+export interface SentimentSignal {
+  type: "negative_keyword" | "failure_phrase" | "cancellation" | "confusion"
+  matched_text: string
+  timestamp: number
+  turn_number: number
+  source: "user" | "agent"
+}
+
+/**
+ * Negative keywords that indicate problems.
+ *
+ * Short keywords (≤5 chars) use word-boundary regex to prevent false positives
+ * like "no" matching "no issues" or "error" matching "error handling".
+ * Benign phrases are excluded via negative-lookahead.
+ */
+const NEGATIVE_KEYWORD_PATTERNS: Array<{ pattern: RegExp; label: string }> = [
+  { pattern: /\bstop\b(?!\s+(worrying|there))/i, label: "stop" },
+  { pattern: /\bwrong\b/i, label: "wrong" },
+  { pattern: /\bno\b(?!\s+(issues?|errors?|problems?|worries|need|thanks|longer|more))/i, label: "no" },
+  { pattern: /\bbad\b(?!\s+(→|->|to))/i, label: "bad" },
+  { pattern: /\bincorrect\b/i, label: "incorrect" },
+  { pattern: /\bconfused\b/i, label: "confused" },
+  { pattern: /\bconfusion\b/i, label: "confusion" },
+  { pattern: /\bmistake\b/i, label: "mistake" },
+  { pattern: /\berror\b(?!\s+(handling|boundary|boundaries|message|code|type|class|object|page|recovery|log))/i, label: "error" },
+  { pattern: /\bbroken\b/i, label: "broken" },
+  { pattern: /not working/i, label: "not working" },
+  { pattern: /doesn't work/i, label: "doesn't work" },
+  { pattern: /isn't working/i, label: "isn't working" },
+]
+
+/** Agent failure admission phrases */
+const FAILURE_PHRASES = [
+  "i apologize",
+  "you are right",
+  "i was wrong",
+  "my mistake",
+  "i misunderstood",
+  "i made an error",
+  "that was incorrect",
+  "i see the issue now",
+  "you're correct",
+  "i should have",
+]
+
+/** Cancellation/restart patterns */
+const CANCELLATION_PATTERNS = [
+  "cancel",
+  "abort",
+  "start over",
+  "begin again",
+  "scratch that",
+  "forget that",
+  "never mind",
+  "nevermind",
+  "let's restart",
+  "do over",
+]
+
+/** Confusion indicators */
+const CONFUSION_PATTERNS = [
+  "i'm confused",
+  "i am confused",
+  "this is confusing",
+  "doesn't make sense",
+  "not making sense",
+  "unclear",
+  "i don't understand",
+  "i do not understand",
+  "what do you mean",
+  "can you explain",
+]
+
+/**
+ * Detect sentiment signals in text
+ */
+export function detectSentiment(
+  text: string,
+  turnNumber: number,
+  source: "user" | "agent" = "user"
+): SentimentSignal[] {
+  const signals: SentimentSignal[] = []
+  const lowerText = text.toLowerCase()
+  const timestamp = Date.now()
+
+  // Check negative keywords (regex-based with word boundaries)
+  for (const { pattern, label } of NEGATIVE_KEYWORD_PATTERNS) {
+    if (pattern.test(lowerText)) {
+      signals.push({
+        type: "negative_keyword",
+        matched_text: label,
+        timestamp,
+        turn_number: turnNumber,
+        source,
+      })
+    }
+  }
+
+  // Check failure phrases
+  for (const phrase of FAILURE_PHRASES) {
+    if (lowerText.includes(phrase)) {
+      signals.push({
+        type: "failure_phrase",
+        matched_text: phrase,
+        timestamp,
+        turn_number: turnNumber,
+        source,
+      })
+    }
+  }
+
+  // Check cancellation patterns
+  for (const pattern of CANCELLATION_PATTERNS) {
+    if (lowerText.includes(pattern)) {
+      signals.push({
+        type: "cancellation",
+        matched_text: pattern,
+        timestamp,
+        turn_number: turnNumber,
+        source,
+      })
+    }
+  }
+
+  // Check confusion patterns
+  for (const pattern of CONFUSION_PATTERNS) {
+    if (lowerText.includes(pattern)) {
+      signals.push({
+        type: "confusion",
+        matched_text: pattern,
+        timestamp,
+        turn_number: turnNumber,
+        source,
+      })
+    }
+  }
+
+  return signals
+}
+
+/**
+ * Check if text contains any negative sentiment
+ */
+export function hasNegativeSentiment(text: string): boolean {
+  return detectSentiment(text, 0).length > 0
+}
+
+/**
+ * Get sentiment summary for display
+ */
+export function getSentimentSummary(signals: SentimentSignal[]): string {
+  if (signals.length === 0) {
+    return "No negative signals detected"
+  }
+
+  const byType = signals.reduce(
+    (acc, signal) => {
+      acc[signal.type] = (acc[signal.type] || 0) + 1
+      return acc
+    },
+    {} as Record<string, number>
+  )
+
+  const parts: string[] = []
+  if (byType["negative_keyword"]) parts.push(`${byType["negative_keyword"]} negative keywords`)
+  if (byType["failure_phrase"]) parts.push(`${byType["failure_phrase"]} failure admissions`)
+  if (byType["cancellation"]) parts.push(`${byType["cancellation"]} cancellations`)
+  if (byType["confusion"]) parts.push(`${byType["confusion"]} confusion indicators`)
+
+  return parts.join(", ")
+}

package/src/schemas/brain-state.ts

@@ -0,0 +1,257 @@
+/**
+ * Brain State Schema
+ * Core state machine for session governance
+ */
+
+import type { HiveMindConfig, GovernanceMode } from "./config.js";
+import type { HierarchyState } from "./hierarchy.js";
+import type { SentimentSignal } from "../lib/sentiment.js";
+
+export type SessionMode = "plan_driven" | "quick_fix" | "exploration";
+export type GovernanceStatus = "LOCKED" | "OPEN";
+
+export interface SessionState {
+  id: string;
+  mode: SessionMode;
+  governance_mode: GovernanceMode;
+  governance_status: GovernanceStatus;
+  start_time: number;
+  last_activity: number;
+}
+
+export interface SelfRating {
+  score: number; // 1-10
+  reason?: string;
+  turn_context?: string;
+  timestamp: number;
+  turn_number: number;
+}
+
+export interface MetricsState {
+  turn_count: number;
+  drift_score: number;
+  files_touched: string[];
+  context_updates: number;
+  ratings: SelfRating[];
+  auto_health_score: number; // 0-100, calculated from success rate
+  total_tool_calls: number;
+  successful_tool_calls: number;
+}
+
+export interface BrainState {
+  session: SessionState;
+  hierarchy: HierarchyState;
+  metrics: MetricsState;
+  sentiment_signals: SentimentSignal[];
+  complexity_nudge_shown: boolean;
+  version: string;
+}
+
+export const BRAIN_STATE_VERSION = "1.0.0";
+
+export function generateSessionId(): string {
+  const timestamp = Date.now();
+  const random = Math.random().toString(36).substring(2, 8);
+  return `session-${timestamp}-${random}`;
+}
+
+export function createBrainState(
+  sessionId: string,
+  config: HiveMindConfig,
+  mode: SessionMode = "plan_driven"
+): BrainState {
+  const now = Date.now();
+  
+  return {
+    session: {
+      id: sessionId,
+      mode,
+      governance_mode: config.governance_mode,
+      governance_status: config.governance_mode === "strict" ? "LOCKED" : "OPEN",
+      start_time: now,
+      last_activity: now,
+    },
+    hierarchy: {
+      trajectory: "",
+      tactic: "",
+      action: "",
+    },
+    metrics: {
+      turn_count: 0,
+      drift_score: 100,
+      files_touched: [],
+      context_updates: 0,
+      ratings: [],
+      auto_health_score: 100,
+      total_tool_calls: 0,
+      successful_tool_calls: 0,
+    },
+    sentiment_signals: [],
+    complexity_nudge_shown: false,
+    version: BRAIN_STATE_VERSION,
+  };
+}
+
+export function isSessionLocked(state: BrainState): boolean {
+  return state.session.governance_status === "LOCKED";
+}
+
+export function unlockSession(state: BrainState): BrainState {
+  return {
+    ...state,
+    session: {
+      ...state.session,
+      governance_status: "OPEN",
+      last_activity: Date.now(),
+    },
+  };
+}
+
+export function lockSession(state: BrainState): BrainState {
+  return {
+    ...state,
+    session: {
+      ...state.session,
+      governance_status: "LOCKED",
+      last_activity: Date.now(),
+    },
+  };
+}
+
+export function incrementTurnCount(state: BrainState): BrainState {
+  return {
+    ...state,
+    metrics: {
+      ...state.metrics,
+      turn_count: state.metrics.turn_count + 1,
+    },
+    session: {
+      ...state.session,
+      last_activity: Date.now(),
+    },
+  };
+}
+
+export function resetTurnCount(state: BrainState): BrainState {
+  return {
+    ...state,
+    metrics: {
+      ...state.metrics,
+      turn_count: 0,
+      drift_score: Math.min(100, state.metrics.drift_score + 10),
+    },
+    session: {
+      ...state.session,
+      last_activity: Date.now(),
+    },
+  };
+}
+
+export function updateHierarchy(
+  state: BrainState,
+  hierarchy: Partial<HierarchyState>
+): BrainState {
+  return {
+    ...state,
+    hierarchy: { ...state.hierarchy, ...hierarchy },
+    metrics: {
+      ...state.metrics,
+      context_updates: state.metrics.context_updates + 1,
+    },
+    session: {
+      ...state.session,
+      last_activity: Date.now(),
+    },
+  };
+}
+
+export function addFileTouched(state: BrainState, filePath: string): BrainState {
+  if (state.metrics.files_touched.includes(filePath)) {
+    return state;
+  }
+  return {
+    ...state,
+    metrics: {
+      ...state.metrics,
+      files_touched: [...state.metrics.files_touched, filePath],
+    },
+  };
+}
+
+export function calculateDriftScore(state: BrainState): number {
+  const turnsPenalty = Math.min(50, state.metrics.turn_count * 5);
+  const updatesBonus = Math.min(20, state.metrics.context_updates * 2);
+  return Math.max(0, Math.min(100, 100 - turnsPenalty + updatesBonus));
+}
+
+export function shouldTriggerDriftWarning(
+  state: BrainState,
+  maxTurns: number
+): boolean {
+  return state.metrics.turn_count >= maxTurns && state.metrics.drift_score < 50;
+}
+
+export function addSelfRating(
+  state: BrainState,
+  rating: Omit<SelfRating, "timestamp" | "turn_number">
+): BrainState {
+  const newRating: SelfRating = {
+    ...rating,
+    timestamp: Date.now(),
+    turn_number: state.metrics.turn_count,
+  };
+  return {
+    ...state,
+    metrics: {
+      ...state.metrics,
+      ratings: [...state.metrics.ratings, newRating],
+    },
+  };
+}
+
+export function trackToolCall(
+  state: BrainState,
+  success: boolean
+): BrainState {
+  const total = state.metrics.total_tool_calls + 1;
+  const successful = success 
+    ? state.metrics.successful_tool_calls + 1 
+    : state.metrics.successful_tool_calls;
+  const healthScore = total > 0 ? Math.round((successful / total) * 100) : 100;
+  
+  return {
+    ...state,
+    metrics: {
+      ...state.metrics,
+      total_tool_calls: total,
+      successful_tool_calls: successful,
+      auto_health_score: healthScore,
+    },
+  };
+}
+
+export function addSentimentSignals(
+  state: BrainState,
+  signals: SentimentSignal[]
+): BrainState {
+  if (signals.length === 0) return state;
+  
+  return {
+    ...state,
+    sentiment_signals: [...state.sentiment_signals, ...signals],
+  };
+}
+
+export function setComplexityNudgeShown(state: BrainState): BrainState {
+  return {
+    ...state,
+    complexity_nudge_shown: true,
+  };
+}
+
+export function resetComplexityNudge(state: BrainState): BrainState {
+  return {
+    ...state,
+    complexity_nudge_shown: false,
+  };
+}

package/src/schemas/config.ts

@@ -0,0 +1,184 @@
+/**
+ * HiveMind Configuration Schema
+ * Defines governance modes, project settings, and agent behavior constraints
+ */
+
+export type GovernanceMode = "permissive" | "assisted" | "strict";
+export type Language = "en" | "vi";
+export type ExpertLevel = "beginner" | "intermediate" | "advanced" | "expert";
+export type OutputStyle = 
+  | "explanatory"      // Detailed explanations, teaching mode
+  | "outline"          // Bullet points, structured summaries
+  | "skeptical"        // Critical review, challenge assumptions
+  | "architecture"     // Focus on design patterns, structure first
+  | "minimal";         // Brief, code-only responses
+
+export interface AgentBehaviorConfig {
+  /** Language for all responses */
+  language: Language;
+  /** Expertise level - affects depth and assumptions */
+  expert_level: ExpertLevel;
+  /** Output style - affects response format */
+  output_style: OutputStyle;
+  /** Additional behavioral constraints */
+  constraints: {
+    /** Require code review before accepting */
+    require_code_review: boolean;
+    /** Enforce test-driven development */
+    enforce_tdd: boolean;
+    /** Maximum response length in tokens (approximate) */
+    max_response_tokens: number;
+    /** Always explain 'why' not just 'what' */
+    explain_reasoning: boolean;
+    /** Challenge user assumptions */
+    be_skeptical: boolean;
+  };
+}
+
+export interface HiveMindConfig {
+  governance_mode: GovernanceMode;
+  language: Language;
+  max_turns_before_warning: number;
+  max_active_md_lines: number;
+  auto_compact_on_turns: number;
+  /** Agent behavior configuration - injected into every session */
+  agent_behavior: AgentBehaviorConfig;
+}
+
+export const DEFAULT_AGENT_BEHAVIOR: AgentBehaviorConfig = {
+  language: "en",
+  expert_level: "intermediate",
+  output_style: "explanatory",
+  constraints: {
+    require_code_review: false,
+    enforce_tdd: false,
+    max_response_tokens: 2000,
+    explain_reasoning: true,
+    be_skeptical: false,
+  },
+};
+
+export const DEFAULT_CONFIG: HiveMindConfig = {
+  governance_mode: "assisted",
+  language: "en",
+  max_turns_before_warning: 5,
+  max_active_md_lines: 50,
+  auto_compact_on_turns: 20,
+  agent_behavior: DEFAULT_AGENT_BEHAVIOR,
+};
+
+export function createConfig(overrides: Partial<HiveMindConfig> = {}): HiveMindConfig {
+  return {
+    ...DEFAULT_CONFIG,
+    ...overrides,
+    agent_behavior: {
+      ...DEFAULT_AGENT_BEHAVIOR,
+      ...overrides.agent_behavior,
+    },
+  };
+}
+
+export function isValidGovernanceMode(mode: string): mode is GovernanceMode {
+  return ["permissive", "assisted", "strict"].includes(mode);
+}
+
+export function isValidLanguage(lang: string): lang is Language {
+  return ["en", "vi"].includes(lang);
+}
+
+export function isValidExpertLevel(level: string): level is ExpertLevel {
+  return ["beginner", "intermediate", "advanced", "expert"].includes(level);
+}
+
+export function isValidOutputStyle(style: string): style is OutputStyle {
+  return ["explanatory", "outline", "skeptical", "architecture", "minimal"].includes(style);
+}
+
+/**
+ * Generates the mandatory agent configuration prompt that is injected
+ * at every session opening and persists throughout the conversation.
+ */
+export function generateAgentBehaviorPrompt(config: AgentBehaviorConfig): string {
+  const lines: string[] = [];
+  
+  lines.push("<agent-configuration>");
+  lines.push("MANDATORY: You MUST obey these constraints for this entire session:");
+  lines.push("");
+  
+  // Language enforcement
+  const langNames: Record<Language, string> = {
+    en: "English",
+    vi: "Vietnamese (Tiếng Việt)",
+  };
+  lines.push(`[LANGUAGE] Respond ONLY in ${langNames[config.language]}. No exceptions.`);
+  lines.push("");
+  
+  // Expert level
+  const expertDescriptions: Record<ExpertLevel, string> = {
+    beginner: "Explain everything simply. Define terms. No assumptions of prior knowledge.",
+    intermediate: "Standard technical depth. Some domain knowledge assumed.",
+    advanced: "Concise, sophisticated. Assume strong domain expertise.",
+    expert: "Terse, reference advanced concepts. Minimal hand-holding.",
+  };
+  lines.push(`[EXPERT LEVEL] ${config.expert_level.toUpperCase()}: ${expertDescriptions[config.expert_level]}`);
+  lines.push("");
+  
+  // Output style
+  const styleInstructions: Record<OutputStyle, string[]> = {
+    explanatory: [
+      "- Explain WHY, not just WHAT",
+      "- Provide context and rationale",
+      "- Use analogies where helpful",
+      "- Answer follow-up questions proactively",
+    ],
+    outline: [
+      "- Use bullet points and structured lists",
+      "- Headings for organization",
+      "- Summary at the top",
+      "- Details collapsed or abbreviated",
+    ],
+    skeptical: [
+      "- Challenge assumptions in the request",
+      "- Point out risks and edge cases",
+      "- Ask clarifying questions",
+      "- Suggest alternatives",
+      "- Verify requirements are complete",
+    ],
+    architecture: [
+      "- Start with high-level design",
+      "- Discuss patterns and trade-offs",
+      "- Component diagrams before code",
+      "- Implementation follows design",
+    ],
+    minimal: [
+      "- Code only, minimal prose",
+      "- No explanations unless asked",
+      "- Direct answers",
+    ],
+  };
+  lines.push(`[OUTPUT STYLE] ${config.output_style.toUpperCase()}:`);
+  styleInstructions[config.output_style].forEach(instruction => lines.push(instruction));
+  lines.push("");
+  
+  // Constraints
+  lines.push("[CONSTRAINTS]");
+  if (config.constraints.require_code_review) {
+    lines.push("- MUST review code before accepting: check for bugs, smells, tests");
+  }
+  if (config.constraints.enforce_tdd) {
+    lines.push("- TDD REQUIRED: Write failing test first, then implementation");
+  }
+  if (config.constraints.explain_reasoning) {
+    lines.push("- ALWAYS explain your reasoning");
+  }
+  if (config.constraints.be_skeptical) {
+    lines.push("- BE SKEPTICAL: Question requirements, point out gaps");
+  }
+  lines.push(`- Maximum response: ~${config.constraints.max_response_tokens} tokens`);
+  lines.push("");
+  
+  lines.push("VIOLATION: If you cannot obey these constraints, state why explicitly.");
+  lines.push("</agent-configuration>");
+  
+  return lines.join("\n");
+}

package/src/schemas/hierarchy.ts

@@ -0,0 +1,58 @@
+/**
+ * Hierarchy Schema
+ * 3-level context hierarchy: trajectory → tactic → action
+ */
+
+export type HierarchyLevel = "trajectory" | "tactic" | "action";
+export type ContextStatus = "pending" | "active" | "complete" | "blocked";
+
+export interface ContextMap {
+  level: HierarchyLevel;
+  content: string;
+  status: ContextStatus;
+  timestamp: number;
+}
+
+export interface HierarchyState {
+  trajectory: string;
+  tactic: string;
+  action: string;
+}
+
+export function createHierarchyState(
+  trajectory = "",
+  tactic = "",
+  action = ""
+): HierarchyState {
+  return { trajectory, tactic, action };
+}
+
+export function updateHierarchyLevel(
+  state: HierarchyState,
+  level: HierarchyLevel,
+  content: string
+): HierarchyState {
+  return { ...state, [level]: content };
+}
+
+export function validateHierarchyTransition(
+  current: HierarchyLevel | "complete",
+  next: HierarchyLevel
+): boolean {
+  const levels: HierarchyLevel[] = ["trajectory", "tactic", "action"];
+  const currentIndex = levels.indexOf(current as HierarchyLevel);
+  const nextIndex = levels.indexOf(next);
+  
+  // Allow same level or moving down (more specific)
+  // Allow moving up only if current is complete
+  return nextIndex >= currentIndex || current === "complete";
+}
+
+export function getLevelDepth(level: HierarchyLevel): number {
+  const depths: Record<HierarchyLevel, number> = {
+    trajectory: 1,
+    tactic: 2,
+    action: 3,
+  };
+  return depths[level];
+}

package/src/schemas/index.ts

@@ -0,0 +1,7 @@
+/**
+ * Schema barrel exports
+ */
+
+export * from "./config.js";
+export * from "./hierarchy.js";
+export * from "./brain-state.js";