specweave 1.0.593 → 2.0.3

package/plugins/specweave/commands/reconcile.md

@@ -1,440 +0,0 @@
----
-description: Reconcile increment ID collisions after multi-developer merge. Renumbers conflicting increments based on modification dates.
-disable-model-invocation: true
----
-
-# Reconcile Increment IDs
-
-**Post-merge command for multi-developer workflows.** When multiple developers create increments with the same ID on different branches, run this after merging to resolve collisions by renumbering.
-
-## Philosophy
-
-**Renumber, don't delete.** Unlike `sw:fix-duplicates` which removes duplicates, this command:
-- Keeps ALL increments intact
-- Renumbers the "later" ones (by modification date) to next available IDs
-- Updates all references (metadata, living docs, external sync)
-- Creates audit trail of what was renamed
-
-## When to Use
-
-Run after merging branches that may have created increments with same IDs:
-
-```bash
-git checkout main
-git merge feature-branch-a
-git merge feature-branch-b
-sw:reconcile           # Fix any ID collisions
-git add . && git commit -m "reconcile: fix increment ID collisions"
-```
-
-## Usage
-
-```bash
-# Detect and fix all ID collisions (interactive)
-sw:reconcile
-
-# Preview what would change (dry-run)
-sw:reconcile --dry-run
-
-# Auto-fix without confirmation
-sw:reconcile --force
-
-# Check specific increment number
-sw:reconcile 0001
-```
-
-## Options
-
-- `<increment-number>`: Optional. Check only collisions for specific number (e.g., "0001")
-- `--dry-run`: Show what would change without making modifications
-- `--force`: Skip confirmation prompts (for CI/scripts)
-- `--by-commit`: Use git commit date instead of file modification date for ordering
-
-## How It Works
-
-### Step 1: Detection
-
-Scans ALL increment directories for ID collisions:
-- `.specweave/increments/NNNN-*` (active)
-- `.specweave/increments/_archive/NNNN-*`
-- `.specweave/increments/_abandoned/NNNN-*`
-- `.specweave/increments/_paused/NNNN-*`
-
-**Collision detection**:
-- Same base number (e.g., two `0001E-*` folders)
-- OR same number with different E-suffix (e.g., `0001-*` and `0001E-*`)
-
-### Step 2: Chronological Ordering
-
-Uses file modification dates to determine which increment came first:
-
-```
-0001E-auth-feature/      modified: 2026-01-15 10:00
-0001E-payment-feature/   modified: 2026-01-20 14:30  ← LATER (renumber)
-```
-
-**Date sources (priority order)**:
-1. `metadata.json` → `created` field
-2. `spec.md` file modification time
-3. Directory modification time
-4. Git first commit date (if `--by-commit`)
-
-### Step 3: Renumbering
-
-The "later" increment gets renumbered to next available ID:
-
-```
-BEFORE:
-  0001E-auth-feature/        (Jan 15)
-  0001E-payment-feature/     (Jan 20)
-
-AFTER:
-  0001E-auth-feature/        (kept as 0001E)
-  0002E-payment-feature/     (renumbered to 0002E)
-```
-
-### Step 4: Reference Updates
-
-Updates ALL references to the renumbered increment:
-
-**Local Files:**
-1. **metadata.json** - Updates `id` field, adds `reconcileHistory` entry
-2. **spec.md frontmatter** - Updates `increment:` field
-3. **Living docs** - Renames `FS-XXX` folders in `.specweave/docs/internal/specs/`
-   - Updates `FEATURE.md` frontmatter and content
-   - Updates all `us-*.md` user story files
-
-**External Tools (automatically updated via API):**
-4. **GitHub**:
-   - Milestone titles containing old feature ID
-   - Issue titles with `[FS-XXX]` prefix
-   - Uses `gh` CLI for updates
-5. **JIRA**:
-   - Epic/story summary (title) containing old feature ID
-   - Uses JIRA REST API v3
-6. **ADO**:
-   - Feature/user story `System.Title` field
-   - Uses ADO REST API
-
-### Step 5: Audit Report
-
-Creates `reports/RECONCILE-{timestamp}.md` documenting:
-- Original ID → New ID mapping
-- Which references were updated
-- Modification dates used for ordering
-
-## Examples
-
-### Example 1: Two External Imports Collision
-
-Two developers imported issues from JIRA, both got 0001E:
-
-```bash
-sw:reconcile
-```
-
-**Output**:
-```
-🔄 Scanning for ID collisions...
-
-Found 1 collision:
-
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-Collision: Base ID 0001E (2 increments)
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-Increments (ordered by modification date):
-  1. 0001E-auth-feature           (2026-01-15) → KEEP
-  2. 0001E-payment-feature        (2026-01-20) → RENUMBER to 0002E
-
-Proceeding with reconciliation...
-
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-Summary
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-Collisions found: 1
-Increments renumbered: 1
-References updated: 7
-
-📦 Operations performed:
-
-  ✓ 0001E-payment-feature → 0002E-payment-feature
-    Feature: FS-001E → FS-002E
-    Updated:
-      ✓ metadata: Renamed folder
-      ✓ metadata: Updated id field in metadata.json
-      ✓ spec: Updated increment field in spec.md
-      ✓ living-docs: Renamed FS-001E → FS-002E
-      ✓ github: Updated issue #45 title: FS-001E → FS-002E
-      ✓ jira: Updated PROJ-123 summary: FS-001E → FS-002E
-      ✓ ado: Updated work item #789 title: FS-001E → FS-002E
-
-📝 Report saved to: .specweave/increments/reports/RECONCILE-20260201-120000.md
-
-💡 Next steps:
-  1. Review the changes
-  2. git add . && git commit -m "reconcile: fix ID collisions"
-  3. Run sw-github:sync or sw-jira:sync to update external tools
-```
-
-### Example 2: Dry-Run Preview
-
-```bash
-sw:reconcile --dry-run
-```
-
-**Output**:
-```
-[DRY RUN] Scanning for ID collisions...
-
-Found 2 collisions:
-
-Collision 1: Base ID 0001E
-  [DRY RUN] Would keep: 0001E-auth-feature (2026-01-15)
-  [DRY RUN] Would renumber: 0001E-payment-feature → 0002E-payment-feature
-
-Collision 2: Base ID 0005
-  [DRY RUN] Would keep: 0005-user-profile (2026-01-10)
-  [DRY RUN] Would renumber: 0005-dashboard → 0006-dashboard
-
-Summary:
-  Would renumber: 2 increments
-  Would update: 8 references
-
-Run without --dry-run to apply changes.
-```
-
-### Example 3: Three-Way Collision
-
-Three developers created 0001E increments:
-
-```bash
-sw:reconcile
-```
-
-**Output**:
-```
-Collision: Base ID 0001E (3 increments)
-
-Increments (ordered by modification date):
-  1. 0001E-auth-feature      (2026-01-10) → KEEP as 0001E
-  2. 0001E-payment-feature   (2026-01-15) → RENUMBER to 0002E
-  3. 0001E-user-profile      (2026-01-20) → RENUMBER to 0003E
-
-Proceed? [y/N]: y
-
-✓ Kept 0001E-auth-feature as 0001E
-✓ Renamed 0001E-payment-feature → 0002E-payment-feature
-✓ Renamed 0001E-user-profile → 0003E-user-profile
-```
-
-### Example 4: Archive Collision
-
-Collision between active and archived increment:
-
-```bash
-sw:reconcile
-```
-
-**Output**:
-```
-Collision: Base ID 0042 (2 increments)
-
-Increments:
-  1. _archive/0042-old-feature    (2026-01-05, archived) → KEEP as 0042
-  2. 0042-new-feature             (2026-01-25, active)   → RENUMBER to 0043
-
-Note: Archived increment keeps original ID (earlier date)
-```
-
-## Reference Update Details
-
-### metadata.json
-
-```json
-// BEFORE
-{ "id": "0001E-payment-feature", ... }
-
-// AFTER
-{ "id": "0002E-payment-feature", ... }
-```
-
-### spec.md Frontmatter
-
-```yaml
-# BEFORE
----
-increment: 0001E-payment-feature
-title: "Payment Feature"
----
-
-# AFTER
----
-increment: 0002E-payment-feature
-title: "Payment Feature"
----
-```
-
-### Living Docs
-
-```
-# BEFORE
-.specweave/docs/internal/specs/backend/FS-001E/
-
-# AFTER
-.specweave/docs/internal/specs/backend/FS-002E/
-```
-
-### External Sync (GitHub)
-
-If GitHub milestone exists:
-- Old: Milestone "FS-001E: Payment Feature"
-- New: Milestone "FS-002E: Payment Feature"
-
-Note: GitHub issue numbers don't change (milestone renamed, not recreated)
-
-## Error Handling
-
-### No Collisions Found
-
-```
-Scanning for ID collisions...
-
-✓ No collisions found!
-
-All increment IDs are unique across all folders.
-```
-
-### Renumbering Fails
-
-```
-Error renumbering 0001E-payment-feature:
-  Failed to rename directory
-  Reason: Permission denied
-
-Recommendation:
-  1. Check folder permissions
-  2. Close any programs using these files
-  3. Retry
-```
-
-### External Sync Reference Update Fails
-
-```
-Warning: Could not update GitHub milestone
-  Milestone "FS-001E" not found on remote
-
-The increment was renumbered locally.
-Run sw-github:sync to recreate the milestone.
-```
-
-## Reconcile Report Format
-
-**File**: `reports/RECONCILE-{timestamp}.md`
-
-```markdown
-# Increment ID Reconciliation Report
-
-**Date**: 2026-02-01 12:00:00 UTC
-**Command**: sw:reconcile
-**Trigger**: Post-merge ID collision resolution
-
-## Collisions Detected
-
-### Collision 1: Base ID 0001E
-
-| Original Path | Modified Date | Action |
-|---------------|---------------|--------|
-| 0001E-auth-feature | 2026-01-15 | KEPT |
-| 0001E-payment-feature | 2026-01-20 | RENUMBERED → 0002E |
-
-## Renaming Operations
-
-| Original ID | New ID | Folder Path |
-|-------------|--------|-------------|
-| 0001E-payment-feature | 0002E-payment-feature | .specweave/increments/ |
-
-## Reference Updates
-
-### 0002E-payment-feature (formerly 0001E)
-
-- [x] metadata.json: id field updated
-- [x] spec.md: frontmatter updated
-- [x] Living docs: FS-001E → FS-002E renamed
-- [ ] GitHub milestone: Not found (needs manual sync)
-- [x] JIRA epic: Updated PROJ-123 custom field
-
-## Summary
-
-- Collisions resolved: 1
-- Increments renumbered: 1
-- Living docs renamed: 1
-- External refs updated: 1
-- Manual action needed: 1 (GitHub milestone)
-```
-
-## Implementation
-
-The reconcile command should:
-
-1. **Scan all increment folders** using `IncrementNumberManager.getAllIncrementNumbers()`
-
-2. **Group by base number** (strip E suffix for comparison):
-   ```typescript
-   const groups = groupBy(increments, inc => inc.baseNumber);
-   const collisions = groups.filter(g => g.length > 1);
-   ```
-
-3. **Order by modification date**:
-   ```typescript
-   collision.sort((a, b) =>
-     new Date(a.modifiedDate).getTime() - new Date(b.modifiedDate).getTime()
-   );
-   ```
-
-4. **Renumber later increments**:
-   ```typescript
-   for (let i = 1; i < collision.length; i++) {
-     const newNumber = IncrementNumberManager.getNextIncrementNumber(root);
-     await renameIncrement(collision[i], newNumber);
-   }
-   ```
-
-5. **Update references**:
-   ```typescript
-   await updateMetadataId(increment, newId);
-   await updateSpecFrontmatter(increment, newId);
-   await renameLivingDocsFolder(oldFeatureId, newFeatureId);
-   await updateExternalSyncRefs(increment, newId);
-   ```
-
-## Related Commands
-
-- `sw:fix-duplicates` - Remove actual duplicates (same increment in multiple locations)
-- `sw:status` - View all increments
-- `sw:sync-docs` - Sync living docs after reconciliation
-- `sw-github:sync` - Update GitHub references after reconciliation
-
-## Best Practices
-
-1. **Always run after multi-branch merge** - Make it a habit
-2. **Use dry-run first** - Preview changes before applying
-3. **Commit the reconciliation** - The renumbering should be a separate commit
-4. **Sync external tools** - Run `sw-github:sync` or `sw-jira:sync` after reconcile
-
-```bash
-# Recommended post-merge workflow
-git merge feature-branch
-sw:reconcile --dry-run    # Preview
-sw:reconcile              # Apply
-git add . && git commit -m "reconcile: fix ID collisions after merge"
-sw-github:sync            # Update external tools
-```
-
-## Safety Notes
-
-- **Non-destructive**: All increments are preserved, only renumbered
-- **Reversible**: Git history preserves original state
-- **Audit trail**: Reports document all changes
-- **External sync safe**: Updates references, doesn't delete external issues

