specweave 0.21.3 → 0.22.2

package/plugins/specweave-github/agents/github-manager/AGENT.md

@@ -1,6 +1,38 @@
 # GitHub Manager Agent
 
-**Role**: GitHub integration specialist for SpecWeave increments
+⚠️ **DEPRECATED: Use Living Docs Sync Instead** ⚠️
+
+**CRITICAL**: This agent creates GitHub issues using the OLD `[Increment XXXX]` format,
+which violates SpecWeave's data flow architecture.
+
+**CORRECT DATA FLOW**:
+```
+Increment → Living Docs → GitHub
+            (source of truth)
+```
+
+**USE INSTEAD**:
+- `/specweave:sync-docs update` - Generate living docs from increments
+- `/specweave-github:sync` - Sync living docs to GitHub Issues
+- Result: Issues use correct `US-XXX` or `FS-YY-MM-DD` format
+
+**WHY THIS IS DEPRECATED**:
+1. Creates issues with `[Increment XXXX]` format (rejected by validation)
+2. Bypasses living docs (source of truth)
+3. No traceability to User Stories/Feature Specs
+4. Cannot sync bidirectionally with living docs
+
+**IF YOU USE THIS AGENT**: GitHub client will REJECT issue creation with error:
+```
+❌ DEPRECATED FORMAT DETECTED: "[Increment 0043] Title"
+GitHub issues MUST use living docs format:
+  ✅ CORRECT: "US-XXX: Title" (User Story)
+  ✅ CORRECT: "FS-YY-MM-DD: Title" (Feature Spec)
+```
+
+---
+
+**Role**: GitHub integration specialist for SpecWeave increments (DEPRECATED)
 
 **Expertise**: GitHub CLI, GitHub API, issue management, project boards, automation, webhooks, Actions
 
@@ -143,9 +175,9 @@ Invoke the github-manager agent (via Task tool) for:
 ### Issue Management
 
 ```bash
-# Create issue
+# ❌ DEPRECATED - Create issue (OLD FORMAT - DO NOT USE)
 gh issue create \
-  --title "[Increment 0004] Plugin Architecture" \
+  --title "[Increment 0004] Plugin Architecture" \  # ❌ DEPRECATED
   --body "$(cat issue-body.md)" \
   --label "specweave,increment,P1" \
   --milestone "v0.4.0"
@@ -384,10 +416,10 @@ When a new increment is created:
    - Parse `tasks.md` for task checklist
    - Format using issue template
 
-4. **Create GitHub Issue**
+4. **Create GitHub Issue** (❌ DEPRECATED - DO NOT USE)
    ```bash
    gh issue create \
-     --title "[Increment 0004] Plugin Architecture" \
+     --title "[Increment 0004] Plugin Architecture" \  # ❌ DEPRECATED
      --body "$(cat /tmp/issue-body.md)" \
      --label "specweave,increment,P1" \
      --milestone "v0.4.0"
@@ -680,9 +712,9 @@ GitHub Manager Agent:
 5. Updating metadata...
    ✓ Saved to .metadata.yaml
 
-✅ GitHub Issue Created!
+✅ GitHub Issue Created! (❌ DEPRECATED FORMAT)
 
-Issue #130: [Increment 0004] Plugin Architecture
+Issue #130: [Increment 0004] Plugin Architecture  # ❌ DEPRECATED
 URL: https://github.com/owner/repo/issues/130
 
 You can now:

package/plugins/specweave-github/commands/specweave-github-create-issue.md

@@ -175,9 +175,9 @@ Creating issue...
 ✓ Milestone set: v0.4.0
 ✓ Metadata updated
 
-✅ GitHub Issue Created!
+✅ GitHub Issue Created! (❌ DEPRECATED FORMAT)
 
-Issue #130: [Increment 0004] Plugin Architecture
+Issue #130: [Increment 0004] Plugin Architecture  # ❌ DEPRECATED
 URL: https://github.com/owner/repo/issues/130
 
 Auto-sync enabled: progress will update automatically after each task.
