specweave 0.33.2 → 0.33.4

package/plugins/specweave/skills/increment-planner/templates/spec-multi-project.md

@@ -8,17 +8,18 @@ created: {{DATE}}
 structure: user-stories
 test_mode: {{TEST_MODE}}
 coverage_target: {{COVERAGE_TARGET}}
-# MANDATORY: Run "specweave context projects" to get valid project/board IDs
-# For 2-level structures: BOTH project AND board are REQUIRED
-project: {{PROJECT_ID}}
-board: {{BOARD_ID}}
+# MANDATORY: Must be RESOLVED values from "specweave context projects" output
+# ⛔ NEVER use {{PROJECT_ID}} or {{BOARD_ID}} placeholders!
+# For 2-level structures: BOTH project AND board are REQUIRED per US
+project: {{RESOLVED_PROJECT}}
+board: {{RESOLVED_BOARD}}
 multi_project: true
 projects:
-  - id: {{PROJECT_FE_ID}}
+  - id: {{RESOLVED_PROJECT_FE}}
     prefix: FE
-  - id: {{PROJECT_BE_ID}}
+  - id: {{RESOLVED_PROJECT_BE}}
     prefix: BE
-  - id: {{PROJECT_SHARED_ID}}
+  - id: {{RESOLVED_PROJECT_SHARED}}
     prefix: SHARED
 ---
 
@@ -30,13 +31,25 @@ projects:
 
 ## User Stories
 
-<!-- Each US has its own **Project** and **Board** fields. User can modify per-US anytime. -->
+<!--
+⚠️ MANDATORY RESOLUTION (v0.34.0+):
+1. Run: specweave context projects
+2. Parse JSON output:
+   - level 1: projects[].id gives valid project IDs
+   - level 2: projects[].id + boardsByProject[project][].id gives project AND board IDs
+3. Replace ALL placeholders with actual IDs from step 2
+4. Each US MUST have **Project**: (and **Board**: for 2-level) with RESOLVED values
+
+❌ FORBIDDEN: Using {{PROJECT_ID}}, {{BOARD_ID}} placeholders
+❌ FORBIDDEN: Inventing project/board names
+✅ REQUIRED: Use ONLY IDs from "specweave context projects" output
+-->
 
 ### Frontend Stories
 
 #### US-FE-001: [Story Title] (P1)
-**Project**: {{PROJECT_ID}}
-**Board**: {{BOARD_FE_ID}}
+**Project**: {{RESOLVED_PROJECT}}
+**Board**: {{RESOLVED_BOARD_FE}}
 
 **As a** [user type]
 **I want** [goal]
@@ -51,8 +64,8 @@ projects:
 ### Backend Stories
 
 #### US-BE-001: [Story Title] (P1)
-**Project**: {{PROJECT_ID}}
-**Board**: {{BOARD_BE_ID}}
+**Project**: {{RESOLVED_PROJECT}}
+**Board**: {{RESOLVED_BOARD_BE}}
 
 **As a** [system/frontend application]
 **I want** [API endpoint/service goal]
@@ -67,8 +80,8 @@ projects:
 ### Shared Library Stories
 
 #### US-SHARED-001: [Story Title] (P1)
-**Project**: {{PROJECT_ID}}
-**Board**: {{BOARD_SHARED_ID}}
+**Project**: {{RESOLVED_PROJECT}}
+**Board**: {{RESOLVED_BOARD_SHARED}}
 
 **As a** developer in FE or BE repos
 **I want** [shared types/utilities/validators]

package/plugins/specweave/skills/increment-planner/templates/spec-single-project.md

@@ -8,8 +8,9 @@ created: {{DATE}}
 structure: user-stories
 test_mode: {{TEST_MODE}}
 coverage_target: {{COVERAGE_TARGET}}
-# MANDATORY: Run "specweave context projects" to get valid project ID
-project: {{PROJECT_ID}}
+# MANDATORY: Must be a RESOLVED value from "specweave context projects" output
+# ⛔ NEVER use {{PROJECT_ID}} placeholder - always resolve BEFORE creating spec.md!
+project: {{RESOLVED_PROJECT}}
 ---
 
 # Feature: {{FEATURE_TITLE}}
@@ -20,10 +21,20 @@ project: {{PROJECT_ID}}
 
 ## User Stories
 
-<!-- Each US can have its own **Project** field. If omitted, uses default_project from frontmatter -->
+<!--
+⚠️ MANDATORY RESOLUTION (v0.34.0+):
+1. Run: specweave context projects
+2. Parse JSON: projects[].id gives valid project IDs
+3. Replace {{RESOLVED_PROJECT}} with actual ID from step 2
+4. Each US MUST have **Project**: field with RESOLVED value
+
+❌ FORBIDDEN: Using {{PROJECT_ID}} placeholder
+❌ FORBIDDEN: Inventing project names
+✅ REQUIRED: Use ONLY IDs from "specweave context projects" output
+-->
 
 ### US-001: [Story Title] (P1)
