hivemind-context-governance 1.3.0

package/src/tools/compact-session.ts

@@ -0,0 +1,97 @@
+/**
+ * compact_session — Archive completed work and reset for next session.
+ *
+ * Agent Thought: "I'm done, archive this session"
+ *
+ * Design: Agent-Native lifecycle verb.
+ *   1. Iceberg — 0-1 args, system handles archive + reset + index update
+ *   2. Context Inference — reads active session from brain state
+ *   3. Signal-to-Noise — 1-line summary output
+ *   4. No-Shadowing — description matches agent intent
+ *   5. Native Parallelism — single call, atomic archival
+ */
+
+import { tool, type ToolDefinition } from "@opencode-ai/plugin/tool"
+import { createStateManager, loadConfig } from "../lib/persistence.js"
+import {
+  createBrainState,
+  generateSessionId,
+  lockSession,
+} from "../schemas/brain-state.js"
+import {
+  readActiveMd,
+  archiveSession,
+  updateIndexMd,
+  resetActiveMd,
+  listArchives,
+} from "../lib/planning-fs.js"
+
+export function createCompactSessionTool(directory: string): ToolDefinition {
+  return tool({
+    description:
+      "Archive completed work and reset for next session. " +
+      "Call this when you're done with your current work.",
+    args: {
+      summary: tool.schema
+        .string()
+        .optional()
+        .describe("Optional 1-line summary of what was accomplished"),
+    },
+    async execute(args) {
+      const stateManager = createStateManager(directory)
+      const config = await loadConfig(directory)
+
+      // Load brain state
+      const state = await stateManager.load()
+      if (!state) {
+        return "ERROR: No active session to compact."
+      }
+
+      // Read current active.md content for archival
+      const activeMd = await readActiveMd(directory)
+      const archiveContent = [
+        `# Archived Session: ${state.session.id}`,
+        "",
+        `**Mode**: ${state.session.mode}`,
+        `**Started**: ${new Date(state.session.start_time).toISOString()}`,
+        `**Archived**: ${new Date().toISOString()}`,
+        `**Turns**: ${state.metrics.turn_count}`,
+        `**Drift Score**: ${state.metrics.drift_score}/100`,
+        `**Files Touched**: ${state.metrics.files_touched.length}`,
+        `**Context Updates**: ${state.metrics.context_updates}`,
+        "",
+        "## Hierarchy at Archive",
+        state.hierarchy.trajectory ? `- **Trajectory**: ${state.hierarchy.trajectory}` : "",
+        state.hierarchy.tactic ? `- **Tactic**: ${state.hierarchy.tactic}` : "",
+        state.hierarchy.action ? `- **Action**: ${state.hierarchy.action}` : "",
+        "",
+        "## Session Content",
+        activeMd.body,
+      ]
+        .filter(Boolean)
+        .join("\n")
+
+      // Archive the session
+      await archiveSession(directory, state.session.id, archiveContent)
+
+      // Update index.md with summary
+      const summaryLine =
+        args.summary ||
+        `Session ${state.session.id}: ${state.metrics.turn_count} turns, ${state.metrics.files_touched.length} files`
+      await updateIndexMd(directory, summaryLine)
+
+      // Reset active.md to template
+      await resetActiveMd(directory)
+
+      // Create fresh brain state (new session, locked)
+      const newSessionId = generateSessionId()
+      const newState = createBrainState(newSessionId, config)
+      await stateManager.save(lockSession(newState))
+
+      // Count archives for output
+      const archives = await listArchives(directory)
+
+      return `Archived. ${state.metrics.turn_count} turns, ${state.metrics.files_touched.length} files saved. ${archives.length} total archives. Session reset.`
+    },
+  })
+}

package/src/tools/declare-intent.ts

