specweave 1.0.301 → 1.0.303

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-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);
 });

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

@@ -1,4 +1,4 @@
-import { readdir, readFile, writeFile } from "fs/promises";
+import { readdir, readFile, writeFile, mkdir } from "fs/promises";
 import { existsSync } from "fs";
 import * as path from "path";
 import * as yaml from "yaml";
@@ -160,7 +160,8 @@ const _GitHubFeatureSync = class _GitHubFeatureSync {
     };
   }
   /**
-   * Find Feature folder in specs directory
+   * Find Feature folder in specs directory.
+   * Falls back to auto-creating from increment spec.md if living docs don't exist.
    */
   async findFeatureFolder(featureId) {
     const projectFolders = await this.findProjectFolders();
@@ -175,8 +176,230 @@ const _GitHubFeatureSync = class _GitHubFeatureSync {
       console.log(`   \u26A0\uFE0F  Found feature in legacy _features folder - consider migrating to project folder`);
       return legacyFolder;
     }
+    console.log(`   \u2139\uFE0F  Feature folder not found in living docs, attempting auto-create from spec.md...`);
+    const created = await this.createFeatureFolderFromSpec(featureId, projectFolders);
+    if (created) {
+      return created;
+    }
     return null;
   }
+  /**
+   * Find the increment folder for a given feature ID.
+   * Converts FS-271 -> finds 0271-xxx-xxx/ in .specweave/increments/
+   */
+  async findIncrementFolder(featureId) {
+    const numMatch = featureId.match(/FS-0*(\d+)E?/i);
+    if (!numMatch) return null;
+    const num = parseInt(numMatch[1], 10);
+    const paddedNum = String(num).padStart(4, "0");
+    const incrementsDir = path.join(this.projectRoot, ".specweave/increments");
+    if (!existsSync(incrementsDir)) return null;
+    const entries = await readdir(incrementsDir);
+    const match = entries.find((e) => e.startsWith(paddedNum + "-"));
+    if (!match) return null;
+    return path.join(incrementsDir, match);
+  }
+  /**
+   * Auto-create a feature folder (FEATURE.md + us-NNN.md files) from an
+   * increment's spec.md. This enables GitHub sync even when the living docs
+   * builder hasn't run yet.
+   */
+  async createFeatureFolderFromSpec(featureId, projectFolders) {
+    try {
+      const incrementFolder = await this.findIncrementFolder(featureId);
+      if (!incrementFolder) {
+        console.log(`   \u26A0\uFE0F  No increment folder found for ${featureId}`);
+        return null;
+      }
+      const specPath = path.join(incrementFolder, "spec.md");
+      if (!existsSync(specPath)) {
+        console.log(`   \u26A0\uFE0F  No spec.md found in ${path.basename(incrementFolder)}`);
+        return null;
+      }
+      const specContent = await readFile(specPath, "utf-8");
+      const fmMatch = specContent.match(/^---\n([\s\S]*?)\n---/);
+      if (!fmMatch) {
+        console.log(`   \u26A0\uFE0F  spec.md has no YAML frontmatter`);
+        return null;
+      }
+      const frontmatter = yaml.parse(fmMatch[1]);
+      const title = frontmatter.title || path.basename(incrementFolder).replace(/^\d+-/, "");
+      const status = frontmatter.status || "active";
+      const priority = frontmatter.priority || "P2";
+      const created = frontmatter.created || (/* @__PURE__ */ new Date()).toISOString().split("T")[0];
+      const incrementId = frontmatter.increment || path.basename(incrementFolder);
+      let targetProjectFolder = projectFolders[0];
+      const projectMatch = specContent.match(/\*\*Project\*\*:\s*(\S+)/);
+      if (projectMatch) {
+        const projectName = projectMatch[1];
+        const matchingFolder = projectFolders.find((f) => path.basename(f) === projectName);
+        if (matchingFolder) {
+          targetProjectFolder = matchingFolder;
+        }
+      }
+      if (!targetProjectFolder) {
+        console.log(`   \u26A0\uFE0F  No project folder available for feature creation`);
+        return null;
+      }
+      const featureFolder = path.join(targetProjectFolder, featureId);
+      await mkdir(featureFolder, { recursive: true });
+      const userStories = this.parseUserStoriesFromSpec(specContent, featureId);
+      const featureMd = this.buildFeatureMd(featureId, title, status, priority, created, incrementId, userStories);
+      await writeFile(path.join(featureFolder, "FEATURE.md"), featureMd, "utf-8");
+      for (const us of userStories) {
+        const usFilename = `us-${us.id.replace("US-", "").padStart(3, "0")}-${this.slugify(us.title)}.md`;
+        const usMd = this.buildUserStoryMd(us, featureId, incrementId);
+        await writeFile(path.join(featureFolder, usFilename), usMd, "utf-8");
+      }
+      console.log(`   \u2705 Auto-created feature folder with ${userStories.length} user stories`);
+      return featureFolder;
+    } catch (error) {
+      console.log(`   \u26A0\uFE0F  Failed to auto-create feature folder: ${error.message}`);
+      return null;
+    }
+  }
+  /**
+   * Parse user stories from spec.md markdown content.
+   */
+  parseUserStoriesFromSpec(specContent, featureId) {
+    const stories = [];
+    const usRegex = /### (US-\d+):\s*(.+?)(?:\s*\((P\d)\))?\s*\n([\s\S]*?)(?=\n### US-|\n## |\n---\s*\n### US-|$)/g;
+    let match;
+    while ((match = usRegex.exec(specContent)) !== null) {
+      const usId = match[1];
+      const rawTitle = match[2].trim();
+      const priority = match[3] || "P2";
+      const body = match[4];
+      if (rawTitle === "[Story Title]") continue;
+      const projectMatch = body.match(/\*\*Project\*\*:\s*(\S+)/);
+      const project = projectMatch ? projectMatch[1] : "specweave";
+      const storyMatch = body.match(/\*\*As a\*\*\s+([\s\S]*?)(?=\n\*\*Acceptance Criteria|$)/);
+      const storyText = storyMatch ? storyMatch[1].trim() : "";
+      const acs = [];
+      const acRegex = /- \[[ x]\] \*\*AC-[^*]+\*\*:\s*(.+)/g;
+      let acMatch;
+      while ((acMatch = acRegex.exec(body)) !== null) {
+        acs.push(acMatch[0]);
+      }
+      const totalAcs = acs.length;
+      const completedAcs = acs.filter((ac) => ac.startsWith("- [x]")).length;
+      let status = "not-started";
+      if (totalAcs > 0 && completedAcs === totalAcs) status = "complete";
+      else if (completedAcs > 0) status = "active";
+      stories.push({
+        id: usId,
+        title: rawTitle,
+        priority,
+        project,
+        storyText,
+        acceptanceCriteria: acs,
+        status
+      });
+    }
+    return stories;
+  }
+  /**
+   * Build FEATURE.md content matching the living docs format.
+   */
+  buildFeatureMd(featureId, title, status, priority, created, incrementId, userStories) {
+    const now = (/* @__PURE__ */ new Date()).toISOString().split("T")[0];
+    const mappedStatus = status === "planned" ? "planning" : status === "completed" || status === "done" ? "complete" : status === "active" || status === "in-progress" ? "active" : "planning";
+    const fm = {
+      id: featureId,
+      title,
+      type: "feature",
+      status: mappedStatus,
+      priority,
+      created,
+      lastUpdated: now,
+      tldr: title,
+      complexity: "medium",
+      auto_created: true
+    };
+    const yamlFm = yaml.stringify(fm);
+    let body = `
+# ${title}
+
+## TL;DR
+
+**What**: ${title}
+**Status**: ${mappedStatus} | **Priority**: ${priority}
+**User Stories**: ${userStories.length}
+
+## Overview
+
+${title}
+
+## Implementation History
+
+| Increment | Status |
+|-----------|--------|
+| [${incrementId}](../../../../../increments/${incrementId}/spec.md) | ${mappedStatus} |
+
+## User Stories
+`;
+    for (const us of userStories) {
+      body += `
+- [${us.id}: ${us.title}](./${us.id.toLowerCase()}.md)`;
+    }
+    return `---
+${yamlFm}---${body}
+`;
+  }
+  /**
+   * Build us-NNN.md content matching the living docs format.
+   */
+  buildUserStoryMd(us, featureId, incrementId) {
+    const now = (/* @__PURE__ */ new Date()).toISOString().split("T")[0];
+    const fm = {
+      id: us.id,
+      feature: featureId,
+      title: us.title,
+      status: us.status,
+      priority: us.priority,
+      created: now,
+      project: us.project
+    };
+    const yamlFm = yaml.stringify(fm);
+    let body = `
+# ${us.id}: ${us.title}
+
+**Feature**: [${featureId}](./FEATURE.md)
+
+`;
+    if (us.storyText) {
+      body += `${us.storyText}
+
+`;
+    }
+    body += `---
+
+## Acceptance Criteria
+
+`;
+    if (us.acceptanceCriteria.length > 0) {
+      body += us.acceptanceCriteria.join("\n") + "\n";
+    } else {
+      body += `- [ ] **AC-${us.id.replace("US-", "US")}-01**: Pending specification
+`;
+    }
+    body += `
+---
+
+## Implementation
+
+**Increment**: [${incrementId}](../../../../../increments/${incrementId}/spec.md)
+`;
+    return `---
+${yamlFm}---${body}
+`;
+  }
+  /**
+   * Convert a title to a URL-safe slug.
+   */
+  slugify(text) {
+    return text.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").substring(0, 60);
+  }
   /**
    * Backfill increment metadata.json with GitHub issue reference (v1.0.240)
    *