@cubis/foundry 0.3.83 → 0.3.84

package/workflows/skills/sadd/examples/02-advanced-usage.md

@@ -1,114 +0,0 @@
-# Example: Mining Specifications from Legacy Code and Verifying a Rewrite
-
-## Context
-
-A team is rewriting a payment processing module from Python 2 to Python 3. The original code has no formal specification, only inline comments and existing tests. The team needs to extract behavioral specifications from the legacy code before rewriting.
-
-## User Prompt
-
-> We're rewriting our payment processing module. The legacy code has no spec -- just 47 tests and scattered comments. I need to: (1) mine the implicit specification from the existing code and tests, (2) create a traceability matrix for the rewrite, and (3) verify the new implementation covers everything the old one did. Walk me through the full SADD workflow.
-
-## Skill Response
-
-### Phase 1: Specification Mining (Spec-Miner Agent)
-
-#### Step 1: Extract Behavioral Specs from Existing Tests
-
-Analyze each test to derive the requirement it implicitly validates:
-
-```markdown
-| Legacy Test | Mined Requirement | REQ ID |
-|-------------|-------------------|--------|
-| test_charge_success | System processes a valid charge and returns a transaction ID | REQ-001 |
-| test_charge_declined | System returns decline reason when card is rejected | REQ-002 |
-| test_charge_insufficient_funds | System distinguishes insufficient funds from other declines | REQ-003 |
-| test_refund_full | System processes full refund for a completed charge | REQ-004 |
-| test_refund_partial | System processes partial refund up to original charge amount | REQ-005 |
-| test_refund_exceeds_charge | System rejects refund exceeding original charge amount | REQ-006 |
-| test_idempotency_key | System returns same result for duplicate requests with same idempotency key | REQ-007 |
-| test_currency_conversion | System converts currencies using rates from rate provider | REQ-008 |
-| test_webhook_delivery | System delivers payment event webhooks to registered endpoints | REQ-009 |
-| test_retry_on_timeout | System retries gateway calls up to 3 times on timeout | REQ-010 |
-```
-
-#### Step 2: Mine Implicit Specs from Code Contracts
-
-```python
-# Legacy code patterns that imply specifications:
-
-def charge(amount, currency, token, idempotency_key=None):
-    """Process a payment charge."""
-    if amount <= 0:                    # REQ-011: Amount must be positive
-        raise ValueError("Amount must be positive")
-    if currency not in SUPPORTED:      # REQ-012: Currency must be in supported list
-        raise ValueError(f"Unsupported currency: {currency}")
-    if len(token) != 32:               # REQ-013: Token must be exactly 32 characters
-        raise ValueError("Invalid token format")
-```
-
-#### Step 3: Mine from Inline Comments
-
-```python
-# Legacy comments that imply specifications:
-# NOTE: Always log PCI-sensitive data as masked  -> REQ-014: PCI data masking in logs
-# HACK: Rate limit to 100 req/s per merchant    -> REQ-015: Rate limiting at 100 req/s
-# TODO: Add support for 3D Secure               -> NOT a requirement (future work)
-```
-
-### Phase 2: Traceability Matrix for Rewrite
-
-| REQ ID | Requirement | Legacy Test | Legacy Code Location | New Test ID | New Code Location | Status |
-|--------|------------|-------------|---------------------|-------------|-------------------|--------|
-| REQ-001 | Process valid charge, return tx ID | test_charge_success | charge.py:45 | TEST-001 | — | Pending |
-| REQ-002 | Return decline reason on rejection | test_charge_declined | charge.py:72 | TEST-002 | — | Pending |
-| REQ-003 | Distinguish insufficient funds | test_charge_insufficient_funds | charge.py:89 | TEST-003 | — | Pending |
-| REQ-004 | Full refund for completed charge | test_refund_full | refund.py:23 | TEST-004 | — | Pending |
-| REQ-005 | Partial refund up to original | test_refund_partial | refund.py:41 | TEST-005 | — | Pending |
-| REQ-006 | Reject over-refund | test_refund_exceeds_charge | refund.py:58 | TEST-006 | — | Pending |
-| REQ-007 | Idempotency key dedup | test_idempotency_key | charge.py:110 | TEST-007 | — | Pending |
-| REQ-008 | Currency conversion | test_currency_conversion | fx.py:15 | TEST-008 | — | Pending |
-| REQ-009 | Webhook delivery | test_webhook_delivery | events.py:30 | TEST-009 | — | Pending |
-| REQ-010 | Retry on timeout (3x) | test_retry_on_timeout | charge.py:130 | TEST-010 | — | Pending |
-| REQ-011 | Amount must be positive | (code contract) | charge.py:46 | TEST-011 | — | Pending |
-| REQ-012 | Currency must be supported | (code contract) | charge.py:48 | TEST-012 | — | Pending |
-| REQ-013 | Token must be 32 chars | (code contract) | charge.py:50 | TEST-013 | — | Pending |
-| REQ-014 | PCI data masking in logs | (comment) | logging.py:12 | TEST-014 | — | Pending |
-| REQ-015 | Rate limit 100 req/s/merchant | (comment) | middleware.py:8 | TEST-015 | — | Pending |
-
-### Phase 3: Verification (Verifier Agent)
-
-After the rewrite is complete, run verification:
-
-```markdown
-## Verification Report
-
-### Coverage Summary
-| Metric | Count |
-|--------|-------|
-| Total requirements | 15 |
-| Requirements with passing tests | 13 |
-| Requirements with failing tests | 1 |
-| Requirements with no test | 1 |
-
-### Failures
-| REQ ID | Issue |
-|--------|-------|
-| REQ-010 | New implementation retries 2 times, not 3. Legacy code used `for i in range(3)` (3 retries after initial attempt = 4 total). New code uses `max_retries=2`. |
-
-### Gaps
-| REQ ID | Issue |
-|--------|-------|
-| REQ-015 | Rate limiting test (TEST-015) exists but is skipped in CI. No integration test validates the 100 req/s threshold under load. |
-
-### Recommendation
-1. Fix REQ-010: Change `max_retries=2` to `max_retries=3` in the new gateway client.
-2. Fix REQ-015: Add a load test that verifies rate limiting engages at 100 req/s.
-3. After fixes, all 15 requirements will have passing tests and verified implementations.
-```
-
-### Key Decisions
-
-1. **Three mining sources** -- Tests, code contracts, and comments each reveal different types of implicit specifications. Using all three provides the most complete picture.
-2. **Legacy-to-new mapping** -- The traceability matrix includes both legacy and new locations, enabling side-by-side verification during the rewrite.
-3. **Verifier catches subtle discrepancy** -- The retry count difference (3 vs 2) is exactly the kind of behavioral regression that code review misses but spec-aware verification catches.
-4. **Excluded TODO comments** -- "TODO: Add 3D Secure" is future work, not an existing behavioral spec. Including it would inflate the requirement set with unimplemented features.

