resolve(all): answer Q02/Q03/Q06/Q07/Q12 with GLM-5.2+Lumen+DevOps lens

All 18 open questions now DECIDED. Key decisions: - Q02: MS Entra → v0.2 (extraction discipline holds even with AI ease) - Q03: Separate Flyway table ✅ (already implemented) - Q06: Wire-version constant WIRE_VERSION=1 in envelope (implement W8/W9) - Q07: Full Gitea Actions CI/CD (ci+release+Snyk+Renovate, test in W12) - Q12: DB rows only v0.1, LoginEventSink SPI v0.2 Zero open questions remaining.
2026-06-24 21:32:30 +02:00
parent 16e09f12dc
commit ae25f07225
1 changed files with 35 additions and 10 deletions
@@ -29,17 +29,17 @@ When a question is decided, this doc gets updated; the decision is also reflecte
 | ID | Topic | Status | Decide by |
 |----|-------|--------|-----------|
 | Q01 | Concrete org table abstraction (Company → generic Organization?) | ✅ Decided (2026-06-24) | n/a |
-| Q02 | Microsoft Entra ID in v0.1 or defer to v0.2 | 🟡 Leaning | Before W2 starts |
+| Q02 | Microsoft Entra ID in v0.1 or defer to v0.2 | ✅ Decided (2026-06-24) — **Defer to v0.2** | n/a |
-| Q03 | Flyway migration strategy (separate schema_history vs baseline reset) | 🟡 Leaning | Before W5 (Flyway work) |
+| Q03 | Flyway migration strategy (separate schema_history vs baseline reset) | ✅ Decided (2026-06-24) — **Separate `flyway_schema_history_auth` table** (already implemented) | n/a |
 | Q04 | Email magic-link provider in v0.1 or v0.2 | ⏭️ Deferred | n/a |
 | Q05 | npm package name (`@platesoft/auth` vs alternatives) | ✅ Decided (2026-06-24) | n/a |
-| Q06 | SemVer policy details — peer-version lockstep enforcement | 🟡 Leaning | Before v0.1.0 release |
+| Q06 | SemVer policy details — peer-version lockstep enforcement | ✅ Decided (2026-06-24) — **Wire-version constant (WIRE_VERSION=1) in envelope + npm peer dep** | n/a |
-| Q07 | Gitea publishing pipeline (Gitea Actions vs manual deploy) | 🟡 Leaning | Before W6 |
+| Q07 | Gitea publishing pipeline (Gitea Actions vs manual deploy) | ✅ Decided (2026-06-24) — **Gitea Actions on `v*` tag** (workflows exist, test in W12) | n/a |
 | Q08 | Spring Boot version pin (4.0.7 vs 4.1.0 vs latest milestone) | ✅ Decided | n/a (4.1.0) |
 | Q09 | Frontend bundler — `tsup` vs `tsc` vs `unbuild` | ✅ Decided (2026-06-24) | n/a |
 | Q10 | License — MIT, Apache-2.0, or internal proprietary | ✅ Decided (2026-06-24) | n/a |
 | Q11 | First-class i18n in `@platesoft/auth`/react? | ⏭️ Deferred | n/a |
-| Q12 | Audit emit channel — DB rows only, or also event stream? | 🟡 Leaning | Before W2 |
+| Q12 | Audit emit channel — DB rows only, or also event stream? | ✅ Decided (2026-06-24) — **DB rows only v0.1; `LoginEventSink` SPI in v0.2** | n/a |
 | Q13 | SecurityFilterChain scoping — `securityMatcher` vs unscoped `anyRequest` | ✅ Decided (2026-06-24) — fixed in code @ b43ab5e | n/a |
 | Q14 | Remove `@ComponentScan` from auto-config — explicit `@Bean`/`@Import`? | ✅ Decided (2026-06-24) — fixed in code @ b43ab5e | n/a |
 | Q15 | v0.1.0 surface — finish full extraction vs rescope to OAuth-core | ✅ Decided (2026-06-24) — **Path A: full extraction** | n/a |
