ai-core-framework 0.1.0

package/core/skills/qa-verify-fix/SKILL.md

@@ -0,0 +1,446 @@
+---
+name: qa-verify-fix
+description: Use when the user asks to run /verify-fix, verify a bug fix in QA, rerun a known reproducer, decide whether to verify or reopen a bug, or regression test a fix.
+command: /verify-fix
+display_name: "Verify Bug Fix"
+version: 1.0.0
+owner_agent: qa-tester
+model_preference: sonnet
+args:
+  - name: bug_id
+    required: true
+    format: "BUG-XXX or TICKET-XXX"
+    description: "Bug ticket to verify fix for"
+  - name: environment
+    required: false
+    type: string
+    default: "staging"
+    enum: [dev, staging, pre-prod]
+preconditions:
+  - bug_exists: true
+  - bug_status: FIXED | READY_FOR_QA
+  - fix_deployed: true
+  - has_original_reproducer: true
+postconditions:
+  - verification_complete: true
+  - bug_status: VERIFIED | REOPENED
+  - regression_tested: true
+---
+
+# /verify-fix
+
+> Verify bug fix actually works. Prevent "fixed but not really" situations.
+
+## 🎯 Purpose
+
+After developer claims the bug is fixed and PR is merged + deployed:
+1. Reproduce original bug → verify no longer reproduces
+2. Run regression tests (what else could the fix have broken?)
+3. Test edge cases around the fix (attacker thinking)
+4. Verify developer added regression test (RULE TEST-008)
+5. Sign off or reopen
+
+## 🚦 Trigger
+
+**Manual**:
+```
+/verify-fix BUG-002
+/verify-fix BUG-002 --env=pre-prod
+```
+
+**Auto**: After `/merge-pr` for bugfix branches + deploy complete.
+
+## 📋 Preconditions
+
+### 1. Bug exists + in correct state
+```bash
+bug_status=$(cat project/bugs/${BUG_ID}.json | jq -r .status)
+[ "$bug_status" = "FIXED" ] || [ "$bug_status" = "READY_FOR_QA" ] || ABORT
+```
+
+### 2. Fix deployed
+Verify build with fix is on target environment.
+
+### 3. Has original reproducer
+Bug report must have `steps_to_reproduce`. If missing → reject bug report back to reporter.
+
+### 4. Fix PR merged
+Check linked PR is merged (not still open).
+
+## 🔄 Execution Flow
+
+```
+┌──────────────────────────────────────────────────────────┐
+│ STEP 1: Load bug context                                 │
+│   - Bug report (steps to reproduce)                      │
+│   - Linked PR + commits (what changed)                   │
+│   - Original severity + impact                           │
+│   - Reporter notes                                       │
+├──────────────────────────────────────────────────────────┤
+│ STEP 2: Verify environment                               │
+│   - Correct build deployed                               │
+│   - Services healthy                                     │
+│   - Test data available                                  │
+├──────────────────────────────────────────────────────────┤
+│ STEP 3: Reproduce original bug                           │
+│   - Follow exact steps from bug report                   │
+│   - Document what happens now                            │
+│                                                          │
+│   Outcomes:                                              │
+│   a. Original bug no longer happens → PROGRESS           │
+│   b. Bug still happens → FAIL, reopen                    │
+│   c. New different behavior → investigate                │
+├──────────────────────────────────────────────────────────┤
+│ STEP 4: Regression test - related flows                  │
+│   Identify areas potentially affected by fix:            │
+│   - Same module/function                                 │
+│   - Callers of changed function                          │
+│   - Shared data/state                                    │
+│                                                          │
+│   Test 3-5 related flows.                                │
+├──────────────────────────────────────────────────────────┤
+│ STEP 5: Edge case exploration                            │
+│   Attacker thinking:                                     │
+│   - Variation 1: What if input X slightly different?    │
+│   - Variation 2: What about concurrent?                  │
+│   - Variation 3: What about different user role?        │
+│   - Variation 4: What if malicious input?                │
+│                                                          │
+│   Find any new bugs near the fix.                        │
+├──────────────────────────────────────────────────────────┤
+│ STEP 6: Verify regression test added                     │
+│   Per RULE TEST-008:                                     │
+│   - Check PR diff for new test file/case                 │
+│   - Verify test actually covers the bug scenario         │
+│   - Run test locally (should pass)                       │
+│   - If regression test missing → FAIL verify             │
+├──────────────────────────────────────────────────────────┤
+│ STEP 7: Verify AC coverage (if bug had AC updates)       │
+│   - Any AC changes since bug filed?                      │
+│   - All still met?                                       │
+├──────────────────────────────────────────────────────────┤
+│ STEP 8: Decision                                         │
+│                                                          │
+│   VERIFIED: Original fixed + regression ok + test added  │
+│     → Bug status: FIXED → VERIFIED                       │
+│     → HANDOFF → scrum-master (ready release)             │
+│                                                          │
+│   REOPENED: Original bug still happens                   │
+│     → Bug status: FIXED → REOPENED                       │
+│     → Comment with new evidence                          │
+│     → HANDOFF → developer                                │
+│                                                          │
+│   NEW_BUG: Found different bug near fix                  │
+│     → Original bug VERIFIED                              │
+│     → File new bug (separate ticket)                     │
+│     → HANDOFF → scrum-master                             │
+│                                                          │
+│   INSUFFICIENT_FIX: Fix works but missing regression     │
+│     → Bug status: stays FIXED                            │
+│     → Comment: dev must add test before VERIFIED         │
+│     → HANDOFF → developer                                │
+├──────────────────────────────────────────────────────────┤
+│ STEP 9: Generate report                                  │
+│   Save to: project/verifications/BUG-XXX-YYYYMMDD.md│
+├──────────────────────────────────────────────────────────┤
+│ STEP 10: Update bug state + notify                       │
+└──────────────────────────────────────────────────────────┘
+```
+
+## 🔒 Hard Rules
+
+### RULE VF-001: Must reproduce exact original steps
+**MUST** try to reproduce with exact steps from bug report. No shortcuts.
+
+### RULE VF-002: Cannot verify without regression test
+If developer didn't add regression test (RULE TEST-008):
+- Fix may work now but could regress
+- **MUST NOT** mark VERIFIED
+- Comment: "Add regression test before verify"
+
+### RULE VF-003: Explore around the fix
+**MUST** do edge case testing near the fix. Don't just rerun original reproducer.
+
+Example: Fix was "login breaks with + in email" → test:
+- Other special chars: -, ., ', spaces
+- Multiple +: "user+tag1+tag2@x.com"
+- + at different positions: "+user@x.com"
+
+### RULE VF-004: Document evidence
+VERIFIED **MUST** include:
+- Screenshot/log showing fix works
+- List of edge cases tested (not just "looked fine")
+- Regression tests executed
+
+### RULE VF-005: Don't verify stale deploys
+If deploy is > 24h old and bug was just fixed → flag, ensure latest.
+
+### RULE VF-006: Severity upgrade if related found
+If exploration finds related bug of higher severity → file new bug + notify tech-lead immediately.
+
+### RULE VF-007: Retest after re-deploy
+If bug was REOPENED, after new fix deploy, **MUST** redo full verification (not just original scenario).
+
+### RULE VF-008: Preserve bug history
+**MUST NOT** delete/edit original reporter's evidence. Only add new verification evidence.
+
+### RULE VF-009: Honest even under pressure
+If scrum-master pushing for release, don't rubber-stamp verify. Per RULE QA-010.
+
+### RULE VF-010: Bug closure authority
+Only QA (this command) transitions bug → VERIFIED. Developer marks FIXED, QA verifies.
+
+## 📤 Output Format (Verified)
+
+```markdown
+## ✅ Verified: BUG-002
+
+**Bug**: Rate limit not enforced on /auth/request-reset
+**Severity**: SEV-2
+**Fixed in**: PR #128 (commit def5678)
+**Verified by**: qa-tester-agent
+**Environment**: staging v1.2.0-rc.4
+**Duration**: 22 min
+
+### Original Reproducer Test
+
+**Steps** (from BUG-002):
+1. Send 20 POST /auth/request-reset requests to staging in 1 minute
+2. Check response codes
+
+**Before fix** (reported):
+- All 20 → 200 OK
+
+**After fix** (now):
+- Requests 1-5 → 200 OK
+- Request 6-20 → 429 Too Many Requests ✅
+- Retry-After header: 3600 ✅
+- Error body: `{"error": "RATE_LIMIT_EXCEEDED"}` ✅
+
+**Original bug**: ✅ FIXED
+
+### Regression Tests
+
+#### Related flow 1: Login endpoint still works
+- Login with valid credentials → 200 ✅
+- Login rate limit also enforced (separate limit) → ✅
+
+#### Related flow 2: Successful resets still work
+- Request reset (first time) → 200 + email sent ✅
+- Use reset link → password updated ✅
+
+#### Related flow 3: Password change (logged in)
+- Not affected by reset rate limit ✅
+
+### Edge Case Exploration
+
+| Variation | Result |
+|-----------|--------|
+| Case variation (User@x.com vs user@x.com) | ✅ Normalized, shared limit |
+| Whitespace in email | ✅ Trimmed before keying |
+| Non-existent email | ✅ Also rate limited |
+| After window expires (61 min) | ✅ Fresh 5-request budget |
+| Simultaneous requests (parallel 10) | ✅ First 5 ok, rest 429 |
+| Different IP, same email | ✅ Email-keyed, still limited |
+| Same IP, different emails | ✅ Each email own budget |
+
+### Developer Regression Test Added
+
+**File**: `tests/auth/rate-limit.test.ts:67-98`
+
+**Verified**:
+- [x] Test covers original bug scenario (5+ requests → 429)
+- [x] Test covers case normalization
+- [x] Test covers whitespace handling
+- [x] Test runs locally (green)
+- [x] Test name descriptive: `should_rate_limit_after_5_requests_regression_BUG_002`
+
+### Decision
+
+✅ **VERIFIED**
+
+Bug status: FIXED → VERIFIED
+
+### Related Bugs Status
+
+- BUG-003 (timing attack on email enumeration): Still open, separate fix
+- BUG-004 (email HTML rendering): Still open, separate fix
+
+### Verification Record
+Saved to: `project/verifications/BUG-002-20260418.md`
+
+---
+HANDOFF → scrum-master
+Action: Ready to include in next release
+```
+
+## 📤 Output Format (Reopened)
+
+```markdown
+## ❌ Reopened: BUG-002
+
+**Bug**: Rate limit not enforced on /auth/request-reset
+**Verified by**: qa-tester-agent
+**Environment**: staging v1.2.0-rc.4
+**Result**: STILL BROKEN
+
+### Original Reproducer - Still Fails
+
+**Steps tried**:
+1. Sent 20 POST /auth/request-reset to staging
+2. Email: `test@example.com`
+
+**Expected**: Requests 6+ return 429
+**Actual**: All 20 returned 200 OK
+
+**Evidence**:
+```
+Time: 2026-04-18 18:30:00 UTC
+Environment: staging.app
+Test script: tests/manual/rate-limit-verify.sh
+Output:
+  [1] 200 (0.15s)
+  [2] 200 (0.14s)
+  ...
+  [20] 200 (0.18s)
+  ❌ Expected 429 after request 5
+```
+
+### Hypothesis
+
+Looking at PR #128 diff:
+- Middleware added to `src/auth/router.ts:45`
+- But registered AFTER `requestResetHandler` → middleware doesn't apply
+
+```typescript
+// Current (BROKEN):
+router.post('/request-reset', requestResetHandler);  // line 45
+router.use(rateLimitMiddleware);                      // line 46 - too late!
+
+// Should be:
+router.use(rateLimitMiddleware);                      // FIRST
+router.post('/request-reset', requestResetHandler);   // AFTER
+```
+
+### Decision
+
+❌ **REOPENED**
+
+Bug status: FIXED → REOPENED
+
+### Additional Notes
+- Developer's unit test passes because it tests middleware in isolation
+- Bug is middleware registration order, missed in integration test
+- Suggest: add integration test that hits actual endpoint
+
+### Action Required
+
+1. **Developer**: Fix middleware registration order
+2. **Developer**: Add integration test hitting real endpoint
+3. **Tech Lead**: Note for review checklist (middleware order)
+
+---
+HANDOFF → developer
+Action: /implement-task BUG-002 (re-fix)
+```
+
+## 📤 Output Format (Missing Regression Test)
+
+```markdown
+## ⚠️ Incomplete: BUG-002
+
+**Bug**: Rate limit not enforced
+**Fix status**: Works but incomplete
+**Verified by**: qa-tester-agent
+
+### Fix Verification: ✅
+
+Original bug no longer reproduces. Rate limit now enforced correctly.
+
+### Regression Test: ❌ MISSING
+
+Per RULE TEST-008, bug fixes MUST include regression test.
+
+**PR #128 diff analysis**:
+- Production code changes: `src/auth/rate-limit.ts`, `src/auth/router.ts`
+- Test changes: 0 new tests, 0 modified tests
+
+**Why this matters**: This bug could silently regress in the future. Without test, next change to rate limit could break it again.
+
+### Required Before VERIFIED
+
+Developer must add:
+```typescript
+// tests/auth/rate-limit.test.ts
+describe('Rate limit - regression tests', () => {
+  it('should rate limit after 5 requests per hour - regression BUG-002', async () => {
+    const email = 'test@example.com';
+    
+    // First 5 should succeed
+    for (let i = 0; i < 5; i++) {
+      const r = await request.post('/auth/request-reset').send({ email });
+      expect(r.status).toBe(200);
+    }
+    
+    // 6th should be rate limited
+    const r = await request.post('/auth/request-reset').send({ email });
+    expect(r.status).toBe(429);
+    expect(r.body.error).toBe('RATE_LIMIT_EXCEEDED');
+  });
+});
+```
+
+### State
+Bug status: stays FIXED (not yet VERIFIED)
+
+### Action Required
+
+1. **Developer**: Add regression test
+2. **Developer**: Push commit, update PR or create follow-up PR
+3. **QA**: Re-verify after test added
+
+---
+HANDOFF → developer
+Action: Add regression test then comment on bug to re-trigger verify
+```
+
+## 🚨 Failure Modes
+
+| Scenario | Action |
+|----------|--------|
+| Cannot reproduce original on broken build | Check right build deployed |
+| Fix works but no regression test | INSUFFICIENT_FIX output |
+| Fix introduces new bug | File new bug, verify original fixed |
+| Environment inconsistent | Time-box 15 min, escalate SM |
+| Reporter's steps invalid | Contact reporter, ask for update |
+| Multiple attempts to fix failed | Escalate tech-lead for pair session |
+
+## 🔗 Related Commands
+
+- **Before**: Bug fix `/merge-pr` + deploy
+- **Related**: `/smoke-test` (for features, this is for bugs)
+- **After**:
+  - VERIFIED: `/release` eventually
+  - REOPENED: `/implement-task` again
+
+## 📊 Metrics Tracked
+
+```json
+{
+  "timestamp": "2026-04-18T18:30:00Z",
+  "bug_id": "BUG-002",
+  "fix_pr": 128,
+  "verifier": "qa-tester-agent",
+  "duration_minutes": 22,
+  "result": "VERIFIED",
+  "regression_tests_run": 3,
+  "edge_cases_tested": 7,
+  "new_bugs_found": 0,
+  "has_regression_test": true,
+  "fix_iterations": 1
+}
+```
+
+---
+**Last updated**: 2026-04-18
+**Maintainer**: QA Lead

