specweave 0.28.7 → 0.28.11

package/plugins/specweave/agents/pm/AGENT.md

@@ -437,6 +437,147 @@ graph TD
 
 ---
 
+## 🔀 Multi-Repo Project-Scoped User Stories (v0.28.8+)
+
+**CRITICAL**: When user describes a multi-repo architecture, you MUST generate **project-scoped user stories** with prefixes!
+
+### Detection Patterns
+
+Detect multi-repo intent when user mentions:
+- **Explicit repos**: "3 repos", "multiple repos", "separate repos"
+- **Repo types**: "Frontend repo", "Backend API repo", "Shared library"
+- **Architecture patterns**: "monorepo with services", "microservices"
+- **Tech stack splits**: React frontend + Node backend + Shared types
+- **GitHub URLs**: Multiple github.com/... URLs
+
+### User Story Prefixing Rules (MANDATORY!)
+
+**When multi-repo detected, NEVER generate generic `US-001`!**
+
+| Repo Type | Prefix | Detection Keywords |
+|-----------|--------|-------------------|
+| Frontend | `FE` | UI, component, page, form, view, theme, drag-drop, builder, menu display |
+| Backend | `BE` | API, endpoint, CRUD, webhook, notification, analytics, database, service |
+| Shared | `SHARED` | validator, schema, types, utilities, localization, common, helpers |
+| Mobile | `MOBILE` | iOS, Android, mobile app, push notification, native |
+| Infrastructure | `INFRA` | Terraform, K8s, Docker, CI/CD, deployment |
+
+### Example: Generic vs Project-Scoped
+
+**❌ WRONG (Generic - for single-repo only)**:
+```markdown
+## User Stories
+
+### US-001: User Registration
+As a user, I want to register...
+
+### US-002: Registration API
+As a system, I want to process registrations...
+
+### US-003: Validation Schema
+As a developer, I want shared validation...
+```
+
+**✅ CORRECT (Project-Scoped - for multi-repo)**:
+```markdown
+## User Stories
+
+### US-FE-001: User Registration Form
+**Related Repo**: frontend
+As a user, I want to fill out the registration form...
+
+### US-BE-001: Registration API Endpoint
+**Related Repo**: backend
+As a system, I want to process POST /api/register...
+
+### US-SHARED-001: Registration Validation Schema
+**Related Repo**: shared
+As a developer, I want reusable validation schemas...
+```
+
+### Acceptance Criteria Also Prefixed
+
+```markdown
+### US-FE-001: Menu Builder Interface
+
+**Acceptance Criteria**:
+- [ ] **AC-FE-US1-01**: Drag-drop menu item ordering
+  - Priority: P0 (Critical)
+  - Testable: Yes
+- [ ] **AC-FE-US1-02**: Category management UI
+  - Priority: P0 (Critical)
+  - Testable: Yes
+
+### US-BE-001: Menu CRUD API
+
+**Acceptance Criteria**:
+- [ ] **AC-BE-US1-01**: POST /api/menus creates menu
+  - Priority: P0 (Critical)
+  - Testable: Yes
+- [ ] **AC-BE-US1-02**: GET /api/menus/:id returns menu
+  - Priority: P0 (Critical)
+  - Testable: Yes
+```
+
+### Cross-Cutting User Stories
+
+For features that span multiple repos (auth, shared state):
+
+```markdown
+### US-AUTH-001: OAuth Integration (Cross-Project)
+**Related Repos**: frontend, backend
+**Tags**: ["cross-project", "auth"]
+
+**Child Stories**:
+- US-FE-002: OAuth Login Button (frontend)
+- US-BE-002: OAuth Token Validation (backend)
+- US-SHARED-002: OAuth Types (shared)
+
+As a user, I want to log in with Google OAuth...
+```
+
+### Workflow in Multi-Repo Mode
+
+1. **Detect** multi-repo intent from user prompt
+2. **Confirm** with user: "I detected FE/BE/Shared architecture. Should I create project-scoped user stories?"
+3. **Generate** prefixed user stories: US-FE-*, US-BE-*, US-SHARED-*
+4. **Route** stories to correct increment in each repo
+5. **Sync** to each repo's own GitHub issues
+
+### Config Check (Optional)
+
+If `.specweave/config.json` has umbrella config:
+```json
+{
+  "umbrella": {
+    "enabled": true,
+    "childRepos": [
+      { "id": "fe", "prefix": "FE" },
+      { "id": "be", "prefix": "BE" },
+      { "id": "shared", "prefix": "SHARED" }
+    ]
+  }
+}
+```
+
+Use these prefixes for user stories. If no config, infer from user prompt.
+
+### Why This Matters
+
+Without project-scoped stories:
+- ❌ All issues created in ONE repo (wrong!)
+- ❌ No clarity which team owns what
+- ❌ Cross-project dependencies unclear
+- ❌ Frontend dev sees backend tasks in their repo
+
+With project-scoped stories:
+- ✅ Each repo gets only its user stories
+- ✅ Clear ownership per team/repo
+- ✅ GitHub issues in correct repo
+- ✅ Clean separation of concerns
+
+---
+
 **Role**: Product Manager specialized in product strategy, requirements gathering, and feature prioritization.
 
 ## Purpose

