specweave 1.0.301 → 1.0.304

package/plugins/specweave/skills/import/SKILL.md

@@ -0,0 +1,186 @@
+---
+description: Import external issues from GitHub, Jira, or Azure DevOps and create SpecWeave increments with platform suffixes (G/J/A). Supports filtering and duplicate prevention. Use when saying "import issues", "pull from github", "grab jira issues", or "import from ado".
+argument-hint: "[platform] [filter-query]"
+---
+
+# External Issue Import
+
+Import issues from external trackers (GitHub, JIRA, Azure DevOps) and create SpecWeave increments with platform-specific suffixes: **G** (GitHub), **J** (JIRA), **A** (ADO).
+
+---
+
+## Workflow
+
+### STEP 1: Load Configuration
+
+1. Read `.specweave/config.json` — check `sync` section
+2. Identify which platforms are configured (`sync.github`, `sync.jira`, `sync.ado`)
+3. If NO platforms configured:
+   - Tell user: "No external tools configured. Run `/sw:sync-setup` to connect GitHub, JIRA, or ADO."
+   - **STOP**
+
+### STEP 2: Platform Selection
+
+1. If user specified a platform in the command argument (e.g., `/sw:import github`), use that
+2. If multiple platforms configured and none specified, ask user which to import from:
+   - Use AskUserQuestion with configured platforms as options
+3. Validate the selected platform is configured and has credentials
+
+### STEP 3: Filter Configuration
+
+Ask user for optional filters (or parse from arguments):
+
+- **Status**: open (default), closed, all
+- **Labels**: comma-separated label filter
+- **Date range**: last N months (default: 3)
+- **Milestone/Epic**: filter by milestone or epic
+- **Search query**: text search in title/description
+- **Max items**: limit results (default: 20)
+
+If user provides no filters, use defaults: open issues, last 3 months, max 20.
+
+### STEP 4: Fetch External Issues
+
+1. Read credentials from `.env` or environment:
+   - GitHub: `GITHUB_TOKEN` or `gh auth status`
+   - JIRA: `JIRA_EMAIL` + `JIRA_API_TOKEN` + domain from config
+   - ADO: `ADO_PAT` + org/project from config
+
+2. Use the platform's API to fetch issues matching filters:
+   - **GitHub**: `gh api repos/{owner}/{repo}/issues` with query params
+   - **JIRA**: JIRA REST API v3 with JQL query
+   - **ADO**: ADO REST API with WIQL query
+
+3. Parse results into a display-friendly list
+
+### STEP 5: Display and Select
+
+Present issues in a numbered table:
+
+```
+# | ID        | Title                          | Status | Priority | Labels
+--|-----------|--------------------------------|--------|----------|--------
+1 | #123      | Fix login redirect loop        | open   | P1       | bug
+2 | #456      | Add dark mode support          | open   | P2       | feature
+3 | #789      | Update API documentation       | open   | P3       | docs
+```
+
+Ask user to select which issues to import:
+- Single: "1"
+- Multiple: "1,3,5"
+- All: "all"
+- Range: "1-5"
+
+### STEP 6: Duplicate Detection
+
+For each selected issue, check if already imported:
+
+1. Generate the canonical `external_ref` string:
+   - GitHub: `github#{owner}/{repo}#{issue_number}`
+   - JIRA: `jira#{project_key}#{issue_key}`
+   - ADO: `ado#{org}/{project}#{work_item_id}`
+
+2. Scan ALL `.specweave/increments/**/metadata.json` files for matching `external_ref`
+   - Check: active, _archive, _abandoned, _paused directories
+
+3. For duplicates found:
+   - Report: "Skipping #{issue_id} — already imported as {increment_id}"
+   - Remove from selection
+
+### STEP 7: Create Increments
+
+For each non-duplicate selected issue:
+
+1. **Generate increment ID** with platform suffix:
+   - GitHub issue #123 "fix-login-bug" → `0271G-fix-login-bug`
+   - JIRA PROJ-456 "payment-flow" → `0272J-payment-flow`
+   - ADO #789 "ci-pipeline" → `0273A-ci-pipeline`
+
+2. **Create increment files** via `createIncrementTemplates()` with `externalSource`:
+   - `metadata.json` — includes `external_ref`, `origin: "external"`, `source_platform`
+   - `spec.md` — pre-filled with issue title, description, and acceptance criteria
+   - `plan.md` — template (to be completed via architect skill)
+   - `tasks.md` — derived from acceptance criteria if available, template otherwise
+
+3. **Map priority**: Use external priority if available, default to P2
+4. **Map type**: bug → bug, feature/epic/story → feature
+
+### STEP 8: Post-Import Summary
+
+Display results:
+
+```
+Import Complete
+===============
+
+Created:
+  - 0271G-fix-login-bug (from GitHub #123)
+  - 0273A-ci-pipeline (from ADO #789)
+
+Skipped (duplicates):
+  - GitHub #456 — already imported as 0200G-dark-mode
+
+Errors: none
+
+Next steps:
+  - /sw:do 0271G  — Start working on first import
+  - /sw:auto 0271G — Run autonomously
+```
+
+---
+
+## Platform Suffix Reference
+
+| Platform | Suffix | Example |
+|----------|--------|---------|
+| GitHub   | G      | `0271G-fix-login-bug` |
+| JIRA     | J      | `0272J-payment-flow` |
+| ADO      | A      | `0273A-ci-pipeline` |
+| Legacy   | E      | `0111E-old-import` (backwards compat) |
+
+---
+
+## Edge Cases
+
+### No issues found
+Tell user "No matching issues found. Try adjusting filters." Suggest broader search.
+
+### External tool API error
+Report the error clearly. Suggest checking credentials: "Run `/sw:sync-setup` to verify credentials."
+
+### Issue has no description
+Create spec with title only and mark as needs-review.
+
+### Issue has no acceptance criteria
+Create template-style tasks.md with placeholder tasks.
+
+### Rate limiting
+Report rate limit and suggest waiting or reducing the import batch size.
+
+### Umbrella / multi-repo project
+If in an umbrella project with multiple repos under `repositories/`, ask which repo's `.specweave/` should receive the increment.
+
+---
+
+## Configuration Reference
+
+Required in `.specweave/config.json`:
+
+```json
+{
+  "sync": {
+    "enabled": true,
+    "github": { "enabled": true, "owner": "...", "repo": "..." },
+    "jira": { "enabled": true, "domain": "...", "projectKey": "..." },
+    "ado": { "enabled": true, "organization": "...", "project": "..." }
+  }
+}
+```
+
+Credentials in `.env` (never committed):
+```
+GITHUB_TOKEN=ghp_...
+JIRA_EMAIL=user@example.com
+JIRA_API_TOKEN=...
+ADO_PAT=...
+```

