guardian-framework 0.1.0

package/templates/pi/prompts/issue-template-set.md

@@ -0,0 +1,392 @@
+# Guardian Issue Template Set
+
+> **Use these templates to generate architecture-aware, independently reviewable issues.**
+> Every issue generated by the Issue Factory follows these templates. Each issue is the smallest independently reviewable unit with complete session context.
+
+## General Rules
+
+Every issue must contain:
+
+- **Why** — Business or platform reason
+- **Scope** — Exact change
+- **In scope** — Bullet list of what's included
+- **Out of scope** — Bullet list of what's explicitly excluded
+- **Dependencies** — blocked by / blocks relationships
+- **Acceptance criteria** — Tied to specific Guardian validators
+- **Verification requirements** — Unit/integration/conformance tests
+- **Canonical references** — Architecture module + ADR paths
+- **Files/layers affected** — domain, application, infrastructure, api
+- **Rollout or operational notes** — When relevant
+
+---
+
+## 1. Contract Issue Template
+
+Use for: Domain contracts, API contracts, event contracts, compatibility rules.
+
+### Title
+
+`contract: <concrete contract change>`
+
+### Why
+
+Why this contract must be defined before implementation.
+
+### Scope
+
+Define the architecture contract precisely.
+
+### In scope
+
+- aggregate or state-machine rule changes
+- API contract changes
+- event contract changes
+- compatibility rules
+
+### Out of scope
+
+- repository implementation
+- worker implementation
+- dashboards/runbooks
+
+### Dependencies
+
+- blocked by: epic approval
+- blocks: schema, repository, handler, runtime issues
+
+### Acceptance criteria
+
+- [ ] Domain/application/runtime contract is explicit
+- [ ] compatibility and versioning rules are explicit
+- [ ] forbidden changes are listed
+- [ ] impacted layers are listed
+
+### Verification
+
+- architecture review
+- contract review
+
+### Canonical references
+
+- `.pi/architecture/modules/<module>.md`
+- relevant ADRs
+
+---
+
+## 2. Schema / Index / Config Issue Template
+
+Use for: Migrations, indexes, RLS policies, queue/Redis/blob/config changes.
+
+### Title
+
+`infrastructure: <schema/index/config action>`
+
+### Why
+
+Why persistence or runtime configuration must change.
+
+### Scope
+
+Describe exact schema/index/config changes.
+
+### In scope
+
+- migrations
+- indexes
+- RLS policies
+- queue/Redis/blob/config changes
+
+### Out of scope
+
+- handler or API behavior beyond what config enables
+- rollout communications unless required for safety
+
+### Dependencies
+
+- blocked by: contract issue
+- blocks: repository/service and runtime issues
+
+### Acceptance criteria
+
+- [ ] migration or config change is explicit
+- [ ] required indexes/policies are present
+- [ ] tenant isolation impact is reviewed
+- [ ] rollback path is documented
+
+### Verification
+
+- migration verification
+- integration tests
+- conformance tests when applicable
+
+### Canonical references
+
+- `.pi/architecture/modules/<module>.md`
+- `.pi/architecture/decisions/ADR-*.md`
+
+---
+
+## 3. Repository / Service Issue Template
+
+Use for: Repository logic, storage adapters, Redis/queue/blob/AI service integration.
+
+### Title
+
+`infrastructure: <repository or service change>`
+
+### Why
+
+Why adapters or persistence services must change.
+
+### Scope
+
+List repositories, service adapters, or infrastructure modules touched.
+
+### In scope
+
+- repository logic
+- storage adapters
+- Redis/queue/blob/AI service integration changes
+- timeout/retry/circuit-breaker changes
+
+### Out of scope
+
+- API contract redesign
+- broad runtime orchestration refactors not required for this issue
+
+### Dependencies
+
+- blocked by: contract issue, schema/index/config issue
+- blocks: handler/runtime issues
+
+### Acceptance criteria
+
+- [ ] tenant guarantees remain intact
+- [ ] idempotency behavior remains intact
+- [ ] timeout/retry behavior is explicit
+- [ ] required observability is added
+
+### Verification
+
+- integration tests
+- infrastructure-focused conformance tests
+
+### Canonical references
+
+- `.pi/architecture/modules/<module>.md`
+- `.pi/architecture/decisions/ADR-*.md`
+
+---
+
+## 4. Handler / Runtime Issue Template
+
+Use for: Command/query handlers, UoW/outbox behavior, worker logic, LangGraph flow changes.
+
+### Title
+
+`application-runtime: <handler or worker action>`
+
+### Why
+
+Why application flow or worker behavior must change.
+
+### Scope
+
+Describe the exact command/query/handler/runtime behavior to implement.
+
+### In scope
+
+- command or query handlers
+- UoW/outbox behavior
+- worker logic
+- LangGraph flow changes
+- retry/resume/checkpoint logic
+
+### Out of scope
+
+- unrelated schema redesign
+- unrelated frontend/BFF changes
+
+### Dependencies
+
+- blocked by: contract issue, repository/service issue
+- blocks: verification and rollout issues
+
+### Acceptance criteria
+
+- [ ] transaction boundary is explicit
+- [ ] state transitions are valid
+- [ ] idempotency behavior is explicit
+- [ ] replay/resume safety is preserved
+- [ ] errors and observability are updated
+
+### Verification
+
+- unit tests
+- integration tests
+- runtime conformance tests
+
+### Canonical references
+
+- `.pi/architecture/modules/<module>.md`
+- `.pi/architecture/decisions/ADR-*.md`
+
+---
+
+## 5. Verification / Conformance Issue Template
+
+Use for: Architecture conformance tests, integration regression tests, contract validation, CI enforcement.
+
+### Title
+
+`verification: <conformance area>`
+
+### Why
+
+Why the architecture needs executable verification for this area.
+
+### Scope
+
+Describe exact checks or tests to add.
+
+### In scope
+
+- architecture conformance tests
+- integration regression tests
+- contract validation tests
+- CI enforcement additions
+
+### Out of scope
+
+- feature implementation unrelated to verification
+
+### Dependencies
+
+- blocked by: contract and implementation issues
+- blocks: release readiness for the epic
+
+### Acceptance criteria
+
+- [ ] failing behavior is detectable automatically
+- [ ] tests run in Guardian CI pipeline
+- [ ] required fixtures/services are defined
+- [ ] documentation explains what is enforced
+
+### Verification
+
+- CI execution proof
+- failing test demonstration where appropriate
+
+### Canonical references
+
+- `.pi/architecture/modules/<module>.md`
+- `.pi/architecture/decisions/ADR-*.md`
+
+---
+
+## 6. Rollout / Runbook / Ops Issue Template
+
+Use for: Dashboards, alerts, runbooks, SLO updates, rollout sequencing, rollback steps.
+
+### Title
+
+`operations: <rollout or runbook change>`
+
+### Why
+
+Why production readiness requires this operational work.
+
+### Scope
+
+Describe exact rollout, monitoring, alerting, or runbook output.
+
+### In scope
+
+- dashboards
+- alerts
+- runbooks
+- SLO updates
+- rollout sequencing
+- rollback steps
+
+### Out of scope
+
+- primary code implementation unless minimal for observability hooks
+
+### Dependencies
+
+- blocked by: implementation and verification issues
+
+### Acceptance criteria
+
+- [ ] operational visibility exists
+- [ ] alerting or dashboard updates are defined
+- [ ] rollback steps exist
+- [ ] release checklist impact is documented
+
+### Verification
+
+- runbook review
+- dashboard/alert validation
+- rollout rehearsal or dry run where necessary
+
+### Canonical references
+
+- `.pi/architecture/modules/<module>.md`
+- `.pi/architecture/decisions/ADR-*.md`
+
+---
+
+## 7. High-Risk Issue Addendum
+
+Use this addendum for issues labeled `risk::high`.
+
+### Additional Required Fields
+
+- Failure mode analysis
+- Data integrity risk
+- Multi-tenant isolation risk
+- Security review notes
+- Rollback plan
+- Feature flag or staged rollout decision
+
+### Additional Approvals
+
+- Architecture Validator Agent
+- Security Agent or security reviewer
+- Operations Agent or release reviewer
+
+---
+
+## Recommended Labels
+
+| Label | Meaning |
+|-------|---------|
+| `layer::domain` | Domain model, entities, value objects |
+| `layer::application` | Use cases, services, handlers |
+| `layer::infrastructure` | Databases, queues, external APIs |
+| `layer::api` | REST/gRPC endpoints, middleware |
+| `layer::security` | Auth, encryption, secrets |
+| `layer::operations` | Observability, runbooks, DR |
+| `type::feature` | New functionality |
+| `type::hardening` | Security/performance improvement |
+| `type::migration` | Schema or config migration |
+| `type::test` | Test-only work |
+| `risk::high` | Breaks existing behavior |
+| `risk::medium` | Changes internal behavior |
+| `risk::low` | Additive, no breaking changes |
+
+---
+
+## Dependency Ordering
+
+1. **contract issue** — Domain contracts, API contracts
+2. **schema/index issue** — Migrations, indexes, config
+3. **repository/service issue** — Data access, adapters
+4. **handler/runtime issue** — Business logic, workers
+5. **verification issue** — Tests, conformance
+6. **rollout/runbook issue** — Ops, monitoring
+
+---
+
+*Use the smallest template that matches the actual unit of work.*