@@ -73,10 +73,12 @@ When a question is decided, this doc gets updated; the decision is also reflecte
 ### Q02 — Microsoft Entra ID in v0.1?
-**Status:** 🟡 Leaning toward: **Defer to v0.2**
+**Status:** ✅ **Decided 2026-06-24** — **Defer to v0.2** (extraction discipline > AI-assisted ease)
 **Context.** InspectFlow Sprint 14.1 ships Google OAuth. Microsoft Entra ID was scoped into the "SSO sprint" but never landed. Sparkboard does not need it day 1.
 **GLM-5.2 + Lumen lens.** With full AI power, adding MS Entra would be ~half a day (same OAuth pattern, SPI hooks ready, V5 migration already indexes the tenant field). The data model supports it. BUT — Sprint 0 is an *extraction* sprint, and MS Entra was never in InspectFlow's Sprint 14 code. Adding it would be a NEW feature, not an extraction. The discipline of "no new features in extraction" holds regardless of how easy AI makes it. The provider is a clean v0.2 addition — same pattern, ~1 day with AI.
 **Options:**
 | Option | Pros | Cons |
@@ -95,7 +97,9 @@ When a question is decided, this doc gets updated; the decision is also reflecte
 ### Q03 — Flyway migration strategy
-**Status:** 🟡 Leaning toward: **Separate `flyway_schema_history_auth` table + multi-locations**
+**Status:** ✅ **Decided 2026-06-24** — **Separate `flyway_schema_history_auth` table** (already implemented in `PlateAuthFlywayConfig`)
 **GLM-5.2 + Lumen lens.** This was already implemented (W5 — `PlateAuthFlywayConfig` creates a second Flyway bean with `table = "flyway_schema_history_auth"`, `locations = "classpath:db/migration/auth"`). It works, it's clean, no reason to revisit. The W-B co-existence test (W12) will prove it against a consumer that also has its own primary Flyway.
 **Context.** InspectFlow has migrations V1..V31 in one history table. plate-auth needs V1..V6 (its own 6 auth migrations — see F2). If we deploy plate-auth into InspectFlow's existing DB, Flyway sees "your V1 is not my V1" — collision.
@@ -151,7 +155,9 @@ When a question is decided, this doc gets updated; the decision is also reflecte
 ### Q06 — SemVer policy and peer-version lockstep
-**Status:** 🟡 Leaning toward: **Lockstep enforced via npm `peerDependencies` + a startup check in the starter**
+**Status:** ✅ **Decided 2026-06-24** — **Wire-version constant (`WIRE_VERSION=1`) in HMAC envelope + npm `peerDependencies`**
 **GLM-5.2 + Lumen lens.** With AI assistance, implementing the wire-version is trivial: add `WIRE_VERSION = 1` to the envelope JSON in both `ExchangeService` (backend) and `signEnvelope()` (frontend), reject on mismatch. This is the *real* enforcement — it's testable, strict, and prevents silent contract drift between the two artifacts. The npm peer dep is a secondary guard. Implement in W8 (backend) + W9 (frontend). ~2 hours across both halves. Bumping wire-version = trigger for a 0.x → 0.(x+1) release.
 **Context.** Backend and frontend ship from the same monorepo at the same version. If a consumer pins backend `0.1.0` and frontend `0.2.0`, the HMAC envelope contract might drift.
@@ -173,7 +179,19 @@ When a question is decided, this doc gets updated; the decision is also reflecte
 ### Q07 — Gitea publishing pipeline