package/plugins/specweave/commands/specweave-done.md

@@ -487,6 +487,34 @@ Closing increment 0001-user-authentication...
 
 ### Step 5: Post-Closure Sync (AUTOMATIC)
 
+**CRITICAL**: After increment closes, the following syncs happen AUTOMATICALLY via the `post-increment-completion.sh` hook:
+
+#### 0) Sync spec.md Status (ALWAYS - v0.28.8+)
+
+**MANDATORY**: Ensures spec.md frontmatter status matches metadata.json.
+
+```
+🔄 Syncing spec.md status to 'completed'...
+✅ spec.md status updated: active → completed
+✅ Status line cache updated
+```
+
+**Why this matters**:
+- Prevents desyncs between metadata.json and spec.md
+- Ensures status line shows correct increment count
+- Maintains source-of-truth discipline
+- No need to manually run `/specweave:sync-status`
+
+**What gets synced**:
+1. spec.md YAML frontmatter `status` field → `completed`
+2. Status line cache updated via `lib/update-status-line.sh`
+
+**If you still see desync after closure**:
+```bash
+# Manual fix (should rarely be needed)
+/specweave:sync-status --fix
+```
+
 **CRITICAL**: After increment closes, automatically perform these syncs:
 
 #### A) Sync Living Docs to GitHub Project

package/plugins/specweave/hooks/hooks.json