package/plugins/specweave/skills/increment/SKILL.md

@@ -46,15 +46,20 @@ Increment planning produces specs, plans, and task breakdowns that require user
 STEP 0A: Discipline Check (BLOCKING)
 STEP 0B: WIP Enforcement
 STEP 0C: Tech Stack Detection
-STEP 1:  Pre-flight (TDD mode, multi-project, Deep Interview)
-STEP 1a: Deep Interview (if enabled)
+STEP 1:  Pre-flight (TDD mode, multi-project, Deep Interview check)
 STEP 2:  Project Context (resolve project/board)
-STEP 3:  Create Increment (via Template API)
+STEP 3:  Create Increment (via Template API) ← folder + ID exist after this
+STEP 3a: Deep Interview (if enabled) ← runs AFTER folder exists
 STEP 4:  Delegation (architect + test-aware-planner)
 STEP 5:  Post-Creation Sync
 STEP 6:  Execution Strategy Recommendation
 ```
 
+**CRITICAL**: Step 3 (Create Increment) MUST run before Step 3a (Deep Interview).
+The interview state file is written to `.specweave/state/interview-{increment-id}.json`,
+and the enforcement guard looks for it by increment ID. If the interview runs before the
+increment folder exists, the guard cannot find the state file and blocks spec.md writing.
+
 ## Step 0A: Discipline Check (MANDATORY)
 
 **Cannot start N+1 until N is DONE.**
@@ -120,24 +125,13 @@ jq -r '.testing.defaultTestMode // "test-after"' .specweave/config.json 2>/dev/n
 # 2. Check multi-project config
 specweave context projects 2>/dev/null
 
-# 3. Check deep interview mode
-jq -r '.planning.deepInterview.enabled // false' .specweave/config.json 2>/dev/null
+# 3. Check deep interview mode (note: interview itself runs at Step 3a, after increment exists)
+DEEP_INTERVIEW=$(jq -r '.planning.deepInterview.enabled // false' .specweave/config.json 2>/dev/null)
 
 # 4. Check WIP limits
 find .specweave/increments -maxdepth 2 -name "metadata.json" -exec grep -l '"status":"active"' {} \; 2>/dev/null | wc -l
 ```
 
