docs: initial Sith plan — charter, architecture, ADRs, threat model, roadmap, competitive

[gnanirahulnutakki]

Sith — initial plan (plan-only, for review)

This PR lands the planning-phase artifacts for Sith: a governed, multi-tenant,
cross-cluster operations federation control plane for generic Kubernetes fleets,
built on Open Cluster Management (OCM). No product/application code — the owner
reviews this plan before any implementation.

The one-sentence job

Give an operator one governed place to see and safely act across many Kubernetes
clusters — while deep cluster access stays local to each cluster.

Headline decision

Adopt OCM as the substrate; do not build a bespoke tunnel/agent. The very first thing
we build is not code — it is a falsification test (Milestone-0): OCM hub + 2 kind/k3d
spokes, enable cluster-proxy + managed-serviceaccount, reach a spoke's in-cluster
Grafana/Argo CD from the hub via a scoped token. If it works, the entire "build the agent"
scope is deleted; if not, we stop before writing product code.

The wedge — three federations (on top of OCM)

• Read federation — normalized fleet model + cross-cluster correlation single-cluster tools can't do.
• Action federation — the only writes are typed intents from a closed verb vocabulary (argocd.sync|rollback, rollout.promote|abort, deployment.scale|restart, gitops.open-pr). No shell, no free-form apply, no secret/RBAC mutation. Signed intents; each spoke re-validates against a local allowlist and executes with its own scoped identity. First write = gitops.open-pr.
• Policy federation — fan-out reasoning: env gates (prod = multi-approver, never auto), wave/canary ordering with a gate per wave, partial-failure/rollback, idempotency, and federation-specific abstention.
• Ardur is the PDP + scoped-identity broker + decision-ledger; Sith is exposed as a governed MCP server so external agents inherit the same governance.

Explicit non-goals

Not a developer portal, not a GitOps controller, not a multi-cluster scheduler, not a telemetry lake.

What's in this PR

File	Contents
README.md	Positioning, one-sentence job, non-goals, built-on-OCM, status: planning
docs/CHARTER.md	Problem, thesis, target user, wedge, why-now, success criteria
docs/ARCHITECTURE.md	Hub + OCM-brokered spokes, three federations, Mermaid topology/component/sequence/ER diagrams, data model, MCP surface, where Ardur plugs in
docs/SCOPE.md	In/out of scope, safe defaults, permanently-excluded actions
docs/ROADMAP.md	Milestone-0 (falsification) → P1 read → P2 first governed write → P3 policy federation + MCP
docs/THREAT-MODEL.md	Hub as crown-jewel, signed intents, per-spoke allowlist, blast-radius controls, MCP write surface, abstention, predecessor anti-patterns avoided
COMPETITIVE.md	Web-verified landscape (OCM/cluster-proxy, Rancher Prime, Komodor, Devtron, Headlamp, Konnectivity, Karmada, Clusterpedia, kagent, argocd-agent) + honest crowding assessment
docs/adr/0001..0006	Adopt-OCM · stack/language · tenancy+isolation · typed-intent action model · AI/MCP+Ardur-PDP · credential/key custody

Verification discipline

Every external claim is web-verified (July 2026) and cited. Key facts: OCM = CNCF
Sandbox; cluster-proxy/managed-serviceaccount v0.10.0 (2026-02-02); MCP tool
annotations (2025-03-26, hints → enforce server-side) + Elicitation (2025-06-18).
Vendor-neutral throughout; no secrets, no customer/employer names.

Follow-up

Milestone-0 and Phase-1 GitHub issues are filed under their milestones for execution after plan approval.

[gnanirahulnutakki]

Milestone-0 (OCM falsification test) → ✅ PASS — headline decision validated

The gating experiment for the plan's headline bet ("adopt OCM; do not build a bespoke tunnel/agent") has been run empirically, before any product code.

A central OCM hub reached an in-cluster service on a managed spoke using a scoped managed-serviceaccount token, over the cluster-proxy reverse tunnel, with the spoke connecting outbound-only and the hub holding no admin kubeconfig.

• Reach: hub retrieved the spoke's cluster-local nginx page through the konnectivity tunnel via clusteradm proxy kubectl --sa=<MSA>.
• Scoped, not admin: the same token was denied cluster-wide secrets and nodes (403) while in-scope reads worked — reach ⟂ privilege.
• Outbound-only: spoke conntrack shows all hub-directed flows originate on the spoke → hub:6443; zero hub→spoke-initiated flows.
• Env/pins: kind (k8s v1.34.0), OCM/clusteradm v1.3.1, cluster-proxy 0.10.0, managed-serviceaccount 0.10.0. ~15 min end-to-end (≪ the ≤1-day gate).

➡️ The "build the transport/agent" scope is deleted. ADR-0001 → Accepted; proceed to Phase 1.

Evidence + runbook and the ADR status flip are in #13 (based on this plan branch): docs/experiments/M0-ocm-falsification.md. Closes the M0 issues #2–#6.