package/workflows/skills/sadd/examples/02-implementation-verification.md

@@ -1,126 +0,0 @@
-# Example: Verify Implementation Against Specifications
-
-## Scenario
-
-A team implemented a user authentication module based on specifications extracted earlier. They need to verify the implementation satisfies all specs and identify any gaps before release.
-
-## User Prompt
-
-> Verify this authentication implementation against our specifications:
->
-> **Specifications:**
-> - SPEC-101: GIVEN valid credentials WHEN the user logs in THEN a JWT access token (15min expiry) and refresh token (7day expiry) are returned.
-> - SPEC-102: GIVEN an expired access token WHEN the user makes an API request THEN a 401 is returned with code TOKEN_EXPIRED.
-> - SPEC-103: GIVEN a valid refresh token WHEN the user requests token refresh THEN a new access token is returned and the old refresh token is revoked.
-> - SPEC-104: GIVEN 5 failed login attempts WHEN the user attempts a 6th login THEN the account is locked for 15 minutes.
-> - SPEC-105: GIVEN a locked account WHEN the lock period expires THEN the user can log in normally.
->
-> **Implementation:**
-> ```python
-> class AuthService:
->     def login(self, email, password):
->         user = self.user_repo.find_by_email(email)
->         if not user or not verify_password(password, user.password_hash):
->             raise InvalidCredentialsError()
->         access_token = create_jwt(user.id, expires_in=900)
->         refresh_token = create_refresh_token(user.id, expires_in=604800)
->         return {"access_token": access_token, "refresh_token": refresh_token}
->
->     def refresh(self, refresh_token):
->         payload = verify_refresh_token(refresh_token)
->         if not payload:
->             raise InvalidTokenError()
->         new_access = create_jwt(payload["user_id"], expires_in=900)
->         return {"access_token": new_access}
->
->     def verify_access(self, token):
->         payload = decode_jwt(token)
->         if not payload:
->             raise AuthenticationError("TOKEN_EXPIRED")
->         return payload
-> ```
-
-## Expected Response
-
-### Verification Report
-
-| Spec ID  | Status           | Evidence                                              |
-|----------|------------------|-------------------------------------------------------|
-| SPEC-101 | SATISFIED        | `login()` creates JWT with 900s (15min) and refresh with 604800s (7day). Token pair returned correctly. |
-| SPEC-102 | PARTIALLY MET    | `verify_access()` raises `AuthenticationError("TOKEN_EXPIRED")` but does not distinguish between expired and invalid tokens. |
-| SPEC-103 | NOT SATISFIED    | `refresh()` creates a new access token but does NOT revoke the old refresh token. Token reuse attack vector. |
-| SPEC-104 | NOT SATISFIED    | No failed login attempt tracking. No account locking mechanism. Entire spec is unimplemented. |
-| SPEC-105 | NOT SATISFIED    | Depends on SPEC-104 which is unimplemented. No lock expiry logic exists. |
-
-### Summary
-
-- **Satisfied**: 1/5 (20%)
-- **Partially met**: 1/5 (20%)
-- **Not satisfied**: 3/5 (60%)
-
-### Gap Details
-
-**SPEC-103: Missing refresh token revocation**
-
-The `refresh()` method issues a new access token but leaves the old refresh token valid. This means:
-- A stolen refresh token can be used indefinitely.
-- There is no way to detect token reuse (a common indicator of compromise).
-
-**Recommended fix**:
-```python
-def refresh(self, refresh_token):
-    payload = verify_refresh_token(refresh_token)
-    if not payload:
-        raise InvalidTokenError()
-    # Revoke old refresh token
-    self.token_repo.revoke(refresh_token)
-    # Issue new token pair
-    new_access = create_jwt(payload["user_id"], expires_in=900)
-    new_refresh = create_refresh_token(payload["user_id"], expires_in=604800)
-    return {"access_token": new_access, "refresh_token": new_refresh}
-```
-
-**SPEC-104 and SPEC-105: Missing account locking**
-
-The login method has no tracking of failed attempts. Implementation needed:
-1. Add a `failed_attempts` counter and `locked_until` timestamp to the user model.
-2. Increment `failed_attempts` on each failed login.
-3. When `failed_attempts >= 5`, set `locked_until = now + 15 minutes`.
-4. Check `locked_until` before validating credentials.
-5. Reset `failed_attempts` on successful login.
-
-### Verification Tests to Add
-
-```python
-def test_spec_103_refresh_revokes_old_token():
-    # Arrange: login and get tokens
-    tokens = auth.login("user@test.com", "password")
-    # Act: refresh to get new tokens
-    new_tokens = auth.refresh(tokens["refresh_token"])
-    # Assert: old refresh token is no longer valid
-    with pytest.raises(InvalidTokenError):
-        auth.refresh(tokens["refresh_token"])
-
-def test_spec_104_account_locks_after_5_failures():
-    # Arrange: valid user exists
-    # Act: attempt login 6 times with wrong password
-    for i in range(5):
-        with pytest.raises(InvalidCredentialsError):
-            auth.login("user@test.com", "wrong")
-    # Assert: 6th attempt raises AccountLockedError
-    with pytest.raises(AccountLockedError):
-        auth.login("user@test.com", "correct_password")
-
-def test_spec_105_lock_expires_after_15_minutes():
-    # Arrange: lock the account by failing 5 times
-    # Act: advance time by 16 minutes
-    # Assert: login succeeds with correct password
-```
-
-## Why This Response Works
-
-- Provides a spec-by-spec verification with clear status and evidence.
-- Distinguishes between "not satisfied" and "partially met" which is important for prioritization.
-- Identifies a security-relevant gap (refresh token reuse) that could be exploited.
-- Provides concrete code fixes, not just descriptions of what is wrong.
-- Includes test cases that would catch these gaps in the future.

