engsys 1.0.0

package/stacks/iac/terraform/skills/iac-terraform/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: iac-terraform
+description: Terraform discipline for any project where Terraform is the active IaC tool — modules, remote state, workspaces, backends, plan/apply gates, drift detection, and import/state surgery. Activate when working on *.tf / *.tfvars files, terraform plan/apply/state operations, backend or workspace config, provider versioning, or diagnosing drift and partial applies.
+---
+
+# Terraform Discipline
+
+The operational discipline for Terraform as the active IaC tool — cloud-independent.
+Service-level resource detail comes from the active `cloud-architecture-<cloud>` pack;
+project file layout and backend config come from `CLAUDE.md`. For repo-specific style
+(naming, ordering, security defaults) see the `terraform-conventions` skill if present.
+
+## Core stance
+
+- **Infrastructure is software.** If it only works once, it doesn't work. "Just apply it
+  again" is not a strategy — understand *why* it failed first.
+- **Plan is the contract.** Never `apply` without reading the `plan`. The plan is the
+  what-if; treat a surprising plan as a bug to investigate, not a step to skip.
+- **Pin everything.** Required Terraform version + provider versions in a lockfile
+  (`.terraform.lock.hcl`, committed). Unpinned providers are how "it worked yesterday"
+  happens.
+
+## State
+
+- **Remote state with locking, always.** Local state is a single point of failure and
+  blocks collaboration. Use a backend with locking (e.g. S3 + DynamoDB lock table, GCS,
+  azurerm with blob lease, or Terraform Cloud). Never commit state — it contains secrets.
+- **Separate state per major component / environment** — smaller blast radius, faster
+  plan/apply, and a failure in one doesn't lock the others. Check the project's
+  `backend.tf` / backend config before touching anything stateful.
+- **State surgery** when reality and state diverge:
+  - `terraform state list` — see what's tracked.
+  - `terraform import <addr> <id>` — adopt an existing resource.
+  - `terraform state mv` — rename/move without destroy+recreate.
+  - `terraform state rm` — stop tracking (does NOT delete the real resource).
+  - Always `plan` after surgery to confirm convergence. Back up state first.
+
+## Modules
+
+- **Modules for groups of related resources only.** Don't wrap a single resource in a
+  module — that's indirection without benefit.
+- Pin module sources to a version/ref. Expose interesting attributes via `output`; mark
+  sensitive ones `sensitive = true`.
+- Avoid deep nesting and circular dependencies. A module should have a clear, narrow
+  interface (typed `variable`s with `description`, validated where it matters).
+- Prefer composition (root config wires modules together) over monolithic mega-modules.
+
+## Workspaces & environments
+
+- Workspaces (`terraform workspace`) give you state isolation for *the same config across
+  environments* — useful, but they share the same backend key prefix and are easy to
+  misuse. For genuinely different environments, **separate backend keys / directories +
+  tfvars** is usually clearer and safer than relying on workspace interpolation.
+- Never let `dev` and `prod` share state. Parameterize via `*.tfvars` per environment;
+  keep secrets out of tfvars (use a secrets manager + data sources / env vars).
+
+## Plan / apply gates
+
+- **`terraform fmt` → `validate` → `plan` → review → `apply`** is the pipeline. In CI:
+  plan on PR (post the plan), apply only on merge to the protected branch, behind
+  approval for prod.
+- **Read the plan for destroys and replacements.** A `-/+` (replace) on a stateful
+  resource (database, disk, bucket) is a data-loss event — stop and confirm. Use
+  `lifecycle { prevent_destroy = true }` on the truly precious.
+- Keep infra applies separate from app deploys unless there's a very good reason not to.
+- `-target` is an escape hatch for recovering a broken apply, not a normal workflow —
+  it produces partial state. Note it when you use it.
+
+## Drift
+
+- **Detect drift before it bites:** `terraform plan` (or `plan -refresh-only`) on a
+  schedule shows out-of-band (click-ops) changes. A non-empty plan on an unchanged config
+  *is* drift.
+- Resolve drift deliberately: either bring the change into code (and apply), or revert
+  the manual change. Don't let an unexplained diff sit — it compounds.
+- **No click-ops in production**, ever. Manual changes create snowflake environments that
+  can't be recreated.
+
+## Troubleshooting
+
+- **Partial apply:** read which resources succeeded, reconcile state (import/refresh),
+  then re-plan. Don't blindly re-apply.
+- **API throttling:** tune `-parallelism`, add provider-level retries, back off.
+- **Provider auth / IAM:** trace the credential chain and the role/policy actually in
+  use; permission errors lie about the real missing action — read them for meaning.
+- **Lock held:** a crashed run can leave a stale lock; `force-unlock` only when you're
+  certain no apply is in flight.
+
+## Preflight
+
+Before applying, run the active cloud's `*-deployment-preflight` skill — it covers the
+cloud-specific concerns (stale/failed deployments, globally-unique naming, quota/SKU
+limits) that `terraform plan` alone won't surface.

