specweave 0.1.9 → 0.3.0

package/src/skills/spec-driven-debugging/test-cases/TC-003-brownfield-missing-spec.yaml

@@ -1,366 +0,0 @@
----
-name: "Brownfield Bug with Missing Spec"
-description: "Debug legacy code with no documentation, requiring retroactive spec creation before fixing"
-skill: spec-driven-debugging
-priority: P2
-estimated_time: "30-40 minutes"
-
-input:
-  prompt: "Payment webhook is randomly failing with 'Invalid signature' error for some Stripe events"
-  context:
-    project_type: "Node.js + Express (brownfield, 2 years old)"
-    increment: null # No increment exists for this code
-    documentation: null # No spec.md or plan.md
-    files_exist:
-      - "src/webhooks/stripe.ts" # legacy code, no comments
-      - "src/services/payment-processor.ts"
-    error_pattern: "Intermittent - fails for ~20% of webhook events"
-    reproduction: "Inconsistent - seems related to event type"
-    legacy_context: "Original developer left, no documentation"
-
-expected_output:
-  phase_0_context_loading:
-    announcement: "This is brownfield code with no SpecWeave increment. I'll need to create retroactive documentation before debugging."
-
-    increment_search:
-      search_result: "No increment found for src/webhooks/stripe.ts"
-      strategy_docs: "No strategy docs for payment/webhooks"
-      architecture_docs: "No ADRs for webhook processing"
-
-    bug_classification: "Missing spec - undocumented legacy code"
-
-    retroactive_spec_needed: true
-    reason: "Cannot debug without understanding intended behavior"
-
-    approach: |
-      1. Analyze code to understand CURRENT behavior (as-is)
-      2. Create retroactive spec documenting intended behavior
-      3. THEN debug the discrepancy between spec and actual behavior
-
-  phase_1_root_cause:
-    step_1_understand_current_code:
-      file_analyzed: "src/webhooks/stripe.ts"
-      code_structure:
-        - "POST /webhooks/stripe endpoint"
-        - "Validates Stripe signature using stripe.webhooks.constructEvent()"
-        - "Routes different event types to handlers"
-        - "Event types: payment_intent.succeeded, charge.failed, customer.subscription.updated"
-
-      observations:
-        - "No comments or documentation"
-        - "Signature validation uses Stripe SDK method"
-        - "Different event types handled differently"
-        - "Some events logged, others not"
-        - "No tests found in codebase"
-
-    step_2_gather_business_context:
-      questions_to_ask_user:
-        - "What SHOULD happen when a payment webhook is received?"
-        - "Which event types are critical vs informational?"
-        - "What's the acceptable failure rate?"
-
-      user_answers:
-        - "All webhook events should be processed successfully"
-        - "payment_intent.succeeded is critical (confirms payment)"
-        - "charge.failed is critical (notifies user of failure)"
-        - "customer.subscription.updated is informational only"
-        - "Failure rate should be 0% (currently 20% failing)"
-
-    step_3_create_retroactive_spec:
-      action: "Create .specweave/increments/0012-webhook-processing/ with retroactive spec"
-      file: ".specweave/increments/0012-webhook-processing/spec.md"
-      content: |
-        # Webhook Processing (Retroactive Spec)
-
-        ## Purpose
-        Process Stripe webhook events to confirm payments and update order status.
-
-        ## Functional Requirements
-
-        ### FR-001: Signature Validation
-        All webhook events MUST validate Stripe signature to prevent spoofing.
-        - Use Stripe SDK: stripe.webhooks.constructEvent()
-        - Signature header: stripe-signature
-        - Webhook secret: STRIPE_WEBHOOK_SECRET env var
-
-        ### FR-002: Event Type Handling
-        System MUST handle these event types:
-        - payment_intent.succeeded → Mark order as paid
-        - charge.failed → Notify customer of payment failure
-        - customer.subscription.updated → Update subscription status
-
-        ### FR-003: Idempotency
-        Webhooks MAY be delivered multiple times (Stripe guarantee: at-least-once).
-        System MUST handle duplicate events gracefully (idempotency).
-
-        ## Non-Functional Requirements
-
-        ### NFR-001: Reliability
-        Success rate MUST be >99.9% (currently failing: need to fix)
-
-        ### NFR-002: Response Time
-        Webhook endpoint MUST respond within 5 seconds (Stripe timeout)
-
-        ## Acceptance Criteria
-        - TC-001: Valid webhook with correct signature → 200 OK
-        - TC-002: Invalid signature → 400 Bad Request
-        - TC-003: Duplicate event → Processed once, returns 200 OK
-        - TC-004: All critical event types processed correctly
-
-    retroactive_spec_created: true
-
-    step_4_now_debug_with_spec:
-      error_analysis:
-        message: "Invalid signature"
-        frequency: "20% of events"
-        pattern_observed: "Fails for customer.subscription.updated events mostly"
-
-      reproduction:
-        approach: "Examine Stripe webhook logs for failed events"
-        findings:
-          - "Failed events all have event type: customer.subscription.*"
-          - "Successful events are payment_intent.* and charge.*"
-          - "Signature validation fails BEFORE event type check"
-
-      spec_comparison:
-        spec_says: "FR-001: All events must validate signature using stripe.webhooks.constructEvent()"
-        actual_behavior: "customer.subscription.* events fail signature validation"
-        discrepancy: "Signature validation works for some events, not others"
-
-      data_flow_trace:
-        step_1: "Stripe sends POST to /webhooks/stripe"
-        step_2: "Express receives raw body"
-        step_3: "Code calls stripe.webhooks.constructEvent(body, signature, secret)"
-        step_4_success: "payment_intent.* events → signature valid ✓"
-        step_4_failure: "customer.subscription.* events → signature invalid ✗"
-
-      hypothesis_forming: "Something different about how subscription events are sent or received"
-
-  phase_2_pattern_analysis:
-    working_examples:
-      event_type: "payment_intent.succeeded"
-      body_format: "Raw JSON string"
-      content_type: "application/json"
-      signature_valid: true
-
-    broken_examples:
-      event_type: "customer.subscription.updated"
-      body_format: "Parsed JSON object (not raw string!)"
-      content_type: "application/json"
-      signature_valid: false
-
-    difference_identified:
-      issue: "Body parsing middleware is parsing SOME events but not others"
-      root_cause: "Express body parser middleware conditionally parsing based on Content-Type or event size"
-
-    code_inspection:
-      file: "src/server.ts"
-      middleware_config: |
-        app.use(express.json()); // Parses all JSON bodies
-        app.post('/webhooks/stripe', stripeWebhookHandler);
-
-      problem: |
-        Stripe signature validation requires RAW body (Buffer), not parsed JSON.
-        Express middleware is parsing body BEFORE webhook handler,
-        making signature validation impossible.
-
-        But why does it work for payment_intent.* events?
-        Hypothesis: Those events are smaller, parsed differently by Express?
-
-      investigation_deeper:
-        finding: |
-          Express json() middleware has a "verify" option that can be used
-          to access raw body before parsing. Current code doesn't use this.
-
-          Stripe documentation says: "You must pass the raw request body"
-          Current code passes parsed body → signature always fails
-          BUT: Why do some events succeed?
-
-        aha_moment: |
-          Checked Express middleware order:
-          1. app.use(express.json()) - parses ALL bodies
-          2. app.use('/api', apiRoutes) - other routes
-          3. app.post('/webhooks/stripe', stripeWebhookHandler) - webhook
-
-          Wait... there's ANOTHER middleware defined ABOVE:
-          app.use(express.raw({ type: 'application/json', limit: '5mb' }))
-
-          This raw middleware runs FIRST, but only for bodies <5mb.
-          Subscription events are >5mb (include full customer object),
-          so they get parsed by json() middleware instead!
-
-  phase_3_hypothesis:
-    hypothesis: "Express middleware parsing bodies >5mb as JSON instead of keeping raw Buffer, breaking Stripe signature validation"
-
-    classification: "Code bug + Config bug - middleware misconfiguration"
-
-    minimal_test:
-      approach: "Send test webhook with >5mb payload"
-      result: "Signature validation fails for large events, succeeds for small events"
-      confirmed: true
-
-  phase_4_implementation:
-    fix_level: "Code-level fix (middleware configuration)"
-
-    retroactive_spec_update:
-      file: ".specweave/increments/0012-webhook-processing/spec.md"
-      addition: |
-        ### FR-004: Raw Body Requirement
-        Webhook endpoint MUST receive raw request body (Buffer) for signature validation.
-        Middleware MUST NOT parse body before signature validation.
-
-    test_creation:
-      level: "Level 3: Code Tests (Integration)"
-      file: "tests/integration/webhooks.test.ts"
-      test_case: |
-        describe('Stripe Webhooks', () => {
-          it('should validate signature for small events (<5mb)', async () => {
-            const event = createTestEvent('payment_intent.succeeded', { size: '1kb' });
-            const signature = generateStripeSignature(event);
-
-            const response = await request(app)
-              .post('/webhooks/stripe')
-              .set('stripe-signature', signature)
-              .send(event);
-
-            expect(response.status).toBe(200);
-          });
-
-          it('should validate signature for large events (>5mb)', async () => {
-            const event = createTestEvent('customer.subscription.updated', { size: '6mb' });
-            const signature = generateStripeSignature(event);
-
-            const response = await request(app)
-              .post('/webhooks/stripe')
-              .set('stripe-signature', signature)
-              .send(event);
-
-            expect(response.status).toBe(200); // Currently fails
-          });
-        });
-
-      test_fails_before_fix: true
-
-    code_fix:
-      file: "src/server.ts"
-      before: |
-        app.use(express.raw({ type: 'application/json', limit: '5mb' })); // Only for small bodies
-        app.use(express.json()); // Parses large bodies as JSON
-        app.post('/webhooks/stripe', stripeWebhookHandler);
-
-      after: |
-        // Webhook route FIRST (before body parsing middleware)
-        app.post('/webhooks/stripe',
-          express.raw({ type: 'application/json', limit: '10mb' }), // Raw body for webhooks
-          stripeWebhookHandler
-        );
-
-        // Body parsing for other routes
-        app.use(express.json());
-
-    verification:
-      test_passes: true
-      production_test: "Sent test webhook with 6mb payload → signature valid ✓"
-      spec_aligned: true
-      failure_rate: "0% (was 20%)"
-
-    attempts_count: 1 # fixed after understanding the retroactive spec
-    ultrathink_needed: false # straightforward once spec was created
-
-  phase_5_documentation:
-    increment_updates:
-      - file: ".specweave/increments/0012-webhook-processing/spec.md"
-        change: "Created retroactive spec + added FR-004 for raw body requirement"
-
-      - file: ".specweave/increments/0012-webhook-processing/plan.md"
-        change: "Documented middleware configuration approach"
-
-      - file: ".specweave/increments/0012-webhook-processing/tests.md"
-        change: "Added TC-005 and TC-006 for signature validation with different payload sizes"
-
-    architecture_updates:
-      - file: ".specweave/docs/internal/architecture/adr/0013-webhook-middleware-order.md"
-        content: |
-          # ADR-0013: Webhook Endpoints Must Bypass Body Parsing
-
-          ## Context
-          Express body parsing middleware (json()) parses request bodies,
-          but Stripe signature validation requires raw Buffer.
-
-          ## Decision
-          Webhook routes defined BEFORE global body parsing middleware,
-          with route-specific express.raw() middleware.
-
-          ## Consequences
-          - Webhooks receive raw body for signature validation
-          - Other routes still get parsed JSON bodies
-          - Must remember this pattern for future webhook integrations
-
-    strategy_updates:
-      - file: ".specweave/docs/internal/strategy/payments/webhooks.md"
-        change: "Created strategy doc for payment webhook processing (retroactive)"
-
-    new_increment_needed: false # retroactive spec created, no new increment
-
-    commit_message: |
-      fix(webhooks): support large Stripe webhook events (>5mb)
-
-      Root cause: Express middleware parsing large webhook bodies as JSON
-      instead of keeping raw Buffer, breaking Stripe signature validation.
-
-      Context: This is brownfield code with no documentation. Created
-      retroactive spec (.specweave/increments/0012-webhook-processing/)
-      to document intended behavior before debugging.
-
-      Retroactive spec revealed:
-      - FR-001: All events must validate signature
-      - FR-004: Raw body required for signature validation
-      - Current implementation violated both for events >5mb
-
-      Solution: Moved webhook route BEFORE global body parsing middleware.
-      Webhook now uses route-specific express.raw() middleware with 10mb limit.
-
-      Spec alignment: Now implements FR-001 and FR-004 correctly.
-
-      Test coverage:
-      - Added: TC-005 (small events <5mb)
-      - Added: TC-006 (large events >5mb)
-      - Verified: Signature validation works for all event sizes
-
-      Documentation created (brownfield):
-      - spec.md: Retroactive spec for webhook processing
-      - plan.md: Middleware configuration documented
-      - tests.md: Test cases for regression prevention
-      - ADR-0013: Webhook middleware pattern documented
-      - webhooks.md: Strategy doc for payment webhooks
-
-      Production impact: Failure rate reduced from 20% to 0%
-
-      Fixes: #156
-
-      🤖 Generated with Claude Code
-      Co-Authored-By: Claude <noreply@anthropic.com>
-
-validation:
-  - "Phase 0: Identified missing spec (brownfield code)"
-  - "Phase 0: Created retroactive spec before debugging"
-  - "Phase 1: Analyzed legacy code to understand current behavior"
-  - "Phase 1: Gathered business context from user"
-  - "Phase 1: Compared actual behavior vs retroactive spec"
-  - "Phase 2: Identified middleware configuration issue"
-  - "Phase 3: Formed hypothesis about large event handling"
-  - "Phase 4: Updated retroactive spec with FR-004"
-  - "Phase 4: Fixed with middleware reordering"
-  - "Phase 5: Created comprehensive documentation (spec, plan, tests, ADR, strategy)"
-  - "Brownfield approach: Document first, debug second"
-
-expected_errors: []
-
-success_criteria:
-  - "Retroactive spec created before debugging"
-  - "Root cause identified (middleware order)"
-  - "Fix verified (0% failure rate)"
-  - "Comprehensive documentation for legacy code"
-  - "ADR created for pattern reuse"
-  - "Living documentation bootstrapped for brownfield"
----