package/workflows/skills/sadd/references/coverage-mapping.md

@@ -1,161 +0,0 @@
-# Coverage Mapping Reference
-
-Load this when building and maintaining traceability matrices and spec coverage reports.
-
----
-
-## Traceability Matrix Fundamentals
-
-A traceability matrix maps every requirement to its specifications, tests, and implementing code. It answers:
-
-- **Forward traceability:** Does every requirement have tests?
-- **Backward traceability:** Does every test trace to a requirement?
-- **Implementation traceability:** Does every requirement have code?
-
----
-
-## Matrix Formats
-
-### Minimal (for small projects)
-
-```markdown
-| Req ID | Test ID | Status |
-|--------|---------|--------|
-| REQ-001 | TEST-001 | Pass |
-| REQ-002 | TEST-002 | Fail |
-| REQ-003 | -- | No test |
-```
-
-### Full (for compliance or audit)
-
-```markdown
-| Req ID | Requirement | Spec ID | Test ID | Test Status | Code Location | Reviewer | Date |
-|--------|------------|---------|---------|-------------|---------------|----------|------|
-| REQ-001 | Users register with email | SPEC-001 | TEST-001 | Pass | auth.ts:45 | @dev | 2026-03 |
-```
-
----
-
-## Building the Matrix
-
-### Step 1: Enumerate Requirements
-
-Source requirements from:
-- Product requirements documents (PRD)
-- User stories and acceptance criteria
-- API specifications (OpenAPI, protobuf)
-- Regulatory or compliance requirements
-- Mined specifications from existing code
-
-Assign each a unique, stable identifier (REQ-001, REQ-002, ...).
-
-### Step 2: Map Specs to Requirements
-
-Each requirement may produce 1-N specifications:
-
-```
-REQ-001: "Users can reset their password"
-  -> SPEC-001: Password reset email is sent on request
-  -> SPEC-002: Reset link expires after 1 hour
-  -> SPEC-003: New password must meet strength requirements
-  -> SPEC-004: All sessions invalidated after reset
-```
-
-### Step 3: Map Tests to Specs
-
-Each spec should have at least one test. Complex specs need multiple tests (positive, negative, boundary):
-
-```
-SPEC-002: Reset link expires after 1 hour
-  -> TEST-005: Link works at 59 minutes (positive boundary)
-  -> TEST-006: Link rejected at 61 minutes (negative boundary)
-  -> TEST-007: Link rejected at 24 hours (far future)
-```
-
-### Step 4: Map Code to Specs
-
-Record the file and function/method that implements each specification:
-
-```
-SPEC-001 -> src/auth/password-reset.ts:sendResetEmail()
-SPEC-002 -> src/auth/password-reset.ts:validateResetToken()
-```
-
----
-
-## Coverage Metrics
-
-### Spec Coverage (most important)
-
-```
-Spec Coverage = Specs with at least one passing test / Total specs
-
-Example: 42 specs tested / 50 total specs = 84% spec coverage
-```
-
-This is more meaningful than code coverage because it measures requirements satisfied, not lines executed.
-
-### Requirement Coverage
-
-```
-Requirement Coverage = Requirements with all specs tested / Total requirements
-
-Example: 18 requirements fully covered / 20 total = 90% requirement coverage
-```
-
-### Gap Analysis
-
-| Gap Type | Count | Action |
-|----------|-------|--------|
-| Requirements with no specs | 3 | Mine specifications from each |
-| Specs with no tests | 5 | Generate test cases |
-| Tests with no spec | 8 | Link to spec or mark as implementation test |
-| Specs with failing tests | 2 | Fix implementation or update spec |
-
----
-
-## Keeping the Matrix Current
-
-### Triggers for Matrix Update
-
-| Event | Matrix Action |
-|-------|--------------|
-| New feature planned | Add requirements |
-| Sprint planning | Add specs for upcoming requirements |
-| Test written | Link test to spec |
-| Code merged | Update code locations |
-| Bug found | Check if a spec exists; if not, add one |
-| Requirement changed | Update spec, flag tests for re-verification |
-| Code refactored | Verify code locations still accurate |
-
-### Automation
-
-**Tag-based traceability:** Add spec IDs to test descriptions.
-
-```javascript
-// @spec SPEC-042
-it('should expire reset link after 1 hour', () => { ... });
-```
-
-Then run a script that:
-1. Scans all tests for `@spec` tags.
-2. Scans the spec registry for all spec IDs.
-3. Produces a coverage report showing matched, unmatched, and missing entries.
-
----
-
-## Reporting
-
-### Dashboard Format
-
-```
-SADD Coverage Dashboard
-========================
-Requirements: 50 total | 45 with specs (90%) | 5 need spec mining
-Specifications: 120 total | 108 with tests (90%) | 12 need tests
-Tests: 150 total | 140 linked to specs (93%) | 10 unlinked
-Implementation: 108 specs with code | 12 pending
-
-Overall Spec Coverage: 90%
-Trend: +3% from last sprint
-```