-**Project**: {{PROJECT_ID}}
+**Project**: {{RESOLVED_PROJECT}}
 
 **As a** [user type]
 **I want** [goal]
@@ -34,7 +45,7 @@ project: {{PROJECT_ID}}
 - [ ] **AC-US1-02**: [Another criterion]
 
 ### US-002: [Story Title] (P2)
-**Project**: {{PROJECT_ID}}
+**Project**: {{RESOLVED_PROJECT}}
 
 [Repeat structure - change Project per US if spanning multiple projects]
 

package/plugins/specweave/skills/spec-generator/SKILL.md

@@ -85,34 +85,93 @@ The LLM MUST resolve these from context - see RULE 0 in increment-planner.
 
 ---
 
+### MANDATORY STEP 0: Get Project Context FIRST (v0.34.0+ BLOCKING!)
+
+**⛔ YOU CANNOT GENERATE spec.md UNTIL YOU COMPLETE THIS STEP!**
+
+**This step is BLOCKING - do not proceed until you have actual project/board IDs.**
+
+**1. Run the context API command:**
+```bash
+specweave context projects
+```
+
+**2. Parse the JSON output:**
+```json
+{
+  "level": 1,
+  "projects": [{"id": "frontend-app", "name": "Frontend App"}],
+  "detectionReason": "multiProject configuration"
+}
+```
+For 2-level:
+```json
+{
+  "level": 2,
+  "projects": [{"id": "acme-corp", "name": "ACME Corp"}],
+  "boardsByProject": {
+    "acme-corp": [
+      {"id": "digital-ops", "name": "Digital Operations"},
+      {"id": "mobile-team", "name": "Mobile Team"}
+    ]
+  }
+}
+```
+
+**3. STORE the actual IDs for use in spec.md:**
+```
+RESOLVED_PROJECT = "frontend-app"  // from projects[].id
+RESOLVED_BOARD = "digital-ops"     // from boardsByProject (2-level only)
+```
+
+**4. Now generate spec.md using RESOLVED values (NEVER placeholders!)**
+
+---
+
 ### Per-US Project Resolution (v0.33.0+ MANDATORY)
 
-**🧠 USE ALL AVAILABLE CONTEXT TO RESOLVE PROJECT/BOARD:**
+**🧠 USE CONTEXT API OUTPUT + LIVING DOCS TO RESOLVE PROJECT/BOARD:**
 
-Before generating spec.md, analyze:
-1. **Living docs folders**: `ls .specweave/docs/internal/specs/` → actual project IDs
-2. **Recent increment patterns**: `grep "**Project**:" .specweave/increments/*/spec.md`
-3. **Config projectMappings**: Exact project IDs from config
-4. **Feature keywords**: Map to actual projects (not generic terms)
+After running `specweave context projects`, you have the valid project/board IDs.
+Now map each user story to the correct project:
+
+**Resolution Flow:**
+```
+1. Get valid projects from context API: ["frontend-app", "backend-api", "shared"]
+2. Analyze feature description for keywords
+3. Map keywords to ACTUAL project IDs (from step 1, NOT generic terms!)
+4. Assign each US to its project
+```
 
 **Resolution Example:**
 ```
+Context API returned: projects = ["frontend-app", "backend-api", "shared"]
+
 Feature: "Add OAuth login to React frontend"
-Detected: "React", "frontend", "login"
+Detected keywords: "React", "frontend", "login"
 
-Step 1: Check living docs → folders: frontend-app/, backend-api/, shared/
-Step 2: "frontend" keyword → matches "frontend-app" folder
-Step 3: Assign **Project**: frontend-app (NOT "frontend"!)
+Mapping:
+- "frontend" keyword → matches "frontend-app" (from context API)
+- "login" spans frontend + backend
 
-If cross-cutting ("OAuth" = both frontend + backend):
+Result:
   US-001 (Login UI) → **Project**: frontend-app
   US-002 (Auth API) → **Project**: backend-api
 ```
 