@@ -0,0 +1,104 @@
+/**
+ * declare_intent — Unlock session by declaring work mode and focus.
+ *
+ * Agent Thought: "I want to start working on something"
+ *
+ * Design: Agent-Native lifecycle verb.
+ *   1. Iceberg — 2 args, system handles state machine + file writes
+ *   2. Context Inference — session ID from context, governance mode from config
+ *   3. Signal-to-Noise — 1-line output
+ *   4. No-Shadowing — description matches agent intent
+ *   5. Native Parallelism — idempotent, safe to call repeatedly
+ */
+
+import { tool, type ToolDefinition } from "@opencode-ai/plugin/tool"
+import { createStateManager, loadConfig } from "../lib/persistence.js"
+import {
+  createBrainState,
+  generateSessionId,
+  unlockSession,
+  resetComplexityNudge,
+} from "../schemas/brain-state.js"
+import type { SessionMode } from "../schemas/brain-state.js"
+import {
+  writeActiveMd,
+  readActiveMd,
+  initializePlanningDirectory,
+} from "../lib/planning-fs.js"
+
+const VALID_MODES: SessionMode[] = ["plan_driven", "quick_fix", "exploration"]
+
+export function createDeclareIntentTool(directory: string): ToolDefinition {
+  return tool({
+    description:
+      "Unlock the session by declaring your work mode and focus. " +
+      "Call this before doing any work to set your intent.",
+    args: {
+      mode: tool.schema
+        .enum(VALID_MODES)
+        .describe("How are you approaching this work? plan_driven | quick_fix | exploration"),
+      focus: tool.schema
+        .string()
+        .describe("What are you working on? (1 sentence)"),
+      reason: tool.schema
+        .string()
+        .optional()
+        .describe("Why this mode? (optional context)"),
+    },
+    async execute(args) {
+      const config = await loadConfig(directory)
+      const stateManager = createStateManager(directory)
+
+      // Ensure planning directory exists
+      await initializePlanningDirectory(directory)
+
+      // Load or create brain state
+      let state = await stateManager.load()
+      if (!state) {
+        const sessionId = generateSessionId()
+        state = createBrainState(sessionId, config, args.mode)
+      }
+
+      // Unlock session
+      state = unlockSession(state)
+      state.session.mode = args.mode
+      state.hierarchy.trajectory = args.focus
+
+      // Reset complexity nudge on new intent declaration
+      state = resetComplexityNudge(state)
+
+      // Save state
+      await stateManager.save(state)
+
+      // Update active.md with session info
+      const activeMd = await readActiveMd(directory)
+      activeMd.frontmatter = {
+        session_id: state.session.id,
+        mode: args.mode,
+        governance_status: "OPEN",
+        start_time: state.session.start_time,
+        last_updated: Date.now(),
+      }
+      activeMd.body = [
+        "# Active Session",
+        "",
+        "## Current Focus",
+        `**Mode**: ${args.mode}`,
+        `**Focus**: ${args.focus}`,
+        args.reason ? `**Reason**: ${args.reason}` : "",
+        "",
+        "## Completed",
+        "<!-- Items marked [x] get archived -->",
+        "",
+        "## Notes",
+        "<!-- Scratchpad - anything goes -->",
+      ]
+        .filter(Boolean)
+        .join("\n")
+
+      await writeActiveMd(directory, activeMd)
+
+      return `Session: "${args.focus}". Mode: ${args.mode}. Status: OPEN.`
+    },
+  })
+}

package/src/tools/index.ts

@@ -0,0 +1,14 @@
+/**
+ * Tool barrel exports — HiveMind lifecycle verbs
+ *
+ * 4 tools total:
+ *   declare_intent  — unlock session, set mode/focus
+ *   map_context     — update hierarchy level
+ *   compact_session — archive + reset
+ *   self_rate       — agent self-assessment
+ */
+
+export { createDeclareIntentTool } from "./declare-intent.js"
+export { createMapContextTool } from "./map-context.js"
+export { createCompactSessionTool } from "./compact-session.js"
+export { createSelfRateTool } from "./self-rate.js"

package/src/tools/map-context.ts