package/workflows/skills/sadd/references/spec-mining.md

@@ -1,96 +0,0 @@
-# Specification Mining Reference
-
-Load this when extracting specifications from legacy code or informal documentation.
-
----
-
-## Mining Source Hierarchy
-
-Not all sources are equally reliable. Prioritize by evidence strength:
-
-| Priority | Source | Reliability | Why |
-|----------|--------|-------------|-----|
-| 1 | Passing tests | High | Tests encode executable specifications; if they pass, the behavior exists. |
-| 2 | Code contracts (guards, validators, type checks) | High | Explicit enforcement means the behavior is intentional. |
-| 3 | API schemas (OpenAPI, protobuf, GraphQL) | High | Machine-readable contracts are typically maintained. |
-| 4 | Inline comments (NOTE, HACK) | Medium | Comments may be stale but often encode undocumented decisions. |
-| 5 | Commit messages | Low | Describe intent at a point in time; may not reflect current behavior. |
-| 6 | External documentation | Variable | Wikis and READMEs decay fastest; cross-reference with code. |
-
----
-
-## Mining from Tests
-
-### Reading a Test as a Specification
-
-Every test encodes a requirement in this form:
-
-```
-GIVEN [test setup / Arrange]
-WHEN  [action / Act]
-THEN  [expected outcome / Assert]
-```
-
-Extract the requirement by converting this to: "The system MUST [THEN] WHEN [WHEN] GIVEN [GIVEN]."
-
-### Example
-
-```python
-def test_discount_applied_for_premium_users():
-    user = create_user(tier="premium")       # GIVEN a premium user
-    order = create_order(user, amount=100)   # WHEN they place a $100 order
-    assert order.total == 90                 # THEN total is $90 (10% discount)
-```
-
-Mined requirement: "The system MUST apply a 10% discount to orders WHEN the user tier is premium."
-
-### Watch for Test Gaps
-
-Tests only cover behaviors someone thought to test. Common untested areas:
-
-- Error handling and edge cases.
-- Concurrent access and race conditions.
-- Resource cleanup and teardown.
-- Configuration and environment-dependent behavior.
-
----
-
-## Mining from Code Contracts
-
-### Input Validation as Specification
-
-```python
-def transfer(from_account, to_account, amount):
-    if amount <= 0:
-        raise ValueError("Amount must be positive")
-    if from_account == to_account:
-        raise ValueError("Cannot transfer to same account")
-    if amount > from_account.balance:
-        raise InsufficientFundsError()
-```
-
-Mined requirements:
-- REQ-XXX: Transfer amount must be positive.
-- REQ-XXX: Source and destination accounts must be different.
-- REQ-XXX: Transfer amount must not exceed source account balance.
-
-### Type Signatures as Specification
-
-```typescript
-function calculateTax(
-  amount: number,       // Must be numeric
-  state: USState,       // Must be a valid US state
-  exemptions: string[]  // Can be empty but must be an array
-): TaxResult            // Always returns a TaxResult, never null
-```
-
----
-
-## Confidence Levels
-
-| Level | Criteria | Action |
-|-------|----------|--------|
-| High | Behavior verified by passing test AND code contract | Include in specification as-is |
-| Medium | Behavior implied by code contract OR comment but no test | Include with "needs test" flag |
-| Low | Behavior mentioned in comment only, no code enforcement | Include with "needs verification" flag |
-| Contradicted | Test says X, code does Y, comment says Z | Flag for human resolution, do not include |

