specweave 0.28.68 → 0.29.1

package/dist/src/utils/feature-id-derivation.js

@@ -0,0 +1,77 @@
+/**
+ * Feature ID Derivation Utility
+ *
+ * Derives feature ID from increment ID using the 1:1 mapping principle:
+ * - Each increment maps to exactly one feature folder
+ * - Feature ID = FS-{increment_number}
+ *
+ * @example
+ * deriveFeatureId('0081-ado-repo-cloning') → 'FS-081'
+ * deriveFeatureId('0100-some-feature') → 'FS-100'
+ * deriveFeatureId('1000-future-feature') → 'FS-1000'
+ *
+ * @see ADR-0140 for the decision rationale
+ */
+/**
+ * Derive feature ID from increment ID
+ *
+ * The feature ID is derived directly from the increment number:
+ * - Extract leading digits from increment ID
+ * - Format as FS-XXX (minimum 3 digits, more if needed)
+ *
+ * This eliminates the need to store feature_id in metadata.json,
+ * as it's 100% derivable from the increment ID.
+ *
+ * @param incrementId - Increment ID (e.g., "0081-ado-repo-cloning")
+ * @returns Feature ID (e.g., "FS-081")
+ * @throws Error if increment ID format is invalid
+ */
+export function deriveFeatureId(incrementId) {
+    const match = incrementId.match(/^(\d+)/);
+    if (!match) {
+        throw new Error(`Invalid increment ID format: ${incrementId}. Expected format: NNNN-name`);
+    }
+    const num = parseInt(match[1], 10);
+    // padStart(3, '0') ensures minimum 3 digits (FS-001 to FS-999)
+    // Numbers 1000+ naturally have 4+ digits (FS-1000, FS-1001, etc.)
+    return `FS-${String(num).padStart(3, '0')}`;
+}
+/**
+ * Extract increment number from increment ID
+ *
+ * @param incrementId - Increment ID (e.g., "0081-ado-repo-cloning")
+ * @returns Increment number (e.g., 81)
+ * @throws Error if increment ID format is invalid
+ */
+export function extractIncrementNumber(incrementId) {
+    const match = incrementId.match(/^(\d+)/);
+    if (!match) {
+        throw new Error(`Invalid increment ID format: ${incrementId}. Expected format: NNNN-name`);
+    }
+    return parseInt(match[1], 10);
+}
+/**
+ * Validate feature ID format
+ *
+ * Valid formats:
+ * - FS-XXX (internal, 3+ digits)
+ * - FS-XXXE (external, 3+ digits with E suffix)
+ *
+ * @param featureId - Feature ID to validate
+ * @returns true if valid, false otherwise
+ */
+export function isValidFeatureId(featureId) {
+    return /^FS-\d{3,}E?$/.test(featureId);
+}
+/**
+ * Check if feature ID is external (imported)
+ *
+ * External features have an 'E' suffix: FS-042E
+ *
+ * @param featureId - Feature ID to check
+ * @returns true if external, false if internal
+ */
+export function isExternalFeatureId(featureId) {
+    return featureId.endsWith('E');
+}
+//# sourceMappingURL=feature-id-derivation.js.map

