ai-core-framework 0.1.0

package/core/rules/06-approval-gates.md

@@ -0,0 +1,388 @@
+# 🔒 RULE 06: Approval Gates & State Transitions (Strict)
+
+> **State machine enforcement**. No skipping states. Every transition has a gate.
+> Enforced by: agent rules + JSON schema + CI validation.
+
+---
+
+## 🎯 Core Principle
+
+**A ticket's state reflects reality, not wishes.** Every transition requires passing gate criteria. No "let's move it along" without meeting conditions.
+
+This prevents:
+- Shipping unfinished work
+- Missing quality gates
+- Orchestration loops ("how did this get to DONE?")
+
+---
+
+## 🔄 Ticket State Machine
+
+### States
+
+```
+┌────────┐   /analyze-requirements           ┌─────────┐
+│        │ ──────────────────────────────▶   │  DRAFT  │
+│ (none) │                                   └────┬────┘
+│        │                                        │ /groom-ticket
+└────────┘                                        ▼
+                                            ┌──────────┐
+                                            │ GROOMED  │
+                                            └────┬─────┘
+                                                 │ /mark-ready
+                                                 ▼
+                                            ┌──────────┐
+                                            │  READY   │
+                                            └────┬─────┘
+                                                 │ /implement-task
+                                                 ▼
+                                            ┌──────────────┐
+                                            │ IN_PROGRESS  │◀──────┐
+                                            └──────┬───────┘       │
+                                                   │ /create-pr    │
+                                                   ▼               │
+                                            ┌──────────────┐       │
+                                            │  IN_REVIEW   │       │ /reopen
+                                            └──────┬───────┘       │ (if bugs)
+                                                   │ /merge-pr     │
+                                                   ▼               │
+                                            ┌──────────────┐       │
+                                            │      QA      │───────┘
+                                            └──────┬───────┘
+                                                   │ /smoke-test PASS
+                                                   ▼
+                                            ┌──────────────┐
+                                            │     DONE     │
+                                            └──────────────┘
+
+
+Side states (can exit any state into these):
+  BLOCKED    — external dependency waiting
+  CANCELLED  — will not be done
+```
+
+### Allowed transitions matrix
+
+| From | To | Gate command | Gate-holder agent |
+|------|----|--------------|--------------------|
+| (none) | DRAFT | `/analyze-requirements` | business-analyst |
+| DRAFT | GROOMED | `/groom-ticket` | tech-lead |
+| DRAFT | BLOCKED | manual | any agent |
+| DRAFT | CANCELLED | manual | business-analyst |
+| GROOMED | READY | `/mark-ready` | scrum-master |
+| GROOMED | DRAFT | manual (if grooming reveals unclear AC) | business-analyst |
+| GROOMED | BLOCKED | manual | tech-lead |
+| READY | IN_PROGRESS | `/implement-task` | developer |
+| READY | BLOCKED | manual | developer |
+| IN_PROGRESS | IN_REVIEW | `/create-pr` | developer |
+| IN_PROGRESS | BLOCKED | manual | developer |
+| IN_REVIEW | IN_PROGRESS | review changes requested | developer |
+| IN_REVIEW | QA | `/merge-pr` | tech-lead |
+| QA | DONE | `/smoke-test` PASS | qa-tester |
+| QA | IN_PROGRESS | `/smoke-test` FAIL | qa-tester |
+| BLOCKED | (previous state) | `/unblock` | any agent |
+
+### Forbidden transitions
+
+The following **MUST NEVER** happen:
+- ❌ DRAFT → READY (skip grooming)
+- ❌ DRAFT → IN_PROGRESS (skip grooming + DoR check)
+- ❌ GROOMED → IN_PROGRESS (skip DoR check)
+- ❌ READY → IN_REVIEW (skip implementation)
+- ❌ IN_PROGRESS → QA (skip review + merge)
+- ❌ IN_PROGRESS → DONE (skip everything)
+- ❌ IN_REVIEW → DONE (skip QA)
+- ❌ QA → IN_REVIEW (must go back to IN_PROGRESS then normal flow)
+- ❌ DONE → any state (once done, stays done; new work = new ticket)
+
+---
+
+## 🔒 Rules
+
+### RULE AG-001: State machine enforcement
+
+**MUST NOT** transition ticket state by directly editing JSON. **MUST** go through gate command.
+
+Why: Commands enforce preconditions. Direct edit bypasses all quality gates.
+
+**Enforcement**: 
+- Agent rule: agents MUST use commands
+- JSON schema: `state_history` field required, each entry must reference command
+- CI check: scripts/validate-state.sh verifies state_history is complete
+
+### RULE AG-002: Every gate has criteria
+
+No command should say "approved, moving to next state" without:
+1. Criteria list (checklist)
+2. Verification each criterion
+3. Documentation in state_history
+
+Each transition command (`/groom-ticket`, `/mark-ready`, `/create-pr`, `/merge-pr`, `/smoke-test`) **MUST** have documented preconditions (see individual command files).
+
+### RULE AG-003: Gate-holder agent only
+
+Some transitions can only be executed by specific agent:
+
+| Transition | Gate-holder | Cannot be done by |
+|------------|-------------|-------------------|
+| DRAFT → GROOMED | tech-lead | Developer, BA, anyone else |
+| GROOMED → READY | scrum-master | Developer (bypassing SM) |
+| IN_REVIEW → QA (merge) | tech-lead | Developer (self-merge forbidden) |
+| QA → DONE | qa-tester | Developer, tech-lead, anyone |
+
+This separation prevents conflict of interest:
+- Dev can't approve own code
+- Tech-lead can't skip QA
+- Self-merge forbidden
+
+### RULE AG-004: Gates from checklists
+
+Each gate has explicit checklist. Reference:
+- GROOMED gate: see `commands/planning/groom-ticket.md`
+- READY gate (DoR): see `rules/07-definition-of-ready.md`
+- IN_REVIEW gate: see `commands/review/create-pr.md`
+- QA gate: see `commands/review/techlead-review.md` + `commands/review/merge-pr.md`
+- DONE gate (DoD): see `rules/08-definition-of-done.md`
+
+### RULE AG-005: Gate failures are OK
+
+If gate fails:
+- **MUST** document reason
+- **MUST** leave ticket in current state (or send back to previous)
+- **MUST NOT** "push through" despite failure
+
+Gate failures are a feature, not a bug. They prevent bad code reaching prod.
+
+### RULE AG-006: BLOCKED state explicit
+
+Ticket goes BLOCKED when:
+- External dependency not ready (e.g., 3rd party API access)
+- Infrastructure issue (env down)
+- Decision pending (awaiting stakeholder)
+- Resource unavailable (no test data)
+
+BLOCKED **MUST** include:
+- What's blocking
+- Who can unblock
+- Expected resolution time
+- Escalation path
+
+Example:
+```json
+{
+  "status": "BLOCKED",
+  "blocked_reason": "Awaiting SendGrid API credentials from DevOps",
+  "blocked_by": "@devops-team",
+  "blocked_at": "2026-04-18T10:00:00Z",
+  "expected_unblock": "2026-04-19",
+  "escalation": "scrum-master"
+}
+```
+
+### RULE AG-007: No zombie tickets
+
+Tickets stuck in a state > X days trigger alerts:
+
+| State | Max days (soft) | Max days (hard) | Action |
+|-------|----------------|----------------|--------|
+| DRAFT | 7 | 14 | SM reviews, either groom or cancel |
+| GROOMED | 14 | 30 | SM reviews, either ready or re-groom |
+| READY | Sprint length | 2x sprint | Include in sprint or deprioritize |
+| IN_PROGRESS | 5 | 10 | Dev must report status, may need split |
+| IN_REVIEW | 2 | 5 | Escalate to tech-lead for review |
+| QA | 3 | 7 | Escalate to QA lead |
+| BLOCKED | 7 | 30 | Weekly review, may cancel |
+
+Alerts: `/ticket-health` command (scrum-master).
+
+### RULE AG-008: State history required
+
+Every ticket **MUST** have complete `state_history` array:
+```json
+{
+  "state_history": [
+    {
+      "from_state": null,
+      "to_state": "DRAFT",
+      "at": "2026-04-18T09:00:00Z",
+      "by_agent": "business-analyst-agent",
+      "by_command": "/analyze-requirements",
+      "reason": "Initial creation"
+    },
+    {
+      "from_state": "DRAFT",
+      "to_state": "GROOMED",
+      "at": "2026-04-18T11:00:00Z",
+      "by_agent": "tech-lead-agent",
+      "by_command": "/groom-ticket",
+      "reason": "Technical feasibility confirmed, estimated 5 points"
+    }
+  ]
+}
+```
+
+Schema validates this structure (see `config/ticket.schema.json`).
+
+### RULE AG-009: Audit trail preserved
+
+State history **MUST NOT** be:
+- Deleted
+- Modified (historical entries immutable)
+- Skipped
+
+Even if ticket goes back-and-forth many times, every transition logged.
+
+### RULE AG-010: Emergency override (RARE)
+
+In true emergency (system recovering from incident), human may override state machine.
+
+**MUST**:
+- Use `/admin-override TICKET-XXX --new-state=X --reason="..."`
+- Command requires `--justification` flag with clear reason
+- Logged in audit trail with `override=true`
+- Post-mortem mandatory afterward
+- Notify stakeholders
+
+Agents **NEVER** override. Only humans.
+
+---
+
+## 🔐 Gate Criteria Summary
+
+### Gate 1: DRAFT → GROOMED
+Owner: `/groom-ticket` (tech-lead)
+
+- [ ] User story compliant with INVEST
+- [ ] Minimum 3 AC scenarios
+- [ ] Technical feasibility assessed
+- [ ] Risks identified (≥1)
+- [ ] Estimate assigned (Fibonacci, ≤8)
+- [ ] Dependencies listed (or "none")
+- [ ] ADR created (if needed)
+
+### Gate 2: GROOMED → READY
+Owner: `/mark-ready` (scrum-master)
+
+Definition of Ready checklist (see rules/07-definition-of-ready.md):
+- [ ] All open questions answered
+- [ ] Mockups/designs finalized (if UI)
+- [ ] Dependencies resolved or acceptable
+- [ ] Test data plan exists
+- [ ] Team has capacity
+- [ ] No blockers
+
+### Gate 3: READY → IN_PROGRESS
+Owner: `/implement-task` (developer)
+
+- [ ] Developer assigned
+- [ ] Sprint has capacity (if sprint-scoped)
+- [ ] Branch created following naming convention
+- [ ] No existing PR for this ticket
+
+### Gate 4: IN_PROGRESS → IN_REVIEW
+Owner: `/create-pr` (developer)
+
+- [ ] All tests passing
+- [ ] Diff coverage ≥ 80%
+- [ ] Lint passing
+- [ ] Self-review complete
+- [ ] PR template filled
+- [ ] Reviewer assigned
+- [ ] Ticket linked to PR
+
+### Gate 5: IN_REVIEW → QA (merge)
+Owner: `/merge-pr` (tech-lead)
+
+- [ ] PR approved by tech-lead
+- [ ] CI green
+- [ ] All comments resolved
+- [ ] No conflicts
+- [ ] Not self-merge
+- [ ] Branch up-to-date with target
+
+### Gate 6: QA → DONE
+Owner: `/smoke-test` (qa-tester)
+
+Definition of Done checklist (see rules/08-definition-of-done.md):
+- [ ] All AC scenarios verified in test env
+- [ ] No new regressions
+- [ ] No open SEV-1/SEV-2 bugs in this area
+- [ ] Performance within target
+- [ ] Security spot-check passed
+- [ ] Documentation updated
+- [ ] CHANGELOG entry
+
+---
+
+## 🚨 Violation Consequences
+
+| Violation | Consequence |
+|-----------|-------------|
+| Agent edits ticket state directly | Schema validation fails, state_history incomplete |
+| Skip gate (e.g., IN_PROGRESS → DONE) | validate-state.sh CI check fails PR |
+| Non-gate-holder agent transitions | Agent rule violation, human escalation |
+| Override without justification | Post-mortem mandatory |
+| Zombie tickets ignored | Health reports surface weekly |
+
+---
+
+## 🔧 Enforcement Mechanisms
+
+### Layer 1: Agent rules (soft)
+Each agent's rules file references this doc. Agents refuse to bypass.
+
+### Layer 2: JSON schema (medium)
+`config/ticket.schema.json` requires:
+- Valid state value
+- state_history array with required fields
+
+### Layer 3: Validation script (medium)
+`scripts/validate-state.sh` runs:
+- All transitions in state_history are valid (matrix)
+- No gaps (e.g., DRAFT → READY missing GROOMED)
+- Every transition has by_command + by_agent
+
+### Layer 4: CI gate (hard)
+`.github/workflows/validate-state.yml` blocks PRs that:
+- Modify tickets with invalid states
+- Bypass transitions
+- Delete state_history entries
+
+### Layer 5: Human review (backup)
+Scrum-master weekly review of all ticket states.
+Anomalies escalated.
+
+---
+
+## 💡 Common Scenarios
+
+### Scenario: Urgent feature, want to skip grooming
+
+**Wrong**: Skip grooming, go DRAFT → IN_PROGRESS.
+
+**Right**: Do expedited grooming (15 min), document risks as accepted. Still follows state machine.
+
+### Scenario: Bug fix small, skip review
+
+**Wrong**: Dev merges own tiny bug fix.
+
+**Right**: Still create PR, still get review. Small fixes break things too.
+
+### Scenario: QA blocked by env, want to mark DONE
+
+**Wrong**: "It'll work, mark DONE."
+
+**Right**: Ticket stays QA. Fix env first (possibly BLOCKED meanwhile).
+
+### Scenario: Post-mortem reveals ticket should have been split
+
+**Wrong**: Delete/modify original ticket.
+
+**Right**: Leave history intact. Create retrospective action item. Learn.
+
+---
+
+**Version**: 1.0.0
+**Last updated**: 2026-04-18
+**Maintainer**: Scrum Master + Tech Lead
+**Next review**: Every sprint retrospective