package/core/skills/release-hotfix/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: release-hotfix
+description: Use when the user asks to run /hotfix, coordinate an emergency SEV-1 or SEV-2 production fix, create a hotfix branch, verify the fix, or record hotfix release follow-up.
+command: /hotfix
+display_name: "Hotfix"
+version: 1.0.0
+status: READY
+owner_agent: tech-lead
+requires_agents:
+  - tech-lead
+  - developer
+  - qa-tester
+consults_agents:
+  - scrum-master
+model_preference: opus
+args:
+  - name: bug_id_or_description
+    required: true
+    description: "BUG-NNN or emergency bug description"
+preconditions:
+  - severity_high_enough: "SEV-1 | SEV-2"
+  - production_impact_confirmed: true
+  - incident_owner_assigned: true
+postconditions:
+  - hotfix_branch_created: true
+  - fix_verified: true
+  - release_record_created: true
+  - followup_ticket_created: true
+---
+
+# /hotfix
+
+> Emergency production fix flow for SEV-1 and SEV-2 issues. Bypasses sprint planning, but not safety gates.
+
+## 🎯 Purpose
+
+Resolve urgent production incidents quickly while preserving traceability, review, tests, QA verification, and post-incident follow-up.
+
+## 🚦 Trigger
+
+Manual:
+
+- `/hotfix BUG-017`
+- `/hotfix "Checkout payments fail for all users"`
+
+## 📋 Preconditions, STRICT
+
+1. Issue is confirmed SEV-1 or SEV-2, or Tech Lead explicitly escalates.
+2. Production impact is documented.
+3. Incident owner is assigned.
+4. Current production version is known.
+5. Rollback option is understood before changes begin.
+6. Working directory is clean.
+7. Communication channel is identified for status updates.
+
+## 🔄 Execution Flow
+
+1. Triage severity and impact.
+2. Create or link `BUG-NNN` in `project/bugs/`.
+3. Create hotfix ticket if needed with minimal AC and status `READY`.
+4. Create branch `hotfix/BUG-NNN-short-slug` or `hotfix/TICKET-NNN-short-slug` from production branch.
+5. Reproduce the issue and write a regression test if feasible.
+6. Implement minimal safe fix.
+7. Run targeted tests, security check, and smoke verification.
+8. Open PR with emergency template and link bug/ticket.
+9. Require Tech Lead review, and second reviewer if the Tech Lead authored the fix.
+10. Merge to production release branch.
+11. Tag patch version and deploy.
+12. QA verifies production or pre-prod depending on incident protocol.
+13. Back-merge hotfix into `develop`.
+14. Create follow-up ticket for full DoD, monitoring, and root cause analysis.
+15. Write incident summary in `project/releases/` or `project/incidents/`.
+
+## 🔒 Hard Rules
+
+### RULE HF-001: Hotfix is for urgent incidents only
+Do not use `/hotfix` for normal feature work or low-severity bugs.
+
+### RULE HF-002: Minimal change only
+Fix the incident cause with the smallest safe change. Broader refactors become follow-up tickets.
+
+### RULE HF-003: Tests are still required
+At minimum, add a regression test or document why test automation is impossible under incident constraints.
+
+### RULE HF-004: Review is required
+No direct push to production. Emergency still requires review.
+
+### RULE HF-005: Back-merge required
+Every hotfix MUST be merged back into `develop` to prevent regression.
+
+### RULE HF-006: Follow-up required
+Create follow-up work for root cause analysis, full DoD gaps, monitoring, and prevention.
+
+## 📤 Outputs
+
+Success:
+
+- Bug/ticket ID
+- Hotfix branch
+- PR link
+- Patch version
+- Deployment status
+- Verification result
+- Follow-up ticket
+
+Failure:
+
+- Incident severity not eligible
+- Reproduction missing
+- Fix unsafe
+- Verification failed
+
+## 🔗 Related Commands
+
+- Before: `/report-bug`, `/triage-bug`
+- During: `/create-pr`, `/techlead-review`, `/merge-pr`
+- After: `/verify-fix`, `/release`, `/rollback`

