Create arch-keycloak note (platform traceability gap) #303

New issue

Open

opened 2026-04-26 00:00:18 +00:00 by forgejo_admin · 0 comments

forgejo_admin commented

2026-04-26 00:00:18 +00:00

Contributor

Type

Chore

Lineage

Discovered scope from Track C of westside-admin bootstrap (2026-04-25). Recurring traceability gap flagged in 5 separate review notes since 2026-04-03 without ever being filed as actionable work — feedback_discovered_scope_always_tracked violation in the review pipeline that this ticket closes.

Repo

forgejo_admin/pal-e-docs (note creation only — no source repo change)

User Story

story:platform-traceability — As a dispatched dev/review agent, I need an arch-keycloak note in pal-e-docs so that I can cross-reference Keycloak architectural decisions when implementing or reviewing tickets that carry the arch:keycloak label, instead of substituting unrelated arch notes or marking the gap as a SCOPE waiver.

Context

The pal-e-docs slug arch-keycloak does not exist (search_notes query "arch keycloak" returns only review notes flagging the absence). The gap has been flagged in 5 separate reviews:

review-785-2026-04-03 — Keycloak service account for programmatic admin API
review-960-2026-04-11 — Keycloak client resource (child of #7)
review-1074-2026-04-22 — Marcus onboarding browser-SSO (arch-keycloak-oidc variant also missing)
review-1096-2026-04-25 v1 — Terraform Keycloak OIDC client westside-admin
review-1096-2026-04-25-v2 — same review, carryover unfixed

Recent SOP sop-keycloak-client-creation (just landed) had to substitute arch-deployment-westside-admin as the cross-reference because arch-keycloak does not exist.

File Targets

pal-e-docs: new note slug arch-keycloak, note_type=arch, project pal-e-platform, tags arch, active, keycloak
pal-e-docs: optionally child note arch-keycloak-oidc if OIDC details warrant separation (decide during scoping)
pal-e-docs: update SCOPE checkboxes in the 5 review notes listed above (or add an "addressed by #XXX" line)

Acceptance Criteria

arch-keycloak note exists with content covering: live realm names + owners; IaC-vs-admin-console boundary (which keycloak resources we manage via terraform vs admin console, per feedback_keycloak_first); OIDC flow contract (auth code + PKCE S256, mandatory state-param, post-logout URI, web-origins); secret-handling boundary (SOPS path pattern + rotation pointer to sop-keycloak-client-creation)
Cross-links present: sop-keycloak-client-creation, sop-gmail-oauth, feedback_keycloak_first, feedback_funnel_requires_auth
All 5 historical review SCOPE checkboxes updated

Test Expectations

N/A (docs-only deliverable)
Verification: search_notes("arch keycloak") returns the new note as top hit; get_note(slug="arch-keycloak") returns the full body; the 5 review notes show their SCOPE items resolved

Constraints

Docs-only. No terraform changes. No realm changes. No live admin-console operations.
Must not duplicate content from sop-keycloak-client-creation — the SOP is procedural (how to create a client); this arch note is structural (what exists and why).

Checklist

Ticket reviewed via /review-ticket and moved backlog → todo
arch-keycloak note created
Cross-links wired
Review SCOPE checkboxes updated in all 5 review notes
PR (if any source repo change) opened with Closes #THIS
Issue closed after note + cross-links verified

Triggered by: review-1096-2026-04-25-v2 (final straw — 5th surfacing)
Sibling architectural notes that should follow same pattern: arch-postgres, arch-harbor, arch-tailscale-funnel (not all known to exist — separate audit)
Memory: feedback_discovered_scope_always_tracked, feedback_traceability_triangle

### Type Chore ### Lineage Discovered scope from Track C of westside-admin bootstrap (2026-04-25). Recurring traceability gap flagged in 5 separate review notes since 2026-04-03 without ever being filed as actionable work — `feedback_discovered_scope_always_tracked` violation in the review pipeline that this ticket closes. ### Repo forgejo_admin/pal-e-docs (note creation only — no source repo change) ### User Story story:platform-traceability — As a dispatched dev/review agent, I need an `arch-keycloak` note in pal-e-docs so that I can cross-reference Keycloak architectural decisions when implementing or reviewing tickets that carry the `arch:keycloak` label, instead of substituting unrelated arch notes or marking the gap as a SCOPE waiver. ### Context The pal-e-docs slug `arch-keycloak` does not exist (`search_notes` query "arch keycloak" returns only review notes flagging the absence). The gap has been flagged in 5 separate reviews: - `review-785-2026-04-03` — Keycloak service account for programmatic admin API - `review-960-2026-04-11` — Keycloak client resource (child of #7) - `review-1074-2026-04-22` — Marcus onboarding browser-SSO (`arch-keycloak-oidc` variant also missing) - `review-1096-2026-04-25` v1 — Terraform Keycloak OIDC client westside-admin - `review-1096-2026-04-25-v2` — same review, carryover unfixed Recent SOP `sop-keycloak-client-creation` (just landed) had to substitute `arch-deployment-westside-admin` as the cross-reference because `arch-keycloak` does not exist. ### File Targets - pal-e-docs: new note slug `arch-keycloak`, `note_type=arch`, project `pal-e-platform`, tags `arch, active, keycloak` - pal-e-docs: optionally child note `arch-keycloak-oidc` if OIDC details warrant separation (decide during scoping) - pal-e-docs: update SCOPE checkboxes in the 5 review notes listed above (or add an "addressed by #XXX" line) ### Acceptance Criteria - [ ] `arch-keycloak` note exists with content covering: live realm names + owners; IaC-vs-admin-console boundary (which keycloak resources we manage via terraform vs admin console, per `feedback_keycloak_first`); OIDC flow contract (auth code + PKCE S256, mandatory state-param, post-logout URI, web-origins); secret-handling boundary (SOPS path pattern + rotation pointer to `sop-keycloak-client-creation`) - [ ] Cross-links present: `sop-keycloak-client-creation`, `sop-gmail-oauth`, `feedback_keycloak_first`, `feedback_funnel_requires_auth` - [ ] All 5 historical review SCOPE checkboxes updated ### Test Expectations - N/A (docs-only deliverable) - Verification: `search_notes("arch keycloak")` returns the new note as top hit; `get_note(slug="arch-keycloak")` returns the full body; the 5 review notes show their SCOPE items resolved ### Constraints - Docs-only. No terraform changes. No realm changes. No live admin-console operations. - Must not duplicate content from `sop-keycloak-client-creation` — the SOP is procedural (how to create a client); this arch note is structural (what exists and why). ### Checklist - [ ] Ticket reviewed via /review-ticket and moved backlog → todo - [ ] arch-keycloak note created - [ ] Cross-links wired - [ ] Review SCOPE checkboxes updated in all 5 review notes - [ ] PR (if any source repo change) opened with `Closes #THIS` - [ ] Issue closed after note + cross-links verified ### Related - Triggered by: review-1096-2026-04-25-v2 (final straw — 5th surfacing) - Sibling architectural notes that should follow same pattern: `arch-postgres`, `arch-harbor`, `arch-tailscale-funnel` (not all known to exist — separate audit) - Memory: `feedback_discovered_scope_always_tracked`, `feedback_traceability_triangle`