package/src/skills/spec-kit-expert/test-cases/test-1-placeholder.yaml

@@ -1,12 +0,0 @@
----
-name: "Placeholder Test"
-description: "TODO: Add actual test case for this skill"
-input:
-  prompt: "Test prompt"
-expected_output:
-  type: "validation"
-validation:
-  - "Placeholder validation"
-success_criteria:
-  - "Test passes"
----

package/src/skills/spec-kit-expert/test-cases/test-2-placeholder.yaml

@@ -1,12 +0,0 @@
----
-name: "Placeholder Test"
-description: "TODO: Add actual test case for this skill"
-input:
-  prompt: "Test prompt"
-expected_output:
-  type: "validation"
-validation:
-  - "Placeholder validation"
-success_criteria:
-  - "Test passes"
----

package/src/skills/spec-kit-expert/test-cases/test-3-placeholder.yaml

@@ -1,12 +0,0 @@
----
-name: "Placeholder Test"
-description: "TODO: Add actual test case for this skill"
-input:
-  prompt: "Test prompt"
-expected_output:
-  type: "validation"
-validation:
-  - "Placeholder validation"
-success_criteria:
-  - "Test passes"
----

package/src/skills/specweave-ado-mapper/test-cases/test-1-export-to-ado.yaml

@@ -1,13 +0,0 @@
-name: "Export SpecWeave Increment to Azure DevOps"
-description: "Test exporting a SpecWeave increment to ADO Epic/Features/Stories"
-user_input: "Export increment 0001-user-auth to Azure DevOps"
-expected_behavior:
-  - Creates Epic from increment spec
-  - Creates Features from main sections
-  - Creates User Stories from tasks
-  - Maps test cases to Test Cases in ADO
-validation:
-  - Epic title matches increment name
-  - Features map to spec sections
-  - User Stories have acceptance criteria
-  - Work item IDs stored in SpecWeave