@@ -0,0 +1,105 @@
+/**
+ * map_context — Update focus in the 3-level hierarchy.
+ *
+ * Agent Thought: "I need to update what I'm focused on"
+ *
+ * Design: Agent-Native lifecycle verb.
+ *   1. Iceberg — 2 args, system handles hierarchy state + file sync
+ *   2. Context Inference — reads current hierarchy from brain state
+ *   3. Signal-to-Noise — 1-line output with visual beacon
+ *   4. No-Shadowing — description matches agent intent
+ *   5. Native Parallelism — can update different levels independently
+ */
+
+import { tool, type ToolDefinition } from "@opencode-ai/plugin/tool"
+import { createStateManager } from "../lib/persistence.js"
+import {
+  resetTurnCount,
+  updateHierarchy,
+} from "../schemas/brain-state.js"
+import type { HierarchyLevel, ContextStatus } from "../schemas/hierarchy.js"
+import {
+  readActiveMd,
+  writeActiveMd,
+  updateIndexMd,
+} from "../lib/planning-fs.js"
+
+const VALID_LEVELS: HierarchyLevel[] = ["trajectory", "tactic", "action"]
+const VALID_STATUSES: ContextStatus[] = ["pending", "active", "complete", "blocked"]
+
+export function createMapContextTool(directory: string): ToolDefinition {
+  return tool({
+    description:
+      "Update your current focus in the 3-level hierarchy. " +
+      "Call this when changing what you're working on.",
+    args: {
+      level: tool.schema
+        .enum(VALID_LEVELS)
+        .describe("Which level to update: trajectory | tactic | action"),
+      content: tool.schema
+        .string()
+        .describe("The new focus (1-2 sentences)"),
+      status: tool.schema
+        .enum(VALID_STATUSES)
+        .optional()
+        .describe("Status of this context item (default: active)"),
+    },
+    async execute(args) {
+      const stateManager = createStateManager(directory)
+      const status = args.status ?? "active"
+
+      // Load brain state
+      let state = await stateManager.load()
+      if (!state) {
+        return "ERROR: No active session. Call declare_intent first."
+      }
+
+      // Update hierarchy
+      state = updateHierarchy(state, { [args.level]: args.content })
+
+      // Reset turn count on context update (re-engagement signal)
+      state = resetTurnCount(state)
+
+      // Save state
+      await stateManager.save(state)
+
+      // Sync to planning files
+      if (args.level === "trajectory") {
+        // Update index.md for trajectory-level changes
+        await updateIndexMd(directory, `[${status.toUpperCase()}] ${args.content}`)
+      } else {
+        // Update active.md for tactic/action level changes
+        const activeMd = await readActiveMd(directory)
+        const levelLabel = args.level === "tactic" ? "Tactic" : "Action"
+        const focusLine = `**${levelLabel}**: ${args.content} [${status.toUpperCase()}]`
+
+        // Append to current focus section
+        if (activeMd.body.includes("## Current Focus")) {
+          const parts = activeMd.body.split("## Current Focus")
+          const afterFocus = parts[1] || ""
+          const nextSection = afterFocus.indexOf("\n## ")
+          const focusContent =
+            nextSection > -1 ? afterFocus.substring(0, nextSection) : afterFocus
+          const rest =
+            nextSection > -1 ? afterFocus.substring(nextSection) : ""
+
+          activeMd.body =
+            parts[0] +
+            "## Current Focus" +
+            focusContent.trimEnd() +
+            "\n" +
+            focusLine +
+            "\n" +
+            rest
+        } else {
+          activeMd.body += `\n## Current Focus\n${focusLine}\n`
+        }
+
+        activeMd.frontmatter.last_updated = Date.now()
+        await writeActiveMd(directory, activeMd)
+      }
+
+      return `[${args.level}] "${args.content}" → ${status}`
+    },
+  })
+}

package/src/tools/self-rate.ts

@@ -0,0 +1,86 @@
+/**
+ * self_rate — Agent self-assessment tool for drift detection.
+ *
+ * Agent Thought: "How well am I doing? Let me rate my performance."
+ *
+ * Design: Agent-Native lifecycle verb.
+ *   1. Iceberg — 1-3 args, system handles storage
+ *   2. Context Inference — turn number from state
+ *   3. Signal-to-Noise — 1-line output
+ *   4. No-Shadowing — description matches agent intent
+ *   5. Native Parallelism — safe to call multiple times
+ */
+
+import { tool, type ToolDefinition } from "@opencode-ai/plugin/tool"
+import { createStateManager } from "../lib/persistence.js"
+import { addSelfRating } from "../schemas/brain-state.js"
+import { createLogger } from "../lib/logging.js"
+import { join } from "node:path"
+
+export function createSelfRateTool(directory: string): ToolDefinition {
+  return tool({
+    description:
+      "Rate your own performance on the current task. " +
+      "Call this periodically to help detect drift and track progress.",
+    args: {
+      score: tool.schema
+        .number()
+        .min(1)
+        .max(10)
+        .describe("Your self-assessment score from 1-10 (10 = excellent)"),
+      reason: tool.schema
+        .string()
+        .optional()
+        .describe("Why you gave this score (optional)"),
+      turn_context: tool.schema
+        .string()
+        .optional()
+        .describe("What you're working on right now (optional)"),
+    },
+    async execute(args) {
+      const stateManager = createStateManager(directory)
+      const log = await createLogger(
+        join(directory, ".opencode", "planning", "logs"),
+        "self-rate"
+      )
+
+      // Load current state
+      let state = await stateManager.load()
+      if (!state) {
+        return "ERROR: No active session. Call declare_intent first."
+      }
+
+      // Add the rating
+      state = addSelfRating(state, {
+        score: args.score,
+        reason: args.reason,
+        turn_context: args.turn_context,
+      })
+
+      // Save state
+      await stateManager.save(state)
+
+      // Log to TUI
+      const turnNumber = state.metrics.turn_count
+      const logMessage = `[SelfRate] Turn ${turnNumber}: ${args.score}/10`
+      await log.info(logMessage)
+
+      // Build response
+      let response = `Rating recorded: ${args.score}/10 at turn ${turnNumber}`
+      if (args.reason) {
+        response += ` — "${args.reason}"`
+      }
+
+      // Provide feedback based on score
+      if (args.score <= 3) {
+        response += "\n⚠️ Low score detected. Consider using compact_session to reset context."
+      } else if (args.score <= 7) {
+        response += "\n💡 Score suggests some drift. Consider map_context to refocus."
+      } else {
+        response += "\n✅ Good progress!"
+      }
+
+      return response
+    },
+  })
+}