package/core/skills/release-release/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: release-release
+description: Use when the user asks to run /release, prepare a versioned release, validate QA and CI gates, create release records or tags, or document deployment start.
+command: /release
+display_name: "Release"
+version: 1.0.0
+status: READY
+owner_agent: scrum-master
+requires_agents:
+  - scrum-master
+consults_agents:
+  - tech-lead
+  - qa-tester
+model_preference: sonnet
+args:
+  - name: version
+    required: true
+    format: "vMAJOR.MINOR.PATCH"
+    description: "Release version to prepare and tag"
+preconditions:
+  - state_valid: true
+  - qa_done_for_release_scope: true
+  - ci_green: true
+  - changelog_ready: true
+postconditions:
+  - release_record_created: true
+  - tag_created: true
+  - deployment_started_or_documented: true
+---
+
+# /release
+
+> Coordinates a production release with state validation, QA evidence, changelog, tag, deployment, and rollback plan.
+
+## 🎯 Purpose
+
+Package verified work into a traceable production release. The command protects production by requiring validated state, green CI, QA sign-off, and rollback instructions.
+
+## 🚦 Trigger
+
+Manual:
+
+- `/release v1.4.0`
+- `/release v1.4.1 --patch`
+
+## 📋 Preconditions, STRICT
+
+1. Version matches semantic version format.
+2. `/validate-state` passes.
+3. All included tickets are `DONE` or explicitly excluded.
+4. No SEV-1 or SEV-2 open bugs without explicit release approval.
+5. CI is green on release source branch.
+6. Security scan and dependency audit pass.
+7. Changelog is generated or updated.
+8. Rollback plan is documented.
+9. Tech Lead approves technical readiness.
+10. QA confirms release candidate verification.
+
+## 🔄 Execution Flow
+
+1. Load config, tickets, bugs, current branch, latest tags, and release notes.
+2. Validate release source branch, normally `develop` or `release/vX.Y.Z`.
+3. Run `bash scripts/validate-state.sh`.
+4. Identify release scope from DONE tickets since previous release.
+5. Confirm QA evidence exists for every included ticket.
+6. Check open bugs and known issues.
+7. Generate changelog with ticket IDs, PRs, bug fixes, migrations, and breaking changes.
+8. Create `project/releases/vX.Y.Z.json` from `core/templates/release/release-record-template.json` with scope, approvals, risks, deploy plan, rollback plan, and timestamps.
+9. Create or update release branch if configured.
+10. Tag release using `vX.Y.Z`.
+11. Trigger deployment or document manual deployment step.
+12. Run post-deploy smoke test plan.
+13. Record release outcome and handoff to QA for post-release verification.
+
+## 🔒 Hard Rules
+
+### RULE REL-001: No unverified work
+A release MUST NOT include tickets that are not `DONE`, unless explicitly marked as non-ticket operational work with approval.
+
+### RULE REL-002: State validation required
+`/validate-state` MUST pass before tagging.
+
+### RULE REL-003: Rollback plan required
+Every release MUST document rollback command, expected data impact, owner, and time limit.
+
+### RULE REL-004: Known issues are explicit
+Open high-severity bugs MUST be listed with release decision and approver.
+
+### RULE REL-005: No silent schema changes
+Database migrations MUST include forward plan, rollback or mitigation, and backup notes.
+
+### RULE REL-006: Tag immutability
+Do not move an existing release tag. Create a new patch release instead.
+
+### RULE REL-007: Release record schema required
+Every release record MUST satisfy `core/config/release.schema.json`. Missing approvals, rollback verification, QA evidence, security scan status, or known issue approval blocks release.
+
+### RULE REL-008: Post-release smoke evidence
+If a release is marked `RELEASED` and `qa.post_release_smoke_required=true`, then `qa.post_release_smoke_passed=true` and the evidence path MUST be recorded.
+
+## 📤 Outputs
+
+Success:
+
+- Release record path
+- Version tag
+- Included tickets
+- Known issues
+- Deployment status
+- Rollback plan
+- Next command: `/smoke-test` or post-release QA checklist
+
+Failure:
+
+- Blocking gate
+- Required owner to resolve
+- Suggested command or remediation
+
+## 🔗 Related Commands
+
+- Before: `/sprint-report`, `/validate-state`, `/smoke-test`
+- After: `/rollback` if release fails
+- Emergency: `/hotfix`