package/src/skills/specweave-ado-mapper/test-cases/test-2-import-from-ado.yaml

@@ -1,13 +0,0 @@
-name: "Import Azure DevOps Epic to SpecWeave"
-description: "Test importing ADO Epic as a SpecWeave increment"
-user_input: "Import ADO Epic #12345 into SpecWeave"
-expected_behavior:
-  - Creates increment folder with ADO Epic name
-  - Generates spec.md from Epic description
-  - Converts Features to sections in spec
-  - Creates tasks.md from User Stories
-validation:
-  - Increment follows SpecWeave structure
-  - spec.md has proper sections
-  - tasks.md includes all stories
-  - ADO references preserved

package/src/skills/specweave-ado-mapper/test-cases/test-3-bidirectional-sync.yaml

@@ -1,13 +0,0 @@
-name: "Bidirectional Sync with Conflict Resolution"
-description: "Test syncing changes between SpecWeave and ADO"
-user_input: "Sync increment 0002-payment with ADO, handle conflicts"
-expected_behavior:
-  - Detects changes in both systems
-  - Shows conflicts for manual resolution
-  - Syncs approved changes bidirectionally
-  - Maintains traceability
-validation:
-  - Conflict detection works
-  - User can choose resolution strategy
-  - Sync maintains data integrity
-  - Audit log of sync operations