@@ -274,15 +274,15 @@ Preview issue body before creating:
 
 Output:
 ```
-📄 Preview: Issue body for increment 0004
+📄 Preview: Issue body for increment 0004 (❌ DEPRECATED FORMAT)
 
-Title: [Increment 0004] Plugin Architecture
+Title: [Increment 0004] Plugin Architecture  # ❌ DEPRECATED
 Labels: specweave, increment, P1
 Milestone: v0.4.0
 
 Body:
 ---
-# [Increment 0004] Plugin Architecture
+# [Increment 0004] Plugin Architecture  # ❌ DEPRECATED
 
 **Status**: Planning
 **Priority**: P1

package/plugins/specweave-github/lib/CodeValidator.js

@@ -0,0 +1,195 @@
+import fs from "fs-extra";
+import path from "path";
+class CodeValidator {
+  constructor(options = {}) {
+    this.options = {
+      minLines: options.minLines ?? 3,
+      minChars: options.minChars ?? 50,
+      projectRoot: options.projectRoot ?? process.cwd()
+    };
+  }
+  /**
+   * Validate that code exists for a task
+   *
+   * Extracts file paths from task description and verifies:
+   * 1. Files exist
+   * 2. Files have meaningful content
+   * 3. Files are not just stubs
+   *
+   * @param taskDescription - Task description with file paths
+   * @param taskId - Task ID for error messages
+   * @returns Validation result
+   */
+  async validateTask(taskDescription, taskId) {
+    const filePaths = this.extractFilePaths(taskDescription);
+    if (filePaths.length === 0) {
+      return {
+        taskId,
+        valid: true,
+        files: [],
+        reason: "No file paths specified in task description"
+      };
+    }
+    const fileResults = [];
+    let allValid = true;
+    const reasons = [];
+    for (const filePath of filePaths) {
+      const result = await this.validateFile(filePath);
+      fileResults.push(result);
+      if (!result.exists) {
+        allValid = false;
+        reasons.push(`File not found: ${filePath}`);
+      } else if (!result.hasContent) {
+        allValid = false;
+        reasons.push(`File has no meaningful content: ${filePath} (${result.reason})`);
+      }
+    }
+    return {
+      taskId,
+      valid: allValid,
+      files: fileResults,
+      reason: reasons.length > 0 ? reasons.join("; ") : void 0
+    };
+  }
+  /**
+   * Validate a single file
+   *
+   * @param filePath - Path to file (relative or absolute)
+   * @returns File validation result
+   */
+  async validateFile(filePath) {
+    const absolutePath = path.isAbsolute(filePath) ? filePath : path.join(this.options.projectRoot, filePath);
+    const exists = await fs.pathExists(absolutePath);
+    if (!exists) {
+      return {
+        path: filePath,
+        exists: false,
+        hasContent: false,
+        lineCount: 0,
+        reason: "File does not exist"
+      };
+    }
+    const content = await fs.readFile(absolutePath, "utf-8");
+    const lines = content.split("\n");
+    const nonEmptyLines = lines.filter((line) => line.trim().length > 0);
+    if (nonEmptyLines.length < this.options.minLines) {
+      return {
+        path: filePath,
+        exists: true,
+        hasContent: false,
+        lineCount: nonEmptyLines.length,
+        reason: `Only ${nonEmptyLines.length} non-empty lines (minimum: ${this.options.minLines})`
+      };
+    }
+    const trimmedContent = content.trim();
+    if (trimmedContent.length < this.options.minChars) {
+      return {
+        path: filePath,
+        exists: true,
+        hasContent: false,
+        lineCount: nonEmptyLines.length,
+        reason: `Only ${trimmedContent.length} characters (minimum: ${this.options.minChars})`
+      };
+    }
+    const stubPatterns = [
+      /^\/\/\s*TODO:/i,
+      /^#\s*TODO:/i,
+      /^\s*throw new Error\(['"]Not implemented['"]\)/i,
+      /^\s*return null;?\s*$/m,
+      /^\s*pass\s*$/m,
+      // Python
+      /^\s*\.\.\.$/m
+      // TypeScript
+    ];
+    const isStub = stubPatterns.some((pattern) => pattern.test(trimmedContent));
+    if (isStub) {
+      return {
+        path: filePath,
+        exists: true,
+        hasContent: false,
+        lineCount: nonEmptyLines.length,
+        reason: "File contains stub/placeholder code"
+      };
+    }
+    return {
+      path: filePath,
+      exists: true,
+      hasContent: true,
+      lineCount: nonEmptyLines.length
+    };
+  }
+  /**
+   * Extract file paths from task description
+   *
+   * Supports multiple formats:
+   * - **Files**: src/foo.ts, src/bar.ts
+   * - **Files to create**: src/foo.ts
+   * - **Files to modify**: src/bar.ts
+   * - Inline code blocks with file paths
+   *
+   * @param description - Task description text
+   * @returns Array of file paths
+   */
+  extractFilePaths(description) {
+    const paths = /* @__PURE__ */ new Set();
+    const filesMatch = description.match(/\*\*Files\*\*:\s*([^\n]+)/i);
+    if (filesMatch) {
+      const filePaths = filesMatch[1].split(",").map((p) => p.trim());
+      filePaths.forEach((p) => paths.add(p));
+    }
+    const createMatch = description.match(/\*\*Files to create\*\*:\s*([^\n]+)/i);
+    if (createMatch) {
+      const filePaths = createMatch[1].split(",").map((p) => p.trim());
+      filePaths.forEach((p) => paths.add(p));
+    }
+    const modifyMatch = description.match(/\*\*Files to modify\*\*:\s*([^\n]+)/i);
+    if (modifyMatch) {
+      const filePaths = modifyMatch[1].split(",").map((p) => p.trim());
+      filePaths.forEach((p) => paths.add(p));
+    }
+    const inlineMatches = description.matchAll(/`([a-zA-Z0-9_\-./]+\.(ts|js|tsx|jsx|py|java|go|rs|cpp|c|h))`/g);
+    for (const match of inlineMatches) {
+      paths.add(match[1]);
+    }
+    const listMatches = description.matchAll(/^[-*]\s+([a-zA-Z0-9_\-./]+\.(ts|js|tsx|jsx|py|java|go|rs|cpp|c|h))/gm);
+    for (const match of listMatches) {
+      paths.add(match[1]);
+    }
+    return Array.from(paths);
+  }
+  /**
+   * Batch validate multiple tasks
+   *
+   * @param tasks - Array of {taskId, description}
+   * @returns Array of validation results
+   */
+  async validateTasks(tasks) {
+    const validationPromises = tasks.map(
+      (task) => this.validateTask(task.description, task.taskId)
+    );
+    return Promise.all(validationPromises);
+  }
+  /**
+   * Get summary of validation results
+   *
+   * @param results - Array of task validation results
+   * @returns Summary statistics
+   */
+  summarizeResults(results) {
+    const total = results.length;
+    const valid = results.filter((r) => r.valid).length;
+    const invalid = results.filter((r) => !r.valid).length;
+    const noFiles = results.filter((r) => r.files.length === 0).length;
+    const invalidTasks = results.filter((r) => !r.valid).map((r) => r.taskId);
+    return {
+      total,
+      valid,
+      invalid,
+      noFiles,
+      invalidTasks
+    };
+  }
+}
+export {
+  CodeValidator
+};

package/plugins/specweave-github/lib/CodeValidator.ts

@@ -0,0 +1,284 @@
+/**
+ * Code Validator
+ *
+ * Validates that completed tasks have actual code implementation.
+ * Prevents marking tasks as complete when:
+ * - Files don't exist
+ * - Files are empty or have trivial content
+ * - Implementation is incomplete
+ *
+ * Used by GitHub sync to enforce code-completion discipline.
+ *
+ * @module CodeValidator
+ */
+
+import fs from 'fs-extra';
+import path from 'path';
+
+/**
+ * File validation result
+ */
+export interface FileValidationResult {
+  path: string;
+  exists: boolean;
+  hasContent: boolean;
+  lineCount: number;
+  reason?: string; // Why validation failed
+}
+
+/**
+ * Task validation result
+ */
+export interface TaskValidationResult {
+  taskId: string;
+  valid: boolean;
+  files: FileValidationResult[];
+  reason?: string; // Summary of why task validation failed
+}
+
+/**
+ * CodeValidator options
+ */
+export interface CodeValidatorOptions {
+  minLines?: number; // Minimum lines for a file to be considered non-empty (default: 3)
+  minChars?: number; // Minimum characters for meaningful content (default: 50)
+  projectRoot?: string; // Project root for resolving relative paths
+}
+
+export class CodeValidator {
+  private options: Required<CodeValidatorOptions>;
+
+  constructor(options: CodeValidatorOptions = {}) {
+    this.options = {
+      minLines: options.minLines ?? 3,
+      minChars: options.minChars ?? 50,
+      projectRoot: options.projectRoot ?? process.cwd()
+    };
+  }
+
+  /**
+   * Validate that code exists for a task
+   *
+   * Extracts file paths from task description and verifies:
+   * 1. Files exist
+   * 2. Files have meaningful content
+   * 3. Files are not just stubs
+   *
+   * @param taskDescription - Task description with file paths
+   * @param taskId - Task ID for error messages
+   * @returns Validation result
+   */
+  async validateTask(taskDescription: string, taskId: string): Promise<TaskValidationResult> {
+    const filePaths = this.extractFilePaths(taskDescription);
+
+    if (filePaths.length === 0) {
+      // No file paths specified - consider it valid (task might be non-code)
+      return {
+        taskId,
+        valid: true,
+        files: [],
+        reason: 'No file paths specified in task description'
+      };
+    }
+
+    const fileResults: FileValidationResult[] = [];
+    let allValid = true;
+    const reasons: string[] = [];
+
+    for (const filePath of filePaths) {
+      const result = await this.validateFile(filePath);
+      fileResults.push(result);
+
+      if (!result.exists) {
+        allValid = false;
+        reasons.push(`File not found: ${filePath}`);
+      } else if (!result.hasContent) {
+        allValid = false;
+        reasons.push(`File has no meaningful content: ${filePath} (${result.reason})`);
+      }
+    }
+
+    return {
+      taskId,
+      valid: allValid,
+      files: fileResults,
+      reason: reasons.length > 0 ? reasons.join('; ') : undefined
+    };
+  }
+
+  /**
+   * Validate a single file
+   *
+   * @param filePath - Path to file (relative or absolute)
+   * @returns File validation result
+   */
+  async validateFile(filePath: string): Promise<FileValidationResult> {
+    // Resolve relative paths
+    const absolutePath = path.isAbsolute(filePath)
+      ? filePath
+      : path.join(this.options.projectRoot, filePath);
+
+    // Check if file exists
+    const exists = await fs.pathExists(absolutePath);
+    if (!exists) {
+      return {
+        path: filePath,
+        exists: false,
+        hasContent: false,
+        lineCount: 0,
+        reason: 'File does not exist'
+      };
+    }
+
+    // Read file content
+    const content = await fs.readFile(absolutePath, 'utf-8');
+    const lines = content.split('\n');
+    const nonEmptyLines = lines.filter(line => line.trim().length > 0);
+
+    // Check line count
+    if (nonEmptyLines.length < this.options.minLines) {
+      return {
+        path: filePath,
+        exists: true,
+        hasContent: false,
+        lineCount: nonEmptyLines.length,
+        reason: `Only ${nonEmptyLines.length} non-empty lines (minimum: ${this.options.minLines})`
+      };
+    }
+
+    // Check character count
+    const trimmedContent = content.trim();
+    if (trimmedContent.length < this.options.minChars) {
+      return {
+        path: filePath,
+        exists: true,
+        hasContent: false,
+        lineCount: nonEmptyLines.length,
+        reason: `Only ${trimmedContent.length} characters (minimum: ${this.options.minChars})`
+      };
+    }
+
+    // Check for stub patterns (common placeholder patterns)
+    const stubPatterns = [
+      /^\/\/\s*TODO:/i,
+      /^#\s*TODO:/i,
+      /^\s*throw new Error\(['"]Not implemented['"]\)/i,
+      /^\s*return null;?\s*$/m,
+      /^\s*pass\s*$/m, // Python
+      /^\s*\.\.\.$/m    // TypeScript
+    ];
+
+    const isStub = stubPatterns.some(pattern => pattern.test(trimmedContent));
+    if (isStub) {
+      return {
+        path: filePath,
+        exists: true,
+        hasContent: false,
+        lineCount: nonEmptyLines.length,
+        reason: 'File contains stub/placeholder code'
+      };
+    }
+
+    // All checks passed
+    return {
+      path: filePath,
+      exists: true,
+      hasContent: true,
+      lineCount: nonEmptyLines.length
+    };
+  }
+
+  /**
+   * Extract file paths from task description
+   *
+   * Supports multiple formats:
+   * - **Files**: src/foo.ts, src/bar.ts
+   * - **Files to create**: src/foo.ts
+   * - **Files to modify**: src/bar.ts
+   * - Inline code blocks with file paths
+   *
+   * @param description - Task description text
+   * @returns Array of file paths
+   */
+  extractFilePaths(description: string): string[] {
+    const paths: Set<string> = new Set();
+
+    // Pattern 1: **Files**: path1, path2, path3
+    const filesMatch = description.match(/\*\*Files\*\*:\s*([^\n]+)/i);
+    if (filesMatch) {
+      const filePaths = filesMatch[1].split(',').map(p => p.trim());
+      filePaths.forEach(p => paths.add(p));
+    }
+
+    // Pattern 2: **Files to create**: path1, path2
+    const createMatch = description.match(/\*\*Files to create\*\*:\s*([^\n]+)/i);
+    if (createMatch) {
+      const filePaths = createMatch[1].split(',').map(p => p.trim());
+      filePaths.forEach(p => paths.add(p));
+    }
+
+    // Pattern 3: **Files to modify**: path1, path2
+    const modifyMatch = description.match(/\*\*Files to modify\*\*:\s*([^\n]+)/i);
+    if (modifyMatch) {
+      const filePaths = modifyMatch[1].split(',').map(p => p.trim());
+      filePaths.forEach(p => paths.add(p));
+    }
+
+    // Pattern 4: Inline file references (e.g., `src/foo/bar.ts`)
+    const inlineMatches = description.matchAll(/`([a-zA-Z0-9_\-./]+\.(ts|js|tsx|jsx|py|java|go|rs|cpp|c|h))`/g);
+    for (const match of inlineMatches) {
+      paths.add(match[1]);
+    }
+
+    // Pattern 5: Markdown list items with file paths
+    const listMatches = description.matchAll(/^[-*]\s+([a-zA-Z0-9_\-./]+\.(ts|js|tsx|jsx|py|java|go|rs|cpp|c|h))/gm);
+    for (const match of listMatches) {
+      paths.add(match[1]);
+    }
+
+    return Array.from(paths);
+  }
+
+  /**
+   * Batch validate multiple tasks
+   *
+   * @param tasks - Array of {taskId, description}
+   * @returns Array of validation results
+   */
+  async validateTasks(tasks: Array<{ taskId: string; description: string }>): Promise<TaskValidationResult[]> {
+    // Use parallel validation for performance
+    const validationPromises = tasks.map(task =>
+      this.validateTask(task.description, task.taskId)
+    );
+
+    return Promise.all(validationPromises);
+  }
+
+  /**
+   * Get summary of validation results
+   *
+   * @param results - Array of task validation results
+   * @returns Summary statistics
+   */
+  summarizeResults(results: TaskValidationResult[]): {
+    total: number;
+    valid: number;
+    invalid: number;
+    noFiles: number;
+    invalidTasks: string[];
+  } {
+    const total = results.length;
+    const valid = results.filter(r => r.valid).length;
+    const invalid = results.filter(r => !r.valid).length;
+    const noFiles = results.filter(r => r.files.length === 0).length;
+    const invalidTasks = results.filter(r => !r.valid).map(r => r.taskId);
+
+    return {
+      total,
+      valid,
+      invalid,
+      noFiles,
+      invalidTasks
+    };
+  }
+}