package/core/rules/07-definition-of-ready.md

@@ -0,0 +1,112 @@
+# 🎯 Definition of Ready (DoR)
+
+> Mandatory checklist a ticket **MUST** pass before it transitions to state `READY`.
+> Enforced by: `/mark-ready` command + `scrum-master` agent.
+
+## ⚠️ Enforcement
+
+If a ticket does not pass DoR, it **MUST NOT** enter a sprint. There are no exceptions.
+
+---
+
+## ✅ Checklist
+
+### 1. User Story
+- [ ] **INVEST-compliant**:
+  - [ ] **I**ndependent, not blocked by another ticket unless that blocker is resolved
+  - [ ] **N**egotiable, with scope open to refinement
+  - [ ] **V**aluable, with clear business value
+  - [ ] **E**stimable, so the team can estimate it
+  - [ ] **S**mall, ≤ 8 story points. If > 8, it **MUST** be split
+  - [ ] **T**estable, with a clear verification path
+- [ ] Format: `As a <role>, I want <action>, so that <value>`
+- [ ] Business value (`so_that`) is specific and unambiguous
+
+### 2. Acceptance Criteria
+- [ ] At least **3 scenarios** (happy path + edge case + error case)
+- [ ] Format Gherkin: `Given / When / Then`
+- [ ] Every scenario is **testable**, and QA can write a test case directly from it
+- [ ] Non-functional requirements are covered:
+  - Performance, if applicable
+  - Security, if applicable
+  - Accessibility, if user-facing
+
+### 3. Estimation
+- [ ] Story points estimated (1, 2, 3, 5, 8)
+- [ ] Estimate completed by ≥1 Dev + 1 Tech Lead. BA-only estimates are **FORBIDDEN**
+- [ ] Estimate is not > 8 points. If > 8, the ticket **MUST** be split
+
+### 4. Technical Feasibility
+- [ ] Tech Lead has reviewed it
+- [ ] Technical approach is documented briefly in the ticket comment
+- [ ] No critical "unknown unknowns" remain
+- [ ] Spike tickets are created when research is required
+
+### 5. Dependencies
+- [ ] `dependencies.blocked_by` is explicit
+- [ ] Blockers are resolved, or there is a concrete plan to resolve them before the ticket starts
+- [ ] External dependencies (API, external services) have confirmed availability
+
+### 6. Design & Assets
+If the ticket has UI:
+- [ ] Figma / mockup link is in the ticket
+- [ ] Design has stakeholder approval
+- [ ] Responsive behavior defined
+- [ ] Dark mode defined, if the app supports it
+
+### 7. Data & API
+If the ticket has data changes:
+- [ ] Schema changes documented
+- [ ] Migration strategy defined
+- [ ] API contract (OpenAPI spec) available
+- [ ] Breaking change impact assessed
+
+### 8. Security & Compliance
+- [ ] Threat model reviewed, if auth or sensitive data is involved
+- [ ] PII handling complies with policy
+- [ ] Audit logging requirements identified
+
+### 9. Testability
+- [ ] Test strategy defined:
+  - Unit test scope
+  - Integration test scope
+  - E2E test scope, if required
+- [ ] Test data available
+- [ ] Test environments ready
+
+### 10. Out of Scope
+- [ ] Clearly list **WHAT IS NOT INCLUDED** in the ticket
+- [ ] Related work is created as separate tickets
+
+---
+
+## 🔒 DoR Enforcement Rules
+
+### RULE DOR-001: No exception
+**MUST NOT** override DoR "just this once". If the rule blocks delivery, raise it in retrospective.
+
+### RULE DOR-002: Who marks ready
+Only the `scrum-master` agent or explicit human approval may mark a ticket READY.
+
+### RULE DOR-003: Re-check
+If a ticket has been READY for > 2 sprints without being picked up, the team **MUST** re-check DoR because the ticket may be stale.
+
+### RULE DOR-004: Mid-sprint ticket
+A ticket added to an active sprint **MUST** pass DoR and have explicit SM + PM approval.
+
+---
+
+## 💡 Common Failures
+
+| Failure | Fix |
+|---------|-----|
+| AC too vague or not testable | BA rewrites using strict Gherkin |
+| Estimate > 8 points | Split into sub-tickets |
+| Dependency unclear | Tech Lead maps the dependency graph |
+| "Figma later" | STOP. Do not accept. Wait for design |
+| Non-functional requirements missing | Add performance/security AC |
+
+---
+
+**Version**: 1.0.0
+**Owner**: Scrum Master + Tech Lead

