@opencode_weave/weave 0.4.1 → 0.5.0

package/dist/features/work-state/index.d.ts

@@ -1,3 +1,5 @@
 export type { WorkState, PlanProgress } from "./types";
+export type { ValidationResult, ValidationIssue, ValidationSeverity, ValidationCategory } from "./validation-types";
 export { WEAVE_DIR, WORK_STATE_FILE, WORK_STATE_PATH, PLANS_DIR } from "./constants";
 export { readWorkState, writeWorkState, clearWorkState, appendSessionId, createWorkState, findPlans, getPlanProgress, getPlanName, } from "./storage";
+export { validatePlan } from "./validation";

package/dist/features/work-state/validation-types.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The 6 validation categories checked by validatePlan().
+ */
+export type ValidationCategory = "structure" | "checkboxes" | "file-references" | "numbering" | "effort-estimate" | "verification";
+/** Severity level for a validation issue. */
+export type ValidationSeverity = "error" | "warning";
+/**
+ * A single validation issue found in a plan file.
+ */
+export interface ValidationIssue {
+    severity: ValidationSeverity;
+    category: ValidationCategory;
+    message: string;
+}
+/**
+ * The result of validating a plan file.
+ * `valid` is false if there are any blocking errors.
+ */
+export interface ValidationResult {
+    /** False when there is at least one error (blocking). True when only warnings or clean. */
+    valid: boolean;
+    /** Blocking issues — prevent /start-work from proceeding */
+    errors: ValidationIssue[];
+    /** Non-blocking issues — surfaced to user but don't block execution */
+    warnings: ValidationIssue[];
+}

package/dist/features/work-state/validation.d.ts

@@ -0,0 +1,9 @@
+import type { ValidationResult } from "./validation-types";
+/**
+ * Validates a plan file's structure and content before /start-work execution.
+ *
+ * @param planPath  Absolute path to the plan markdown file
+ * @param projectDir  Absolute path to the project root (used for file-reference checks)
+ * @returns ValidationResult with errors (blocking) and warnings (non-blocking)
+ */
+export declare function validatePlan(planPath: string, projectDir: string): ValidationResult;

package/dist/hooks/index.d.ts