-## Step 1a: Deep Interview Mode (if enabled)
-
-**If deep interview is enabled, delegate to PM skill:**
-
-```typescript
-Skill({ skill: "sw:pm", args: "Deep interview mode for: <user description>" })
-```
-
-**THINK about complexity first** - assess before asking:
-- Trivial: 0-3 questions | Small: 4-8 | Medium: 9-18 | Large: 19-40+
-
 ## Step 2: Project Context
 
 ```bash
@@ -246,6 +240,26 @@ Create files in order: metadata.json FIRST, then spec.md, plan.md, tasks.md.
 4. **Increment naming** - Format: `####-descriptive-kebab-case`
 5. **Multi-repo** - In umbrella projects with `repositories/` folder, create increments in EACH repo's `.specweave/`, not the umbrella root
 
+## Step 3a: Deep Interview Mode (if enabled)
+
+**IMPORTANT**: This step runs AFTER the increment folder is created (Step 3), so the
+interview state file can reference the real increment ID.
+
+**If deep interview is enabled, delegate to PM skill:**
+
+```typescript
+Skill({ skill: "sw:pm", args: "Deep interview for increment XXXX-name: <user description>" })
+```
+
+The PM skill will:
+1. Assess complexity and determine question count (trivial: 0-3, small: 4-8, medium: 9-18, large: 19-40)
+2. Interview the user across relevant categories
+3. Write interview state to `.specweave/state/interview-{increment-id}.json`
+4. Return interview summary for spec.md creation
+
+**After PM returns**, read the interview state file to confirm all categories are covered
+before proceeding to spec.md creation (especially when `enforcement: "strict"`).
+
 ## Step 4: Delegation
 
 After increment creation:

package/plugins/specweave/skills/pm/SKILL.md

@@ -44,8 +44,35 @@ If `true`:
    - Small features: 4-8 questions
    - Medium features: 9-18 questions
    - Large features: 19-40 questions