package/dist/src/utils/feature-id-derivation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"feature-id-derivation.js","sourceRoot":"","sources":["../../../src/utils/feature-id-derivation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,eAAe,CAAC,WAAmB;IACjD,MAAM,KAAK,GAAG,WAAW,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;IAC1C,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,MAAM,IAAI,KAAK,CAAC,gCAAgC,WAAW,8BAA8B,CAAC,CAAC;IAC7F,CAAC;IAED,MAAM,GAAG,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IACnC,+DAA+D;IAC/D,kEAAkE;IAClE,OAAO,MAAM,MAAM,CAAC,GAAG,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC;AAC9C,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,sBAAsB,CAAC,WAAmB;IACxD,MAAM,KAAK,GAAG,WAAW,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;IAC1C,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,MAAM,IAAI,KAAK,CAAC,gCAAgC,WAAW,8BAA8B,CAAC,CAAC;IAC7F,CAAC;IACD,OAAO,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;AAChC,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,gBAAgB,CAAC,SAAiB;IAChD,OAAO,eAAe,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;AACzC,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,mBAAmB,CAAC,SAAiB;IACnD,OAAO,SAAS,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;AACjC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specweave",
-  "version": "0.28.68",
+  "version": "0.29.1",
   "description": "Spec-driven development framework for Claude Code. AI-native workflow with living documentation, intelligent agents, and multilingual support (9 languages). Enterprise-grade traceability with permanent specs and temporary increments.",
   "type": "module",
   "main": "dist/index.js",
@@ -95,6 +95,7 @@
     "js-yaml": "^4.1.0",
     "open": "^11.0.0",
     "ora": "^9.0.0",
+    "uuid": "^13.0.0",
     "yaml": "^2.3.4"
   },
   "devDependencies": {
@@ -102,6 +103,7 @@
     "@playwright/test": "^1.48.0",
     "@types/js-yaml": "^4.0.9",
     "@types/node": "^24.10.0",
+    "@types/uuid": "^10.0.0",
     "@vitest/coverage-v8": "^2.1.9",
     "@vitest/ui": "^2.1.9",
     "ajv": "^8.17.1",

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

@@ -0,0 +1,141 @@
+# Discrepancies Command
+
+View and manage documentation discrepancies. Supports two modes:
+1. **Code-to-Spec**: Real-time discrepancies between code and specs
+2. **Brownfield**: Documentation gaps detected by brownfield analysis
+
+## Usage
+
+```bash
+# Brownfield discrepancies (documentation gaps)
+/specweave:discrepancies                  # List pending brownfield discrepancies
+/specweave:discrepancies --module payment # Filter by module name
+/specweave:discrepancies --type missing-docs    # Filter by type
+/specweave:discrepancies --priority critical    # Filter by priority
+/specweave:discrepancies show DISC-0001   # View details
+/specweave:discrepancies ignore DISC-0001 "False positive"  # Ignore with reason
+
+# Code-to-spec discrepancies (legacy)
+/specweave:discrepancies --check          # Run code-spec check now
+/specweave:discrepancies --severity major # Filter by severity
+```
+
+## Arguments
+
+**Brownfield mode (default)**:
+- `--module <name>`: Filter by module name (e.g., "payment-service")
+- `--type <type>`: Filter by type: `missing-docs`, `stale-docs`, `knowledge-gap`, `orphan-doc`, `missing-adr`
+- `--priority <level>`: Filter by priority: `critical`, `high`, `medium`, `low`
+- `--status <status>`: Filter by status: `pending`, `in-progress`, `resolved`, `ignored`
+
+**Code-to-spec mode**:
+- `--check`: Run discrepancy detection now
+- `--severity <level>`: Filter by severity: `trivial`, `minor`, `major`, `breaking`
+
+**Common**:
+- `--json`: Output as JSON for scripting
+
+## Subcommands
+
+### list (default)
+
+Lists detected discrepancies with severity, type, and description.
+
+```
+🔍 DETECTED DISCREPANCIES (5)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+DISC-0001   ❌ BREAKING   api-route          POST /api/users removed
+DISC-0002   ⚠️ MAJOR      function-signature  getUserById params changed
+DISC-0003   ⚠️ MINOR      api-route          GET /api/orders path changed
+DISC-0004   ✅ TRIVIAL    type-definition    User type updated
+DISC-0005   ⚠️ MAJOR      api-route          New DELETE /api/users/:id
+
+Use '/specweave:discrepancies show <id>' to view details
+Use '/specweave:discrepancies accept <id>' to apply patch
+```
+
+### show <id>
+
+Shows full discrepancy details with recommended action and patch.
+
+```
+🔍 DISCREPANCY DETAILS
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+ID:          DISC-0002
+Type:        function-signature
+Category:    modified
+Severity:    ⚠️ major
+Risk:        medium
+
+Spec Value:  getUserById(id: string): User
+Code Value:  getUserById(id: string, options?: Options): User | null
+
+Spec File:   docs/api.md:45
+Code File:   src/services/user.ts:123
+
+Description: Function signature has changed from documented version.
+             Code is the source of truth - specs should be updated.
+
+Recommended: 👀 review-required
+Patch Available: Yes
+
+Use '/specweave:discrepancies accept DISC-0002' to apply patch
+Use '/specweave:discrepancies dismiss DISC-0002' to mark intentional
+```
+
+### check
+
+Run discrepancy detection immediately.
+
+```
+🔍 Running discrepancy check...
+
+Analyzing:
+  ✓ TypeScript functions: 156 exported
+  ✓ Type definitions: 89 exported
+  ✓ API routes: 34 detected
+
+Comparing against specs:
+  ✓ Parsed 12 spec files
+
+Results:
+  Found 5 discrepancies
+  - Breaking: 1
+  - Major: 2
+  - Minor: 1
+  - Trivial: 1
+
+Use '/specweave:discrepancies' to view list
+```
+
+### accept <id>
+
+Apply the recommended patch to update specs.
+
+```
+🔧 Applying patch for DISC-0002...
+
+File:    docs/api.md
+Line:    45
+Change:  getUserById(id: string): User
+      →  getUserById(id: string, options?: Options): User | null
+
+✅ Patch applied successfully
+Remaining: 4 discrepancies
+```
+
+### dismiss <id>
+
+Mark a discrepancy as intentional (won't be flagged again).
+
+```
+✅ Dismissed DISC-0002 (marked as intentional)
+Remaining: 4 discrepancies
+```
+
+## Related
+
+- `/specweave:sync-monitor`: Dashboard showing discrepancy count
+- `/specweave:notifications`: View discrepancy notifications

package/plugins/specweave/commands/specweave-discrepancy-to-increment.md

@@ -0,0 +1,160 @@
+# Discrepancy to Increment Command
+
+Convert one or more brownfield discrepancies into a new increment for systematic documentation improvement.
+
+## Usage
+
+```bash
+/specweave:discrepancy-to-increment DISC-0001
+/specweave:discrepancy-to-increment DISC-0001 DISC-0002 DISC-0003
+/specweave:discrepancy-to-increment --module payment-service
+```
+
+## Arguments
+
+- `<discrepancy-ids>`: One or more discrepancy IDs to convert (e.g., DISC-0001 DISC-0002)
+- `--module <name>`: Convert all pending discrepancies for a specific module
+- `--type <type>`: Convert all discrepancies of a specific type
+- `--priority <level>`: Convert all discrepancies at or above a priority level
+- `--dry-run`: Preview what would be created without making changes
+
+## Process
+
+1. **Read Discrepancy Details**
+   - Load specified discrepancies from `.specweave/discrepancies/`
+   - Verify all discrepancies exist and are in `pending` status
+
+2. **Group by Module** (if multiple)
+   - If discrepancies span multiple modules, ask if user wants:
+     - Single increment covering all modules
+     - Separate increments per module
+
+3. **Generate Increment Spec**
+   - Create increment with auto-generated ID
+   - Include discrepancy context in spec.md
+   - Generate user stories from discrepancies
+   - Link code/doc locations
+
+4. **Update Discrepancy Status**
+   - Change status from `pending` to `in-progress`
+   - Add `incrementId` reference
+
+5. **On Increment Completion**
+   - When increment closes via `/specweave:done`
+   - All linked discrepancies auto-marked `resolved`
+   - Archived to `resolved/YYYY-MM/`
+
+## Example Output
+
+```
+🔄 Converting discrepancies to increment...
+
+Selected discrepancies:
+  ├─ DISC-0001: missing-docs (payment-service)
+  ├─ DISC-0002: missing-docs (payment-service)
+  └─ DISC-0003: stale-docs (payment-service)
+
+Module: payment-service
+Total: 3 discrepancies
+
+Generated increment: 0087-payment-docs-improvement
+
+📝 spec.md created with:
+  • 1 user story: Document payment-service module
+  • 3 acceptance criteria (one per discrepancy)
+  • Links to affected code locations
+
+Updated discrepancy status:
+  ├─ DISC-0001: pending → in-progress
+  ├─ DISC-0002: pending → in-progress
+  └─ DISC-0003: pending → in-progress
+
+Next steps:
+  1. Review: .specweave/increments/0087-payment-docs-improvement/spec.md
+  2. Plan: /specweave:plan 0087
+  3. Execute: /specweave:do 0087
+```
+
+## Generated Spec Structure
+
+```markdown
+---
+increment: 0087-payment-docs-improvement
+status: planning
+type: documentation
+---
+
+# Documentation Improvement: payment-service
+
+## Context
+
+This increment addresses documentation gaps detected during brownfield analysis.
+
+### Source Discrepancies
+
+| ID | Type | Priority | Summary |
+|----|------|----------|---------|
+| DISC-0001 | missing-docs | high | 12 undocumented exports |
+| DISC-0002 | missing-docs | medium | processPayment function lacks docs |
+| DISC-0003 | stale-docs | high | Payment flow diagram outdated |
+
+## User Story
+
+### US-001: Document payment-service Module
+
+**As a** new developer joining the team,
+**I want** comprehensive documentation for the payment-service module,
+**So that** I can understand and contribute to the payment flow.
+
+#### Acceptance Criteria
+
+- [ ] **AC-US1-01**: Document all 12 undocumented exports (DISC-0001)
+- [ ] **AC-US1-02**: Add JSDoc to processPayment function (DISC-0002)
+- [ ] **AC-US1-03**: Update payment flow diagram to match current implementation (DISC-0003)
+
+## Technical Notes
+
+### Affected Files
+
+From DISC-0001:
+- `src/payment/processor.ts`
+- `src/payment/validator.ts`
+- `src/payment/types.ts`
+
+From DISC-0003:
+- `docs/modules/payment.md` (diagram needs update)
+```
+
+## Completion Hook
+
+When the increment is closed with `/specweave:done`:
+
+```typescript
+// Automatically triggered by increment completion
+async function onIncrementComplete(incrementId: string) {
+  const manager = new BrownfieldDiscrepancyManager(projectPath);
+
+  // Find all discrepancies linked to this increment
+  const discrepancies = await manager.listDiscrepancies({
+    incrementId,
+    status: 'in-progress'
+  });
+
+  // Resolve each discrepancy
+  for (const disc of discrepancies) {
+    await manager.resolveDiscrepancy(disc.id, {
+      type: 'doc-updated',
+      resolvedAt: new Date().toISOString(),
+      resolvedBy: 'increment-completion'
+    });
+  }
+
+  console.log(`✅ Resolved ${discrepancies.length} discrepancies`);
+}
+```
+
+## Related
+
+- `/specweave:discrepancies` - View pending discrepancies
+- `/specweave:increment` - Create new increment manually
+- `/specweave:done` - Complete increment (triggers resolution)

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

@@ -16,6 +16,7 @@ Monitor and manage long-running background operations:
 - **Repository cloning** (multi-repo/umbrella setup)
 - **Issue import** (10K+ items from GitHub/JIRA/ADO)
 - **External sync** operations
+- **Brownfield analysis** (codebase documentation gap detection)
 
 **ASYNC ARCHITECTURE (2025-12-01)**:
 - Jobs run as **detached processes** that survive terminal close
@@ -58,21 +59,27 @@ STATE_FILE=".specweave/state/background-jobs.json"
 ```
 📋 Background Jobs
 
-🔄 Running (1):
+🔄 Running (2):
   [abc12345] import-issues (ADO)
      Progress: 2,500/10,000 (25%)
      Rate: 15.2/s | ETA: ~8m 14s
      PID: 45678 | Started: 2 mins ago
 
+  [bfa99001] brownfield-analysis
+     Phase: 3/5 (doc-matching)
+     Files scanned: 1,234 | Discrepancies: 45
+     PID: 45680 | Started: 5 mins ago
+
 ⏸️  Paused (1):
   [def67890] import-issues (GitHub)
      Progress: 1,234/10,000 (12%)
      Reason: Rate limited (resumes in 45s)
      Resume: /specweave:jobs --resume def67890
 
-✅ Completed (2):
+✅ Completed (3):
   [ghi11111] import-issues - 4,500 items - 5 mins ago
   [jkl22222] clone-repos - 4/4 repos - 1 hour ago
+  [bfa88001] brownfield-analysis - 127 discrepancies - 2 hours ago
 
 💡 Commands:
    /specweave:jobs --id abc12345     → Details for specific job
@@ -231,6 +238,7 @@ const result = await launchImportJob({
 | `clone-repos` | Multi-repo cloning | 1-5 mins |
 | `import-issues` | Issue import from external | 5-60 mins |
 | `sync-external` | Bidirectional sync | 1-10 mins |
+| `brownfield-analysis` | Doc gap detection | 2-30 mins |
 
 ---
 
@@ -240,6 +248,41 @@ const result = await launchImportJob({
 - Called after `/specweave:import-external` starts background import
 - Called after `/specweave-github:sync` for large syncs
 - Called after `/specweave-jira:sync` for large syncs
+- Called after `specweave init` brownfield analysis prompt
+
+---
+
+## Brownfield Analysis Completion
+
+When a brownfield-analysis job completes, it shows a summary:
+
+```
+✅ Brownfield Analysis Complete (bfa88001)
+
+📊 Results Summary:
+   Files analyzed: 2,456
+   Modules detected: 18
+   Duration: 12m 34s
+
+📋 Discrepancies Found: 127
+   By Type:
+     missing-docs:   72 (57%)
+     stale-docs:     28 (22%)
+     knowledge-gap:  15 (12%)
+     orphan-doc:      8 (6%)
+     missing-adr:     4 (3%)
+
+   By Priority:
+     🔴 Critical:    3
+     🟠 High:       24
+     🟡 Medium:     68
+     🟢 Low:        32
+
+💡 Next Steps:
+   /specweave:discrepancies           → View all pending discrepancies
+   /specweave:discrepancies --module auth → Filter by module
+   /specweave:discrepancy-to-increment DISC-0001 DISC-0002 → Create increment
+```
 
 ---
 

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

@@ -0,0 +1,92 @@
+# Notifications Command
+
+View and manage sync notifications - import completions, discrepancies, sync failures, and more.
+
+## Usage
+
+```bash
+/specweave:notifications                     # List pending notifications
+/specweave:notifications --all               # Include dismissed notifications
+/specweave:notifications --type sync-failure # Filter by type
+/specweave:notifications --severity warning  # Filter by severity
+/specweave:notifications show <id>           # Show notification details
+/specweave:notifications dismiss <id>        # Dismiss a notification
+/specweave:notifications dismiss-all         # Dismiss all pending notifications
+```
+
+## Arguments
+
+- `--all`: Include dismissed notifications in the list
+- `--type <type>`: Filter by notification type:
+  - `import-complete`: Import job finished
+  - `discrepancy`: Code-spec discrepancy detected
+  - `sync-failure`: Sync operation failed
+  - `drift`: Status drift detected
+  - `job-complete`: Scheduled job finished
+- `--severity <level>`: Filter by severity: `info`, `warning`, `critical`
+- `--json`: Output as JSON for scripting
+
+## Subcommands
+
+### list (default)
+
+Lists notifications with severity emoji, title, and age.
+
+```
+📬 PENDING NOTIFICATIONS (3)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+notif-abc123   ❗ CRITICAL   GitHub sync failed           2m ago
+notif-def456   ⚠️ WARNING    2 discrepancies in FS-045    1h ago
+notif-ghi789   ℹ️ INFO       107 items imported           3h ago
+
+Use '/specweave:notifications show <id>' to view details
+Use '/specweave:notifications dismiss <id>' to dismiss
+```
+
+### show <id>
+
+Shows full notification details including data payload.
+
+```
+📬 NOTIFICATION DETAILS
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+ID:        notif-abc123
+Type:      sync-failure
+Severity:  ❗ critical
+Title:     GitHub sync failed
+Message:   Rate limit exceeded. Retry in 15 minutes.
+Created:   2025-12-01 12:00:00 (2m ago)
+
+Data:
+  platform: github
+  error: Rate limit exceeded
+  retryAfter: 900
+```
+
+### dismiss <id>
+
+Dismisses a single notification.
+
+```
+✅ Dismissed notification notif-abc123
+
+Remaining: 2 pending notifications
+```
+
+### dismiss-all
+
+Dismisses all pending notifications with confirmation.
+
+```
+⚠️ This will dismiss 3 pending notifications.
+Proceed? [y/N]: y
+
+✅ Dismissed 3 notifications
+```
+
+## Related
+
+- `/specweave:sync-monitor`: Dashboard showing notification summary
+- `/specweave:discrepancies`: View and act on discrepancy notifications