Reconcile Pass 1 — first holistic LLM-driven reconciliation pass per
~/.claude/skills/reconcile-catalyst-docs/SKILL.md. Skill triggered after
the post-Group-M architectural batch (#161, #162, #163, #167, #168,
#169, #170, #171, #173, #174, #175). Live ground truth verified against
kubectl + ls platform/ + git log + GHCR + componentGroups.ts.
Drift categories fixed:
- A. Numerical: bp-powerdns 1.0.5 → 1.0.6; component-logos 63 → 62
(powerdns SVG missing, tracked under #173); bootstrap kit 11 → 12
with bp-powerdns added per #167.
- B. Service: pool-domain-manager + 5 registrar adapters
(Cloudflare/Namecheap/GoDaddy/OVH/Dynadot, #170) added to
IMPLEMENTATION-STATUS, ARCHITECTURE, PLATFORM-TECH-STACK, GLOSSARY,
and PROVISIONING-PLAN; bp-powerdns added to ARCHITECTURE bootstrap
kit + Catalyst-on-Catalyst dependency tree.
- C. Architectural: SOVEREIGN-PROVISIONING §3 + DEMO-RUNBOOK Step 4
+ ORCHESTRATOR-STATE Step 6 rewritten from Dynadot-direct DNS writes
to PowerDNS authoritative + PDM /v1/commit + registrar-adapter
NS-flip; PROVISIONING-PLAN Phase 4 paths corrected to
products/catalyst/bootstrap/api/ (per INVIOLABLE-PRINCIPLES #3 the
Go provisioner does NOT call cloud APIs); Phase 6 retitled and
rewritten for the new DNS architecture.
- D. Process: RUNBOOK-PROVISIONING §2 wizard-step table + DEMO-RUNBOOK
Step 2 wizard-step table updated to canonical 7-step ordering
(Org → Domain → Topology → Provider → Credentials → Components →
Review per WIZARD_STEPS in WizardLayout.tsx, post #169 + #174); the
three-mode StepDomain (pool / byo-manual / byo-api per #169) and
two-tab StepComponents (mandatory infra + apps per #161/#162/#175)
now documented.
- E. Cross-doc: Group G ✅ across PROVISIONING-PLAN +
ORCHESTRATOR-STATE (superseded by #167+#163+#170, not by the
original Dynadot-multi-domain plan); Group C ✅ in
PROVISIONING-PLAN (Flux is reconciling from openova-public today);
README Stack-at-a-glance DNS row expanded.
- F. Stale terminology: 11-grep banned-terms scan clean — every k8gb
residual is a legitimate "removed at #171, replaced by lua-records"
reference.
VALIDATION-LOG.md gains the Reconcile Pass 1 entry per skill spec.
Reconcile-skill numbering is independent of the Audit-skill numbering
(which continues at Pass 108+).
Files: 13 docs + VALIDATION-LOG entry.
Escalations: none.
Concluding the validation loop with a process artifact. The new file
records:
- Why the validation existed (post-rewrite trust verification).
- Each pass's scope and concrete fixes (16 iterations across Pass 1
+ sweeps in Passes 2/3/4/5).
- The acceptance criteria as runnable grep commands so any future
contributor can re-verify.
- Authorship convention (hatiyildiz, per-commit identity flags).
- Re-validation cadence (after rewrites, after new banned terms,
after component renames, quarterly drift check).
Linked from README.md docs table.
This file is meant as a playbook for the next validation, not a
status snapshot — for status, IMPLEMENTATION-STATUS.md remains
canonical.
Refs #37
README + CLAUDE.md (iter 9):
- README's "Build a Blueprint" section was contradicting itself: said
"A Blueprint is a Git repo" while elsewhere we'd locked in the
monorepo decision. Rewritten: Blueprint = a folder under
platform/<name>/ or products/<name>/ in this monorepo. CI publishes
per-folder OCI artifacts.
- CLAUDE.md "Repo structure": replaced the brief tree with a more
honest one that distinguishes target structure from current
placeholders (core/apps/ is target console+projector+...; current
has only legacy bootstrap/ and manager/ .gitkeep dirs). Annotated
each products/<name>/ folder with current state (axon = real code;
others = README only; catalyst = bootstrap/ui scaffold).
- CLAUDE.md banned-terms entry "Workspace": now covers component
names too (was only Catalyst scope), matching GLOSSARY's expanded
banned-term entry.
PLATFORM-TECH-STACK (iter 10) — substantive reorganization:
The §1 categorization established three buckets:
(a) Catalyst control plane (per-Sovereign on mgt)
(b) Per-host-cluster infrastructure (every host cluster)
(c) Application Blueprints (a la carte)
But §2 "Catalyst control plane components" was mixing buckets (a)
and (b): it listed flux, crossplane, cert-manager, kyverno, harbor,
external-secrets, reloader, vpa, keda, k8gb, coraza, falco, trivy,
sigstore, syft-grype, minio, velero, failover-controller all under
"Catalyst control plane" — but those are per-host-cluster
infrastructure per §1, and §1 itself said Crossplane "Never
user-facing" / per-host-cluster.
Reorganized §2 + §3:
- §2 now contains ONLY the Catalyst control plane:
2.1 User-facing surfaces (console, marketplace, admin)
2.2 Catalyst backend services (projector, catalog-svc, provisioning,
environment-controller, blueprint-controller, billing)
2.3 Per-Sovereign supporting services (keycloak, openbao, spire-
server, nats-jetstream, gitea, observability)
- New §3 Per-host-cluster infrastructure with subsections for
networking, GitOps+IaC, security+policy, scaling+ops, storage+
registry, resilience.
- Application Blueprints renumbered §3 → §4. Added missing
opensearch row to §4.1 (was previously misplaced in observability).
- Composite Blueprints (Products) §4 → §5.
- Multi-Region §5 → §6. Resource estimates §6 → §7. Cluster
deployment §7 → §8. User choice §8 → §9. SIEM §9 → §10. License §10 → §11.
Cross-doc references to PLATFORM-TECH-STACK §1 / §2 (in NAMING,
ARCHITECTURE, IMPLEMENTATION-STATUS) all still resolve correctly
under the new numbering.
SRE (iter 11):
- §2.4 split-brain table: "MongoDB" → "FerretDB" (MongoDB was
retired in favor of FerretDB-on-CNPG per project-memory).
- §2.5 data replication: clarified each row's layer (Application
Blueprint vs per-host-cluster vs Catalyst control plane) instead
of misclassifying MinIO/Harbor as Application Blueprints. Added
OpenSearch row.
- §3.1 Flagger and §3.2 Flipt: explicitly marked "Status: design,
not yet a deployed Blueprint" since they're "components to watch"
in TECHNOLOGY-FORECAST, not in the current PLATFORM-TECH-STACK §3
inventory.
BUSINESS-STRATEGY + TECHNOLOGY-FORECAST (iter 12):
- Final scan: clean. No tenant/operator-team/Catalyst-IDP/Lifecycle
Manager/Synapse(product) violations remaining.
Refs #37
SECURITY (iter 6):
- "Environment repo" → "Environment Gitea repo" in §3 secrets diagram.
- "ChangePolicy enforces approvals" → "EnvironmentPolicy enforces
approvals" in §9 SOC2 row (ChangePolicy was a fictional CRD —
EnvironmentPolicy is the real one defined in ARCHITECTURE §8).
- "Catalyst's compliance-controller surfaces evidence" → "evidence
surfaced via Catalyst console audit views and SIEM exports"
(compliance-controller wasn't defined elsewhere; this avoids
inventing new components in compliance prose).
SOVEREIGN-PROVISIONING (iter 7):
- "vault-stored" → "stored in OpenBao on the provisioner"
(Vault was replaced by OpenBao; "vault-stored" was generic English
but read as a contradiction).
BLUEPRINT-AUTHORING (iter 8):
- OCI artifact naming locked: `ghcr.io/openova-io/bp-<name>:<semver>`
where `<name>` is the folder name. The `bp-` prefix lives in the
OCI artifact name (self-identifying), not the folder name.
Fixed in §1, §10, §11, §13 — and propagated to README.md so the
pattern is consistent across the repo.
- Crossplane Composition example: `compositeTypeRef.apiVersion`
changed from `bp-wordpress.openova.io/v1alpha1` (per-Blueprint
group, ugly) to `compose.openova.io/v1alpha1` (shared XRD group
across all Blueprints).
- §11 CI pipeline final step: "publish blueprint.yaml as the
manifest" → "as the OCI manifest's metadata layer" (clearer about
what it does in the OCI sense).
Refs #37
First validation iteration. Three concrete corrections.
1. Add docs/IMPLEMENTATION-STATUS.md as the bridge between target
architecture and current code state. Status legend (✅ / 🚧 / 📐 / ⏸)
applied per-component. Catalyst control plane = mostly 📐. Component
READMEs = 🚧 (README only, no Blueprint manifests yet). products/axon
= ✅ (only product with real code). core/ = 📐 (just .gitkeep).
2. Status banner added to ARCHITECTURE, SECURITY, SOVEREIGN-PROVISIONING,
BLUEPRINT-AUTHORING, PERSONAS-AND-JOURNEYS, PLATFORM-TECH-STACK, SRE
pointing readers at IMPLEMENTATION-STATUS.md before they treat any
described feature as built. GLOSSARY also references it.
3. Architectural decision (Option A — monorepo canonical):
- Each platform/<name>/ and products/<name>/ folder is the source of
ONE Blueprint, published as ghcr.io/openova-io/<name>:<semver> by
CI fan-out from the monorepo root.
- BLUEPRINT-AUTHORING.md §1, §2, §13 rewritten to match.
- README.md "what's in this repo" rewritten to clarify monorepo +
OCI-fan-out shape; no longer claims every directory is a Blueprint
in a way that contradicts BLUEPRINT-AUTHORING.
Wrong-org fixes (3 places):
- docs/PERSONAS-AND-JOURNEYS.md:13 github.com/openova → openova-io
- docs/BLUEPRINT-AUTHORING.md:13 github.com/openova → openova-io
- docs/BLUEPRINT-AUTHORING.md:404 github.com/openova → openova-io
- docs/BLUEPRINT-AUTHORING.md ghcr.io/openova/* (3 refs) → openova-io
API group consistency:
- All references unified to catalyst.openova.io/v1alpha1
(was mixed v1 / v1alpha1; v1alpha1 is correct since the CRDs are
design-stage with no implementation).
core/README.md updated to honestly describe the directory tree as
"target structure with .gitkeep placeholders" rather than implying
the apps/console, apps/projector, etc. binaries already exist.
The legacy apps/bootstrap and apps/manager directories are
acknowledged as transitional placeholders that will be removed when
the new apps/ layout is scaffolded.
CLAUDE.md and .claude/project-memory.md updated to put
IMPLEMENTATION-STATUS.md second in the read-first ordering.
Refs #37
Repositions the public repo's identity. OpenOva is the company; Catalyst
is the platform. Sovereign is a deployed Catalyst. The historical
positioning (OpenOva = platform, Catalyst = bootstrap+IDP+lifecycle
sub-product) is retired. Catalyst now subsumes bootstrap, lifecycle, and
IDP responsibilities into one control plane.
- README.md Catalyst-first front door. Sovereign concept,
repo structure, stack at a glance, cloud
provider matrix, getting-started paths
(managed via marketplace.openova.io vs
self-host via catalyst-provisioner).
- CLAUDE.md Codebase guide for Claude. Banned-term table,
commit conventions (hatiyildiz default for
public repo), the no-fourth-surface rule,
per-component README rule of thumb.
- .claude/project-memory.md Reduced to an index + decision log;
full architecture moved to docs/. Stack
decisions locked (NATS JetStream, OpenBao,
SPIFFE/SPIRE, per-Org Keycloak SME / per-
Sovereign corporate, Crossplane only IaC,
no Terraform/Pulumi user-facing surface).
- core/README.md Catalyst control-plane Go application. Drops
the bootstrap-vs-manager split (both fold under
"Catalyst control plane"). Lists each component
deployable from this codebase: console,
marketplace, admin, projector, catalog-svc,
provisioning, workspace-controller, blueprint-
controller, billing. CRD list updated:
Sovereign / Organization / Environment /
Application / Blueprint / EnvironmentPolicy /
SecretPolicy / Runbook.
Refs #37
Remove hierarchical grouping (networking/, security/, etc.) and use flat
structure for all 41 platform components.
Changes:
- All components now directly under platform/ (no subfolders)
- AI Hub components moved from meta-platforms/ai-hub/components/ to platform/
- Open Banking components (lago, openmeter) moved to platform/
- meta-platforms/ now only contains README files that reference platform/
- Open Banking custom services remain in meta-platforms/open-banking/services/
Structure:
- platform/ (41 components, flat)
- meta-platforms/ai-hub/ (README only, references platform/)
- meta-platforms/open-banking/ (README + 6 custom services)
All documentation links updated.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Harbor moved from storage/ to registry/ (artifact management, not storage)
- Kyverno moved from security/ to policy/ (policy engine for validation,
mutation, generation - broader than just security)
Updated structure:
- platform/registry/harbor/
- platform/policy/kyverno/
All documentation links updated accordingly.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