@@ -10,3 +10,5 @@ export { detectKeywords, buildKeywordInjection, processMessageForKeywords, DEFAU
 export type { KeywordAction } from "./keyword-detector";
 export { buildVerificationReminder } from "./verification-reminder";
 export type { VerificationInput, VerificationResult } from "./verification-reminder";
+export { setContextLimit, updateUsage, getState, clearSession as clearTokenSession, clear as clearAllTokenState, } from "./session-token-state";
+export type { SessionTokenEntry } from "./session-token-state";

package/dist/hooks/session-token-state.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Per-session token state tracker.
+ *
+ * Bridges the gap between:
+ * - `chat.params` hook → provides model context limit (maxTokens)
+ * - `message.updated` event → provides latest input token usage (usedTokens)
+ *
+ * Uses an in-memory Map keyed by sessionId. State resets on plugin restart,
+ * which is acceptable — data rebuilds on the next `chat.params` + `message.updated` pair.
+ */
+export interface SessionTokenEntry {
+    maxTokens: number;
+    usedTokens: number;
+}
+/**
+ * Store the model's context limit for a session.
+ * Called from the `chat.params` hook when a session starts.
+ * Does NOT overwrite existing `usedTokens`.
+ */
+export declare function setContextLimit(sessionId: string, maxTokens: number): void;
+/**
+ * Update the latest input token usage for a session.
+ * Called from `message.updated` events with AssistantMessage tokens.
+ * Stores the latest value — NOT cumulative across messages.
+ * Does NOT overwrite existing `maxTokens`.
+ * Only updates when inputTokens > 0 (guards against partial streaming updates).
+ */
+export declare function updateUsage(sessionId: string, inputTokens: number): void;
+/**
+ * Get the current token state for a session.
+ * Returns undefined if the session is unknown.
+ */
+export declare function getState(sessionId: string): SessionTokenEntry | undefined;
+/**
+ * Remove a session from the tracker.
+ * Called on `session.deleted` events.
+ */
+export declare function clearSession(sessionId: string): void;
+/**
+ * Clear all session state. Used in tests only.
+ */
+export declare function clear(): void;

package/dist/hooks/start-work-hook.d.ts

@@ -2,6 +2,7 @@
  * Start-work hook: detects the /start-work command, resolves the target plan,
  * creates/updates work state, and returns context for injection into the prompt.
  */
+import type { ValidationResult } from "../features/work-state";
 export interface StartWorkInput {
     promptText: string;
     sessionId: string;
@@ -18,3 +19,7 @@ export interface StartWorkResult {
  * Returns null contextInjection if this message is not a /start-work command.
  */
 export declare function handleStartWork(input: StartWorkInput): StartWorkResult;
+/**
+ * Format validation errors and warnings as a markdown string.
+ */
+export declare function formatValidationResults(result: ValidationResult): string;

package/dist/index.js

@@ -563,7 +563,9 @@ For complex tasks that benefit from structured planning before execution:
 1. PLAN: Delegate to Pattern to produce a plan saved to \`.weave/plans/{name}.md\`
    - Pattern researches the codebase, produces a structured plan with \`- [ ]\` checkboxes
    - Pattern ONLY writes .md files in .weave/ — it never writes code
-2. REVIEW (optional): For complex plans, delegate to Weft to validate the plan before execution
+2. REVIEW: Delegate to Weft to validate the plan before execution
+   - TRIGGER: Plan touches 3+ files OR has 5+ tasks — Weft review is mandatory
+   - SKIP ONLY IF: User explicitly says "skip review"
    - Weft reads the plan, verifies file references, checks executability
    - If Weft rejects, send issues back to Pattern for revision
 3. EXECUTE: Tell the user to run \`/start-work\` to begin execution
@@ -1875,6 +1877,286 @@ function getPlanProgress(planPath) {
 function getPlanName(planPath) {
   return basename(planPath, ".md");
 }
+// src/features/work-state/validation.ts
+import { readFileSync as readFileSync5, existsSync as existsSync6 } from "fs";
+import { resolve as resolve2 } from "path";
+function validatePlan(planPath, projectDir) {
+  const errors = [];
+  const warnings = [];
+  const resolvedPlanPath = resolve2(planPath);
+  const allowedDir = resolve2(projectDir, PLANS_DIR);
+  if (!resolvedPlanPath.startsWith(allowedDir + "/") && resolvedPlanPath !== allowedDir) {
+    errors.push({
+      severity: "error",
+      category: "structure",
+      message: `Plan path is outside the allowed directory (${PLANS_DIR}/): ${planPath}`
+    });
+    return { valid: false, errors, warnings };
+  }
+  if (!existsSync6(resolvedPlanPath)) {
+    errors.push({
+      severity: "error",
+      category: "structure",
+      message: `Plan file not found: ${planPath}`
+    });
+    return { valid: false, errors, warnings };
+  }
+  const content = readFileSync5(resolvedPlanPath, "utf-8");
+  validateStructure(content, errors, warnings);
+  validateCheckboxes(content, errors, warnings);
+  validateFileReferences(content, projectDir, warnings);
+  validateNumbering(content, errors, warnings);
+  validateEffortEstimate(content, warnings);
+  validateVerificationSection(content, errors);
+  return {
+    valid: errors.length === 0,
+    errors,
+    warnings
+  };
+}
+function extractSection(content, heading) {
+  const lines = content.split(`
+`);
+  let startIdx = -1;
+  for (let i = 0;i < lines.length; i++) {
+    if (lines[i].trim() === heading) {
+      startIdx = i + 1;
+      break;
+    }
+  }
+  if (startIdx === -1)
+    return null;
+  const sectionLines = [];
+  for (let i = startIdx;i < lines.length; i++) {
+    if (/^## /.test(lines[i]))
+      break;
+    sectionLines.push(lines[i]);
+  }
+  return sectionLines.join(`
+`);
+}
+function hasSection(content, heading) {
+  return content.split(`
+`).some((line) => line.trim() === heading);
+}
+function validateStructure(content, errors, warnings) {
+  const requiredSections = [
+    ["## TL;DR", "Missing required section: ## TL;DR"],
+    ["## TODOs", "Missing required section: ## TODOs"],
+    ["## Verification", "Missing required section: ## Verification"]
+  ];
+  for (const [heading, message] of requiredSections) {
+    if (!hasSection(content, heading)) {
+      errors.push({ severity: "error", category: "structure", message });
+    }
+  }
+  const optionalSections = [
+    ["## Context", "Missing optional section: ## Context"],
+    ["## Objectives", "Missing optional section: ## Objectives"]
+  ];
+  for (const [heading, message] of optionalSections) {
+    if (!hasSection(content, heading)) {
+      warnings.push({ severity: "warning", category: "structure", message });
+    }
+  }
+}
+function validateCheckboxes(content, errors, warnings) {
+  const todosSection = extractSection(content, "## TODOs");
+  if (todosSection === null) {
+    return;
+  }
+  const checkboxPattern = /^- \[[ x]\] /m;
+  if (!checkboxPattern.test(todosSection)) {
+    errors.push({
+      severity: "error",
+      category: "checkboxes",
+      message: "## TODOs section contains no checkboxes (- [ ] or - [x])"
+    });
+    return;
+  }
+  const lines = todosSection.split(`
+`);
+  let taskIndex = 0;
+  for (let i = 0;i < lines.length; i++) {
+    const line = lines[i];
+    if (/^- \[[ x]\] /.test(line)) {
+      taskIndex++;
+      const taskLabel = `Task ${taskIndex}`;
+      const bodyLines = [];
+      let j = i + 1;
+      while (j < lines.length && !/^- \[[ x]\] /.test(lines[j])) {
+        bodyLines.push(lines[j]);
+        j++;
+      }
+      const body = bodyLines.join(`
+`);
+      if (!/\*\*What\*\*/.test(body)) {
+        warnings.push({
+          severity: "warning",
+          category: "checkboxes",
+          message: `${taskLabel} is missing **What** sub-field`
+        });
+      }
+      if (!/\*\*Files\*\*/.test(body)) {
+        warnings.push({
+          severity: "warning",
+          category: "checkboxes",
+          message: `${taskLabel} is missing **Files** sub-field`
+        });
+      }
+      if (!/\*\*Acceptance\*\*/.test(body)) {
+        warnings.push({
+          severity: "warning",
+          category: "checkboxes",
+          message: `${taskLabel} is missing **Acceptance** sub-field`
+        });
+      }
+    }
+  }
+}
+var NEW_FILE_INDICATORS = [
+  /^\s*create\s+/i,
+  /^\s*new:\s*/i,
+  /\(new\)/i,
+  /^\s*add\s+/i
+];
+function isNewFile(rawPath) {
+  return NEW_FILE_INDICATORS.some((re) => re.test(rawPath));
+}
+function extractFilePath(raw) {
+  let cleaned = raw.replace(/^\s*(create|modify|new:|add)\s+/i, "").replace(/\(new\)/gi, "").trim();
+  const firstToken = cleaned.split(/\s+/)[0];
+  if (firstToken && (firstToken.includes("/") || firstToken.endsWith(".ts") || firstToken.endsWith(".js") || firstToken.endsWith(".json") || firstToken.endsWith(".md"))) {
+    cleaned = firstToken;
+  } else if (!cleaned.includes("/")) {
+    return null;
+  }
+  return cleaned || null;
+}
+function validateFileReferences(content, projectDir, warnings) {
+  const todosSection = extractSection(content, "## TODOs");
+  if (todosSection === null)
+    return;
+  const lines = todosSection.split(`
+`);
+  for (const line of lines) {
+    const filesMatch = /^\s*\*\*Files\*\*:?\s*(.+)$/.exec(line);
+    if (!filesMatch)
+      continue;
+    const rawValue = filesMatch[1].trim();
+    const parts = rawValue.split(",");
+    for (const part of parts) {
+      const trimmed = part.trim();
+      if (!trimmed)
+        continue;
+      const newFile = isNewFile(trimmed);
+      const filePath = extractFilePath(trimmed);
+      if (!filePath)
+        continue;
+      if (newFile)
+        continue;
+      if (filePath.startsWith("/")) {
+        warnings.push({
+          severity: "warning",
+          category: "file-references",
+          message: `Absolute file path not allowed in plan references: ${filePath}`
+        });
+        continue;
+      }
+      const resolvedProject = resolve2(projectDir);
+      const absolutePath = resolve2(projectDir, filePath);
+      if (!absolutePath.startsWith(resolvedProject + "/") && absolutePath !== resolvedProject) {
+        warnings.push({
+          severity: "warning",
+          category: "file-references",
+          message: `File reference escapes project directory (path traversal): ${filePath}`
+        });
+        continue;
+      }
+      if (!existsSync6(absolutePath)) {
+        warnings.push({
+          severity: "warning",
+          category: "file-references",
+          message: `Referenced file does not exist (may be created by an earlier task): ${filePath}`
+        });
+      }
+    }
+  }
+}
+function validateNumbering(content, errors, warnings) {
+  const todosSection = extractSection(content, "## TODOs");
+  if (todosSection === null)
+    return;
+  const numbers = [];
+  const seen = new Set;
+  for (const line of todosSection.split(`
+`)) {
+    const match = /^- \[[ x]\] (\d+)\./.exec(line);
+    if (!match)
+      continue;
+    const n = parseInt(match[1], 10);
+    if (seen.has(n)) {
+      errors.push({
+        severity: "error",
+        category: "numbering",
+        message: `Duplicate task number: ${n}`
+      });
+    } else {
+      seen.add(n);
+      numbers.push(n);
+    }
+  }
+  if (numbers.length < 2)
+    return;
+  const sorted = [...numbers].sort((a, b) => a - b);
+  for (let i = 1;i < sorted.length; i++) {
+    if (sorted[i] !== sorted[i - 1] + 1) {
+      warnings.push({
+        severity: "warning",
+        category: "numbering",
+        message: `Gap in task numbering: expected ${sorted[i - 1] + 1} but found ${sorted[i]}`
+      });
+    }
+  }
+}
+var VALID_EFFORT_VALUES = ["quick", "short", "medium", "large", "xl"];
+function validateEffortEstimate(content, warnings) {
+  const tldrSection = extractSection(content, "## TL;DR");
+  if (tldrSection === null) {
+    return;
+  }
+  const effortMatch = /\*\*Estimated Effort\*\*:?\s*(.+)/i.exec(tldrSection);
+  if (!effortMatch) {
+    warnings.push({
+      severity: "warning",
+      category: "effort-estimate",
+      message: "Missing **Estimated Effort** in ## TL;DR section"
+    });
+    return;
+  }
+  const value = effortMatch[1].trim().toLowerCase();
+  if (!VALID_EFFORT_VALUES.includes(value)) {
+    warnings.push({
+      severity: "warning",
+      category: "effort-estimate",
+      message: `Invalid effort estimate value: "${effortMatch[1].trim()}". Expected one of: Quick, Short, Medium, Large, XL`
+    });
+  }
+}
+function validateVerificationSection(content, errors) {
+  const verificationSection = extractSection(content, "## Verification");
+  if (verificationSection === null) {
+    return;
+  }
+  const hasCheckbox = /^- \[[ x]\] /m.test(verificationSection);
+  if (!hasCheckbox) {
+    errors.push({
+      severity: "error",
+      category: "verification",
+      message: "## Verification section contains no checkboxes — at least one verifiable condition is required"
+    });
+  }
+}
 // src/hooks/start-work-hook.ts
 function handleStartWork(input) {
   const { promptText, sessionId, directory } = input;
@@ -1890,10 +2172,33 @@ function handleStartWork(input) {
   if (existingState) {
     const progress = getPlanProgress(existingState.active_plan);
     if (!progress.isComplete) {
+      const validation = validatePlan(existingState.active_plan, directory);
+      if (!validation.valid) {
+        clearWorkState(directory);
+        return {
+          switchAgent: "tapestry",
+          contextInjection: `## Plan Validation Failed
+The active plan "${existingState.plan_name}" has structural issues. Work state has been cleared.
+
+${formatValidationResults(validation)}
+
+Tell the user to fix the plan file and run /start-work again.`
+        };
+      }
       appendSessionId(directory, sessionId);
+      const resumeContext = buildResumeContext(existingState.active_plan, existingState.plan_name, progress);
+      if (validation.warnings.length > 0) {
+        return {
+          switchAgent: "tapestry",
+          contextInjection: `${resumeContext}
+
+### Validation Warnings
+${formatValidationResults(validation)}`
+        };
+      }
       return {
         switchAgent: "tapestry",
-        contextInjection: buildResumeContext(existingState.active_plan, existingState.plan_name, progress)
+        contextInjection: resumeContext
       };
     }
   }
@@ -1932,12 +2237,34 @@ The plan "${getPlanName(matched)}" has all ${progress.total} tasks completed.
 Tell the user this plan is already done and suggest creating a new one with Pattern.`
     };
   }
+  const validation = validatePlan(matched, directory);
+  if (!validation.valid) {
+    return {
+      switchAgent: "tapestry",
+      contextInjection: `## Plan Validation Failed
+The plan "${getPlanName(matched)}" has structural issues that must be fixed before execution can begin.
+
+${formatValidationResults(validation)}
+
+Tell the user to fix these issues in the plan file and try again.`
+    };
+  }
   clearWorkState(directory);
   const state = createWorkState(matched, sessionId, "tapestry");
   writeWorkState(directory, state);
+  const freshContext = buildFreshContext(matched, getPlanName(matched), progress);
+  if (validation.warnings.length > 0) {
+    return {
+      switchAgent: "tapestry",
+      contextInjection: `${freshContext}
+
+### Validation Warnings
+${formatValidationResults(validation)}`
+    };
+  }
   return {
     switchAgent: "tapestry",
-    contextInjection: buildFreshContext(matched, getPlanName(matched), progress)
+    contextInjection: freshContext
   };
 }
 function handlePlanDiscovery(allPlans, sessionId, directory) {
@@ -1959,11 +2286,33 @@ Tell the user to switch to Pattern agent to create a new plan.`
   if (incompletePlans.length === 1) {
     const plan = incompletePlans[0];
     const progress = getPlanProgress(plan);
+    const validation = validatePlan(plan, directory);
+    if (!validation.valid) {
+      return {
+        switchAgent: "tapestry",
+        contextInjection: `## Plan Validation Failed
+The plan "${getPlanName(plan)}" has structural issues that must be fixed before execution can begin.
+
+${formatValidationResults(validation)}
+
+Tell the user to fix these issues in the plan file and try again.`
+      };
+    }
     const state = createWorkState(plan, sessionId, "tapestry");
     writeWorkState(directory, state);
+    const freshContext = buildFreshContext(plan, getPlanName(plan), progress);
+    if (validation.warnings.length > 0) {
+      return {
+        switchAgent: "tapestry",
+        contextInjection: `${freshContext}
+
+### Validation Warnings
+${formatValidationResults(validation)}`
+      };
+    }
     return {
       switchAgent: "tapestry",
-      contextInjection: buildFreshContext(plan, getPlanName(plan), progress)
+      contextInjection: freshContext
     };
   }
   const listing = incompletePlans.map((p) => {
@@ -1988,6 +2337,25 @@ function findPlanByName(plans, requestedName) {
   const partial = plans.find((p) => getPlanName(p).toLowerCase().includes(lower));
   return partial || null;
 }
+function formatValidationResults(result) {
+  const lines = [];
+  if (result.errors.length > 0) {
+    lines.push("**Errors (blocking):**");
+    for (const err of result.errors) {
+      lines.push(`- [${err.category}] ${err.message}`);
+    }
+  }
+  if (result.warnings.length > 0) {
+    if (result.errors.length > 0)
+      lines.push("");
+    lines.push("**Warnings:**");
+    for (const warn of result.warnings) {
+      lines.push(`- [${warn.category}] ${warn.message}`);
+    }
+  }
+  return lines.join(`
+`);
+}
 function buildFreshContext(planPath, planName, progress) {
   return `## Starting Plan: ${planName}
 **Plan file**: ${planPath}
@@ -2074,12 +2442,12 @@ Only mark complete when ALL checks pass.`
 
 // src/hooks/create-hooks.ts
 function createHooks(args) {
-  const { isHookEnabled, directory } = args;
+  const { pluginConfig, isHookEnabled, directory } = args;
   const writeGuardState = createWriteGuardState();
   const writeGuard = createWriteGuard(writeGuardState);
   const contextWindowThresholds = {
-    warningPct: 0.8,
-    criticalPct: 0.95
+    warningPct: pluginConfig.experimental?.context_window_warning_threshold ?? 0.8,
+    criticalPct: pluginConfig.experimental?.context_window_critical_threshold ?? 0.95
   };
   return {
     checkContextWindow: isHookEnabled("context-window-monitor") ? (state) => checkContextWindow(state, contextWindowThresholds) : null,
@@ -2094,7 +2462,30 @@ function createHooks(args) {
     verificationReminder: isHookEnabled("verification-reminder") ? buildVerificationReminder : null
   };
 }
-
+// src/hooks/session-token-state.ts
+var sessionMap = new Map;
+function setContextLimit(sessionId, maxTokens) {
+  const existing = sessionMap.get(sessionId);
+  sessionMap.set(sessionId, {
+    usedTokens: existing?.usedTokens ?? 0,
+    maxTokens
+  });
+}
+function updateUsage(sessionId, inputTokens) {
+  if (inputTokens <= 0)
+    return;
+  const existing = sessionMap.get(sessionId);
+  sessionMap.set(sessionId, {
+    maxTokens: existing?.maxTokens ?? 0,
+    usedTokens: inputTokens
+  });
+}
+function getState(sessionId) {
+  return sessionMap.get(sessionId);
+}
+function clearSession2(sessionId) {
+  sessionMap.delete(sessionId);
+}
 // src/plugin/plugin-interface.ts
 function createPluginInterface(args) {
   const { pluginConfig, hooks, tools, configHandler, agents, client } = args;
@@ -2114,13 +2505,6 @@ function createPluginInterface(args) {
     },
     "chat.message": async (input, _output) => {
       const { sessionID } = input;
-      if (hooks.checkContextWindow) {
-        hooks.checkContextWindow({
-          usedTokens: 0,
-          maxTokens: 0,
-          sessionId: sessionID
-        });
-      }
       if (hooks.firstMessageVariant) {
         if (hooks.firstMessageVariant.shouldApplyVariant(sessionID)) {
           hooks.firstMessageVariant.markApplied(sessionID);
@@ -2159,7 +2543,15 @@ ${result.contextInjection}`;
         }
       }
     },