package/templates/pi/prompts/issue-template.md

@@ -0,0 +1,207 @@
+# Guardian Issue Contract
+
+> **Professional issue template with complete context for a fresh session agent to implement correctly.**
+> Every issue generated by `/architect` follows this contract. The YAML front matter is parsed by Guardian; the body is the agent's complete session context.
+
+---
+
+## Template
+
+```markdown
+---
+guardian_issue:
+  id: ISSUE-001
+  title: "JWT Token Validation"
+  epic: "Auth Module v1"
+  epic_id: EPIC-001
+  tracking_issue: 100
+  status: planned
+  priority: high
+  created_at: "2026-05-17T00:00:00Z"
+  updated_at: "2026-05-17T00:00:00Z"
+
+  intent: |
+    Implement JWT token validation for the auth system. Validate tokens from
+    request headers, check expiry, verify signature with RS256, and enforce
+    required claims (sub, iss, exp, iat).
+
+  dependencies:
+    - name: none
+      type: external
+      note: "No internal dependencies. This is a root component."
+
+  in_scope:
+    - JWT token parsing and validation
+    - RS256 signature verification with JWK rotation
+    - Expiry and claim validation
+    - Error handling for invalid/expired tokens
+    - Unit tests for all validation paths
+    - Integration tests with mock JWT provider
+
+  out_of_scope:
+    - Token generation (handled by upstream auth provider)
+    - OAuth2 flow (handled by OAuth2 Provider Integration component)
+    - Session storage (handled by Session Management component)
+    - UI/login pages
+
+  affected_layers:
+    domain:
+      - "New: JwtToken entity"
+      - "New: TokenValidator interface"
+      - "New: ValidationError domain errors"
+    application:
+      - "New: ValidateToken use case"
+      - "New: TokenValidationService"
+    infrastructure:
+      - "New: JwkClient for fetching public keys"
+      - "New: Redis cache for JWK rotation"
+    api:
+      - "New: Auth middleware for token validation"
+      - "Modified: Error response format for 401/403"
+
+  canonical_references:
+    - module: ".pi/architecture/modules/auth-system.md#jwt-token-validation"
+    - adr:
+        - ".pi/architecture/decisions/ADR-001-auth-pattern.md"
+        - ".pi/architecture/decisions/ADR-003-jwt-algorithm.md"
+    - last_sync: "2026-05-17"
+
+  acceptance_criteria:
+    - "CI pipeline passes (validate-ci.sh)"
+    - "All unit tests pass with ≥ 90% coverage"
+    - "Integration tests pass against mock JWT provider"
+    - "validate-security.sh passes (no hardcoded secrets, proper key handling)"
+    - "validate-architecture.sh passes (layer boundaries respected)"
+    - "validate-canonical.sh passes (implementation references architecture)"
+
+  validators:
+    - ci
+    - tests
+    - security
+    - architecture
+    - canonical
+
+  implementation_notes: |
+    - Use PyJWT library for Python / jsonwebtoken for TypeScript
+    - JWK cache TTL: 1 hour, refresh on signature failure
+    - Required claims: sub, iss, exp, iat, aud
+    - Reject tokens with exp < now() - 30s (clock skew tolerance)
+    - Log validation failures at WARN level with token ID (not full token)
+    - Do NOT log token contents or secrets
+
+  file_changes:
+    - "create: src/auth/jwt_validator.py"
+    - "create: src/auth/token_validator.py"
+    - "create: src/auth/errors.py"
+    - "create: tests/unit/auth/test_jwt_validator.py"
+    - "create: tests/integration/auth/test_token_validation.py"
+    - "modify: src/middleware/auth_middleware.py"
+
+  pipeline_steps:
+    - implement
+    - validate
+    - create-mr
+    - merge
+---
+
+# ISSUE-001: JWT Token Validation
+
+## Intent
+
+Implement JWT token validation for the auth system. Validate tokens from
+request headers, check expiry, verify signature with RS256, and enforce
+required claims (sub, iss, exp, iat).
+
+## Dependencies
+
+```
+┌─────────────────────────────────┐
+│   JWT Token Validation          │ ← THIS ISSUE
+│   (root component, no deps)     │
+└──────────────┬──────────────────┘
+               │
+               ▼
+┌─────────────────────────────────┐
+│   OAuth2 Provider Integration   │ ← ISSUE-002 (depends on this)
+└─────────────────────────────────┘
+```
+
+No internal dependencies. This is a root component.
+
+## In Scope
+
+- JWT token parsing and validation
+- RS256 signature verification with JWK rotation
+- Expiry and claim validation
+- Error handling for invalid/expired tokens
+- Unit tests for all validation paths
+- Integration tests with mock JWT provider
+
+## Out of Scope
+
+- Token generation (handled by upstream auth provider)
+- OAuth2 flow (handled by OAuth2 Provider Integration component)
+- Session storage (handled by Session Management component)
+- UI/login pages
+
+## Affected Layers
+
+### Domain
+- New: `JwtToken` entity
+- New: `TokenValidator` interface
+- New: `ValidationError` domain errors
+
+### Application
+- New: `ValidateToken` use case
+- New: `TokenValidationService`
+
+### Infrastructure
+- New: `JwkClient` for fetching public keys
+- New: Redis cache for JWK rotation
+
+### API
+- New: Auth middleware for token validation
+- Modified: Error response format for 401/403
+
+## Canonical References
+
+- **Module:** `.pi/architecture/modules/auth-system.md#jwt-token-validation`
+- **ADR-001:** `.pi/architecture/decisions/ADR-001-auth-pattern.md`
+- **ADR-003:** `.pi/architecture/decisions/ADR-003-jwt-algorithm.md`
+
+## Acceptance Criteria
+
+| # | Criterion | Validator |
+|---|-----------|-----------|
+| 1 | CI pipeline passes | `validate-ci.sh` |
+| 2 | All unit tests pass with ≥ 90% coverage | `validate-tests.sh` |
+| 3 | Integration tests pass against mock JWT provider | `validate-integration.sh` |
+| 4 | No hardcoded secrets, proper key handling | `validate-security.sh` |
+| 5 | Layer boundaries respected | `validate-architecture.sh` |
+| 6 | Implementation references architecture | `validate-canonical.sh` |
+
+## Implementation
+
+> **Agent:** Load this file as your complete session context. All information you need is above.
+> Start by reading the canonical reference files, then implement following the layer structure.
+
+### Steps
+
+1. Read canonical architecture references
+2. Create domain entities and interfaces
+3. Implement validation logic
+4. Add JWK client with caching
+5. Create auth middleware
+6. Write unit tests (≥ 90% coverage)
+7. Write integration tests
+8. Run all validators
+9. Create MR
+
+## Notes
+
+- Use PyJWT library for Python / jsonwebtoken for TypeScript
+- JWK cache TTL: 1 hour, refresh on signature failure
+- Required claims: sub, iss, exp, iat, aud
+- Reject tokens with exp < now() - 30s (clock skew tolerance)
+- Log validation failures at WARN level with token ID (not full token)
+- **Do NOT log token contents or secrets**