package/src/skills/specweave-detector/test-cases/test-1-basic-detection.yaml

@@ -1,37 +0,0 @@
----
-name: "Basic SpecWeave Project Detection"
-description: "Tests if specweave-detector can identify a SpecWeave project by presence of .specweave/ directory"
-input:
-  prompt: "User opens Claude Code in a SpecWeave project directory"
-  files:
-    - ".specweave/config.yaml"
-  context:
-    cwd: "/path/to/specweave-project"
-    files_present:
-      - ".specweave/"
-      - ".specweave/config.yaml"
-      - "features/"
-      - "specifications/"
-expected_output:
-  type: "skill_activation"
-  activates: true
-  reason: "Detected .specweave/config.yaml"
-  actions:
-    - "Load project configuration"
-    - "Enable SpecWeave-specific commands"
-    - "Activate SpecWeave workflow"
-  contains:
-    - "SpecWeave project detected"
-    - "Loading configuration"
-validation:
-  - "Skill activates proactively (without user request)"
-  - "Detects .specweave/ directory"
-  - "Reads config.yaml successfully"
-  - "Enables SpecWeave commands"
-  - "Does not activate in non-SpecWeave projects"
-success_criteria:
-  - "Proactive activation works (proactive: true in SKILL.md)"
-  - "Configuration loaded correctly"
-  - "SpecWeave workflows enabled"
-  - "No false positives (activates only in SpecWeave projects)"
----