package/stacks/iac/terraform/skills/terraform-conventions/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: terraform-conventions
+description: Terraform code conventions — security, modularity, maintainability, style, documentation, and testing expectations for any *.tf file. Activate when writing or reviewing Terraform configuration (typically under infra/terraform/ or the project's IaC directory) to enforce consistent structure and safe defaults.
+---
+
+# Terraform Conventions
+
+Applies to any `*.tf` file. Primary location is the project's IaC directory (commonly
+`infra/terraform/` — confirm in `CLAUDE.md`). These are code conventions; for the
+operational discipline (state, plan/apply gates, drift, imports) see the `iac-terraform`
+skill, and for service-level resource detail see the active `cloud-architecture-<cloud>`
+pack.
+
+## Security
+
+- Use the latest stable Terraform + provider versions; patch regularly. Pin versions and
+  commit `.terraform.lock.hcl`.
+- **Secrets never in state files, variables, or version control.** Store them in the
+  cloud's secret manager (AWS Secrets Manager / SSM, Azure Key Vault, GCP Secret Manager)
+  and reference them via data sources or environment variables. Rotate; automate rotation
+  where possible.
+- Mark any sensitive variable/output `sensitive = true`.
+- Least-privilege IAM/roles. Restrict network access with the cloud's native controls
+  (security groups + NACLs, NSGs, firewall rules).
+- Resources in private subnets/networks by default; public only for load balancers / NAT
+  / similar entry points.
+- Encryption at rest (disks, object storage, managed databases) and in transit (TLS).
+- Scan with `trivy`, `tfsec`, or `checkov` in CI.
+
+## Modularity
+
+- Separate state/projects for major components — reduces blast radius, speeds up
+  plan/apply.
+- Modules for groups of related resources only. Don't wrap a single resource in a module.
+- Avoid deep nesting and circular dependencies.
+- Expose interesting attributes via `output`; mark sensitive ones.
+
+## Maintainability
+
+- Prefer readable, explicit configs over clever ones.
+- Variables (with sensible defaults where appropriate) instead of hard-coded values.
+- Data sources for *existing* external resources; outputs for in-config references.
+- `locals` for repeated values to enforce consistency.
+- Avoid stale/unnecessary data sources — they slow plan/apply.
+
+## Style
+
+- 2-space indents. Run `terraform fmt`, `terraform validate`, `tflint`.
+- File naming by resource grouping (`providers.tf`, `variables.tf`, `network.tf`,
+  `outputs.tf`, etc.).
+- Alphabetize providers, variables, data sources, resources, and outputs.
+- Order within a resource: `depends_on` → `for_each`/`count` → attributes (required, then
+  optional) → `lifecycle`.
+- Use `for_each` for collections; `count` for numeric iteration.
+- Blank lines to separate logical sections.
+
+## Documentation
+
+- `description` + `type` on every variable and output.
+- Comment intent and non-obvious decisions, not the obvious.
+- `README.md` per project; consider `terraform-docs` for generated module docs.
+
+## Testing
+
+- Use `.tftest.hcl` for tests.
+- Cover positive and negative scenarios.
+- Tests must be idempotent.
+
+## This repo's stack
+
+- The active cloud, services, and IaC directory are declared in `CLAUDE.md`; the
+  `cloud-architecture-<cloud>` pack carries the service-level detail.
+- Check the backend config (`backend.tf` or equivalent) before changing anything
+  stateful.
+
+## Hard-won lessons
+
+### Span two control planes? Use a multi-provider tool so one apply wires both sides
+**Symptom:** Infrastructure crosses a cloud *and* a managed SaaS (e.g. Azure +
+MongoDB Atlas, where a Private Endpoint requires resources on **both** the Atlas
+Private Link service and the Azure side, cross-referenced).
+**Cause:** Single-cloud IaC (Bicep, CDK, raw ARM) can only manage its own cloud — it
+structurally cannot touch the SaaS half, so that half drops back to console clicks or
+a second tool, breaking "everything repeatable" for the exact resources that matter.
+**Fix:** Choose **Terraform** (multi-provider — e.g. `azurerm` + `mongodbatlas` in
+one graph) so a single `terraform apply` wires both sides of the integration. Adopt
+pre-existing/shared resources as data sources or `terraform import`; don't recreate.