-**Status:** 🟡 Leaning toward: **Gitea Actions on tag `v*`**
+**Status:** ✅ **Decided 2026-06-24** — **Gitea Actions on `v*` tag — full CI/CD, not just basic publishing**
 **Patrick's directive:** *"For Gitea and the DevOps tools behind us that make our lives so much nicer — always try to be up-to-date. For Gitea, let's explore and do the hard stuff if it's worth it. We will learn and get better."*
 **Decision:** Full Gitea Actions pipeline, not just basic tag-publishing. This includes:
 1. **`ci.yml`** — on every push/PR: `mvn verify` + `pnpm build` + unit/integration tests (matrix Java 25 + Node 22)
 2. **`release.yml`** — on `v*` tag: build + test + publish Maven JAR to Gitea Package Registry + publish npm tarball to Gitea npm registry
 3. **Snyk / OWASP dep-check** (§9.10 security checklist) — scan for CVEs at release tag, fail build on >medium severity
 4. **Renovate** — configured for post-release dependency management (keeps deps current automatically)
 5. **Provenance** — explore Gitea Package Registry's provenance/signing features as they mature
 6. **Test with `v0.0.1` validation tag** (W12) before cutting the real `v0.1.0`
 Workflows (`ci.yml` + `release.yml`) already exist in the repo. W12 tests the full pipeline end-to-end. The homelab's self-hosted `act_runner` on TrueNAS is the execution backend (same as CannaManage/InspectFlow). With GLM-5.2 + Lumen, we explore and adopt Gitea's latest Actions features as they land.
 **Context.** Gitea supports both Maven and npm registries. We need to publish on each tag.
@@ -248,7 +266,9 @@ When a question is decided, this doc gets updated; the decision is also reflecte
 ### Q12 — Audit emit channel
-**Status:** 🟡 Leaning toward: **DB rows only in v0.1; pluggable `AuditEmitter` SPI in v0.2**
+**Status:** ✅ **Decided 2026-06-24** — **DB rows only v0.1; `LoginEventSink` SPI in v0.2**
 **GLM-5.2 + Lumen lens.** A `LoginEventSink` SPI is trivially easy to add (one interface, one no-op default, one `@ConditionalOnMissingBean`). But the question isn't effort — it's *need*. For a 2-consumer homelab library (Sparkboard + InspectFlow), DB rows are sufficient. The `LoginEventService` writes rows, and W11 adds Envers `RevInfo` for entity-change audit. Together these cover the full v0.1 audit surface (login events + state changes). External shipping (Kafka/SIEM) is a v0.2 concern. The SPI will be a clean addition then.
 **Context.** [`LoginEvent`](backend/src/main/java/de/platesoft/inspectflow/entity) writes a DB row per login. Some consumers may want to emit to Kafka, NATS, syslog, or an external SIEM.
@@ -345,6 +365,11 @@ When a question is decided, this doc gets updated; the decision is also reflecte
 | Q17 | `RefreshToken` entity/repository deleted — stateless JWT refresh for v0.1 — fixed @ b43ab5e | 2026-06-24 | Review v3 §1 B5 |
 | Q18 | `spring-boot-starter-web` → `spring-boot-starter-webmvc` (Spring Boot 4.x deprecation) — fix in W10 | 2026-06-24 | Review v3 §2 N1, Plan v2 §13.3 |
 | Q09 | Frontend bundler → **`tsup`** (`packages/auth/tsup.config.ts` exists) — implemented in W9 | 2026-06-24 | Plan v2 §13.2, this doc |
 | Q02 | Microsoft Entra ID → **defer to v0.2** (extraction discipline holds even with AI ease; SPI + V5 migration ready) | 2026-06-24 | Roadmap.md v0.2, this doc |
 | Q03 | Flyway → **separate `flyway_schema_history_auth` table** (already implemented in `PlateAuthFlywayConfig`) | 2026-06-24 | Plan v2 §7.3, this doc |
 | Q06 | Lockstep → **wire-version constant (`WIRE_VERSION=1`) in HMAC envelope + npm peer dep** (implement in W8/W9) | 2026-06-24 | Architecture.md §1, Plan v2 §13.1/§13.2 |
 | Q07 | Publishing → **full Gitea Actions CI/CD** (ci.yml + release.yml + Snyk + Renovate; test with v0.0.1 in W12) | 2026-06-24 | Plan v2 §8 + §13.5 W12, this doc |
 | Q12 | Audit → **DB rows only v0.1** (LoginEventService + Envers RevInfo in W11); `LoginEventSink` SPI v0.2 | 2026-06-24 | Roadmap.md v0.2, this doc |
 ---