opencode-empirical-plan 0.3.0 → 0.3.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-empirical-plan",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "OpenCode lifecycle plugin for empirical plan orchestration.",
   "author": "chuck",
   "license": "MIT",

package/src/hooks/skill-reminder.ts

@@ -0,0 +1,66 @@
+const KEY = Symbol.for("opencode-empirical-plan.skillReminder");
+
+interface SkillReminderStore {
+  armedSessions: Set<string>;
+}
+
+if (!(globalThis as Record<symbol, unknown>)[KEY]) {
+  (globalThis as Record<symbol, unknown>)[KEY] = {
+    armedSessions: new Set<string>(),
+  } satisfies SkillReminderStore;
+}
+
+const store = (globalThis as Record<symbol, unknown>)[KEY] as SkillReminderStore;
+
+const ENGLISH_KEYWORD_REGEX = /\b(plan|planning)\b/i;
+const CHINESE_KEYWORDS = ["计划", "规划", "制定计划", "做计划"];
+
+interface TextPartLike {
+  type?: string;
+  text?: unknown;
+}
+
+function containsPlanningKeywords(text: string): boolean {
+  if (ENGLISH_KEYWORD_REGEX.test(text)) {
+    return true;
+  }
+
+  return CHINESE_KEYWORDS.some((keyword) => text.includes(keyword));
+}
+
+function extractText(parts: unknown[]): string {
+  const texts: string[] = [];
+  for (const part of parts) {
+    const candidate = part as TextPartLike;
+    if (candidate.type === "text" && typeof candidate.text === "string") {
+      texts.push(candidate.text);
+    }
+  }
+  return texts.join("\n");
+}
+
+export async function handleSkillReminderChatMessage(
+  sessionID: string,
+  parts: unknown[],
+): Promise<void> {
+  try {
+    const text = extractText(parts);
+    if (!text) return;
+    if (!containsPlanningKeywords(text)) return;
+    store.armedSessions.add(sessionID);
+  } catch (err) {
+    console.error("[empirical-plan] skill-reminder chat.message error:", err);
+  }
+}
+
+export function consumeSkillReminderArmed(sessionID: string): boolean {
+  if (!store.armedSessions.has(sessionID)) {
+    return false;
+  }
+  store.armedSessions.delete(sessionID);
+  return true;
+}
+
+export function cleanupSkillReminderSession(sessionID: string): void {
+  store.armedSessions.delete(sessionID);
+}

package/src/hooks/system-transform.ts

@@ -0,0 +1,21 @@
+import { consumeSkillReminderArmed } from "./skill-reminder.ts";
+
+const SKILL_REMINDER_TEXT = `<skill-reminder>
+User message contains planning-related keywords. BEFORE responding:
+1. Call skill(name="empirical-plan") to load the full planning workflow
+2. Only skip if: this is a clarification question (not a task), or empirical-plan is already loaded this session
+</skill-reminder>`;
+
+export async function handleSystemTransform(
+  sessionID: string | undefined,
+  system: string[],
+): Promise<void> {
+  try {
+    if (!sessionID) return;
+    const armed = consumeSkillReminderArmed(sessionID);
+    if (!armed) return;
+    system.push(SKILL_REMINDER_TEXT);
+  } catch (err) {
+    console.error("[empirical-plan] system-transform error:", err);
+  }
+}

package/src/index.ts

@@ -6,6 +6,8 @@ import { handleToolAfter } from "./hooks/tool-after.ts";
 import { recordCallStart } from "./hooks/tool-before.ts";
 import { handleSessionIdle } from "./hooks/session-idle.ts";
 import { cleanup, cleanupChild } from "./state/active-lifecycles.ts";
