hivemind-context-governance 1.3.0

package/dist/tools/declare-intent.js

@@ -0,0 +1,83 @@
+/**
+ * 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 } from "@opencode-ai/plugin/tool";
+import { createStateManager, loadConfig } from "../lib/persistence.js";
+import { createBrainState, generateSessionId, unlockSession, resetComplexityNudge, } from "../schemas/brain-state.js";
+import { writeActiveMd, readActiveMd, initializePlanningDirectory, } from "../lib/planning-fs.js";
+const VALID_MODES = ["plan_driven", "quick_fix", "exploration"];
+export function createDeclareIntentTool(directory) {
+    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.`;
+        },
+    });
+}
+//# sourceMappingURL=declare-intent.js.map

package/dist/tools/declare-intent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"declare-intent.js","sourceRoot":"","sources":["../../src/tools/declare-intent.ts"],"names":[],"mappings":"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"}

package/dist/tools/index.d.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";
+//# sourceMappingURL=index.d.ts.map

package/dist/tools/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,uBAAuB,EAAE,MAAM,qBAAqB,CAAA;AAC7D,OAAO,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAA;AACvD,OAAO,EAAE,wBAAwB,EAAE,MAAM,sBAAsB,CAAA;AAC/D,OAAO,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAA"}

package/dist/tools/index.js

@@ -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";
+//# sourceMappingURL=index.js.map

package/dist/tools/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,uBAAuB,EAAE,MAAM,qBAAqB,CAAA;AAC7D,OAAO,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAA;AACvD,OAAO,EAAE,wBAAwB,EAAE,MAAM,sBAAsB,CAAA;AAC/D,OAAO,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAA"}

package/dist/tools/map-context.d.ts

@@ -0,0 +1,15 @@
+/**
+ * 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 { type ToolDefinition } from "@opencode-ai/plugin/tool";
+export declare function createMapContextTool(directory: string): ToolDefinition;
+//# sourceMappingURL=map-context.d.ts.map

package/dist/tools/map-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"map-context.d.ts","sourceRoot":"","sources":["../../src/tools/map-context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAQ,KAAK,cAAc,EAAE,MAAM,0BAA0B,CAAA;AAgBpE,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,MAAM,GAAG,cAAc,CA2EtE"}

package/dist/tools/map-context.js

@@ -0,0 +1,85 @@
+/**
+ * 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 } from "@opencode-ai/plugin/tool";
+import { createStateManager } from "../lib/persistence.js";
+import { resetTurnCount, updateHierarchy, } from "../schemas/brain-state.js";
+import { readActiveMd, writeActiveMd, updateIndexMd, } from "../lib/planning-fs.js";
+const VALID_LEVELS = ["trajectory", "tactic", "action"];
+const VALID_STATUSES = ["pending", "active", "complete", "blocked"];
+export function createMapContextTool(directory) {
+    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}`;
+        },
+    });
+}
+//# sourceMappingURL=map-context.js.map

package/dist/tools/map-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"map-context.js","sourceRoot":"","sources":["../../src/tools/map-context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,IAAI,EAAuB,MAAM,0BAA0B,CAAA;AACpE,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAA;AAC1D,OAAO,EACL,cAAc,EACd,eAAe,GAChB,MAAM,2BAA2B,CAAA;AAElC,OAAO,EACL,YAAY,EACZ,aAAa,EACb,aAAa,GACd,MAAM,uBAAuB,CAAA;AAE9B,MAAM,YAAY,GAAqB,CAAC,YAAY,EAAE,QAAQ,EAAE,QAAQ,CAAC,CAAA;AACzE,MAAM,cAAc,GAAoB,CAAC,SAAS,EAAE,QAAQ,EAAE,UAAU,EAAE,SAAS,CAAC,CAAA;AAEpF,MAAM,UAAU,oBAAoB,CAAC,SAAiB;IACpD,OAAO,IAAI,CAAC;QACV,WAAW,EACT,sDAAsD;YACtD,iDAAiD;QACnD,IAAI,EAAE;YACJ,KAAK,EAAE,IAAI,CAAC,MAAM;iBACf,IAAI,CAAC,YAAY,CAAC;iBAClB,QAAQ,CAAC,qDAAqD,CAAC;YAClE,OAAO,EAAE,IAAI,CAAC,MAAM;iBACjB,MAAM,EAAE;iBACR,QAAQ,CAAC,+BAA+B,CAAC;YAC5C,MAAM,EAAE,IAAI,CAAC,MAAM;iBAChB,IAAI,CAAC,cAAc,CAAC;iBACpB,QAAQ,EAAE;iBACV,QAAQ,CAAC,+CAA+C,CAAC;SAC7D;QACD,KAAK,CAAC,OAAO,CAAC,IAAI;YAChB,MAAM,YAAY,GAAG,kBAAkB,CAAC,SAAS,CAAC,CAAA;YAClD,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,IAAI,QAAQ,CAAA;YAEtC,mBAAmB;YACnB,IAAI,KAAK,GAAG,MAAM,YAAY,CAAC,IAAI,EAAE,CAAA;YACrC,IAAI,CAAC,KAAK,EAAE,CAAC;gBACX,OAAO,sDAAsD,CAAA;YAC/D,CAAC;YAED,mBAAmB;YACnB,KAAK,GAAG,eAAe,CAAC,KAAK,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC,CAAA;YAE9D,4DAA4D;YAC5D,KAAK,GAAG,cAAc,CAAC,KAAK,CAAC,CAAA;YAE7B,aAAa;YACb,MAAM,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;YAE9B,yBAAyB;YACzB,IAAI,IAAI,CAAC,KAAK,KAAK,YAAY,EAAE,CAAC;gBAChC,+CAA+C;gBAC/C,MAAM,aAAa,CAAC,SAAS,EAAE,IAAI,MAAM,CAAC,WAAW,EAAE,KAAK,IAAI,CAAC,OAAO,EAAE,CAAC,CAAA;YAC7E,CAAC;iBAAM,CAAC;gBACN,mDAAmD;gBACnD,MAAM,QAAQ,GAAG,MAAM,YAAY,CAAC,SAAS,CAAC,CAAA;gBAC9C,MAAM,UAAU,GAAG,IAAI,CAAC,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAA;gBAChE,MAAM,SAAS,GAAG,KAAK,UAAU,OAAO,IAAI,CAAC,OAAO,KAAK,MAAM,CAAC,WAAW,EAAE,GAAG,CAAA;gBAEhF,kCAAkC;gBAClC,IAAI,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC,kBAAkB,CAAC,EAAE,CAAC;oBAC/C,MAAM,KAAK,GAAG,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,kBAAkB,CAAC,CAAA;oBACrD,MAAM,UAAU,GAAG,KAAK,CAAC,CAAC,CAAC,IAAI,EAAE,CAAA;oBACjC,MAAM,WAAW,GAAG,UAAU,CAAC,OAAO,CAAC,OAAO,CAAC,CAAA;oBAC/C,MAAM,YAAY,GAChB,WAAW,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC,EAAE,WAAW,CAAC,CAAC,CAAC,CAAC,UAAU,CAAA;oBACtE,MAAM,IAAI,GACR,WAAW,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,SAAS,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,EAAE,CAAA;oBAE3D,QAAQ,CAAC,IAAI;wBACX,KAAK,CAAC,CAAC,CAAC;4BACR,kBAAkB;4BAClB,YAAY,CAAC,OAAO,EAAE;4BACtB,IAAI;4BACJ,SAAS;4BACT,IAAI;4BACJ,IAAI,CAAA;gBACR,CAAC;qBAAM,CAAC;oBACN,QAAQ,CAAC,IAAI,IAAI,uBAAuB,SAAS,IAAI,CAAA;gBACvD,CAAC;gBAED,QAAQ,CAAC,WAAW,CAAC,YAAY,GAAG,IAAI,CAAC,GAAG,EAAE,CAAA;gBAC9C,MAAM,aAAa,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAA;YAC1C,CAAC;YAED,OAAO,IAAI,IAAI,CAAC,KAAK,MAAM,IAAI,CAAC,OAAO,OAAO,MAAM,EAAE,CAAA;QACxD,CAAC;KACF,CAAC,CAAA;AACJ,CAAC"}

package/dist/tools/self-rate.d.ts

@@ -0,0 +1,15 @@
+/**
+ * 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 { type ToolDefinition } from "@opencode-ai/plugin/tool";
+export declare function createSelfRateTool(directory: string): ToolDefinition;
+//# sourceMappingURL=self-rate.d.ts.map

package/dist/tools/self-rate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"self-rate.d.ts","sourceRoot":"","sources":["../../src/tools/self-rate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAQ,KAAK,cAAc,EAAE,MAAM,0BAA0B,CAAA;AAMpE,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,cAAc,CAkEpE"}

package/dist/tools/self-rate.js

@@ -0,0 +1,76 @@
+/**
+ * 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 } 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) {
+    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;
+        },
+    });
+}
+//# sourceMappingURL=self-rate.js.map

package/dist/tools/self-rate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"self-rate.js","sourceRoot":"","sources":["../../src/tools/self-rate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,IAAI,EAAuB,MAAM,0BAA0B,CAAA;AACpE,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAA;AAC1D,OAAO,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAA;AACzD,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAChD,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AAEhC,MAAM,UAAU,kBAAkB,CAAC,SAAiB;IAClD,OAAO,IAAI,CAAC;QACV,WAAW,EACT,iDAAiD;YACjD,iEAAiE;QACnE,IAAI,EAAE;YACJ,KAAK,EAAE,IAAI,CAAC,MAAM;iBACf,MAAM,EAAE;iBACR,GAAG,CAAC,CAAC,CAAC;iBACN,GAAG,CAAC,EAAE,CAAC;iBACP,QAAQ,CAAC,uDAAuD,CAAC;YACpE,MAAM,EAAE,IAAI,CAAC,MAAM;iBAChB,MAAM,EAAE;iBACR,QAAQ,EAAE;iBACV,QAAQ,CAAC,oCAAoC,CAAC;YACjD,YAAY,EAAE,IAAI,CAAC,MAAM;iBACtB,MAAM,EAAE;iBACR,QAAQ,EAAE;iBACV,QAAQ,CAAC,6CAA6C,CAAC;SAC3D;QACD,KAAK,CAAC,OAAO,CAAC,IAAI;YAChB,MAAM,YAAY,GAAG,kBAAkB,CAAC,SAAS,CAAC,CAAA;YAClD,MAAM,GAAG,GAAG,MAAM,YAAY,CAC5B,IAAI,CAAC,SAAS,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,CAAC,EAChD,WAAW,CACZ,CAAA;YAED,qBAAqB;YACrB,IAAI,KAAK,GAAG,MAAM,YAAY,CAAC,IAAI,EAAE,CAAA;YACrC,IAAI,CAAC,KAAK,EAAE,CAAC;gBACX,OAAO,sDAAsD,CAAA;YAC/D,CAAC;YAED,iBAAiB;YACjB,KAAK,GAAG,aAAa,CAAC,KAAK,EAAE;gBAC3B,KAAK,EAAE,IAAI,CAAC,KAAK;gBACjB,MAAM,EAAE,IAAI,CAAC,MAAM;gBACnB,YAAY,EAAE,IAAI,CAAC,YAAY;aAChC,CAAC,CAAA;YAEF,aAAa;YACb,MAAM,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;YAE9B,aAAa;YACb,MAAM,UAAU,GAAG,KAAK,CAAC,OAAO,CAAC,UAAU,CAAA;YAC3C,MAAM,UAAU,GAAG,mBAAmB,UAAU,KAAK,IAAI,CAAC,KAAK,KAAK,CAAA;YACpE,MAAM,GAAG,CAAC,IAAI,CAAC,UAAU,CAAC,CAAA;YAE1B,iBAAiB;YACjB,IAAI,QAAQ,GAAG,oBAAoB,IAAI,CAAC,KAAK,eAAe,UAAU,EAAE,CAAA;YACxE,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;gBAChB,QAAQ,IAAI,OAAO,IAAI,CAAC,MAAM,GAAG,CAAA;YACnC,CAAC;YAED,kCAAkC;YAClC,IAAI,IAAI,CAAC,KAAK,IAAI,CAAC,EAAE,CAAC;gBACpB,QAAQ,IAAI,2EAA2E,CAAA;YACzF,CAAC;iBAAM,IAAI,IAAI,CAAC,KAAK,IAAI,CAAC,EAAE,CAAC;gBAC3B,QAAQ,IAAI,kEAAkE,CAAA;YAChF,CAAC;iBAAM,CAAC;gBACN,QAAQ,IAAI,oBAAoB,CAAA;YAClC,CAAC;YAED,OAAO,QAAQ,CAAA;QACjB,CAAC;KACF,CAAC,CAAA;AACJ,CAAC"}

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "hivemind-context-governance",
+  "version": "1.3.0",
+  "description": "Context-Aware Governance Layer for OpenCode - prevents drift and manages session state across lifecycles",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "hivemind-context-governance": "dist/cli.js",
+    "hivemind": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/shynlee04/hivemind-plugin.git"
+  },
+  "bugs": {
+    "url": "https://github.com/shynlee04/hivemind-plugin/issues"
+  },
+  "homepage": "https://github.com/shynlee04/hivemind-plugin#readme",
+  "scripts": {
+    "clean": "rm -rf dist",
+    "build": "npm run clean && tsc",
+    "dev": "tsc --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "tsx --test tests/**/*.test.ts",
+    "prepublishOnly": "npm run typecheck && npm test && npm run build"
+  },
+  "keywords": [
+    "opencode",
+    "opencode-plugin",
+    "plugin",
+    "governance",
+    "context-management",
+    "agent-lifecycle",
+    "hivemind"
+  ],
+  "author": "HiveMind Contributors",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "yaml": "^2.3.4",
+    "zod": "^3.22.4"
+  },
+  "devDependencies": {
+    "@opencode-ai/plugin": "^1.1.53",
+    "@types/bun": "^1.2.0",
+    "@types/node": "^20.10.0",
+    "tsx": "^4.7.0",
+    "typescript": "^5.3.0"
+  },
+  "peerDependencies": {
+    "@opencode-ai/plugin": "*"
+  },
+  "peerDependenciesMeta": {
+    "@opencode-ai/plugin": {
+      "optional": false
+    }
+  }
+}