-3. Cover relevant categories (skip those that don't apply)
-4. Only proceed to Research phase after sufficient clarity
+3. Check `minQuestions` config: `jq -r '.planning.deepInterview.minQuestions // 5' .specweave/config.json`
+   - If complexity assessment yields fewer questions than minQuestions, use minQuestions as the floor
+4. Cover relevant categories (skip those that don't apply)
+5. Only proceed to Research phase after sufficient clarity
+
+### Writing Interview State to Disk (CRITICAL)
+
+**This skill runs with `context: fork` (isolated LLM context), but file writes persist.**
+
+When invoked from `sw:increment` with an increment ID (e.g., "Deep interview for increment 0266-foo: ..."),
+you MUST write the interview state file to disk so the enforcement guard can find it:
+
+```bash
+# Extract increment ID from the args (e.g., "Deep interview for increment 0266-foo: ...")
+# Initialize interview state file BEFORE starting questions
+mkdir -p .specweave/state
+echo '{"incrementId":"XXXX-name","startedAt":"'$(date -Iseconds)'","coveredCategories":{}}' \
+  > .specweave/state/interview-XXXX-name.json
+```
+
+After covering each category, update the state file:
+```bash
+jq '.coveredCategories.architecture = {"coveredAt": "'$(date -Iseconds)'", "summary": "..."}' \
+  .specweave/state/interview-XXXX-name.json > tmp && mv tmp .specweave/state/interview-XXXX-name.json
+```
+
+**Why this matters**: The `interview-enforcement-guard.sh` (PreToolUse hook on Write) checks
+`.specweave/state/interview-{increment-id}.json` before allowing spec.md writes. If this file
+is missing or incomplete, spec.md creation is BLOCKED in strict mode.
 
 ## Core Principles
 

package/plugins/specweave/skills/pm/phases/00-deep-interview.md

@@ -207,6 +207,18 @@ When factors point to different complexity levels:
 | **Medium** | 9-18 questions | Multiple components, some integration points |
 | **Large** | 19-40 questions | Architectural, cross-cutting, high-risk (payments, security) |
 
+### Config Floor: minQuestions
+
+The project may define a minimum question count in config:
+
+```bash
+jq -r '.planning.deepInterview.minQuestions // 5' .specweave/config.json 2>/dev/null
+```
+
+**Rule**: If your complexity assessment yields fewer questions than `minQuestions`, use `minQuestions` as the floor. For example, if you assess a feature as "trivial" (0-3 questions) but `minQuestions` is 5, ask at least 5 questions.
+
+This prevents teams from accidentally under-interviewing when they have set an organizational minimum.
+
 ### What's a "Single Component"?
 
 A "single component" means **isolated scope** - changes contained to one area:

package/plugins/specweave/skills/team-lead/SKILL.md

@@ -664,8 +664,10 @@ Orchestrator Final Check:
   2. No unresolved BLOCKING_ISSUE messages
   3. Run full test suite (all domains combined)
   4. Run /sw:grill on the combined increment
-  5. If all pass -> /sw:team-merge
-  6. If failures -> identify owning agent, send fix request via SendMessage
+  5. Run /sw:done --auto <id> for each increment in dependency order
+  6. If any /sw:done --auto fails, report the failure and continue with remaining increments
+  7. If all pass -> /sw:team-merge
+  8. If failures -> identify owning agent, send fix request via SendMessage
 ```
 
 ### Grill Checklist per Domain

package/plugins/specweave/skills/team-merge/SKILL.md

@@ -71,8 +71,8 @@ Closure order respects contract chain:
 For each teammate's increment, in dependency order:
 
 ```bash
-# Run /sw:done per increment -- triggers quality gates
-/sw:done <increment-id>
+# Run /sw:done --auto per increment -- triggers quality gates, skips user confirmation
+/sw:done <increment-id> --auto
 ```
 
 This ensures:

package/plugins/specweave-github/lib/github-ac-comment-poster.js

@@ -1,4 +1,6 @@
 import { readFile } from "fs/promises";
+import { existsSync } from "fs";
+import * as path from "path";
 import { execFileNoThrow } from "../../../src/utils/execFileNoThrow.js";
 import { pushSyncUserStories } from "./github-push-sync.js";
 async function postACProgressComments(incrementId, affectedUSIds, specPath, options) {
@@ -16,7 +18,7 @@ async function postACProgressComments(incrementId, affectedUSIds, specPath, opti
     });
     return result;
   }
-  const issueLinks = parseIssueLinks(content);
+  const issueLinks = await parseIssueLinks(specPath);
   const repoSlug = `${options.owner}/${options.repo}`;
   const env = options.token ? { GH_TOKEN: options.token } : void 0;
   for (const usId of affectedUSIds) {
@@ -53,26 +55,36 @@ async function postACProgressComments(incrementId, affectedUSIds, specPath, opti
   }
   return result;
 }
-function parseIssueLinks(content) {
+async function parseIssueLinks(specPath) {
   const links = {};
-  const fmMatch = content.match(/^---\n([\s\S]*?)\n---/);
-  if (!fmMatch) return links;
-  const frontmatter = fmMatch[1];
-  const usBlockMatch = frontmatter.match(/userStories:\s*\n((?:\s{6,}[\s\S]*?)(?=\n\s{0,3}\S|$))/);
-  if (!usBlockMatch) return links;
-  const usBlock = usBlockMatch[1];
-  const usEntries = usBlock.match(/^\s+(US-\d+):\s*\n((?:\s+\w[\s\S]*?)(?=\n\s+US-|\s*$))/gm);
-  if (!usEntries) return links;
-  for (const entry of usEntries) {
-    const idMatch = entry.match(/(US-\d+):/);
-    const numMatch = entry.match(/issueNumber:\s*(\d+)/);
-    const urlMatch = entry.match(/issueUrl:\s*"([^"]+)"/);
-    if (idMatch && numMatch) {
-      links[idMatch[1]] = {
-        issueNumber: parseInt(numMatch[1], 10),
-        issueUrl: urlMatch ? urlMatch[1] : ""
-      };
+  try {
+    const metadataPath = path.join(path.dirname(specPath), "metadata.json");
+    if (!existsSync(metadataPath)) return links;
+    const raw = await readFile(metadataPath, "utf-8");
+    const metadata = JSON.parse(raw);
+    if (metadata.github?.issues && Array.isArray(metadata.github.issues)) {
+      for (const entry of metadata.github.issues) {
+        if (entry.userStory && entry.number) {
+          links[entry.userStory] = {
+            issueNumber: entry.number,
+            issueUrl: entry.url || ""
+          };
+        }
+      }
+    }
+    if (metadata.externalLinks?.github?.issues) {
+      const issues = metadata.externalLinks.github.issues;
+      for (const [usId, data] of Object.entries(issues)) {
+        const issueData = data;
+        if (issueData.issueNumber) {
+          links[usId] = {
+            issueNumber: issueData.issueNumber,
+            issueUrl: issueData.issueUrl || ""
+          };
+        }
+      }
     }
+  } catch {
   }
   return links;
 }

package/plugins/specweave-github/lib/github-ac-comment-poster.ts

@@ -9,6 +9,8 @@
  */
 
 import { readFile } from 'fs/promises';
+import { existsSync } from 'fs';
+import * as path from 'path';
 import { execFileNoThrow } from '../../../src/utils/execFileNoThrow.js';
 import { pushSyncUserStories } from './github-push-sync.js';
 import type { UserStoryForSync } from './github-push-sync.js';
@@ -69,7 +71,7 @@ export async function postACProgressComments(
     return result;
   }
 
-  const issueLinks = parseIssueLinks(content);
+  const issueLinks = await parseIssueLinks(specPath);
   const repoSlug = `${options.owner}/${options.repo}`;
   const env = options.token ? { GH_TOKEN: options.token } : undefined;
 
@@ -116,37 +118,52 @@ export async function postACProgressComments(
 }
 
 /**
- * Parse issue links from spec.md YAML frontmatter.
- * Extracts externalLinks.github.userStories entries.
+ * Parse issue links from metadata.json (sibling of spec.md).
+ *
+ * Supports TWO formats:
+ * - OLD: metadata.github.issues[] with { userStory, number, url }
+ * - NEW: metadata.externalLinks.github.issues with { [US-XXX]: { issueNumber, issueUrl } }
+ *
+ * Falls back to empty if metadata.json is missing or invalid.
  */
-function parseIssueLinks(content: string): Record<string, ParsedUSIssueLink> {
+async function parseIssueLinks(specPath: string): Promise<Record<string, ParsedUSIssueLink>> {
   const links: Record<string, ParsedUSIssueLink> = {};
 
-  const fmMatch = content.match(/^---\n([\s\S]*?)\n---/);
-  if (!fmMatch) return links;
-
-  const frontmatter = fmMatch[1];
-
-  // Parse userStories section from YAML frontmatter
-  const usBlockMatch = frontmatter.match(/userStories:\s*\n((?:\s{6,}[\s\S]*?)(?=\n\s{0,3}\S|$))/);
-  if (!usBlockMatch) return links;
-
-  const usBlock = usBlockMatch[1];
-  const usEntries = usBlock.match(/^\s+(US-\d+):\s*\n((?:\s+\w[\s\S]*?)(?=\n\s+US-|\s*$))/gm);
-
-  if (!usEntries) return links;
-
-  for (const entry of usEntries) {
-    const idMatch = entry.match(/(US-\d+):/);
-    const numMatch = entry.match(/issueNumber:\s*(\d+)/);
-    const urlMatch = entry.match(/issueUrl:\s*"([^"]+)"/);
+  try {
+    const metadataPath = path.join(path.dirname(specPath), 'metadata.json');
+    if (!existsSync(metadataPath)) return links;
+
+    const raw = await readFile(metadataPath, 'utf-8');
+    const metadata = JSON.parse(raw);
+
+    // OLD format: metadata.github.issues[] array
+    if (metadata.github?.issues && Array.isArray(metadata.github.issues)) {
+      for (const entry of metadata.github.issues) {
+        if (entry.userStory && entry.number) {
+          links[entry.userStory] = {
+            issueNumber: entry.number,
+            issueUrl: entry.url || '',
+          };
+        }
+      }
+    }
 
-    if (idMatch && numMatch) {
-      links[idMatch[1]] = {
-        issueNumber: parseInt(numMatch[1], 10),
-        issueUrl: urlMatch ? urlMatch[1] : '',
-      };
+    // NEW format: metadata.externalLinks.github.issues object
+    if (metadata.externalLinks?.github?.issues) {
+      const issues = metadata.externalLinks.github.issues;
+      for (const [usId, data] of Object.entries(issues)) {
+        const issueData = data as { issueNumber?: number; issueUrl?: string };
+        if (issueData.issueNumber) {
+          // NEW format entries override OLD format for the same US
+          links[usId] = {
+            issueNumber: issueData.issueNumber,
+            issueUrl: issueData.issueUrl || '',
+          };
+        }
+      }
     }
+  } catch {
+    // Graceful fallback: return empty if metadata.json is missing or invalid
   }
 
   return links;

package/plugins/specweave-github/lib/github-feature-sync-cli.js

@@ -135,12 +135,17 @@ async function main() {
     }
     process.exit(0);
   } catch (error) {
+    const msg = error instanceof Error ? error.message : String(error);
+    console.log(`
+[ERROR] Sync failed for ${featureId}: ${msg}`);
     console.error(`
 \u274C Sync failed:`, error);
     process.exit(1);
   }
 }
 main().catch((error) => {
+  const msg = error instanceof Error ? error.message : String(error);
+  console.log(`[FATAL] ${msg}`);
   console.error("Fatal error:", error);
   process.exit(1);
 });

package/plugins/specweave-github/lib/github-feature-sync-cli.ts

@@ -195,7 +195,11 @@ async function main() {
     }
 
     process.exit(0);
-  } catch (error) {
+  } catch (error: unknown) {
+    // FIXED (v1.0.302): Write errors to stdout too, since stderr may be suppressed
+    // by run_with_timeout() in shell handlers. This ensures errors appear in throttle.log.
+    const msg = error instanceof Error ? error.message : String(error);
+    console.log(`\n[ERROR] Sync failed for ${featureId}: ${msg}`);
     console.error(`\n❌ Sync failed:`, error);
     process.exit(1);
   }
@@ -203,6 +207,8 @@ async function main() {
 
 // Run CLI
 main().catch(error => {
+  const msg = error instanceof Error ? error.message : String(error);
+  console.log(`[FATAL] ${msg}`);
   console.error('Fatal error:', error);
   process.exit(1);
 });