package/src/skills/specweave-detector/test-cases/test-2-missing-config.yaml

@@ -1,37 +0,0 @@
----
-name: "Detection with Missing Configuration"
-description: "Tests edge case where .specweave/ exists but config.yaml is missing or invalid"
-input:
-  prompt: "User opens Claude Code in directory with incomplete SpecWeave setup"
-  files:
-    - ".specweave/"  # directory exists but empty
-  context:
-    cwd: "/path/to/incomplete-project"
-    files_present:
-      - ".specweave/"
-    files_missing:
-      - ".specweave/config.yaml"
-expected_output:
-  type: "error_handling"
-  activates: true
-  reason: "Detected .specweave/ but missing config"
-  actions:
-    - "Warn user about missing config.yaml"
-    - "Offer to initialize SpecWeave project"
-    - "Provide sample config.yaml"
-  contains:
-    - "SpecWeave directory detected"
-    - "Missing config.yaml"
-    - "Initialize project?"
-validation:
-  - "Detects incomplete setup"
-  - "Provides helpful error message"
-  - "Offers initialization option"
-  - "Does not crash or fail silently"
-  - "Suggests next steps"
-success_criteria:
-  - "Graceful error handling"
-  - "User-friendly error message"
-  - "Actionable recommendations"
-  - "No silent failures"
----

package/src/skills/specweave-detector/test-cases/test-3-non-specweave-project.yaml

@@ -1,34 +0,0 @@
----
-name: "No Activation in Non-SpecWeave Projects"
-description: "Tests that specweave-detector does NOT activate in regular projects without .specweave/"
-input:
-  prompt: "User opens Claude Code in a regular Node.js project"
-  files:
-    - "package.json"
-    - "src/"
-    - "README.md"
-  context:
-    cwd: "/path/to/regular-project"
-    files_present:
-      - "package.json"
-      - "src/"
-    files_missing:
-      - ".specweave/"
-      - ".specweave/config.yaml"
-expected_output:
-  type: "no_activation"
-  activates: false
-  reason: "No .specweave/ directory found"
-  actions: []
-  contains: []
-validation:
-  - "Does NOT activate in non-SpecWeave projects"
-  - "No false positives"
-  - "No unnecessary warnings"
-  - "Does not interfere with normal Claude Code operation"
-success_criteria:
-  - "Zero false positives"
-  - "Only activates when .specweave/ present"
-  - "Silent when not applicable"
-  - "No performance impact on non-SpecWeave projects"
----

