solveos-cli 0.1.0

package/dist/hooks/brief-anchor.js

@@ -0,0 +1,236 @@
+/**
+ * solveOS Brief Anchor — OpenCode plugin.
+ *
+ * Periodically reminds the AI agent to check work against the Plan Brief
+ * during the Build phase. Triggers after every N tool calls (configurable),
+ * injecting a reminder to verify alignment with success criteria and
+ * out-of-scope boundaries.
+ *
+ * Implements the solveOS principle: "The brief is your compass."
+ *
+ * Installed to: .opencode/plugins/solveos-brief-anchor.ts
+ * Events: tool.execute.after
+ */
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+const SOLVEOS_DIR = ".solveos";
+const DEFAULT_INTERVAL = 10;
+/**
+ * Read .solveos/config.json from the project directory.
+ * Returns null if not found or unparseable.
+ */
+function readSolveosConfig(projectDir) {
+    try {
+        const raw = readFileSync(join(projectDir, SOLVEOS_DIR, "config.json"), "utf-8");
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Read current cycle state from .solveos/STATE.md frontmatter.
+ * Returns the current_state string or null.
+ */
+function readCurrentState(projectDir) {
+    try {
+        const raw = readFileSync(join(projectDir, SOLVEOS_DIR, "STATE.md"), "utf-8");
+        const fmMatch = raw.match(/^---\n([\s\S]*?)\n---/);
+        if (!fmMatch)
+            return null;
+        const data = JSON.parse(fmMatch[1]);
+        return data.current_state;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Read the Plan Brief from .solveos/BRIEF.md.
+ * Returns the raw content or null.
+ */
+function readBrief(projectDir) {
+    try {
+        return readFileSync(join(projectDir, SOLVEOS_DIR, "BRIEF.md"), "utf-8");
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Extract success criteria from a Plan Brief markdown string.
+ * Looks for `- [ ] criterion` lines under ## Success Criteria.
+ */
+export function extractSuccessCriteria(brief) {
+    const criteria = [];
+    const lines = brief.split("\n");
+    let inSection = false;
+    for (const line of lines) {
+        if (line.startsWith("## Success Criteria")) {
+            inSection = true;
+            continue;
+        }
+        if (inSection && line.startsWith("## ")) {
+            break; // Next section
+        }
+        if (inSection) {
+            const match = line.match(/^- \[[ x]\] (.+)$/);
+            if (match) {
+                criteria.push(match[1]);
+            }
+        }
+    }
+    return criteria;
+}
+/**
+ * Extract out-of-scope items from a Plan Brief markdown string.
+ */
+export function extractOutOfScope(brief) {
+    const items = [];
+    const lines = brief.split("\n");
+    let inSection = false;
+    for (const line of lines) {
+        if (line.startsWith("## Out of Scope")) {
+            inSection = true;
+            continue;
+        }
+        if (inSection && line.startsWith("## ")) {
+            break;
+        }
+        if (inSection) {
+            const match = line.match(/^- (.+)$/);
+            if (match) {
+                items.push(match[1]);
+            }
+        }
+    }
+    return items;
+}
+/**
+ * Check if the hook is enabled via config.
+ */
+function isEnabled(config) {
+    if (!config?.hooks)
+        return true; // enabled by default
+    return config.hooks.brief_anchor !== false;
+}
+/**
+ * Get the tool call interval from config.
+ */
+function getInterval(config) {
+    return config?.hooks?.brief_anchor_interval ?? DEFAULT_INTERVAL;
+}
+// ---------------------------------------------------------------------------
+// Reminder message
+// ---------------------------------------------------------------------------
+/**
+ * Generate a brief anchor reminder with the actual criteria and boundaries.
+ */
+export function generateReminder(criteria, outOfScope) {
+    const criteriaList = criteria.length > 0
+        ? criteria.map((c, i) => `  ${i + 1}. ${c}`).join("\n")
+        : "  (no criteria found — check .solveos/BRIEF.md)";
+    const oosLine = outOfScope.length > 0
+        ? `\n**Out of scope:** ${outOfScope.join(", ")}`
+        : "";
+    return `
+---
+**solveOS Brief Anchor** — alignment check
+
+Pause and verify your current work:
+
+**Success Criteria:**
+${criteriaList}
+${oosLine}
+
+**Ask yourself:**
+1. Does my current task connect to one of these criteria?
+2. Am I within scope?
+3. Am I approaching a rabbit hole?
+
+If any answer is wrong, stop and recalibrate before continuing.
+---
+`.trim();
+}
+/**
+ * Generate a minimal reminder when no brief is found.
+ */
+export function generateMinimalReminder() {
+    return `
+---
+**solveOS Brief Anchor** — alignment check
+
+No Plan Brief found at \`.solveos/BRIEF.md\`. Consider running \`/solveos:plan\` to create one.
+
+If you have a brief, verify your current work still aligns with the plan's success criteria and out-of-scope boundaries.
+---
+`.trim();
+}
+export function createAnchorState() {
+    return {
+        toolCallCount: 0,
+        sessionId: null,
+    };
+}
+/**
+ * Check if a reminder should be emitted based on current tool call count.
+ */
+export function shouldRemind(state, interval) {
+    return state.toolCallCount > 0 && state.toolCallCount % interval === 0;
+}
+// ---------------------------------------------------------------------------
+// Plugin export
+// ---------------------------------------------------------------------------
+/**
+ * The OpenCode plugin export.
+ *
+ * Subscribes to tool.execute.after events to count tool calls during Build.
+ * At configurable intervals, logs a brief anchor reminder.
+ */
+export const SolveosBriefAnchor = async (ctx) => {
+    const config = readSolveosConfig(ctx.worktree || ctx.directory);
+    if (!isEnabled(config)) {
+        return {}; // Hook disabled — no event subscriptions
+    }
+    const interval = getInterval(config);
+    const state = createAnchorState();
+    return {
+        "tool.execute.after": async (input, _output) => {
+            // Check if we're in a Build phase
+            const projectDir = ctx.worktree || ctx.directory;
+            const currentState = readCurrentState(projectDir);
+            if (currentState !== "BUILDING")
+                return;
+            // Reset state if session changed
+            const sessionId = input.sessionID ?? null;
+            if (sessionId && sessionId !== state.sessionId) {
+                state.toolCallCount = 0;
+                state.sessionId = sessionId;
+            }
+            state.toolCallCount++;
+            if (shouldRemind(state, interval)) {
+                const brief = readBrief(projectDir);
+                let message;
+                if (brief) {
+                    const criteria = extractSuccessCriteria(brief);
+                    const outOfScope = extractOutOfScope(brief);
+                    message = generateReminder(criteria, outOfScope);
+                }
+                else {
+                    message = generateMinimalReminder();
+                }
+                await ctx.client.app.log({
+                    body: {
+                        service: "solveos-brief-anchor",
+                        level: "info",
+                        message,
+                    },
+                });
+            }
+        },
+    };
+};
+//# sourceMappingURL=brief-anchor.js.map

package/dist/hooks/brief-anchor.js.map

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

package/dist/hooks/context-monitor.d.ts

@@ -0,0 +1,70 @@
+/**
+ * solveOS Context Monitor — OpenCode plugin.
+ *
+ * Monitors context window utilization during Build phase execution.
+ * When message count exceeds a configurable threshold (proxy for context usage),
+ * warns the user and suggests spawning a fresh sub-agent for remaining work.
+ *
+ * This prevents the quality degradation that happens as context fills
+ * with accumulated state — inspired by GSD's approach of keeping the
+ * orchestrator at 30-40% utilization.
+ *
+ * Installed to: .opencode/plugins/solveos-context-monitor.ts
+ * Events: message.updated
+ */
+/**
+ * Context monitor plugin state — tracks message count per session.
+ * Resets when a new session starts.
+ */
+interface MonitorState {
+    messageCount: number;
+    warned60: boolean;
+    warned80: boolean;
+    sessionId: string | null;
+}
+/**
+ * Create a fresh monitor state.
+ */
+export declare function createMonitorState(): MonitorState;
+/**
+ * Check if a warning should be emitted based on current message count.
+ * Returns the warning message or null.
+ */
+export declare function checkContextUsage(state: MonitorState, threshold: number): {
+    warning: string | null;
+    level: "60" | "80" | null;
+};
+/**
+ * The OpenCode plugin export.
+ *
+ * Subscribes to message.updated events to track context usage.
+ * When thresholds are crossed, logs a warning via the client.
+ */
+export declare const SolveosContextMonitor: (ctx: {
+    directory: string;
+    worktree: string;
+    client: {
+        app: {
+            log: (opts: {
+                body: {
+                    service: string;
+                    level: string;
+                    message: string;
+                };
+            }) => Promise<void>;
+        };
+    };
+}) => Promise<{
+    event?: undefined;
+} | {
+    event: ({ event }: {
+        event: {
+            type: string;
+            properties?: {
+                sessionID?: string;
+            };
+        };
+    }) => Promise<void>;
+}>;
+export {};
+//# sourceMappingURL=context-monitor.d.ts.map

package/dist/hooks/context-monitor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-monitor.d.ts","sourceRoot":"","sources":["../../src/hooks/context-monitor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AA0GH;;;GAGG;AACH,UAAU,YAAY;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,OAAO,CAAC;IAClB,QAAQ,EAAE,OAAO,CAAC;IAClB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAED;;GAEG;AACH,wBAAgB,kBAAkB,IAAI,YAAY,CAOjD;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,YAAY,EACnB,SAAS,EAAE,MAAM,GAChB;IAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,KAAK,EAAE,IAAI,GAAG,IAAI,GAAG,IAAI,CAAA;CAAE,CAevD;AAED;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,GAAU,KAAK;IAC/C,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE;QAAE,GAAG,EAAE;YAAE,GAAG,EAAE,CAAC,IAAI,EAAE;gBAAE,IAAI,EAAE;oBAAE,OAAO,EAAE,MAAM,CAAC;oBAAC,KAAK,EAAE,MAAM,CAAC;oBAAC,OAAO,EAAE,MAAM,CAAA;iBAAE,CAAA;aAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;SAAE,CAAA;KAAE,CAAC;CAClH;;;uBAW4B;QAAE,KAAK,EAAE;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,UAAU,CAAC,EAAE;gBAAE,SAAS,CAAC,EAAE,MAAM,CAAA;aAAE,CAAA;SAAE,CAAA;KAAE;EA+B5F,CAAC"}

package/dist/hooks/context-monitor.js

@@ -0,0 +1,166 @@
+/**
+ * solveOS Context Monitor — OpenCode plugin.
+ *
+ * Monitors context window utilization during Build phase execution.
+ * When message count exceeds a configurable threshold (proxy for context usage),
+ * warns the user and suggests spawning a fresh sub-agent for remaining work.
+ *
+ * This prevents the quality degradation that happens as context fills
+ * with accumulated state — inspired by GSD's approach of keeping the
+ * orchestrator at 30-40% utilization.
+ *
+ * Installed to: .opencode/plugins/solveos-context-monitor.ts
+ * Events: message.updated
+ */
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+const SOLVEOS_DIR = ".solveos";
+const DEFAULT_THRESHOLD = 60;
+/**
+ * Read .solveos/config.json from the project directory.
+ * Returns null if not found or unparseable.
+ */
+function readSolveosConfig(projectDir) {
+    try {
+        const raw = readFileSync(join(projectDir, SOLVEOS_DIR, "config.json"), "utf-8");
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Read current cycle state from .solveos/STATE.md frontmatter.
+ * Returns the current_state string or null.
+ */
+function readCurrentState(projectDir) {
+    try {
+        const raw = readFileSync(join(projectDir, SOLVEOS_DIR, "STATE.md"), "utf-8");
+        const fmMatch = raw.match(/^---\n([\s\S]*?)\n---/);
+        if (!fmMatch)
+            return null;
+        const data = JSON.parse(fmMatch[1]);
+        return data.current_state;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Check if the hook is enabled via config.
+ */
+function isEnabled(config) {
+    if (!config?.hooks)
+        return true; // enabled by default
+    return config.hooks.context_monitor !== false;
+}
+/**
+ * Get the message count threshold from config.
+ */
+function getThreshold(config) {
+    return config?.hooks?.context_monitor_threshold ?? DEFAULT_THRESHOLD;
+}
+// ---------------------------------------------------------------------------
+// Warning message templates
+// ---------------------------------------------------------------------------
+const WARNING_60 = `
+---
+**solveOS Context Monitor** — context usage is growing.
+
+You've exchanged a significant number of messages in this session. Context quality may start degrading.
+
+**Recommendation:** Consider summarizing progress so far, then spawning a fresh sub-agent for the remaining work using a new subtask. Pass it:
+1. The Plan Brief (\`.solveos/BRIEF.md\`)
+2. A summary of what's been completed
+3. What remains to be done
+
+This keeps each agent working with clean, focused context.
+---
+`.trim();
+const WARNING_80 = `
+---
+**solveOS Context Monitor** — HIGH context usage.
+
+This session has accumulated substantial context. Response quality is likely degrading — the AI may start forgetting earlier instructions, repeating itself, or making errors it wouldn't make with fresh context.
+
+**Strong recommendation:** Wrap up the current unit of work and spawn a fresh sub-agent immediately. The Plan Brief and build summary will bring the new agent up to speed quickly.
+
+Run \`/solveos:status\` to capture current state before transitioning.
+---
+`.trim();
+/**
+ * Create a fresh monitor state.
+ */
+export function createMonitorState() {
+    return {
+        messageCount: 0,
+        warned60: false,
+        warned80: false,
+        sessionId: null,
+    };
+}
+/**
+ * Check if a warning should be emitted based on current message count.
+ * Returns the warning message or null.
+ */
+export function checkContextUsage(state, threshold) {
+    const pct60 = Math.floor(threshold * 0.6);
+    const pct80 = Math.floor(threshold * 0.8);
+    if (state.messageCount >= pct80 && !state.warned80) {
+        state.warned80 = true;
+        return { warning: WARNING_80, level: "80" };
+    }
+    if (state.messageCount >= pct60 && !state.warned60) {
+        state.warned60 = true;
+        return { warning: WARNING_60, level: "60" };
+    }
+    return { warning: null, level: null };
+}
+/**
+ * The OpenCode plugin export.
+ *
+ * Subscribes to message.updated events to track context usage.
+ * When thresholds are crossed, logs a warning via the client.
+ */
+export const SolveosContextMonitor = async (ctx) => {
+    const config = readSolveosConfig(ctx.worktree || ctx.directory);
+    if (!isEnabled(config)) {
+        return {}; // Hook disabled — no event subscriptions
+    }
+    const threshold = getThreshold(config);
+    const state = createMonitorState();
+    return {
+        event: async ({ event }) => {
+            // Only track message events
+            if (event.type !== "message.updated")
+                return;
+            // Check if we're in a Build phase
+            const currentState = readCurrentState(ctx.worktree || ctx.directory);
+            if (currentState !== "BUILDING")
+                return;
+            // Reset state if session changed
+            const sessionId = event.properties?.sessionID ?? null;
+            if (sessionId && sessionId !== state.sessionId) {
+                state.messageCount = 0;
+                state.warned60 = false;
+                state.warned80 = false;
+                state.sessionId = sessionId;
+            }
+            state.messageCount++;
+            const { warning } = checkContextUsage(state, threshold);
+            if (warning) {
+                await ctx.client.app.log({
+                    body: {
+                        service: "solveos-context-monitor",
+                        level: "warn",
+                        message: warning,
+                    },
+                });
+            }
+        },
+    };
+};
+//# sourceMappingURL=context-monitor.js.map

package/dist/hooks/context-monitor.js.map

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

package/dist/lib/artifacts.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Artifact management for solveos-cli.
+ *
+ * Handles creating, reading, writing, and archiving files in the
+ * .solveos/ directory. All cycle state persists as markdown and JSON
+ * files — no databases, no cloud, no accounts.
+ */
+import type { Config, CycleStateData, PlanBrief } from "../types.js";
+/**
+ * Check if a .solveos/ directory exists and is valid.
+ */
+export declare function projectExists(projectDir: string): Promise<boolean>;
+/**
+ * Create the .solveos/ directory structure.
+ * Safe to run multiple times — does not overwrite existing files.
+ */
+export declare function initProject(projectDir: string): Promise<void>;
+/**
+ * Read .solveos/config.json. Returns defaults for any missing fields.
+ */
+export declare function readConfig(projectDir: string): Promise<Config>;
+/**
+ * Write .solveos/config.json.
+ */
+export declare function writeConfig(projectDir: string, config: Config): Promise<void>;
+/**
+ * Read and parse .solveos/STATE.md.
+ * STATE.md uses a JSON frontmatter block between `---` markers.
+ */
+export declare function readState(projectDir: string): Promise<CycleStateData | null>;
+/**
+ * Write structured state to .solveos/STATE.md.
+ * Format: YAML-like frontmatter (JSON) between --- markers, then human-readable summary.
+ */
+export declare function writeState(projectDir: string, state: CycleStateData): Promise<void>;
+/**
+ * Read .solveos/BRIEF.md and return its raw content, or null if not found.
+ */
+export declare function readBrief(projectDir: string): Promise<string | null>;
+/**
+ * Write a Plan Brief to .solveos/BRIEF.md.
+ * Accepts either a PlanBrief object (rendered to markdown) or raw markdown string.
+ */
+export declare function writeBrief(projectDir: string, brief: PlanBrief | string): Promise<void>;
+/**
+ * Archive the current cycle to .solveos/history/cycle-{n}/.
+ * Copies BRIEF.md, STATE.md, and validations/ to the archive.
+ * Clears current BRIEF.md and validations/ after archiving.
+ */
+export declare function archiveCycle(projectDir: string, cycleNumber: number): Promise<void>;
+/**
+ * Write a research summary to .solveos/research/{topic}-research.md.
+ */
+export declare function writeResearch(projectDir: string, topic: string, content: string): Promise<void>;
+/**
+ * Write a validation artifact.
+ */
+export declare function writeValidation(projectDir: string, filename: string, content: string): Promise<void>;
+/**
+ * Write a review artifact.
+ */
+export declare function writeReview(projectDir: string, filename: string, content: string): Promise<void>;
+//# sourceMappingURL=artifacts.d.ts.map

package/dist/lib/artifacts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"artifacts.d.ts","sourceRoot":"","sources":["../../src/lib/artifacts.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,OAAO,KAAK,EAAE,MAAM,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AA6CrE;;GAEG;AACH,wBAAsB,aAAa,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAOxE;AAkBD;;;GAGG;AACH,wBAAsB,WAAW,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CA+BnE;AAMD;;GAEG;AACH,wBAAsB,UAAU,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAcpE;AAED;;GAEG;AACH,wBAAsB,WAAW,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAGnF;AAMD;;;GAGG;AACH,wBAAsB,SAAS,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CAQlF;AAED;;;GAGG;AACH,wBAAsB,UAAU,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAIzF;AAgFD;;GAEG;AACH,wBAAsB,SAAS,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAO1E;AAED;;;GAGG;AACH,wBAAsB,UAAU,CAC9B,UAAU,EAAE,MAAM,EAClB,KAAK,EAAE,SAAS,GAAG,MAAM,GACxB,OAAO,CAAC,IAAI,CAAC,CAIf;AAmED;;;;GAIG;AACH,wBAAsB,YAAY,CAChC,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,IAAI,CAAC,CA+Cf;AAMD;;GAEG;AACH,wBAAsB,aAAa,CACjC,UAAU,EAAE,MAAM,EAClB,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,IAAI,CAAC,CAIf;AAED;;GAEG;AACH,wBAAsB,eAAe,CACnC,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,IAAI,CAAC,CAGf;AAED;;GAEG;AACH,wBAAsB,WAAW,CAC/B,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,IAAI,CAAC,CAGf"}