-**NEVER:**
-- ❌ Use generic keywords as project names ("frontend", "backend")
-- ❌ Ask user when context provides the answer
-- ❌ Leave `{{PROJECT_ID}}` placeholders
+**VALIDATION RULES:**
+
+```
+✅ REQUIRED: Run "specweave context projects" BEFORE generating spec.md
+✅ REQUIRED: Use ONLY project IDs from the API response
+✅ REQUIRED: Each US has explicit **Project**: field with resolved value
+✅ REQUIRED: For 2-level, each US has explicit **Board**: field with resolved value
+
+❌ FORBIDDEN: Generating spec.md without running context API first
+❌ FORBIDDEN: Using {{PROJECT_ID}} or {{BOARD_ID}} placeholders
+❌ FORBIDDEN: Using generic keywords as project names ("frontend" vs "frontend-app")
+❌ FORBIDDEN: Inventing project names not in the API response
+```
 
 ## Success Metrics
 [How we'll measure success]

package/plugins/specweave-ado/lib/per-us-sync.js

@@ -0,0 +1,247 @@
+import { consoleLogger } from "../../../src/utils/logger.js";
+class PerUSAdoSync {
+  constructor(adoClient, projectMappings, options = {}) {
+    this.adoClient = adoClient;
+    this.projectMappings = projectMappings;
+    this.logger = options.logger ?? consoleLogger;
+  }
+  /**
+   * Sync all user stories to their respective ADO projects
+   *
+   * @param userStories - User stories with explicit project/board fields
+   * @param featureId - Feature ID (e.g., "FS-137")
+   * @param options - Sync options
+   */
+  async syncUserStories(userStories, featureId, options = {}) {
+    const synced = [];
+    const failed = [];
+    const externalRefs = {};
+    const groups = this.groupByProject(userStories, options.defaultProject);
+    this.logger.log(`\u{1F4E1} Per-US ADO Sync: ${userStories.length} USs across ${groups.size} projects`);
+    for (const [projectId, stories] of groups) {
+      const mapping = this.projectMappings[projectId]?.ado;
+      if (!mapping) {
+        this.logger.warn(`   \u26A0\uFE0F  No ADO mapping for project "${projectId}" - skipping ${stories.length} USs`);
+        for (const story of stories) {
+          failed.push({
+            usId: story.id,
+            projectId,
+            adoProject: "N/A",
+            areaPath: "",
+            workItemId: 0,
+            url: "",
+            action: "skipped",
+            error: `No ADO mapping for project "${projectId}"`
+          });
+        }
+        continue;
+      }
+      for (const story of stories) {
+        try {
+          const result = await this.syncUserStory(story, mapping, featureId, options);
+          synced.push({
+            ...result,
+            projectId
+          });
+          if (!options.dryRun && result.action !== "skipped") {
+            externalRefs[story.id] = {
+              ado: {
+                provider: "ado",
+                issueNumber: result.workItemId,
+                url: result.url,
+                targetProject: projectId,
+                lastSynced: (/* @__PURE__ */ new Date()).toISOString()
+              }
+            };
+          }
+        } catch (error) {
+          failed.push({
+            usId: story.id,
+            projectId,
+            adoProject: mapping.project,
+            areaPath: mapping.areaPath || "",
+            workItemId: 0,
+            url: "",
+            action: "skipped",
+            error: error instanceof Error ? error.message : String(error)
+          });
+        }
+      }
+    }
+    const created = synced.filter((r) => r.action === "created").length;
+    const updated = synced.filter((r) => r.action === "updated").length;
+    const skipped = synced.filter((r) => r.action === "skipped").length;
+    return {
+      success: failed.length === 0,
+      synced,
+      failed,
+      externalRefs,
+      summary: {
+        total: userStories.length,
+        created,
+        updated,
+        skipped,
+        failed: failed.length
+      }
+    };
+  }
+  /**
+   * Sync a single user story to ADO
+   *
+   * For 2-level structures:
+   * - **Project**: maps to ADO project
+   * - **Board**: maps to area path under the project
+   */
+  async syncUserStory(story, mapping, featureId, options) {
+    const title = `[${featureId}][${story.id}] ${story.title}`;
+    const description = this.buildWorkItemDescription(story, featureId);
+    let areaPath = mapping.areaPath || mapping.project;
+    if (story.board) {
+      areaPath = `${mapping.project}\\${story.board}`;
+    }
+    if (options.dryRun) {
+      this.logger.log(`   \u{1F50D} [DRY-RUN] Would sync ${story.id} to ${mapping.project} (area: ${areaPath})`);
+      return {
+        usId: story.id,
+        projectId: story.project || "unknown",
+        adoProject: mapping.project,
+        areaPath,
+        workItemId: 0,
+        url: "",
+        action: "skipped"
+      };
+    }
+    const existingItem = await this.findExistingWorkItem(mapping.project, story.id);
+    if (existingItem) {
+      await this.adoClient.updateWorkItem(
+        mapping.project,
+        existingItem.id,
+        title,
+        description,
+        areaPath
+      );
+      this.logger.log(`   \u{1F504} Updated ${story.id} \u2192 ${mapping.project}/${existingItem.id}`);
+      return {
+        usId: story.id,
+        projectId: story.project || "unknown",
+        adoProject: mapping.project,
+        areaPath,
+        workItemId: existingItem.id,
+        url: this.adoClient.getWorkItemUrl(mapping.project, existingItem.id),
+        action: "updated"
+      };
+    } else {
+      const newItem = await this.adoClient.createWorkItem(
+        mapping.project,
+        "User Story",
+        title,
+        description,
+        areaPath
+      );
+      this.logger.log(`   \u2705 Created ${story.id} \u2192 ${mapping.project}/${newItem.id}`);
+      return {
+        usId: story.id,
+        projectId: story.project || "unknown",
+        adoProject: mapping.project,
+        areaPath,
+        workItemId: newItem.id,
+        url: newItem.url,
+        action: "created"
+      };
+    }
+  }
+  /**
+   * Find existing work item by US ID in title
+   */
+  async findExistingWorkItem(project, usId) {
+    try {
+      const query = `[System.Title] Contains '[${usId}]'`;
+      const results = await this.adoClient.searchWorkItems(project, query);
+      return results.length > 0 ? { id: results[0].id } : null;
+    } catch {
+      return null;
+    }
+  }
+  /**
+   * Build work item description from user story
+   */
+  buildWorkItemDescription(story, featureId) {
+    const lines = [];
+    lines.push(`<h1>${story.title}</h1>`);
+    lines.push("");
+    if (story.description) {
+      lines.push(`<p>${story.description}</p>`);
+      lines.push("");
+    }
+    if (story.acceptanceCriteria && story.acceptanceCriteria.length > 0) {
+      lines.push("<h2>Acceptance Criteria</h2>");
+      lines.push("<ul>");
+      for (const ac of story.acceptanceCriteria) {
+        lines.push(`  <li>${ac}</li>`);
+      }
+      lines.push("</ul>");
+      lines.push("");
+    }
+    lines.push("<hr/>");
+    lines.push("");
+    lines.push(`<p><strong>Feature</strong>: ${featureId}</p>`);
+    lines.push(`<p><strong>User Story</strong>: ${story.id}</p>`);
+    if (story.project) {
+      lines.push(`<p><strong>Project</strong>: ${story.project}</p>`);
+    }
+    if (story.board) {
+      lines.push(`<p><strong>Board</strong>: ${story.board}</p>`);
+    }
+    lines.push("");
+    lines.push("<p><em>Auto-generated by SpecWeave</em></p>");
+    return lines.join("\n");
+  }
+  /**
+   * Group user stories by their explicit project field
+   */
+  groupByProject(userStories, defaultProject) {
+    const groups = /* @__PURE__ */ new Map();
+    for (const story of userStories) {
+      const project = story.project || defaultProject || "default";
+      if (!groups.has(project)) {
+        groups.set(project, []);
+      }
+      groups.get(project).push(story);
+    }
+    return groups;
+  }
+}
+function formatPerUSSyncResults(result) {
+  const lines = [];
+  lines.push("");
+  lines.push("\u{1F4CA} Per-US ADO Sync Results");
+  lines.push("");
+  const byProject = /* @__PURE__ */ new Map();
+  for (const r of [...result.synced, ...result.failed]) {
+    const existing = byProject.get(r.projectId) || [];
+    existing.push(r);
+    byProject.set(r.projectId, existing);
+  }
+  for (const [projectId, results] of byProject) {
+    const adoProject = results[0]?.adoProject || "N/A";
+    const areaPath = results[0]?.areaPath || "";
+    lines.push(`**${projectId}** (\u2192 ${adoProject}${areaPath ? ` [${areaPath}]` : ""}):`);
+    for (const r of results) {
+      const icon = r.action === "created" ? "\u2705" : r.action === "updated" ? "\u{1F504}" : r.error ? "\u274C" : "\u23ED\uFE0F";
+      if (r.workItemId > 0) {
+        lines.push(`  ${icon} ${r.usId} \u2192 ${r.adoProject}/${r.workItemId}`);
+      } else if (r.error) {
+        lines.push(`  ${icon} ${r.usId}: ${r.error}`);
+      } else {
+        lines.push(`  ${icon} ${r.usId} (${r.action})`);
+      }
+    }
+    lines.push("");
+  }
+  lines.push(`\u{1F4C8} Summary: ${result.summary.created} created, ${result.summary.updated} updated, ${result.summary.failed} failed`);
+  return lines.join("\n");
+}
+export {
+  PerUSAdoSync,
+  formatPerUSSyncResults
+};