package/workflows/skills/sadd/references/test-from-spec.md

@@ -1,122 +0,0 @@
-# Test-from-Spec Reference
-
-Load this when generating tests directly from requirement text.
-
----
-
-## The Principle
-
-Tests should be derived from specifications, not from implementation. Spec-first testing ensures:
-
-- Tests validate **intended behavior**, not accidental behavior.
-- Tests survive refactoring because they are anchored to requirements, not code structure.
-- Coverage is measured against requirements, not lines of code.
-
----
-
-## The Derivation Process
-
-### Step 1: Decompose the Requirement
-
-Break a requirement into its constituent conditions and outcomes:
-
-**Requirement:** "The system must send a notification email when an order ships, containing the tracking number and estimated delivery date."
-
-| Component | Value |
-|-----------|-------|
-| Trigger | Order ships |
-| Action | Send notification email |
-| Content requirement 1 | Contains tracking number |
-| Content requirement 2 | Contains estimated delivery date |
-| Implicit | Email is sent to the customer who placed the order |
-| Implicit | Email is not sent if order is cancelled before shipping |
-
-### Step 2: Generate Positive Tests
-
-One test per component combination that should succeed:
-
-```
-TEST-001: When order ships, notification email is sent to the order's customer.
-TEST-002: Notification email contains the tracking number.
-TEST-003: Notification email contains the estimated delivery date.
-```
-
-### Step 3: Generate Negative Tests
-
-One test per boundary or failure condition:
-
-```
-TEST-004: No email is sent if order is cancelled before shipping.
-TEST-005: No email is sent if customer has unsubscribed from notifications.
-TEST-006: If tracking number is unavailable, email is sent with "tracking pending" message.
-```
-
-### Step 4: Generate Boundary Tests
-
-For numeric, time, or size constraints:
-
-```
-Requirement: "Password must be at least 8 characters."
-
-TEST-007: Password with exactly 8 characters is accepted.    (boundary - valid)
-TEST-008: Password with 7 characters is rejected.            (boundary - invalid)
-TEST-009: Password with 100 characters is accepted.          (large input)
-TEST-010: Empty password is rejected.                        (zero input)
-```
-
----
-
-## Test Naming Convention
-
-Name tests to read as specification statements:
-
-```
-should_[expected behavior]_when_[condition]
-
-should_send_notification_when_order_ships
-should_reject_password_when_fewer_than_8_characters
-should_return_404_when_resource_not_found
-```
-
-This convention makes test suites readable as living specification documents.
-
----
-
-## Mapping Requirement Types to Test Types
-
-| Requirement Type | Test Type | Example |
-|-----------------|-----------|---------|
-| Functional (happy path) | Unit test | Input -> expected output |
-| Functional (error handling) | Unit test with error assertion | Invalid input -> specific error |
-| Performance | Benchmark / load test | Response time < 200ms at P95 |
-| Security | Security test | SQL injection input -> safe handling |
-| Compatibility | Cross-environment test | Works on Node 18 and Node 20 |
-| Accessibility | Automated a11y check | WCAG 2.1 AA compliance |
-
----
-
-## Common Pitfalls
-
-### Testing Implementation Instead of Specification
-
-**Wrong:** Test that `calculateDiscount` calls `lookupTier` method.
-**Right:** Test that a premium user gets 10% discount on orders.
-
-The first test breaks when you refactor the internal method. The second test survives because it tests the specified behavior.
-
-### Compound Test Cases
-
-**Wrong:** One test that checks sending, content, and recipient simultaneously.
-**Right:** Separate tests for each: sending occurs, content is correct, recipient is correct.
-
-Compound tests report a single failure that could be any of several issues.
-
-### Missing the Implicit Requirements
-
-Specifications often leave behaviors implicit:
-
-- What happens on timeout?
-- What happens with empty input?
-- What happens when a dependency is unavailable?
-
-Explicitly mine these gaps and create tests for the decisions you make.