@@ -1,5 +1,17 @@
 {
   "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Edit",
+        "matcher_content": "\\.specweave/increments/[0-9]{4}-.+/tasks\\.md",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/pre-task-completion-edit.sh"
+          }
+        ]
+      }
+    ],
     "UserPromptSubmit": [
       {
         "hooks": [

package/plugins/specweave/hooks/post-increment-completion.sh

@@ -117,10 +117,69 @@ Increment \`$INCREMENT_ID\` has been marked as complete.
   fi
 fi
 
+# ============================================================================
+# SYNC SPEC.MD STATUS (CRITICAL - v0.28.8)
+# ============================================================================
+# PROBLEM: metadata.json is updated to "completed" but spec.md frontmatter
+# may still say "active". This causes desyncs that break status line.
+#
+# SOLUTION: Explicitly update spec.md frontmatter to match metadata.json.
+# This ensures source-of-truth discipline is maintained.
+#
+# See: Incident 2025-11-20 - metadata.json="completed" but spec.md="active"
+# See: /specweave:sync-status command for manual recovery
+
+SPEC_FILE="$INCREMENT_DIR/spec.md"
+
+if [ -f "$SPEC_FILE" ]; then
+  echo "🔄 Syncing spec.md status to 'completed'..."
+
+  # Read current status from spec.md frontmatter
+  SPEC_STATUS=$(awk '
+    BEGIN { in_frontmatter=0 }
+    /^---$/ {
+      if (in_frontmatter == 0) {
+        in_frontmatter=1; next
+      } else {
+        exit
+      }
+    }
+    in_frontmatter == 1 && /^status:/ {
+      gsub(/^status:[ \t]*/, "");
+      gsub(/["'\''']/, "");
+      print;
+      exit
+    }
+  ' "$SPEC_FILE" | tr -d '\r\n')
+
+  if [ "$SPEC_STATUS" != "completed" ]; then
+    # Update spec.md frontmatter to "completed"
+    # Use sed for atomic in-place update
+    if [[ "$(uname)" == "Darwin" ]]; then
+      # macOS sed requires different syntax
+      sed -i '' 's/^status:.*$/status: completed/' "$SPEC_FILE" 2>/dev/null || {
+        echo "⚠️  Failed to update spec.md status (non-blocking)" >&2
+      }
+    else
+      # GNU sed
+      sed -i 's/^status:.*$/status: completed/' "$SPEC_FILE" 2>/dev/null || {
+        echo "⚠️  Failed to update spec.md status (non-blocking)" >&2
+      }
+    fi
+    echo "✅ spec.md status updated: $SPEC_STATUS → completed"
+  else
+    echo "✅ spec.md status already 'completed'"
+  fi
+else
+  echo "⚠️  spec.md not found at $SPEC_FILE" >&2
+fi
+
 # Update status line cache (increment no longer open)
 HOOK_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 bash "$HOOK_DIR/lib/update-status-line.sh" 2>/dev/null || true
 
+echo "✅ Status line cache updated"
+
 # ============================================================================
 # SYNC LIVING DOCS (NEW in v0.24.0 - Critical Missing Feature)
 # ============================================================================

package/plugins/specweave/hooks/post-increment-planning.sh

@@ -58,10 +58,12 @@ cd "$PROJECT_ROOT" 2>/dev/null || true
 # CONFIGURATION
 # ============================================================================
 
-# Translation settings (can be overridden by .specweave/config.json)
-TRANSLATION_ENABLED=true
-AUTO_TRANSLATE_INTERNAL_DOCS=true
-TARGET_LANGUAGE="en"  # Always translate TO English (for maintainability)
+# Translation settings (loaded from .specweave/config.json)
+TRANSLATION_ENABLED=false  # Opt-in: User MUST enable in config
+AUTO_TRANSLATE_INCREMENT_SPECS=false  # Opt-in: scope.incrementSpecs
+AUTO_TRANSLATE_LIVING_DOCS=false  # Opt-in: scope.livingDocs
+TARGET_LANGUAGE="en"  # Loaded from config.language (default: en)
+KEEP_ENGLISH_ORIGINALS=false  # If true, create .en.md backups
 
 # Paths
 SPECWEAVE_DIR=".specweave"
@@ -96,24 +98,59 @@ log_error() {
 
 load_config() {
   if [ ! -f "$CONFIG_FILE" ]; then
-    log_debug "No config file found, using defaults"
+    log_debug "No config file found, using defaults (translation disabled)"
     return
   fi
 
-  # Check if translation is enabled in config
-  local translation_enabled=$(cat "$CONFIG_FILE" | grep -o '"enabled"[[:space:]]*:[[:space:]]*\(true\|false\)' | grep -o '\(true\|false\)' || echo "true")
+  # Load target language from config.language (default: en)
+  local config_language=$(cat "$CONFIG_FILE" | grep -o '"language"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed 's/.*"\([^"]*\)".*/\1/' || echo "en")
+  if [ -n "$config_language" ]; then
+    TARGET_LANGUAGE="$config_language"
+    log_debug "Target language: $TARGET_LANGUAGE"
+  fi
+
+  # If target language is English, no translation needed
+  if [ "$TARGET_LANGUAGE" = "en" ]; then
+    TRANSLATION_ENABLED=false
+    log_debug "Target language is English, translation not needed"
+    return
+  fi
+
+  # Check if translation is enabled in config.translation.enabled
+  # Search within "translation" block for "enabled"
+  local translation_section=$(cat "$CONFIG_FILE" | awk '/"translation"[[:space:]]*:/,/^[[:space:]]*}/' 2>/dev/null)
+  local translation_enabled=$(echo "$translation_section" | grep -o '"enabled"[[:space:]]*:[[:space:]]*\(true\|false\)' | head -1 | grep -o '\(true\|false\)' || echo "false")
 
-  if [ "$translation_enabled" = "false" ]; then
+  if [ "$translation_enabled" = "true" ]; then
+    TRANSLATION_ENABLED=true
+    log_debug "Translation enabled in config"
+  else
     TRANSLATION_ENABLED=false
-    log_debug "Translation disabled in config"
+    log_debug "Translation disabled in config (opt-in required)"
+  fi
+
+  # Check translation scope (within translation.scope block)
+  local scope_section=$(echo "$translation_section" | awk '/"scope"[[:space:]]*:/,/^[[:space:]]*}/' 2>/dev/null)
+
+  # scope.incrementSpecs - translate spec.md, plan.md, tasks.md
+  local scope_increment=$(echo "$scope_section" | grep -o '"incrementSpecs"[[:space:]]*:[[:space:]]*\(true\|false\)' | grep -o '\(true\|false\)' || echo "false")
+  if [ "$scope_increment" = "true" ]; then
+    AUTO_TRANSLATE_INCREMENT_SPECS=true
+    log_debug "Auto-translate increment specs enabled"
   fi
 
-  # Check if auto-translation of internal docs is enabled
-  local auto_translate=$(cat "$CONFIG_FILE" | grep -o '"autoTranslateInternalDocs"[[:space:]]*:[[:space:]]*\(true\|false\)' | grep -o '\(true\|false\)' || echo "true")
+  # scope.livingDocs - translate living docs on update
+  local scope_living=$(echo "$scope_section" | grep -o '"livingDocs"[[:space:]]*:[[:space:]]*\(true\|false\)' | grep -o '\(true\|false\)' || echo "false")
+  if [ "$scope_living" = "true" ]; then
+    AUTO_TRANSLATE_LIVING_DOCS=true
+    log_debug "Auto-translate living docs enabled"
+  fi
 
-  if [ "$auto_translate" = "false" ]; then
-    AUTO_TRANSLATE_INTERNAL_DOCS=false
-    log_debug "Auto-translation of internal docs disabled in config"
+  # keepEnglishOriginals - create .en.md backups
+  local keep_originals=$(echo "$translation_section" | grep -o '"keepEnglishOriginals"[[:space:]]*:[[:space:]]*\(true\|false\)' | grep -o '\(true\|false\)' || echo "false")
+  if [ "$keep_originals" = "true" ]; then
+    KEEP_ENGLISH_ORIGINALS=true
+    log_debug "Keep English originals enabled"
   fi
 }
 
@@ -168,21 +205,21 @@ detect_file_language() {
 translate_file() {
   local file_path="$1"
   local file_name=$(basename "$file_path")
+  local target_lang="${TARGET_LANGUAGE:-en}"
 
-  log_info "  📄 Translating $file_name..."
+  log_info "  📄 Translating $file_name to $target_lang..."
 
   # Call the translate-file.ts script
-  # In production, this would invoke the LLM via Task tool
-  # For now, we'll create a marker file to indicate translation is needed
+  # Uses TARGET_LANGUAGE from config (default: en)
 
   if [ -f "${CLAUDE_PLUGIN_ROOT}/lib/hooks/translate-file.js" ]; then
     # Production: Use compiled TypeScript
-    node "${CLAUDE_PLUGIN_ROOT}/lib/hooks/translate-file.js" "$file_path" --target-lang en --verbose 2>&1 | while read -r line; do
+    node "${CLAUDE_PLUGIN_ROOT}/lib/hooks/translate-file.js" "$file_path" --target-lang "$target_lang" --verbose 2>&1 | while read -r line; do
       echo "     $line"
     done
 
     if [ ${PIPESTATUS[0]} -eq 0 ]; then
-      log_info "  ✅ $file_name translated successfully"
+      log_info "  ✅ $file_name translated to $target_lang"
       return 0
     else
       log_error "  ⚠️  Translation failed for $file_name"
@@ -191,7 +228,7 @@ translate_file() {
   else
     # Development/Testing: Just mark the file
     log_info "  ℹ️  Translation script not compiled (run 'npm run build')"
-    log_info "  ℹ️  In production, $file_name would be translated to English"
+    log_info "  ℹ️  In production, $file_name would be translated to $target_lang"
     return 0
   fi
 }
@@ -584,26 +621,20 @@ main() {
   # 1. Load configuration
   load_config
 
+  # Check if translation is needed (non-English target + enabled)
   if [ "$TRANSLATION_ENABLED" = "false" ]; then
-    log_debug "Translation disabled, exiting"
-    cat <<EOF
-{
-  "continue": true,
-  "message": "Translation disabled in config"
-}
-EOF
-    exit 0
+    log_debug "Translation disabled or target is English, skipping translation"
+    # Continue with other hook tasks (GitHub sync, living docs, etc.)
   fi
 
-  if [ "$AUTO_TRANSLATE_INTERNAL_DOCS" = "false" ]; then
-    log_debug "Auto-translation of internal docs disabled, exiting"
-    cat <<EOF
-{
-  "continue": true,
-  "message": "Auto-translation of internal docs disabled"
-}
-EOF
-    exit 0
+  # Log translation configuration
+  if [ "$TRANSLATION_ENABLED" = "true" ]; then
+    log_info ""
+    log_info "🌐 Translation Configuration:"
+    log_info "   Target language: $TARGET_LANGUAGE"
+    log_info "   Increment specs: $AUTO_TRANSLATE_INCREMENT_SPECS"
+    log_info "   Living docs: $AUTO_TRANSLATE_LIVING_DOCS"
+    log_info "   Keep English originals: $KEEP_ENGLISH_ORIGINALS"
   fi
 
   # 2. Get latest increment directory
@@ -656,17 +687,25 @@ EOF
     fi
   fi
 
-  # 4. Translate increment files (if needed)
+  # 4. Translate increment files (if enabled in scope and non-English content detected)
   local increment_success_count=0
   local increment_total_count=${#files_to_translate[@]}
 
-  if [ "$needs_translation" = "true" ] && [ ${#files_to_translate[@]} -gt 0 ]; then
-    # 5. Perform translation of increment files
+  if [ "$TRANSLATION_ENABLED" = "true" ] && [ "$AUTO_TRANSLATE_INCREMENT_SPECS" = "true" ] && [ "$needs_translation" = "true" ] && [ ${#files_to_translate[@]} -gt 0 ]; then
+    # 5. Perform translation of increment files TO user's language
     log_info ""
-    log_info "🌐 Detected non-English content in increment $increment_id"
-    log_info "   Translating increment files to English..."
+    log_info "🌐 Translating increment $increment_id to $TARGET_LANGUAGE..."
     log_info ""
 
+    # Create English backups if configured
+    if [ "$KEEP_ENGLISH_ORIGINALS" = "true" ]; then
+      for file in "${files_to_translate[@]}"; do
+        local backup="${file%.md}.en.md"
+        cp "$file" "$backup" 2>/dev/null || true
+        log_debug "Created English backup: $backup"
+      done
+    fi
+
     for file in "${files_to_translate[@]}"; do
       if translate_file "$file"; then
         ((increment_success_count++))
@@ -675,19 +714,24 @@ EOF
 
     log_info ""
     if [ "$increment_success_count" -eq "$increment_total_count" ]; then
-      log_info "✅ Increment files translation complete! All $increment_total_count file(s) now in English"
+      log_info "✅ Increment files translated to $TARGET_LANGUAGE! ($increment_total_count file(s))"
     else
-      log_error "Increment files translation completed with errors: $increment_success_count/$increment_total_count files translated"
+      log_error "Translation completed with errors: $increment_success_count/$increment_total_count files"
     fi
-  else
-    log_info "✅ All increment files already in English"
+  elif [ "$TRANSLATION_ENABLED" = "true" ] && [ "$AUTO_TRANSLATE_INCREMENT_SPECS" = "false" ]; then
+    log_debug "Increment spec translation disabled in scope.incrementSpecs"
+  elif [ "$needs_translation" = "false" ]; then
+    log_debug "All increment files already in target language"
   fi
 
-  # 6. Translate living docs specs (if any were created)
-  log_info ""
-  log_info "🌐 Checking living docs for translation..."
-
-  translate_living_docs_specs "$increment_id"
+  # 6. Translate living docs specs (if enabled in scope)
+  if [ "$TRANSLATION_ENABLED" = "true" ] && [ "$AUTO_TRANSLATE_LIVING_DOCS" = "true" ]; then
+    log_info ""
+    log_info "🌐 Checking living docs for translation to $TARGET_LANGUAGE..."
+    translate_living_docs_specs "$increment_id"
+  else
+    log_debug "Living docs translation disabled (scope.livingDocs=$AUTO_TRANSLATE_LIVING_DOCS)"
+  fi
 
   # ============================================================================
   # INCREMENT-LEVEL GITHUB ISSUE CREATION (DEPRECATED v0.24.0+)