@opencode_weave/weave 0.4.2 → 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/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

@@ -1877,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;
@@ -1892,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
       };
     }
   }
@@ -1934,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) {
@@ -1961,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) => {
@@ -1990,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}

package/package.json

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