package/plugins/specweave/commands/reflect.md

@@ -1,264 +0,0 @@
----
-description: Analyze session and extract learnings to CLAUDE.md Skill Memories. Supports subcommands --on, --off, --status, --clear. Activates for reflect, remember, learn from session, extract learnings.
-argument-hint: [--on | --off | --status | --clear [--skill name | --all]]
----
-
-# Reflect Command
-
-**Analyze session and extract learnings to CLAUDE.md Skill Memories section.**
-
-## Usage
-
-```bash
-# Manual reflection (analyzes session signals)
-sw:reflect
-sw:reflect "Focus on the API patterns we discussed"
-
-# Enable auto-reflection on session end
-sw:reflect --on
-
-# Disable auto-reflection
-sw:reflect --off
-
-# Show reflection config and learning statistics
-sw:reflect --status
-
-# Clear learnings
-sw:reflect --clear --skill frontend
-sw:reflect --clear --all
-```
-
-## Subcommands
-
-### Default (no flags) - Manual Reflection
-
-Scans conversation for learnable signals and extracts to CLAUDE.md.
-
-**Signal Detection:**
-
-**Corrections (High Confidence)**
-```
-User: "No, don't use that button. Use our <Button variant='primary'>"
-      → Learning: Always use Button component with variant='primary' from design system
-      → Skill: frontend
-```
-
-**Problem Reports (High Confidence)**
-```
-User: "Voice control doesn't recognize commands"
-      → Learning: Voice dictation mangles slash commands - type manually or paste
-      → Skill: general
-```
-
-**Approvals (Medium Confidence)**
-```
-User: "Perfect! That's exactly how our API should look."
-      → Learning: Continue using API pattern with status, data, error fields
-      → Skill: backend
-```
-
-**LLM Extraction** uses Claude Haiku to extract SpecWeave-specific learnings, then writes to the `## Skill Memories` section in CLAUDE.md.
-
-### `--on` - Enable Auto-Reflection
-
-Enables automatic session analysis via the stop hook.
-
-**Execution:**
-1. Read existing config from `.specweave/config.json`
-2. Update config to set `reflect.enabled: true`
-3. Display confirmation
-
-**Output:**
-```
-Auto-reflection ENABLED
-
-Stop hook will analyze sessions on exit.
-Learnings saved to CLAUDE.md Skill Memories section.
-
-Disable with: sw:reflect --off
-```
-
-### `--off` - Disable Auto-Reflection
-
-Disables automatic session analysis. Manual `sw:reflect` still works.
-
-**CRITICAL: This is a SIMPLE operation. NO Glob, NO parallel tool calls needed.**
-
-**Execution:**
-1. Read existing config from `.specweave/state/reflect-config.json`
-   (If file doesn't exist, create with autoReflect: false)
-2. Write updated config: set `autoReflect` to `false`, preserve other fields
-3. Display confirmation
-
-**Output:**
-```
-Auto-reflection DISABLED
-
-Manual sw:reflect still works.
-Existing learnings preserved.
-
-Re-enable with: sw:reflect --on
-```
-
-**WARNING**: Do NOT use Glob to scan directories - this operation only writes ONE file.
-
-### `--status` - Show Config & Statistics
-
-Shows reflection configuration and learning statistics.
-
-**Execution:**
-1. Read config from `.specweave/config.json` for reflect settings
-2. Read CLAUDE.md to find Skill Memories section
-3. Parse learnings by skill category
-4. Display dashboard
-
-**Output:**
-```
-REFLECT: Status Dashboard
-
-CONFIGURATION
-  Reflection:      Enabled
-  Model:           haiku
-  Max/session:     3
-
-SKILL MEMORIES (CLAUDE.md)
-  Skill           Learnings
-  devops          1
-  frontend        2
-  backend         3
-  general         2
-  Total:          8
-
-RECENT LEARNINGS
-  - [devops] LSP requires ENABLE_LSP_TOOL=1 env var
-  - [frontend] Use shadcn/ui Button component
-  - [backend] Return 404 for missing resources
-
-## Skill Refinement Suggestions
-  Skill            Signals (J/R/C)   Severity   Last seen         Command
-  sw:architect     5 (3/1/1)         high       2026-04-19 18:22  sw:skill-refine sw:architect
-  sw:pm            3 (2/1/0)         medium     2026-04-18 09:07  sw:skill-refine sw:pm
-```
-
-Introduced in **increment 0671 — skill refinement loop**. Skills with ≥3 negative signals in `.specweave/state/skill-signals.json` (`type: "refinement"`) are ranked by severity × recency. Entries with `<3` signals are omitted from the list; the whole section is omitted when no skills qualify.
-
-Signal sources (J/R/C = judge-llm / rubric / code-reviewer) come from closure gates. See [`sw:skill-refine`](./skill-refine.md) for flags, attribution heuristics, and the four red-line ADRs.
-
-### `--clear` - Remove Learnings
-
-Remove specific learnings from CLAUDE.md Skill Memories section.
-
-```bash
-sw:reflect --clear --skill frontend   # Clear all learnings for skill
-sw:reflect --clear --all              # Clear ALL learnings (requires confirmation)
-```
-
-**Execution:**
-1. Read CLAUDE.md to find Skill Memories section
-2. Show confirmation with what will be deleted
-3. Edit CLAUDE.md to remove matching learnings on confirmation
-
-## Session-end Nudge
-
-Added in increment 0671. When `/sw:done` closes an increment, the reflect stop-hook checks whether the session accumulated either:
-
-- ≥1 high-confidence learning (eligible for CLAUDE.md persistence), or
-- ≥1 refinement signal in `.specweave/state/skill-signals.json` attributed to an existing skill.
-
-If so, a **single-line** prompt is printed at closure time:
-
-```
-Detected: 2 signals for sw:architect — run sw:skill-refine sw:architect? (y/N)
-```
-
-or, for a learning nudge:
-
-```
-Detected: 1 high-confidence learning — run sw:reflect? (y/N)
-```
-
-**The nudge never auto-executes a command.** The user must explicitly run the suggested command. Declining (N or no input within 5s) logs no penalty; signals remain in `skill-signals.json` for later invocation.
-
-Performance: the nudge check adds <100ms to `/sw:done` close time.
-
-### Disabling the nudge
-
-Set `reflect.autoNudge: false` in `.specweave/config.json`:
-
-```json
-{
-  "reflect": {
-    "enabled": true,
-    "autoNudge": false
-  }
-}
-```
-
-When `autoNudge` is false, no nudge is printed at close; `sw:reflect` and `sw:skill-refine` remain manually invocable.
-
-## Configuration
-
-In `.specweave/config.json`:
-
-```json
-{
-  "reflect": {
-    "enabled": true,
-    "model": "haiku",
-    "maxLearningsPerSession": 3
-  }
-}
-```
-
-| Setting | Default | Description |
-|---------|---------|-------------|
-| `enabled` | `true` | Master switch for reflection |
-| `model` | `"haiku"` | LLM model for extraction |
-| `maxLearningsPerSession` | `3` | Limit per session |
-| `autoNudge` | `true` | Session-end nudge when learnings or refinement signals are detected (0671) |
-
-## Skill Categories
-
-Learnings are routed to these skills:
-
-| Skill | What it covers |
-|-------|---------------|
-| `mobile` | React Native, Expo, iOS, Android |
-| `frontend` | React, Vue, Next.js, UI components |
-| `backend` | APIs, Node.js, .NET, databases |
-| `testing` | Vitest, Jest, Playwright, E2E |
-| `devops` | CI/CD, Docker, deployments |
-| `architect` | System design, ADRs, patterns |
-| `general` | Fallback for general SpecWeave learnings |
-
-## Quality Rules
-
-**NEVER store user input verbatim. ALWAYS synthesize into actionable rules.**
-
-### Learning Quality Checklist
-
-Before storing ANY learning:
-
-| Check | Requirement | Example Failure |
-|-------|-------------|-----------------|
-| Complete | Full sentence, not truncated | `"eplicilty how to g"` |
-| Actionable | Contains DO/DON'T/USE/AVOID | `"Where should I deploy?"` |
-| Specific | Names tools, patterns, concepts | `"always command not recognized"` |
-| Standalone | Understandable without context | `"user pojrect"` |
-| Not a Question | Must be a statement | `"Where should I deploy?"` |
-
-### What to REJECT (Never Store)
-
-1. **Questions** - Not learnings
-2. **Fragments** - Truncated mid-sentence
-3. **Raw complaints** - Without solution/workaround
-4. **Gibberish/typos** - `"pojrect"`, `"promp"`
-5. **Duplicates** - Already exists in memory
-
-### Self-Check Before Storing
-
-> "If I read this learning in 6 months with no context, would it help me?"
->
-> If NO → Don't store it.
-> If MAYBE → Improve it until YES.
-> If YES → Store it.