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

chrisfu f83ec8169c docs(plans): file Junie briefs for queue items #2 , #6 , #7 , #13 , #15

Five self-contained work briefs in a new docs/plans/junie/ subdirectory,
each tagged against a numbered item in docs/TODO.md so Junie can take
them independently in any order.

  02-k3s-prole-rename.md            -> queue #2  (drift R5)
  06-patch-garage-script-fixes.md   -> queue #6  (drift R9)
  07-init-cnpg-gke-sa-wiring.md     -> queue #7  (drift R8)
  13-podmonitor-manual-management.md-> queue #13
  15-remove-dead-dashboard-consumer.md-> queue #15

Each brief follows the same shape: Why -> What changes (concrete file
paths + line numbers + before/after) -> Verification -> Out of scope ->
Commit shape -> Definition of done. The intent is that Junie reads cold
(no shared chat history) and lands the change without escalating
questions.

Also adds:
  - docs/plans/junie/README.md describing the convention.
  - Row in docs/plans/README.md so newcomers find the subdirectory.
  - Brief reference + "Assigned to Junie" tag on each of the five queue
    items in docs/TODO.md.

Existing in-progress assignment to Junie (Phase 2 pg_oauth) is unchanged.

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

2026-05-01 16:13:20 -07:00

4.5 KiB

Raw Blame History

Plans

Engineering plans for the knoe.dev platform. Each document scopes one initiative — its strategic context, design, schema, and the components it adds — and is intended to outlive the implementation work itself: when the work ships, the plan stays as the architectural reference.

Who this is for

You are a junior or mid-level engineer who has been invited to contribute to knoe.dev. These documents are written for you. They assume:

You are comfortable reading code and skimming a Maven pom.xml.
You have used Kubernetes at least casually (kubectl get pods, helm charts).
You may not have prior Kerberos, OIDC, or CNPG experience — relevant terms are defined inline or in the glossary section of each plan.
You have not seen this repo before. Each plan starts with the strategic context and links to existing code before it asks you to write any.

If a sentence in a plan assumes knowledge you don't have, that's a bug in the plan — open an issue.

What lives here

File	Initiative	When you should read it
`knoe-auth-round-1.md`	Identity backbone for the platform: MIT Kerberos KDC + invite-anchored web enrollment + TOTP 2FA. Round 1 of N. Shipped.	Before touching `authority/`, `etc/init_kdc.sh`, `etc/init_knoe_users.sh`, anything in `deploy/gcp/gke/knoe-auth-` or `knoe-kdc-`, or the `knoe.*` database schema.
`deployment-modes.md`	Four-mode installer (`min` / `k3d` / `k3s` / `gke`) with a welcome-screen mode selector and a `min`-mode fast-path through the wizard. Shipped in Phase 0.	Before touching `knoe/ui/screens/welcome.py`, `knoe/ui/screens/navigation.py`, or adding any new wizard screen.
`customer-deploy-resync.md`	Original plan to converge `~/dev/prole` onto `knoe-db/main` as a customer-deploy branch. Dormant — prole rebrand merged into `main`; no separate prole working tree currently under development.	Only if you're considering activating a per-customer branching workflow.
`junie/` (subdirectory)	Self-contained, single-task work briefs for Junie to consume from inside the IDE. Tactical, single-MR scope, paired against numbered items in `../TODO.md`.	When you want to hand a discrete task to Junie or audit what's been queued.
`../TODO.md` (sibling)	Master TODO index — single source of truth for unfinished work, including reality-vs-intent gaps flagged in `CLAUDE.md`/`AGENTS.md`.	Before picking up any task, to see what's already on the queue.

Each plan follows the same shape: Context → How it's wired (file references) → Architecture → Schema / API → Step-by-step → Verification → Glossary.

Status conventions

A plan in this directory has one of three statuses, declared at the top:

Active plan. Not yet implemented. — the design is agreed, the code isn't there yet. Read deliverables top-to-bottom.
Implemented and operational. Architectural reference. — the work shipped. The doc explains how it works and why; cross-references point at real files. Read the context and the rationale; jump to specific sections when you have a question.
Archived. — superseded by a later round or a different approach. Lives in archive/ with a one-line "see X instead" pointer.

Customer deploys

The knoe.dev platform supports per-customer deployments — currently the most active is prole.org. The convention is branches in this repo, not separate forks. Customer-specific divergence (config, branding, on-prem manifests, kubeconfig handling) lives on a branch named after the customer; platform changes always land on main and customer branches rebase or merge from main on a regular cadence. See the customer's own docs/plans/ for resync notes — for example, ~/dev/prole/docs/plans/customer-deploy-resync.md if you have that working tree checked out.

How to propose a new plan

Copy knoe-auth-round-1.md as a template — the section structure is the convention.
Lead with why (one or two paragraphs). Half the value of a plan is forcing the author to articulate the motivation.
Cite real files with paths relative to the repo root. If you reference something that doesn't exist yet, label it (net-new) so a reader doesn't go hunting.
End with a Verification section — a short checklist a reviewer can run to decide whether the plan is done, or — once shipped — that the implementation still matches the spec.
Open an MR. Plans are reviewed like code.

4.5 KiB Raw Blame History