+import { handleSkillReminderChatMessage, cleanupSkillReminderSession } from "./hooks/skill-reminder.ts";
+import { handleSystemTransform } from "./hooks/system-transform.ts";
 
 export const EmpiricalPlanPlugin: Plugin = async ({ client }) => {
   return {
@@ -15,6 +17,18 @@ export const EmpiricalPlanPlugin: Plugin = async ({ client }) => {
       lifecycle_record_reflection: lifecycleRecordReflectionTool,
     },
 
+    "chat.message": async (input, output) => {
+      try {
+        await handleSkillReminderChatMessage(input.sessionID, output.parts);
+      } catch (err) {
+        console.error("[empirical-plan] chat.message error:", err);
+      }
+    },
+
+    "experimental.chat.system.transform": async (input, output) => {
+      await handleSystemTransform(input.sessionID, output.system);
+    },
+
     "tool.execute.before": async (input) => {
       try {
         recordCallStart(input.callID);
@@ -49,6 +63,7 @@ export const EmpiricalPlanPlugin: Plugin = async ({ client }) => {
           if (sessionID) {
             cleanup(sessionID);
             cleanupChild(sessionID);
+            cleanupSkillReminderSession(sessionID);
           }
         }
       } catch (err) {

package/src/state/lifecycle-state.ts

@@ -1,6 +1,25 @@
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
-import { type LifecycleState, STATE_FILENAME, validateLifecycleState } from "../schema.ts";
+import { type LifecyclePhase, type LifecycleState, STATE_FILENAME, validateLifecycleState } from "../schema.ts";
+
+const PHASE_ORDER: LifecyclePhase[] = ["plan", "execute", "reflect", "done"];
+
+export async function assertPhaseAtLeast(
+  runDir: string,
+  required: LifecyclePhase,
+): Promise<{ ok: true } | { ok: false; reason: string }> {
+  const state = await readLifecycleState(runDir);
+  if (!state) return { ok: true };
+  const current = PHASE_ORDER.indexOf(state.phase);
+  const needed = PHASE_ORDER.indexOf(required);
+  if (current < needed) {
+    return {
+      ok: false,
+      reason: `lifecycle phase is "${state.phase}", expected at least "${required}"`,
+    };
+  }
+  return { ok: true };
+}
 
 export async function readLifecycleState(runDir: string): Promise<LifecycleState | null> {
   const stateFile = path.join(runDir, STATE_FILENAME);

package/src/tools/lifecycle-record-execution.ts

@@ -3,6 +3,7 @@ import * as fs from "node:fs/promises";
 import * as path from "node:path";
 import { atomicWrite } from "../state/frontmatter.ts";
 import { ensureExecutionMd } from "../hooks/tool-after.ts";
+import { assertPhaseAtLeast } from "../state/lifecycle-state.ts";
 
 const SUMMARY_MARKER = "<!-- EXECUTION:SUMMARY -->";
 
@@ -25,8 +26,9 @@ export const lifecycleRecordExecutionTool = tool({
 execution.md is the dedicated execution record file — separate from plan.md (which stays read-only after Phase 1-3).
 
 Guards (hard-block):
-- plan.md must exist and contain "## Plan Steps" (Phase 1-3 complete)
-- execution.md must already exist (initialized by the tool.execute.after hook when EXECUTE phase began)
+- lifecycle-state.json phase must be >= "execute" (fail-open if state file missing)
+- plan.md must exist
+- execution.md must exist (auto-created if missing)
 - <!-- EXECUTION:SUMMARY --> must NOT already exist in execution.md (idempotent guard)
 
 On success: appends the execution_summary section into execution.md and updates its Phase frontmatter field to "summarized".
@@ -47,33 +49,33 @@ The execution_summary should compare each Plan Step against what actually happen
     const planFile = path.join(runDir, "plan.md");
     const executionFile = path.join(runDir, "execution.md");
 
-    const result = await doRecord(planFile, executionFile, args.execution_summary);
+    const result = await doRecord(runDir, planFile, executionFile, args.execution_summary);
     return JSON.stringify(result);
   },
 });
 
 async function doRecord(
+  runDir: string,
   planFile: string,
   executionFile: string,
   executionSummary: string,
 ): Promise<RecordResult> {
-  // Guard 1: plan.md must exist with Phase 1-3 complete
-  if (!(await fileExists(planFile))) {
+  const phaseCheck = await assertPhaseAtLeast(runDir, "execute");
+  if (!phaseCheck.ok) {
     return {
       success: false,
       code: "PHASE_NOT_READY",
-      reason: `plan.md not found at ${planFile}`,
+      reason: phaseCheck.reason,
       next_action: "Complete the PLAN phase first — run empirical-plan skill to produce plan.md",
     };
   }
 
-  const planContent = await fs.readFile(planFile, "utf-8");
-  if (!planContent.includes("## Plan Steps")) {
+  if (!(await fileExists(planFile))) {
     return {
       success: false,
       code: "PHASE_NOT_READY",
-      reason: "plan.md does not contain '## Plan Steps' — Phase 1-3 incomplete",
-      next_action: "Complete the PLAN phase using the empirical-plan skill",
+      reason: `plan.md not found at ${planFile}`,
+      next_action: "Complete the PLAN phase first — run empirical-plan skill to produce plan.md",
     };
   }
 

package/src/tools/lifecycle-record-reflection.ts

@@ -2,8 +2,8 @@ import { tool } from "@opencode-ai/plugin";
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
 import { applyFrontmatterLifecycle, atomicWrite } from "../state/frontmatter.ts";
+import { assertPhaseAtLeast } from "../state/lifecycle-state.ts";
 
-const EXECUTION_SUMMARY_MARKER = "<!-- EXECUTION:SUMMARY -->";
 const REFLECTION_MARKER = "<!-- LIFECYCLE:REFLECTION -->";
 
 async function fileExists(p: string): Promise<boolean> {
@@ -19,7 +19,8 @@ export const lifecycleRecordReflectionTool = tool({
   description: `Record Phase 5 (Reflection & Optimization) into plan.md.
 
 Guards (hard-block):
-- execution.md must exist and contain <!-- EXECUTION:SUMMARY --> (Phase 4 already recorded)
+- lifecycle-state.json phase must be >= "reflect" (fail-open if state file missing)
+- execution.md must exist
 - reflect.md must exist in run_dir (REFLECT phase complete)
 - <!-- LIFECYCLE:REFLECTION --> must NOT already exist in plan.md (idempotent guard)
 
@@ -40,7 +41,16 @@ The reflection_record should contain: execution quality assessment, plan design
     const executionFile = path.join(runDir, "execution.md");
     const reflectFile = path.join(runDir, "reflect.md");
 
-    // Guard 1: plan.md must exist
+    const phaseCheck = await assertPhaseAtLeast(runDir, "reflect");
+    if (!phaseCheck.ok) {
+      return JSON.stringify({
+        success: false,
+        code: "PHASE_NOT_READY",
+        reason: phaseCheck.reason,
+        next_action: "Complete EXECUTE phase and call lifecycle_record_execution first",
+      });
+    }
+
     if (!(await fileExists(planFile))) {
       return JSON.stringify({
         success: false,
@@ -50,7 +60,7 @@ The reflection_record should contain: execution quality assessment, plan design
       });
     }
 
-    // Guard 2: execution.md must exist and contain EXECUTION:SUMMARY
+    // Guard 2: execution.md must exist
     if (!(await fileExists(executionFile))) {
       return JSON.stringify({
         success: false,
@@ -60,16 +70,6 @@ The reflection_record should contain: execution quality assessment, plan design
       });
     }
 
-    const executionContent = await fs.readFile(executionFile, "utf-8");
-    if (!executionContent.includes(EXECUTION_SUMMARY_MARKER)) {
-      return JSON.stringify({
-        success: false,
-        code: "EXECUTION_NOT_RECORDED",
-        reason: "Phase 4 summary (EXECUTION:SUMMARY) not yet recorded in execution.md",
-        next_action: "Call lifecycle_record_execution first to record Phase 4",
-      });
-    }
-
     // Guard 3: reflect.md must exist
     if (!(await fileExists(reflectFile))) {
       return JSON.stringify({

package/src/tools/lifecycle-start.ts

@@ -58,7 +58,7 @@ advances lifecycle-state.json to the next phase (plan→execute→reflect→done
           next_action: "Wait for the current lifecycle to complete before starting a new one.",
         });
       }
-      console.log(`[empirical-plan] lifecycle_start: stale map entry for session ${ctx.sessionID} (phase=${existingState?.phase ?? "missing"}), proceeding with new lifecycle`);
+
     }
 
     await fs.mkdir(runDir, { recursive: true });