package/src/cli/init.ts

@@ -0,0 +1,214 @@
+/**
+ * HiveMind Init — One-command project initialization.
+ *
+ * Creates:
+ *   - .opencode/planning/ directory structure
+ *   - index.md with template
+ *   - active.md with LOCKED status
+ *   - brain.json with initial state
+ *   - config.json with governance preferences
+ *   - Auto-registers plugin in opencode.json
+ */
+
+import { existsSync, readFileSync, writeFileSync } from "node:fs"
+import { join } from "node:path"
+import type { GovernanceMode, Language, ExpertLevel, OutputStyle } from "../schemas/config.js"
+import { createConfig, isValidGovernanceMode, isValidLanguage, isValidExpertLevel, isValidOutputStyle } from "../schemas/config.js"
+import { createBrainState, generateSessionId } from "../schemas/brain-state.js"
+import { createStateManager, saveConfig } from "../lib/persistence.js"
+import { initializePlanningDirectory } from "../lib/planning-fs.js"
+
+export interface InitOptions {
+  language?: Language
+  governanceMode?: GovernanceMode
+  expertLevel?: ExpertLevel
+  outputStyle?: OutputStyle
+  requireCodeReview?: boolean
+  enforceTdd?: boolean
+  silent?: boolean
+}
+
+// eslint-disable-next-line no-console
+const log = (msg: string) => console.log(msg)
+
+const PLUGIN_NAME = "hivemind-context-governance"
+
+/**
+ * Auto-register the HiveMind plugin in opencode.json.
+ * Creates the file if it doesn't exist.
+ * Adds the plugin if not already registered.
+ */
+function registerPluginInConfig(directory: string, silent: boolean): void {
+  const configPath = join(directory, "opencode.json")
+
+  let config: Record<string, unknown> = {}
+
+  if (existsSync(configPath)) {
+    try {
+      const raw = readFileSync(configPath, "utf-8")
+      config = JSON.parse(raw)
+    } catch {
+      // Malformed JSON — overwrite
+      config = {}
+    }
+  }
+
+  // Ensure plugin array exists
+  if (!Array.isArray(config.plugin)) {
+    config.plugin = []
+  }
+
+  const plugins = config.plugin as string[]
+
+  // Check if already registered (exact match or versioned match)
+  const alreadyRegistered = plugins.some(
+    (p) => p === PLUGIN_NAME || p.startsWith(PLUGIN_NAME + "@")
+  )
+
+  if (alreadyRegistered) {
+    if (!silent) {
+      log(`  ✓ Plugin already registered in opencode.json`)
+    }
+    return
+  }
+
+  plugins.push(PLUGIN_NAME)
+  config.plugin = plugins
+
+  writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n", "utf-8")
+
+  if (!silent) {
+    log(`  ✓ Plugin registered in opencode.json`)
+    log(`    → OpenCode will auto-install on next launch`)
+  }
+}
+
+export async function initProject(
+  directory: string,
+  options: InitOptions = {}
+): Promise<void> {
+  const planningDir = join(directory, ".opencode", "planning")
+  const brainPath = join(planningDir, "brain.json")
+
+  // Guard: Check brain.json existence, not just directory.
+  // The directory may exist from logger side-effects without full initialization.
+  if (existsSync(brainPath)) {
+    if (!options.silent) {
+      log("⚠ HiveMind already initialized in this project.")
+      log(`  Directory: ${planningDir}`)
+      log("  Use 'npx hivemind-context-governance status' to see current state.")
+    }
+    return
+  }
+
+  if (!options.silent) {
+    log("")
+    log("🐝 HiveMind Context Governance — Initialization")
+    log("─".repeat(48))
+  }
+
+  // Validate and set governance mode
+  const governanceMode = options.governanceMode ?? "assisted"
+  if (!isValidGovernanceMode(governanceMode)) {
+    log(`✗ Invalid governance mode: ${governanceMode}`)
+    log("  Valid: permissive, assisted, strict")
+    return
+  }
+
+  // Validate and set language
+  const language = options.language ?? "en"
+  if (!isValidLanguage(language)) {
+    log(`✗ Invalid language: ${language}`)
+    log("  Valid: en, vi")
+    return
+  }
+
+  // Validate and set expert level
+  const expertLevel = options.expertLevel ?? "intermediate"
+  if (!isValidExpertLevel(expertLevel)) {
+    log(`✗ Invalid expert level: ${expertLevel}`)
+    log("  Valid: beginner, intermediate, advanced, expert")
+    return
+  }
+
+  // Validate and set output style
+  const outputStyle = options.outputStyle ?? "explanatory"
+  if (!isValidOutputStyle(outputStyle)) {
+    log(`✗ Invalid output style: ${outputStyle}`)
+    log("  Valid: explanatory, outline, skeptical, architecture, minimal")
+    return
+  }
+
+  // Create config with agent behavior
+  const config = createConfig({
+    governance_mode: governanceMode,
+    language,
+    agent_behavior: {
+      language,
+      expert_level: expertLevel,
+      output_style: outputStyle,
+      constraints: {
+        require_code_review: options.requireCodeReview ?? false,
+        enforce_tdd: options.enforceTdd ?? false,
+        max_response_tokens: 2000,
+        explain_reasoning: true,
+        be_skeptical: outputStyle === "skeptical",
+      },
+    },
+  })
+
+  if (!options.silent) {
+    log(`  Governance: ${governanceMode}`)
+    log(`  Language: ${language}`)
+    log(`  Expert Level: ${expertLevel}`)
+    log(`  Output Style: ${outputStyle}`)
+    if (options.requireCodeReview) log("  ✓ Code review required")
+    if (options.enforceTdd) log("  ✓ TDD enforced")
+    log("")
+  }
+
+  // Create planning directory structure
+  if (!options.silent) {
+    log("Creating planning directory...")
+  }
+  await initializePlanningDirectory(directory)
+
+  // Save config
+  await saveConfig(directory, config)
+
+  // Initialize brain state
+  const stateManager = createStateManager(directory)
+  const sessionId = generateSessionId()
+  const state = createBrainState(sessionId, config)
+  await stateManager.save(state)
+
+  // Auto-register plugin in opencode.json
+  registerPluginInConfig(directory, options.silent ?? false)
+
+  if (!options.silent) {
+    log("")
+    log("✓ Planning directory created:")
+    log(`  ${planningDir}/`)
+    log("  ├── index.md      (project trajectory)")
+    log("  ├── active.md     (current session)")
+    log("  ├── brain.json    (machine state)")
+    log("  ├── config.json   (governance settings)")
+    log("  └── archive/      (completed sessions)")
+    log("")
+    log(`Session ${sessionId} initialized.`)
+    log(`Status: ${state.session.governance_status}`)
+    log("")
+
+    if (governanceMode === "strict") {
+      log("🔒 STRICT MODE — agents must call declare_intent before writing.")
+    } else if (governanceMode === "assisted") {
+      log("🔔 ASSISTED MODE — agents get warnings but can proceed.")
+    } else {
+      log("🟢 PERMISSIVE MODE — agents work freely, activity tracked.")
+    }
+
+    log("")
+    log("✅ Done! Open OpenCode in this project — HiveMind is active.")
+    log("")
+  }
+}