-    "chat.params": async (_input, _output) => {},
+    "chat.params": async (_input, _output) => {
+      const input = _input;
+      const sessionId = input.sessionID ?? "";
+      const maxTokens = input.model?.limit?.context ?? 0;
+      if (sessionId && maxTokens > 0) {
+        setContextLimit(sessionId, maxTokens);
+        log("[context-window] Captured context limit", { sessionId, maxTokens });
+      }
+    },
     "chat.headers": async (_input, _output) => {},
     event: async (input) => {
       const { event } = input;
@@ -2173,6 +2565,35 @@ ${result.contextInjection}`;
           hooks.firstMessageVariant.clearSession(evt.properties.info.id);
         }
       }
+      if (event.type === "session.deleted") {
+        const evt = event;
+        clearSession2(evt.properties.info.id);
+      }
+      if (event.type === "message.updated" && hooks.checkContextWindow) {
+        const evt = event;
+        const info = evt.properties?.info;
+        if (info?.role === "assistant" && info.sessionID) {
+          const inputTokens = info.tokens?.input ?? 0;
+          if (inputTokens > 0) {
+            updateUsage(info.sessionID, inputTokens);
+            const tokenState = getState(info.sessionID);
+            if (tokenState && tokenState.maxTokens > 0) {
+              const result = hooks.checkContextWindow({
+                usedTokens: tokenState.usedTokens,
+                maxTokens: tokenState.maxTokens,
+                sessionId: info.sessionID
+              });
+              if (result.action !== "none") {
+                log("[context-window] Threshold crossed", {
+                  sessionId: info.sessionID,
+                  action: result.action,
+                  usagePct: result.usagePct
+                });
+              }
+            }
+          }
+        }
+      }
       if (hooks.workContinuation && event.type === "session.idle") {
         const evt = event;
         const sessionId = evt.properties?.sessionID ?? "";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opencode_weave/weave",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "description": "Weave — lean OpenCode plugin with multi-agent orchestration",
   "author": "Weave",
   "license": "MIT",