package/src/skills/specweave-jira-mapper/test-cases/test-1-export-to-jira.yaml

@@ -1,13 +0,0 @@
-name: "Export SpecWeave Increment to JIRA"
-description: "Test exporting a SpecWeave increment to JIRA Epic/Stories/Subtasks"
-user_input: "Export increment 0003-dashboard to JIRA"
-expected_behavior:
-  - Creates JIRA Epic from increment spec
-  - Creates Stories from main sections
-  - Creates Subtasks from tasks
-  - Maps test cases to JIRA Test issues
-validation:
-  - Epic summary matches increment name
-  - Stories have proper descriptions
-  - Subtasks linked to Stories
-  - JIRA keys stored in SpecWeave

package/src/skills/specweave-jira-mapper/test-cases/test-2-import-from-jira.yaml

@@ -1,13 +0,0 @@
-name: "Import JIRA Epic to SpecWeave"
-description: "Test importing JIRA Epic as a SpecWeave increment"
-user_input: "Import JIRA Epic PROJ-123 into SpecWeave"
-expected_behavior:
-  - Creates increment folder from Epic key
-  - Generates spec.md from Epic description
-  - Converts Stories to spec sections
-  - Creates tasks.md from Subtasks
-validation:
-  - Increment follows naming convention
-  - spec.md includes Epic details
-  - tasks.md has all subtasks
-  - JIRA links preserved

package/src/skills/specweave-jira-mapper/test-cases/test-3-sync-status.yaml

@@ -1,13 +0,0 @@
-name: "Sync Status Updates Between Systems"
-description: "Test syncing task status between SpecWeave and JIRA"
-user_input: "Sync status updates for increment 0004-notifications"
-expected_behavior:
-  - Detects status changes in SpecWeave (tasks.md)
-  - Updates JIRA issue status accordingly
-  - Syncs JIRA status back to SpecWeave
-  - Handles workflow state mapping
-validation:
-  - Status mapping works correctly
-  - Bidirectional sync maintains consistency
-  - Workflow transitions respected
-  - Sync logs available

package/src/skills/stripe-integrator/test-cases/test-1-placeholder.yaml

@@ -1,12 +0,0 @@
----
-name: "Placeholder Test"
-description: "TODO: Add actual test case for this skill"
-input:
-  prompt: "Test prompt"
-expected_output:
-  type: "validation"
-validation:
-  - "Placeholder validation"
-success_criteria:
-  - "Test passes"
----

package/src/skills/stripe-integrator/test-cases/test-2-placeholder.yaml

@@ -1,12 +0,0 @@
----
-name: "Placeholder Test"
-description: "TODO: Add actual test case for this skill"
-input:
-  prompt: "Test prompt"
-expected_output:
-  type: "validation"
-validation:
-  - "Placeholder validation"
-success_criteria:
-  - "Test passes"
----

package/src/skills/stripe-integrator/test-cases/test-3-placeholder.yaml

@@ -1,12 +0,0 @@
----
-name: "Placeholder Test"
-description: "TODO: Add actual test case for this skill"
-input:
-  prompt: "Test prompt"
-expected_output:
-  type: "validation"
-validation:
-  - "Placeholder validation"
-success_criteria:
-  - "Test passes"
----

package/src/skills/task-builder/test-cases/test-1-placeholder.yaml

@@ -1,12 +0,0 @@
----
-name: "Placeholder Test"
-description: "TODO: Add actual test case for this skill"
-input:
-  prompt: "Test prompt"
-expected_output:
-  type: "validation"
-validation:
-  - "Placeholder validation"
-success_criteria:
-  - "Test passes"
----

package/src/skills/task-builder/test-cases/test-2-placeholder.yaml

@@ -1,12 +0,0 @@
----
-name: "Placeholder Test"
-description: "TODO: Add actual test case for this skill"
-input:
-  prompt: "Test prompt"
-expected_output:
-  type: "validation"
-validation:
-  - "Placeholder validation"
-success_criteria:
-  - "Test passes"
----