package/core/rules/08-definition-of-done.md

@@ -0,0 +1,149 @@
+# ✅ Definition of Done (DoD)
+
+> Mandatory checklist a ticket **MUST** pass before it transitions to state `DONE`.
+> Enforced by: `/smoke-test` + `qa-tester` agent + CI pipeline.
+
+## ⚠️ Enforcement
+
+If a ticket does not pass DoD, it **MUST NOT** be closed. "Ship it, we'll fix later" is **FORBIDDEN**.
+
+---
+
+## ✅ Checklist
+
+### 1. Code Complete
+- [ ] All AC scenarios implemented
+- [ ] Code merged into `develop` or the main branch
+- [ ] No TODO/FIXME/HACK remains without a linked follow-up ticket
+- [ ] No commented-out code
+- [ ] Dead code removed
+
+### 2. Testing
+- [ ] Unit tests for all AC scenarios
+- [ ] Integration tests for new API endpoints
+- [ ] **Diff coverage ≥ 80%**
+- [ ] **All tests pass** (unit + integration + E2E, if present)
+- [ ] Edge cases + error cases covered
+- [ ] Test names descriptive (`should_X_when_Y`)
+- [ ] No `.skip`, `xit`, or `@Disabled` without ticket justification
+
+### 3. Code Review
+- [ ] PR approved by **≥1 Tech Lead**
+- [ ] All review comments resolved
+- [ ] **No self-approval** (G-008b)
+- [ ] PR template fully completed
+
+### 4. Quality Gates
+- [ ] **Linter pass** (0 errors)
+- [ ] **Type check pass**, if the language is typed
+- [ ] **CI pipeline green**
+- [ ] **Security scan pass** (SAST, dependency check)
+- [ ] **No new critical/high vulnerabilities**
+- [ ] Performance regression check, if critical path
+
+### 5. Documentation
+- [ ] **README** updated, if setup changed
+- [ ] **API docs** updated, if endpoints are new or changed
+- [ ] **CHANGELOG** entry added
+- [ ] **ADR** created, if there is an architecture decision
+- [ ] Inline code comments for complex logic
+- [ ] Deprecation notices, if any
+
+### 6. QA Verification
+- [ ] Smoke test passes on staging
+- [ ] Every AC scenario verified manually or through automation
+- [ ] Regression test passes, with no broken existing features
+- [ ] Cross-browser check, if frontend and applicable
+- [ ] Mobile responsive check, if applicable
+- [ ] Accessibility check, WCAG AA for user-facing functionality
+
+### 7. Non-Functional Requirements
+- [ ] **Performance**: Response time within SLA
+- [ ] **Security**: OWASP Top 10 checklist pass
+- [ ] **Observability**: Logs, metrics, traces added
+- [ ] **Error handling**: Graceful degradation
+- [ ] **Internationalization**: i18n keys, if multi-language
+
+### 8. Deployment
+- [ ] Deployed to staging environment
+- [ ] Staging smoke test pass
+- [ ] Feature flag configured, if the project uses feature flags
+- [ ] Rollback plan documented
+- [ ] Database migration tested, if any
+
+### 9. Business Verification
+- [ ] Product Owner / Stakeholder approval, if visible feature
+- [ ] Analytics / tracking events implemented
+- [ ] Help docs updated, if user-facing
+
+### 10. Ticket Hygiene
+- [ ] Ticket state updated in `project/tickets/`
+- [ ] `completed_at` timestamp set
+- [ ] PR URL linked
+- [ ] Release version tagged after release
+- [ ] Related tickets updated (dependencies)
+
+---
+
+## 🔒 DoD Enforcement Rules
+
+### RULE DOD-001: No exception
+There are no "temporary" skips. If the sprint is ending and the ticket has not passed DoD, the ticket rolls over. It **MUST NOT** be closed.
+
+### RULE DOD-002: Automated gates first
+Automatable items (tests, lint, coverage, CI) **MUST** pass before human DoD review.
+
+### RULE DOD-003: QA has veto
+The QA agent **MUST** reject a "Done" claim if it finds an issue. State returns to `IN_PROGRESS`.
+
+### RULE DOD-004: Ship debt tracking
+If any DoD item is skipped with justification, the team **MUST** create a tech-debt ticket.
+
+### RULE DOD-005: No self-sign-off
+Developers **MUST NOT** mark their own tickets DONE. QA or Tech Lead verification is required.
+
+### RULE DOD-006: Machine-readable DoD required
+Ticket status `DONE` MUST include `dod_checklist` fields set to true for code, tests, docs, review, QA, release notes, and security. `completed_at`, `pr_url`, and `qa_evidence.path` are required and validated by `scripts/validate-state.sh` and `scripts/validate-docs.sh`.
+
+---
+
+## 🎯 DoD Tiers (by ticket type)
+
+### Feature / Enhancement
+Apply the **full checklist** (1-10).
+
+### Bug Fix
+Apply the full checklist plus extras:
+- [ ] Root cause analysis documented
+- [ ] Regression test for this specific bug
+- [ ] Similar bugs pattern check
+
+### Tech Debt / Refactor
+Apply 1-7. Skip 8-9 only if there is no user-facing change:
+- [ ] Performance benchmark (before/after)
+- [ ] Behavior preservation verified (tests still pass)
+
+### Hotfix
+**Emergency path** (relaxed):
+- [ ] Minimum: Fix works + basic test + Tech Lead review + deployed
+- [ ] **Follow-up ticket** to complete full DoD in the next sprint (MANDATORY)
+
+### Spike
+- [ ] Research documented in ADR or design doc
+- [ ] Recommendation clear
+- [ ] Follow-up tickets created
+
+---
+
+## 📊 DoD Metrics
+
+Track in retrospective:
+- % tickets pass DoD first try
+- Which DoD items commonly fail
+- Time wasted on rework
+
+---
+
+**Version**: 1.0.0
+**Owner**: Scrum Master + QA Lead
+**Review cadence**: End of each sprint