Bmad epic 6 (#321)

* Create Epic 6 story files and update sprint status

Add story files for all four Epic 6 stories (Identity & Audit
integration tests) and transition epic to in-progress with all
stories at ready-for-dev status.

Co-authored-by: Cursor <cursoragent@cursor.com>

* Add integration tests for Group and GroupAlias types (Story 6.1)

Covers create, update, and delete with full Vault state verification
for both Group (identity groups) and GroupAlias (asymmetric API with
PrepareInternalValues accessor lookup). Includes exact policy list
assertions and mount_accessor cross-verification against sys/auth.

Co-authored-by: Cursor <cursoragent@cursor.com>

* Add integration tests for Identity OIDC types (Story 6.2)

Integration tests covering IdentityOIDCScope, IdentityOIDCAssignment,
IdentityOIDCClient, and IdentityOIDCProvider full lifecycle (create,
update, delete) with Vault state verification. Includes 4 decoder
methods, 4 controller registrations, and review-driven assertions for
redirect_uris, assignments, and allowed_client_ids.

Co-authored-by: Cursor <cursoragent@cursor.com>

* Add integration tests for Identity Token types (Story 6.3)

Co-authored-by: Cursor <cursoragent@cursor.com>

* Add integration tests for Audit and AuditRequestHeader types (Story 6.4)

Co-authored-by: Cursor <cursoragent@cursor.com>

* Add Epic 6 retrospective and Story 7.0 test performance refactoring task

Epic 6 retro completed — short epic with clean code reviews.
Story 7.0 added as warm-up task for Epic 7 to refactor RandomSecret
integration tests to share fixtures via BeforeAll/AfterAll, eliminating
~100-150s of redundant setup/teardown across 4 Context blocks.

Co-authored-by: Cursor <cursoragent@cursor.com>

---------

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: raffaelespazzoli

_bmad-output/implementation-artifacts/6-1-integration-tests-for-group-and-groupalias-types.md

@@ -0,0 +1,110 @@
+# Story 7.0: Refactor RandomSecret Test to Use Shared Fixtures
+
+Status: backlog
+
+## Story
+
+As an operator developer,
+I want the RandomSecret integration tests to share prerequisite resources across Context blocks using Ginkgo BeforeAll/AfterAll,
+So that redundant setup/teardown is eliminated and the integration test suite runs significantly faster.
+
+## Background / Motivation
+
+Performance profiling of the integration test suite (Epic 6 retrospective, 2026-05-02) identified RandomSecret and VaultSecret tests as the biggest time outliers — consuming ~31% of total test time despite not integrating with any external tools (no PostgreSQL, RabbitMQ, LDAP, etc.).
+
+Root cause analysis revealed that the slowness is **structural**: each of the 4 `Context` blocks in `randomsecret_controller_test.go` independently creates and tears down the same 6 prerequisite resources (PasswordPolicy, 2 Policies, 2 KubernetesAuthEngineRoles, SecretEngineMount), each requiring its own `Eventually` polling loop (2-second interval, typically 2-6 seconds per poll). This results in ~12 redundant `Eventually` round-trips × 3 extra copies = ~100-150 seconds of wasted time.
+
+### Current test structure (problematic)
+
+```
+Describe("Random Secret controller for v2 secrets")
+  Context("retain policy")           → creates 6-8 prereqs, tests, tears down all
+  Context("multi-key")               → creates 6 prereqs (same), tests, tears down all
+  Context("multi-key-recreate")      → creates 6 prereqs (same), tests, tears down all
+  Context("refreshPeriod")           → creates 6 prereqs (same), tests, tears down all
+```
+
+### Target test structure
+
+```
+Describe("Random Secret controller for v2 secrets")
+  BeforeAll → creates shared prereqs once
+  AfterAll  → tears down shared prereqs once
+  Context("retain policy")           → creates only test-specific resources
+  Context("multi-key")               → creates only test-specific resources
+  Context("multi-key-recreate")      → creates only test-specific resources
+  Context("refreshPeriod")           → creates only test-specific resources
+```
+
+## Scope
+
+| File | Change | Impact |
+|------|--------|--------|
+| `controllers/randomsecret_controller_test.go` (1717 lines) | Major refactor — lift shared prereqs to BeforeAll/AfterAll | Primary target |
+| `controllers/vaultsecret_controller_test.go` (679 lines) | No change — single Context, nothing to deduplicate | Out of scope |
+| `controllers/vaultsecret_controller_v2_test.go` (491 lines) | No change — single Context, nothing to deduplicate | Out of scope |
+
+Cross-file fixture sharing (between RandomSecret and VaultSecret v2 tests) is explicitly out of scope — it would require deeper structural changes for marginal gain.
+
+## Acceptance Criteria
+
+1. **Given** the refactored `randomsecret_controller_test.go` **When** the full integration test suite runs **Then** all existing RandomSecret tests pass with identical assertions and behavior.
+
+2. **Given** shared prerequisites (PasswordPolicy, Policies, KubernetesAuthEngineRoles, SecretEngineMount) **When** the Describe block starts **Then** they are created exactly once in BeforeAll and torn down exactly once in AfterAll.
+
+3. **Given** Context 1 (retain) needs extra resources (secret-reader policy + role for VaultSecret reading) **When** that Context runs **Then** the extra resources are created/destroyed within that Context's BeforeAll/AfterAll or inline, not in the shared set.
+
+4. **Given** all 4 Context blocks **When** they execute sequentially **Then** there is no cross-Context state leakage — each Context's test-specific resources (RandomSecret, VaultSecret) are fully self-contained.
+
+5. **Given** the refactored suite **When** compared to the pre-refactor run **Then** the RandomSecret test group duration decreases by at least 40%.
+
+## Tasks / Subtasks
+
+- [ ] Task 1: Identify shared prerequisites
+  - [ ] 1.1: Catalog which YAML fixtures are identical across all 4 Context blocks
+  - [ ] 1.2: Identify Context-1-only extras (secret-reader policy + KubernetesAuthEngineRole)
+
+- [ ] Task 2: Refactor to BeforeAll/AfterAll
+  - [ ] 2.1: Add `BeforeAll` at `Describe` level — create shared PasswordPolicy, Policies, KubernetesAuthEngineRoles, SecretEngineMount with their `Eventually` blocks
+  - [ ] 2.2: Add `AfterAll` at `Describe` level — delete shared resources with their `Eventually` blocks
+  - [ ] 2.3: Remove duplicated setup/teardown from each of the 4 `It` blocks
+  - [ ] 2.4: For Context 1, keep the extra secret-reader resources scoped to that Context
+
+- [ ] Task 3: Verify isolation
+  - [ ] 3.1: Ensure each Context's test-specific resources (RandomSecret instances, VaultSecret instances) use unique names and don't collide
+  - [ ] 3.2: Verify the SecretEngineMount and its KV path remain available across all Contexts
+
+- [ ] Task 4: End-to-end verification
+  - [ ] 4.1: Run `make integration` and verify all tests pass (RandomSecret + all others)
+  - [ ] 4.2: Compare before/after timing from Ginkgo JSON report to confirm improvement
+
+## Dev Notes
+
+### Ginkgo BeforeAll/AfterAll semantics
+
+Ginkgo v2 `BeforeAll` runs once before the first spec in a container (Describe/Context). If it fails, all specs in that container are skipped. This is the desired behavior — if shared infrastructure can't be created, there's no point running any of the tests.
+
+Variables created in `BeforeAll` must be declared at the container scope (before the `BeforeAll` block) so they're accessible in the `It` blocks.
+
+### The refreshPeriod test's ~20-second wait is inherent
+
+The `refreshPeriod` Context (Context 4) uses `11-randomsecret-refresh-v2.yaml` with `refreshPeriod: 15s`, plus a 5-second `Consistently` check. This ~20-second wait is testing real timer behavior and cannot be optimized away. The savings from this refactoring come from eliminating the ~4× duplicated infrastructure setup, not from changing test logic.
+
+### Shared fixture catalog
+
+| Resource | YAML path | Used by |
+|----------|-----------|---------|
+| PasswordPolicy | `test/randomsecret/v2/00-passwordpolicy-simple-password-policy-v2.yaml` | All 4 Contexts |
+| Policy (kv-engine-admin) | `test/randomsecret/v2/01-policy-kv-engine-admin-v2.yaml` | All 4 Contexts |
+| Policy (secret-writer) | `test/randomsecret/v2/04-policy-secret-writer-v2.yaml` | All 4 Contexts |
+| Policy (secret-reader) | `test/vaultsecret/v2/00-policy-secret-reader-v2.yaml` | Context 1 only |
+| KubernetesAuthEngineRole (kv-engine-admin) | `test/randomsecret/v2/02-kubernetesauthenginerole-kv-engine-admin-v2.yaml` | All 4 Contexts |
+| KubernetesAuthEngineRole (secret-writer) | `test/randomsecret/v2/05-kubernetesauthenginerole-secret-writer-v2.yaml` | All 4 Contexts |
+| KubernetesAuthEngineRole (secret-reader) | `test/vaultsecret/v2/00-kubernetesauthenginerole-secret-reader-v2.yaml` | Context 1 only |
+| SecretEngineMount | `test/randomsecret/v2/03-secretenginemount-kv-v2.yaml` | All 4 Contexts |
+
+### Estimated time savings
+
+- Current: ~4 × (6 prereq creates + 6 prereq deletes) × ~3-4s each = ~150-200s in prereq overhead
+- After: 1 × (6 prereq creates + 6 prereq deletes) × ~3-4s each = ~40-50s in prereq overhead
+- **Net savings: ~100-150 seconds** (~40-60% of total RandomSecret test time)

_bmad-output/implementation-artifacts/6-2-integration-tests-for-identity-oidc-types.md

@@ -0,0 +1,169 @@
+# Epic 6 Retrospective — Identity & Audit Integration Tests
+
+**Date:** 2026-05-02
+**Facilitator:** Bob (Scrum Master)
+**Participants:** Raffa (Project Lead), Alice (Product Owner), Charlie (Senior Dev), Dana (QA Engineer), Amelia (Developer Agent)
+
+---
+
+## Epic Summary
+
+| Metric | Value |
+|--------|-------|
+| Epic | 6: Identity & Audit Integration Tests |
+| Stories | 4 of 4 completed (100%) |
+| Duration | ~3 days (April 30 – May 2, 2026) |
+| Scope | Integration tests for 11 types across 4 families |
+| Types tested | Group, GroupAlias, IdentityOIDCScope/Assignment/Client/Provider, IdentityTokenConfig/Key/Role, Audit, AuditRequestHeader |
+| Infrastructure added | None (all Tier 1) |
+| Debug failures | 1 total (Story 6.4 — AuditRequestHeader delete returns HTTP 400 not nil) |
+| Code review findings | 4 total (2 in Story 6.2, 2 in Story 6.4) — all patches |
+| Production code fixes | 0 |
+| Regressions | 0 |
+| Coverage delta | 46.0% → 53.7% (+7.7 pp) |
+| Integration test specs | 63 → 83+ (20+ new specs) |
+
+### AI Models Used
+
+| Story | Model |
+|-------|-------|
+| 6.1 — Group/GroupAlias | Claude Opus 4.6 (Cursor) |
+| 6.2 — IdentityOIDC (4 types) | Claude Opus 4.6 (Cursor) |
+| 6.3 — IdentityToken (3 types) | Claude Opus 4 |
+| 6.4 — Audit/AuditRequestHeader | Claude Opus 4.6 |
+
+---
+
+## Epic 5 Retrospective Follow-Through
+
+| Action Item | Status |
+|-------------|--------|
+| ObservedGeneration baseline assertion guidance | ✅ Applied — All 4 stories recorded baseline before update, asserted strictly greater after. Zero code review intervention needed. |
+| Document write-only Vault endpoints when discovered | N/A — No write-only endpoints encountered in Epic 6 |
+| PKI `CreateOrUpdateConfig` dual bug (carried from Epic 2) | ❌ Still in Epic 7 backlog — confirmed non-blocking |
+| AC#4 extra-field handling → Story 7-4 (carried from Epic 1) | ⏳ Still in backlog — scope continues to grow |
+| Story 4.2 `omitempty` workaround revert | ⏳ Epic 7.5 backlog |
+| Continue Opus-class models | ✅ All stories used Opus 4/4.6 |
+| Continue code review process | ✅ Reviews ran on all 4 stories, caught 4 findings |
+| Three-tier infrastructure classification | ✅ All 11 types correctly classified as Tier 1 |
+| Story ordering by complexity/dependency | ✅ Followed Epic 5 retro's suggested ordering exactly: 6.1 → 6.2 → 6.3 → 6.4 |
+
+Completed 5/9, N/A 1/9, in-progress 2/9, not addressed 1/9.
+
+---
+
+## Successes
+
+1. **Cleanest epic to date.** Only 1 debug failure and 4 review findings across 4 stories covering 11 types. This is the lowest issue rate of any epic.
+
+2. **Largest single-epic coverage gain.** 7.7 percentage points (46.0% → 53.7%) — exceeding Epic 5's 4.0 pp gain. Combined with Epic 5, the two epics gained nearly 12 points.
+
+3. **Zero infrastructure setup.** All 11 types were Tier 1 (Vault internal APIs). No Helm charts, no service deployments, no external dependency debugging. This is the primary reason for the fast execution.
+
+4. **Story spec maturity payoff.** Detailed dev notes — Vault API response shapes, checked type assertion reminders, dependency chain ordering, delete verification patterns — gave dev agents nearly everything they needed. This directly caused the drop from 8 review findings (Epic 5) to 4 (Epic 6).
+
+5. **ObservedGeneration guidance fully embedded.** The Epic 5 retro action item worked perfectly — all 4 stories used baseline assertions without code review intervention. This action item can be retired.
+
+6. **Third reconciler variant tested.** Story 6.4's Audit type uses `VaultAuditResource` — the third and final reconciler variant. All three variants (VaultResource, VaultEngineResource, VaultAuditResource) now have integration test coverage.
+
+7. **GroupAlias PrepareInternalValues worked first try.** The most complex type in Epic 6 (accessor lookup + group canonical_id resolution + conditional alias creation) had zero debug failures.
+
+---
+
+## Challenges
+
+1. **AuditRequestHeader delete returns HTTP 400 (Story 6.4).** Vault returns HTTP 400 (not nil or 404) for non-existent request headers. This was the only debug failure in the epic — a genuine Vault API inconsistency rather than a test design issue. Resolved by accepting the expected `vault.ResponseError` status codes in the delete verification.
+
+2. **Missing assertions in Story 6.2 review.** Client create test didn't assert `redirect_uris` or `assignments`; Provider create test didn't assert `allowed_client_ids`. Minor completeness gaps caught in review and patched.
+
+---
+
+## Key Insights
+
+1. **Preparation quality compounds.** Epic 6's smooth execution is a direct result of improvements made in Epics 4 and 5 retros: tier classification, story ordering, ObservedGeneration guidance, detailed dev notes. Each retro's improvements reduce the next epic's friction.
+
+2. **Zero-infrastructure epics execute dramatically faster.** Epic 6 (0 infrastructure, 11 types, 3 days) vs Epic 5 (1 new infrastructure, 6 types, 2 days) vs Epic 4 (3 new infrastructure, 6 types, 1 day but compressed). Infrastructure setup is the dominant variable in execution speed.
+
+3. **Review finding rate is a quality indicator for story specs, not dev agents.** The drop from 8 to 4 findings correlates with story spec detail level, not model choice. Both Opus 4 and 4.6 produced clean results when given sufficient context.
+
+---
+
+## Action Items
+
+### Process Improvements
+
+1. **Continue detailed dev notes in story specs**
+   - Owner: Bob (Scrum Master)
+   - Description: Maintain Vault API response shapes, delete verification patterns, and dependency chains in story specs. This is the primary driver behind review finding reduction.
+   - Success criteria: Epic 7 story specs maintain or exceed Epic 6 detail level
+
+### Technical Debt (Carried)
+
+2. **PKI `CreateOrUpdateConfig` dual bug** (CARRIED from Epic 2)
+   - Owner: Epic 7
+   - Priority: Medium — confirmed non-blocking through Epic 6
+
+3. **AC#4 extra-field handling → Story 7-4** (CARRIED from Epic 1)
+   - Owner: Epic 7, Story 7.4
+   - Priority: High — primary target of Epic 7
+
+4. **Story 4.2 `omitempty` workaround revert**
+   - Owner: Epic 7.5, Story 7.5.1
+   - Status: Properly tracked
+
+### Dismissed
+
+5. ~~ObservedGeneration baseline assertion tracking~~ — Fully embedded in practice. All 4 Epic 6 stories applied it without intervention. No longer needs explicit tracking.
+
+### Team Agreements
+
+- Continue using Opus-class models — validated across 19 consecutive stories (Epics 2–6)
+- Continue the code review process — trend is positive (8 → 4 findings)
+- Three-tier infrastructure classification is standard practice
+- Story ordering by complexity/dependency remains effective
+
+---
+
+## Epic 7 Preparation
+
+### Dependencies on Epic 6
+
+None. Epic 7 shifts domain from "add integration test coverage" to "hardening" (webhooks, error paths, credential resolution, extra-field audit).
+
+### Infrastructure Requirements
+
+None for Stories 7.1–7.3. Story 7.4 may need mock Vault API responses for Tier 3 types (cloud providers) that cannot be tested against a live service.
+
+### Suggested Story Ordering
+
+| Order | Story | Scope | Complexity |
+|-------|-------|-------|------------|
+| 1 | 7.1 | Webhook `ValidateUpdate` immutable path tests | Low — unit tests, table-driven |
+| 2 | 7.2 | `PrepareInternalValues` unit tests (15 types) | Medium — mock-based, wide scope |
+| 3 | 7.3 | Error path integration tests | Medium — invalid auth, unreachable Vault |
+| 4 | 7.4 | Audit Vault API responses + harden `IsEquivalentToDesiredState` (46 types) | High — 3-phase, large scope |
+| 5 | 7.5 | Drift detection integration tests | Medium — depends on 7.4 |
+
+### New Patterns to Watch
+
+- **Unit tests (7.1, 7.2):** First stories focused on pure unit tests rather than integration tests
+- **Error path testing (7.3):** Testing failure conditions rather than happy paths
+- **Multi-phase audit (7.4):** Audit → Fix → Test across 46 types — largest single story scope to date
+- **Story 7.4 scope risk:** May need to be broken into sub-stories during story creation
+
+### Readiness Assessment
+
+- Testing & Quality: All 83+ specs passing, coverage at 53.7%
+- Technical Health: Codebase stable, zero regressions across 6 epics
+- Infrastructure: None needed for initial stories
+- Unresolved Blockers: None
+
+### Verdict
+
+**Ready to proceed with Epic 7.** No prep work needed. Story ordering: 7.1 → 7.2 → 7.3 → 7.4 → 7.5. Monitor Story 7.4 scope during story creation.
+
+---
+
+## Team Performance
+
+Epic 6 delivered 4 stories covering integration tests for 11 identity and audit types (Group, GroupAlias, IdentityOIDCScope/Assignment/Client/Provider, IdentityTokenConfig/Key/Role, Audit, AuditRequestHeader) in ~3 days — the cleanest epic to date with only 1 debug failure and 4 review findings. All types were Tier 1 (no infrastructure), enabling the fastest per-type execution rate. Coverage grew 7.7 percentage points (46.0% → 53.7%), the largest single-epic gain. All three reconciler variants (VaultResource, VaultEngineResource, VaultAuditResource) now have integration test coverage. The team is well-positioned for Epic 7's shift to hardening work.

_bmad-output/implementation-artifacts/6-3-integration-tests-for-identity-token-types.md

@@ -35,7 +35,22 @@
 # - Dev moves story to 'review', then runs code-review (fresh context, different LLM recommended)
 
 generated: 2026-04-11
-last_updated: 2026-04-29
+last_updated: 2026-05-02
+# Epic 6 done + retrospective completed 2026-05-02
+# Story 6.4 done 2026-05-02
+# Story 6.4 review 2026-05-02
+# Story 6.4 in-progress 2026-05-02
+# Story 6.3 done 2026-05-02
+# Story 6.3 review 2026-05-02
+# Story 6.2 done 2026-05-01
+# Story 6.2 review 2026-05-01
+# Story 6.1 done 2026-05-01
+# Story 6.1 review 2026-05-01
+# Story 6.4 ready-for-dev 2026-05-01
+# Story 6.3 ready-for-dev 2026-04-30
+# Story 6.2 ready-for-dev 2026-04-30
+# Story 6.1 ready-for-dev 2026-04-30
+# Epic 6 in-progress 2026-04-30
 # Epic 5 done + retrospective completed 2026-04-29
 # Story 5.3 done 2026-04-29
 # Story 5.3 review 2026-04-29
@@ -138,15 +153,16 @@ development_status:
   epic-5-retrospective: done
 
   # Epic 6: Identity & Audit Integration Tests
-  epic-6: backlog
-  6-1-integration-tests-for-group-and-groupalias-types: backlog
-  6-2-integration-tests-for-identity-oidc-types: backlog
-  6-3-integration-tests-for-identity-token-types: backlog
-  6-4-integration-tests-for-audit-types: backlog
-  epic-6-retrospective: optional
+  epic-6: done
+  6-1-integration-tests-for-group-and-groupalias-types: done
+  6-2-integration-tests-for-identity-oidc-types: done
+  6-3-integration-tests-for-identity-token-types: done
+  6-4-integration-tests-for-audit-types: done
+  epic-6-retrospective: done
 
   # Epic 7: Hardening — Webhooks, Error Paths & Credential Resolution
   epic-7: backlog
+  7-0-refactor-randomsecret-test-shared-fixtures: backlog
   7-1-webhook-validation-tests-for-immutable-spec-path-rule: backlog
   7-2-unit-tests-for-prepareinternalvalues-credential-resolution: backlog
   7-3-error-path-integration-tests: backlog