mirror of https://github.com/dredx/prole.git synced 2026-09-23 12:03:59 +00:00

chrisfu 6d484ef13e docs(plans): k3d-mirror-of-GKE plan + Phase 1 brief for Junie

The next development thread is knoe-auth Phase 2 OIDC iteration, which
just landed on main but has no fast inner-loop. Instead of bouncing
edits through the GKE deploy chain, we want a laptop-resident model
where knoe-auth runs from the IDE / mvn against real Postgres + KDC
brought up in k3d.

Two new docs:

  docs/plans/k3d-gke-mirror.md
    Architectural plan. Top-to-bottom rationale for what the k3d
    model should mirror, what we deliberately skip (supabase, kong,
    oauth2-proxy, Studio — all unnecessary for knoe-auth's surfaces),
    and the phasing. Captures the three scope decisions taken
    2026-05-02 with the user:
      - knoe-auth runs on the laptop, not as a pod (faster inner loop)
      - stack scope is CNPG + KDC only
      - single-replica CNPG, realm KNOE.LOCAL (distinct from KNOE.DEV)
    Out-of-scope for Phase 1 listed explicitly so reviewer
    expectations match scope: SPNEGO E2E, image-build-and-load,
    supabase, oauth2-proxy, OidcCodeService DB persistence.

  docs/plans/junie/k3d-knoe-auth-dev-loop.md
    Phase 1 brief. Concrete deliverables:
      - k8s/knoe/knoe-kdc-{deployment,service,configmap,pvc,init-job}.yaml
      - etc/init_knoe_auth.sh --mode k3d flag (or sibling script)
      - Makefile: k3d-knoe-{up,pf,down}
      - etc/krb5.local.conf (with udp_preference_limit=1 for
        kubectl port-forward UDP flakiness on macOS)
      - docs/local-dev-knoe-auth.md (engineer-facing)
      - scripts/k3d-knoe-smoke.sh
    Definition of done: a fresh-clone laptop can `make k3d-knoe-up`
    + `make k3d-knoe-pf` + `mvn -pl authority spring-boot:run` and
    hit /health, /.well-known/openid-configuration in <8 minutes.

Index updates:
  docs/plans/README.md           — k3d-gke-mirror.md row added
  docs/plans/junie/README.md     — split into Active / Shipped;
                                   k3d brief listed under Active;
                                   the 5 shipped-2026-05-02 briefs
                                   moved to Shipped with commit refs.
  docs/TODO.md In-progress       — k3d brief now top of "In progress";
                                   the previously in-flight "Phase 2
                                   pg_oauth in install/deploy.sh"
                                   item demoted to "paused" (resume
                                   after the local dev loop lands).

No code changes; all docs.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

2026-05-02 04:45:28 -07:00

3.7 KiB

Raw Blame History

Junie briefs

Self-contained, single-task briefs for Junie to consume from inside the IntelliJ IDE. Each file is a hand-off — Junie reads the brief cold (no shared chat history), implements the change, and opens an MR.

What lives here vs. `../`

The .. parent directory holds architectural plans — multi-section documents covering an initiative's strategy, schema, and component design. They outlive the implementation and become the architectural reference once shipped.

This subdirectory holds work briefs — smaller, more tactical, scoped to a single MR's worth of changes. They reference the master TODO index (../../TODO.md) and contain enough context for Junie to land the change without escalating questions.

Brief shape (convention)

Each brief follows this skeleton:

Why — one or two paragraphs of context, including the trigger event if any (e.g. "the 4/28 14:00 UTC outage").
What changes — concrete file paths, line numbers, before/after where useful. Don't make Junie re-derive the change.
Verification — runnable commands or helm template diffs that confirm the change. Each brief ends with a Definition of done checklist.
Out of scope — explicit fences. The TODO is interconnected; without this section briefs creep.
Commit shape — proposed commit message + structure.

Status tracking

Every brief here corresponds to a numbered item in ../../TODO.md (or has an explicit "doesn't yet exist in TODO" note). When Junie lands a brief:

Move the corresponding item from the TODO ranked queue into the Done section with date + commit ref (or the convention used by the rest of the file).
Don't delete the brief from this directory — it stays as the design record.

Current briefs (as of 2026-05-02)

Active (in flight)

File	Tracked at	Subject
`k3d-knoe-auth-dev-loop.md`	TODO §"In progress"; parent `../k3d-gke-mirror.md`	Phase 1 of the k3d-mirror-of-GKE plan: stand up CNPG + KDC in k3d so host-side knoe-auth can iterate against real Postgres + Kerberos

Shipped (kept as design record)

File	Queue #	Subject
`02-k3s-prole-rename.md`	#2	Rename k3s `prole-.yaml` → `knoe-.yaml` (kustomize is broken). Shipped 2026-05-02 (commit `fb7e8b7`).
`06-patch-garage-script-fixes.md`	#6	Three defects in `scripts/patch_garage_cross_cluster.sh`. Shipped 2026-05-02 (commits `34a25dd` + `5d17325`).
`07-init-cnpg-gke-sa-wiring.md`	#7	Wire `cnpg-backup-sa` into CNPG cluster spec; bump operator to v1.29. Shipped 2026-05-02 (commit `c3fae73`).
`13-podmonitor-manual-management.md`	#13	Migrate off CNPG-deprecated `enablePodMonitor` + `podMonitorRelabelings`. Shipped 2026-05-02 (commit `c3fae73`).
`15-remove-dead-dashboard-consumer.md`	#15	Remove dead Kong DASHBOARD consumer + `basicauth_credentials`. Shipped 2026-05-02 (commit `c3fae73`).

How a session fires off a batch

The driving session (Claude Code, Cowork+Code, or a human) writes the briefs into this directory and points Junie at one or more of them. Junie reads the brief, implements, runs the verification checklist, opens an MR. Each brief is independent — Junie can take them in any order, or in parallel across separate IDE sessions.

The brief is the contract. If something is unclear, the brief is buggy and should be edited before Junie continues.

3.7 KiB Raw Blame History