package/stacks/lang/kotlin/skills/android-testing/SKILL.md

@@ -0,0 +1,263 @@
+---
+name: android-testing
+description: "Write and review Android/Kotlin tests across the pyramid: JUnit (4/5) unit tests, MockK, Turbine for Flow/StateFlow assertions, coroutine testing with runTest and test dispatchers, Robolectric JVM tests, Espresso instrumented UI tests, and Compose UI testing with createComposeRule and semantics matchers. Use when writing or fixing unit tests, testing coroutines/Flows, mocking dependencies, choosing JVM vs instrumented tests, or testing Compose UI and ViewModels on Android."
+---
+
+# Android Testing
+
+Write and review tests for Android/Kotlin targeting JUnit, MockK, Turbine,
+kotlinx-coroutines-test, Robolectric, Espresso, and Compose UI testing. Favor a
+test pyramid: many fast JVM unit tests, fewer Robolectric/Compose tests, and a
+thin layer of instrumented end-to-end tests. Test behavior, not implementation.
+
+## Contents
+
+- [Test Pyramid and Source Sets](#test-pyramid-and-source-sets)
+- [Unit Tests (JUnit)](#unit-tests-junit)
+- [Mocking with MockK](#mocking-with-mockk)
+- [Testing Coroutines](#testing-coroutines)
+- [Testing Flows with Turbine](#testing-flows-with-turbine)
+- [Testing ViewModels](#testing-viewmodels)
+- [Robolectric](#robolectric)
+- [Compose UI Testing](#compose-ui-testing)
+- [Espresso](#espresso)
+- [Common Mistakes](#common-mistakes)
+- [Review Checklist](#review-checklist)
+
+## Test Pyramid and Source Sets
+
+| Location | Runs on | Use for |
+|---|---|---|
+| `src/test/` | Local JVM (`testDebugUnitTest`) | Logic, ViewModels, repos, mappers, Robolectric |
+| `src/androidTest/` | Device/emulator (`connectedDebugAndroidTest`) | Espresso, Compose UI, integration |
+
+Keep most tests in `src/test/` — they are fast and run in the unit-test gate.
+Reserve `src/androidTest/` for tests that genuinely need a device/emulator.
+
+## Unit Tests (JUnit)
+
+JUnit 4 is still the Android default; JUnit 5 is fine for pure-JVM modules with
+the platform engine configured. Name tests by behavior.
+
+```kotlin
+class PriceFormatterTest {
+    @Test
+    fun `formats whole dollars without decimals`() {
+        assertEquals("$5", PriceFormatter.format(500))
+    }
+}
+```
+
+Prefer a fluent assertion library (Truth or AssertK) for readable failures:
+
+```kotlin
+assertThat(result).isEqualTo(expected)
+assertThat(items).containsExactly(a, b).inOrder()
+```
+
+## Mocking with MockK
+
+MockK is the idiomatic Kotlin mocking library (handles final classes, coroutines,
+and relaxed mocks). Prefer fakes for owned interfaces; use mocks for verifying
+interactions or stubbing boundaries.
+
+```kotlin
+@Test
+fun `loads profile from repo`() = runTest {
+    val repo = mockk<ProfileRepository>()
+    coEvery { repo.profile(42) } returns Profile(name = "Ada")
+
+    val result = ProfileService(repo).load(42)
+
+    assertThat(result.name).isEqualTo("Ada")
+    coVerify(exactly = 1) { repo.profile(42) }
+}
+```
+
+- Use `coEvery`/`coVerify` for suspend functions.
+- Use `relaxed = true` to auto-stub return values you don't care about.
+- Prefer hand-written **fakes** over mocks for repositories/data sources you own —
+  they're more robust and document behavior.
+
+## Testing Coroutines
+
+Use `kotlinx-coroutines-test`. `runTest` provides a `TestScope` with a virtual
+clock that auto-advances through `delay`.
+
+```kotlin
+@Test
+fun `retries after delay`() = runTest {
+    val result = withTimeout(1.seconds) { service.fetchWithRetry() }
+    assertThat(result).isNotNull()
+    // delay(30_000) inside fetchWithRetry is skipped — virtual time
+}
+```
+
+- Inject dispatchers so tests can substitute a test dispatcher. Provide a
+  `MainDispatcherRule` to swap `Dispatchers.Main` (needed for `viewModelScope`):
+
+```kotlin
+class MainDispatcherRule(
+    private val dispatcher: TestDispatcher = StandardTestDispatcher(),
+) : TestWatcher() {
+    override fun starting(d: Description) = Dispatchers.setMain(dispatcher)
+    override fun finished(d: Description) = Dispatchers.resetMain()
+}
+```
+
+- `StandardTestDispatcher` queues coroutines — call `advanceUntilIdle()` /
+  `runCurrent()` to run them. `UnconfinedTestDispatcher` runs eagerly — handy for
+  simple cases but order-sensitive.
+- Never use `Thread.sleep` or real `delay` waits in tests.
+
+## Testing Flows with Turbine
+
+Turbine makes Flow assertions deterministic without manual collection
+boilerplate. Use it for `Flow`, `StateFlow`, and `SharedFlow`.
+
+```kotlin
+@Test
+fun `emits loading then loaded`() = runTest {
+    viewModel.uiState.test {
+        assertThat(awaitItem()).isEqualTo(UiState.Loading)
+        viewModel.load()
+        assertThat(awaitItem()).isInstanceOf(UiState.Loaded::class.java)
+        cancelAndIgnoreRemainingEvents()
+    }
+}
+```
+
+- `awaitItem()` suspends for the next emission; `awaitError()` / `awaitComplete()`
+  for terminal events.
+- For `StateFlow`, the first `awaitItem()` is the current value; call
+  `cancelAndIgnoreRemainingEvents()` (or `expectMostRecentItem()`) to finish.
+- `test {}` fails if unconsumed events remain — this catches unexpected emissions.
+
+## Testing ViewModels
+
+Combine the `MainDispatcherRule`, `runTest`, fakes, and Turbine:
+
+```kotlin
+class FeedViewModelTest {
+    @get:Rule val mainDispatcherRule = MainDispatcherRule()
+
+    @Test
+    fun `shows error when repo throws`() = runTest {
+        val repo = FakeFeedRepository(throws = IOException())
+        val vm = FeedViewModel(repo)
+
+        vm.state.test {
+            assertThat(awaitItem()).isEqualTo(FeedUiState.Loading)
+            assertThat(awaitItem()).isInstanceOf(FeedUiState.Error::class.java)
+            cancelAndIgnoreRemainingEvents()
+        }
+    }
+}
+```
+
+## Robolectric
+
+Robolectric runs Android-framework-dependent code on the JVM (no emulator), so
+it stays in `src/test/`. Use it when a unit test needs `Context`, resources,
+`SharedPreferences`, or Android components — but the logic doesn't need a real
+device.
+
+```kotlin
+@RunWith(RobolectricTestRunner::class)
+class ResourceTest {
+    @Test
+    fun `reads string resource`() {
+        val context = ApplicationProvider.getApplicationContext<Context>()
+        assertThat(context.getString(R.string.app_name)).isEqualTo("Demo")
+    }
+}
+```
+
+Prefer pure unit tests where possible; reach for Robolectric only when framework
+types are genuinely involved. It is slower than plain JVM tests but far faster
+than instrumented ones.
+
+## Compose UI Testing
+
+Use `createComposeRule()` (no Activity) or `createAndroidComposeRule<Activity>()`.
+These can run as Robolectric tests in `src/test/` or instrumented in
+`src/androidTest/`. Query by **semantics**, and add `Modifier.testTag` /
+content descriptions for stable selectors.
+
+```kotlin
+class CounterTest {
+    @get:Rule val composeRule = createComposeRule()
+
+    @Test
+    fun increments_on_click() {
+        composeRule.setContent { Counter() }
+
+        composeRule.onNodeWithText("Count: 0").assertIsDisplayed()
+        composeRule.onNodeWithTag("increment").performClick()
+        composeRule.onNodeWithText("Count: 1").assertExists()
+    }
+}
+```
+
+- Compose tests synchronize automatically with the runtime; avoid arbitrary
+  waits. For non-Compose async, use `composeRule.waitUntil { ... }`.
+- Use `onNodeWithTag`/`onNodeWithContentDescription` for robust, localized-text-
+  independent selectors.
+- Disable indeterminate animations or use `mainClock.autoAdvance = false` to
+  control time when asserting animated states.
+
+## Espresso
+
+Espresso drives real instrumented UI tests (`src/androidTest/`, runs on an
+emulator/device). Use for end-to-end flows and legacy View-based screens.
+
+```kotlin
+@RunWith(AndroidJUnit4::class)
+class LoginFlowTest {
+    @get:Rule val activityRule = ActivityScenarioRule(LoginActivity::class.java)
+
+    @Test
+    fun successful_login_navigates_home() {
+        onView(withId(R.id.email)).perform(typeText("a@b.com"))
+        onView(withId(R.id.submit)).perform(click())
+        onView(withId(R.id.home)).check(matches(isDisplayed()))
+    }
+}
+```
+
+- Idle synchronization is automatic for the main thread; register an
+  `IdlingResource` for custom async work.
+- Keep Espresso tests few — they are slow and flaky-prone. Push coverage down to
+  unit/Compose tests.
+
+## Common Mistakes
+
+1. **`Thread.sleep`/real delays in tests** — use `runTest` virtual time and
+   Turbine/`waitUntil`.
+2. **No `MainDispatcherRule`** when testing `viewModelScope` — `Dispatchers.Main`
+   isn't available on the JVM and the test fails or hangs.
+3. **Hardcoded dispatchers** in production code — can't substitute test
+   dispatchers; inject them.
+4. **Manual Flow collection** in tests — use Turbine for determinism.
+5. **Over-mocking owned types** — prefer fakes; mocks couple tests to call order.
+6. **Putting everything in `androidTest`** — slow; most tests belong in `test/`.
+7. **Asserting on localized text** in UI tests — use `testTag`/content
+   descriptions.
+8. **Testing implementation details** — assert observable behavior/state.
+9. **Leaking `Dispatchers.setMain`** — always `resetMain()` (the rule handles it).
+10. **Ignoring Turbine unconsumed-event failures** — they reveal real bugs;
+    don't blanket-`cancelAndIgnore` without checking.
+
+## Review Checklist
+
+- [ ] Most tests are fast JVM unit tests in `src/test/`
+- [ ] Coroutine tests use `runTest`; no real sleeps/delays
+- [ ] `MainDispatcherRule` present for ViewModel/`viewModelScope` tests
+- [ ] Dispatchers injected for testability
+- [ ] Flow assertions use Turbine (`awaitItem`/`awaitError`)
+- [ ] Fakes preferred over mocks for owned dependencies; MockK for boundaries
+- [ ] Robolectric used only when Android framework types are needed
+- [ ] Compose tests query by semantics/`testTag`, not localized text
+- [ ] Espresso reserved for true end-to-end instrumented flows
+- [ ] Tests assert behavior, not implementation
+- [ ] Error/cancellation paths covered, not just the happy path