diff --git a/README.md b/README.md index d310f64..a0d0e76 100644 --- a/README.md +++ b/README.md @@ -18,6 +18,7 @@ Platform tooling, **access documentation**, and Jira planning for the Platypus ( - [PLAT board](https://catalystsoftware.atlassian.net/jira/software/c/projects/PLAT/summary) - [Access docs](access/) — endpoints, agents, MCP map (scaffold; synthesis ticket pending) +- [Galva program](docs/research/galva-program.md) — modernization research via `platform-galva` (E10 / [PLAT-96](https://catalystsoftware.atlassian.net/browse/PLAT-96)) - [Security policy](docs/security.md) — no secrets in git ## Status diff --git a/docs/how-we-work.md b/docs/how-we-work.md index 10741da..03b65ab 100644 --- a/docs/how-we-work.md +++ b/docs/how-we-work.md @@ -46,7 +46,7 @@ cp config/config.yaml.example ~/.config/platform-tools/config.yaml Override the path with `PLATFORM_TOOLS_CONFIG` if needed. **Never** commit `~/.config/platform-tools/config.yaml` or copy its contents into PRs, Jira tickets, or agent context. -The same convention applies to other Platypus repos (`platform-ikg`, `platform-castleguard`, `platform-zaha`): each uses `~/.config//config.yaml` for local secrets and endpoints. +The same convention applies to other Platypus repos (`platform-ikg`, `platform-castleguard`, `platform-zaha`, `platform-galva`): each uses `~/.config//config.yaml` for local secrets and endpoints. ## Privacy @@ -82,6 +82,21 @@ Access docs and Jira tickets in this repo must respect **personal privacy**, **c Scaffold-only content is expected until the synthesis ticket ([PLAT-92](https://catalystsoftware.atlassian.net/browse/PLAT-92)) is completed via privacy-safe PRs. +## Galva — modernization research (E10) + +**Galva** ([PLAT-96](https://catalystsoftware.atlassian.net/browse/PLAT-96)) is the PLAT program for researching how to modernize, migrate, and refactor older codebases — without executing production changes in the research phase. The future implementation repo is **`totango/platform-galva`** (same naming pattern as `platform-ikg`, `platform-castleguard`, `platform-zaha`). + +| Concept | Guidance | +|---------|----------| +| **Repo** | `totango/platform-galva` — research tooling and intake automation (not yet scaffolded) | +| **Intake** | Facts in (topology, deps, versions) → strategy out (savings, effort, risk, blast radius) | +| **Sizing** | Small galvas (one program) vs big galvas (service groups) — see [galva-program.md](research/galva-program.md) | +| **Languages** | Java, Python, Go, etc. — derive ASTs per ecosystem; no single-language assumption | +| **Platform context** | Use IKG (E09), FinOps (E04), access docs — not personal machine paths | +| **Handoff** | Approved plans become delivery stories under E01/E02/… — Galva does not merge infra changes | + +Example inaugural galva: [catalyst-ingest → shared Temporal](research/galva-catalyst-ingest.md) ([PLAT-98](https://catalystsoftware.atlassian.net/browse/PLAT-98)). + ## Deployment and merge process `main` is **protected** on Platypus repos. Treat merges as a small deployment: traceable ticket, human review, and CI validation. @@ -101,7 +116,7 @@ Apply or update protection on a repo: .github/scripts/setup-branch-protection.sh totango/platform-tools ``` -Use the same script (with a different `owner/repo` argument) when bootstrapping `platform-ikg`, `platform-castleguard`, `platform-zaha`, and other Platypus repos. +Use the same script (with a different `owner/repo` argument) when bootstrapping `platform-ikg`, `platform-castleguard`, `platform-zaha`, `platform-galva`, and other Platypus repos. ### PR title (Jira-linked) diff --git a/docs/jira-space-overview.md b/docs/jira-space-overview.md index 8132eab..5f7b710 100644 --- a/docs/jira-space-overview.md +++ b/docs/jira-space-overview.md @@ -22,7 +22,7 @@ Epic (initiative — quarter / multi-month) **Rule:** Acceptance criteria on **Story**; definition of done on **Tasks**. -## Epic map (E01–E09) +## Epic map (E01–E10) | Epic | Name | |------|------| @@ -35,8 +35,11 @@ Epic (initiative — quarter / multi-month) | E07 | Agent research & validation | | E08 | Agent platform & lifecycle | | E09 | Infra Knowledge Graph (IKG) & Zaha UI | +| E10 | Galva — modernization research & migration planning ([PLAT-96](https://catalystsoftware.atlassian.net/browse/PLAT-96)) | -Traceability labels: `plat-ref:E01` … `plat-ref:E09`, `plat-ref:100` for logical IDs. +Traceability labels: `plat-ref:E01` … `plat-ref:E10`, `plat-ref:100` for logical IDs. + +**Galva (E10):** research/planning for modernizing older codebases — future repo `totango/platform-galva`; see [docs/research/galva-program.md](research/galva-program.md). ## Tooling in this repo diff --git a/docs/research/galva-catalyst-ingest.md b/docs/research/galva-catalyst-ingest.md new file mode 100644 index 0000000..d473ef6 --- /dev/null +++ b/docs/research/galva-catalyst-ingest.md @@ -0,0 +1,110 @@ +--- +title: "Galva example — catalyst-ingest migrate to shared Temporal" +tags: [eng-information, galva, catalyst-ingest, temporal, migration] +last_updated: "2026-08-28" +status: scaffold +audience: [engineers, agents] +gaps: + - "Current Temporal version and namespace layout not verified" + - "PostgreSQL sizing, HA model, and migration tooling unknown" + - "Shared Temporal target cluster/version not selected" + - "Consumer blast radius not inventoried" +sources_to_synthesize: + - "Approved service repo (catalyst-ingest) — via PR, no personal paths" + - "Platform IKG when available (E09)" + - "FinOps signals for dedicated vs shared Temporal cost (E04)" +jira: "PLAT-98" +--- + +# Galva: catalyst-ingest → shared Temporal + +**Jira:** [PLAT-98](https://catalystsoftware.atlassian.net/browse/PLAT-98) (Story under [PLAT-96](https://catalystsoftware.atlassian.net/browse/PLAT-96) / E10) +**Size:** Small-to-medium galva (single primary workload; shared infra dependency) +**Program:** [galva-program.md](./galva-program.md) + +## Goal + +Research whether **catalyst-ingest** should migrate from its **dedicated Temporal deployment** (possibly older version) to a **shared Temporal platform**, including PostgreSQL requirements and EKS placement constraints. + +This document is a **research scaffold** — facts marked `TBD` must be verified before any delivery epic is opened. + +## Known facts (intake) + +| Field | Value | Verified | +|-------|-------|----------| +| Workload | `catalyst-ingest` | Partial — name only | +| EKS placement | Dedicated cluster, **same AWS account and VPC** as shared services | `TBD` | +| Workflow engine | Temporal (version `TBD` — possibly behind current shared standard) | `TBD` | +| Data store | PostgreSQL required | `TBD` | +| Languages | `TBD` (likely Java and/or Go — confirm from repo) | `TBD` | + +## Research questions + +### 1. Current state + +| Question | Notes | +|----------|-------| +| Which EKS cluster and namespace? | Same-VPC constraint affects network path to shared Temporal | +| Temporal version, namespace, and task queue layout? | Version skew drives SDK and server compatibility matrix | +| PostgreSQL: RDS vs in-cluster? Region? HA? | Co-migration vs split-brain risk | +| Workflow/activity inventory | Count, criticality, long-running vs cron | +| Who consumes ingest outputs? | Blast radius for cutover | + +### 2. Target state options + +| Option | Pros | Cons | +|--------|------|------| +| **A. Shared Temporal cluster, new namespace** | Lower ops cost; centralized upgrades | Noisy-neighbor; RBAC/isolation design needed | +| **B. Shared Temporal + version upgrade in place** | Single migration event | Higher risk; longer freeze window | +| **C. Stay dedicated; upgrade only** | Minimal blast radius | Does not capture shared-platform savings | + +**Deliverable:** Recommended option with rollback path. + +### 3. Cost and efficiency + +| Line item | Dedicated (today) | Shared (hypothesis) | +|-----------|-------------------|---------------------| +| Temporal compute / storage | `TBD` | `TBD` | +| PostgreSQL | `TBD` | `TBD` | +| Engineering toil (upgrades, on-call) | Qualitative | Qualitative | + +Coordinate with **FinOps (E04)** for utilization data — do not paste billing exports into git. + +### 4. Effort, risk, blast radius + +| Dimension | Initial hypothesis | +|-----------|-------------------| +| **Effort** | `TBD` — depends on SDK version gap and DB migration approach | +| **Risk** | Workflow nondeterminism on SDK upgrade; DB schema migration downtime | +| **Blast radius** | All workflows and downstream consumers of ingest artifacts | +| **Dependencies** | Shared Temporal readiness; VPC/security group rules; DB access (see [PLAT-95](https://catalystsoftware.atlassian.net/browse/PLAT-95)) | + +### 5. Suggested migration phases (draft) + +1. **Discover** — AST/repo analysis + IKG topology; verify intake table above +2. **Design** — target namespace, RBAC, DB strategy, compatibility matrix +3. **Pilot** — non-prod namespace on shared Temporal; shadow traffic or canary workflows +4. **Cutover** — phased queue migration with rollback triggers +5. **Decommission** — retire dedicated Temporal resources after soak period + +## Language / AST focus + +When analyzing the catalyst-ingest repo: + +- Locate Temporal **workflow** and **activity** registrations +- Map **PostgreSQL** access (ORM, migrations, connection pools) +- Identify **deployment config** (Helm/K8s, env vars — placeholders only in docs) +- Flag **version-sensitive** APIs (Temporal SDK changelog) + +## Out of scope + +- Executing production migration (opens under delivery epic after galva sign-off) +- Committing kubeconfig, connection strings, or customer data +- Bulk-creating Jira tasks without human review + +## Acceptance criteria (PLAT-98) + +- [ ] Intake table verified or gaps explicitly documented +- [ ] Target-state recommendation with cost/effort/risk summary +- [ ] Up to 5 follow-up delivery tasks **proposed** (not auto-created) +- [ ] All examples obfuscated; no secrets in git diff --git a/docs/research/galva-program.md b/docs/research/galva-program.md new file mode 100644 index 0000000..12b56d0 --- /dev/null +++ b/docs/research/galva-program.md @@ -0,0 +1,139 @@ +--- +title: "Galva — modernization research & migration planning" +tags: [eng-information, galva, modernization, migration] +last_updated: "2026-08-28" +status: draft +audience: [engineers, agents] +gaps: + - "totango/platform-galva repo does not exist yet — program brief lives in platform-tools until scaffolded" + - "Per-language AST tooling choices (Java, Python, Go) not finalized" + - "Intake automation and IKG integration paths TBD" +sources_to_synthesize: + - "argocd-tele: workspace/docs/jira-space-organization.md (E03 RFW, E04 FinOps, E09 IKG)" + - "platform-tools/docs/research/galva-catalyst-ingest.md (example inaugural galva)" +jira: "PLAT-96" +--- + +# Galva program brief + +**Jira Epic:** [PLAT-96](https://catalystsoftware.atlassian.net/browse/PLAT-96) (E10 — Galva) +**Future repo:** `totango/platform-galva` (not created in this pass) +**Board:** [PLAT](https://catalystsoftware.atlassian.net/jira/software/c/projects/PLAT/summary) + +## What is Galva? + +**Galva** is a platform program for **research and planning** on how to modernize, improve cost efficiency, migrate, and refactor older codebases. Galva does **not** execute production changes — it produces strategies, estimates, and risk analysis for humans to approve and deliver under separate epics. + +``` +Facts in (topology, deps, versions, constraints) + │ + ▼ +┌───────────────────┐ +│ Galva research │ AST / static analysis per language +│ + platform ctx │ deployment patterns, VPC/EKS limits +└─────────┬─────────┘ + │ + ▼ +Strategy out: savings · effort · risk · blast radius · phases +``` + +## Sizing: big vs small galvas + +| Size | Scope | Example | Typical output | +|------|-------|---------|----------------| +| **Small galva** | Single program, one service, narrow infra move | Move one worker to shared Temporal namespace | 1–2 week research; focused migration plan | +| **Big galva** | Service group, cross-cutting refactor, multi-cluster | Consolidate ingest pipeline onto shared platform services | Multi-sprint research; phased program with checkpoints | + +Use **effort**, **risk**, and **blast radius** together — a small code change with wide consumer impact may still be a **big galva**. + +## Intake template (facts in → strategy out) + +Every galva starts with a structured intake. Fill what is known; mark unknowns explicitly. + +| Field | Description | Example (placeholder) | +|-------|-------------|-------------------------| +| **Workload name** | Service or repo identifier | `catalyst-ingest` | +| **Languages / runtimes** | Primary stacks | Java 11, Go 1.21, Python 3.9 | +| **Deployment** | Cluster, namespace, account (no secrets) | Dedicated EKS in ``, same VPC as shared services | +| **Dependencies** | Data stores, queues, external APIs | PostgreSQL, Temporal ``, S3 | +| **Consumers** | Who depends on this workload | Downstream ``, batch jobs | +| **Constraints** | VPC, region, compliance, uptime | Same-VPC only; no cross-region DB today | +| **Cost signals** | Known waste or duplication | Dedicated Temporal cluster vs shared | +| **Goal** | What “better” looks like | Migrate to shared Temporal; upgrade workflow SDK | + +**Output sections** (every galva deliverable): + +1. Current-state architecture (verified or marked `TBD`) +2. Target-state options (≥2 where feasible) +3. Cost / efficiency comparison (qualitative OK for v1) +4. Effort estimate (T-shirt + dependencies) +5. Risk register + blast radius +6. Recommended phases + rollback strategy +7. Proposed follow-up delivery tickets (human review — no bulk create) + +## Language-agnostic analysis + +Galva must work across **Java, Python, Go**, and other stacks without assuming one toolchain. + +| Ecosystem | Analysis approach (research) | Derives | +|-----------|------------------------------|---------| +| **Java** | AST via parser (e.g. JavaParser) or build-tool graph (Maven/Gradle) | Service boundaries, Temporal workflow/activity usage, JDBC deps | +| **Python** | `ast` module, import graph, optional type hints | Worker entrypoints, ORM usage, async patterns | +| **Go** | `go/ast`, module graph, static call graph | Temporal SDK usage, gRPC clients, config loading | +| **Infra** | Terraform/K8s manifests, Helm values (from approved repos) | Cluster placement, IAM, network paths | + +Galva should **compose** language-specific extractors behind a common intake schema rather than one monolithic analyzer. + +## Platform context Galva needs + +Galva research quality depends on deployment and platform knowledge: + +| Source | Use | +|--------|-----| +| **IKG (E09)** | Service topology, AWS/K8s/TF relationships | +| **Castleguard** | Boundary and security findings | +| **FinOps (E04)** | Cost baselines and savings hypotheses | +| **RFW (E03)** | Proactive debt that migrations should not repeat | +| **Access docs** | How engineers reach clusters, DBs, shared services | +| **PLAT-95** | Teleport / multi-cluster / DB access patterns | + +## Relationship to other PLAT epics + +```mermaid +flowchart LR + E10[PLAT-E10 Galva] + E03[E03 RFW] + E04[E04 FinOps] + E09[E09 IKG] + DEL[Delivery epics E01/E02/...] + + E09 --> E10 + E04 --> E10 + E03 --> E10 + E10 -->|approved plans| DEL +``` + +- **Galva (E10)** — research and migration **planning** +- **RFW (E03)** — prevent repeat pain; galva findings often spawn RFW stories +- **FinOps (E04)** — savings validation; Zaha may feed cost signals into intake +- **Delivery epics** — execute approved migrations after galva sign-off + +## Privacy and content rules + +- No customer names, tenant IDs, or production hostnames in git or Jira bodies +- No secrets, tokens, or personal machine paths +- Use `~/.config//config.yaml` for local tooling references only +- Obfuscate examples: ``, ``, `` + +## Stories under E10 + +| Key | Summary | +|-----|---------| +| [PLAT-97](https://catalystsoftware.atlassian.net/browse/PLAT-97) | platform-galva — intake model and multi-language research scaffold | +| [PLAT-98](https://catalystsoftware.atlassian.net/browse/PLAT-98) | Galva: catalyst-ingest migrate to shared Temporal (example inaugural galva) | + +## Next steps + +1. Review and approve [PR for galva docs](https://github.com/totango/platform-tools/pulls) (branch `ab/galva-epic`) +2. Scaffold `totango/platform-galva` repo when ready (separate ticket) +3. Execute PLAT-98 research brief — [galva-catalyst-ingest.md](./galva-catalyst-ingest.md) diff --git a/jira/plans/examples/galva-epic-ticket-draft.md b/jira/plans/examples/galva-epic-ticket-draft.md new file mode 100644 index 0000000..c2baffb --- /dev/null +++ b/jira/plans/examples/galva-epic-ticket-draft.md @@ -0,0 +1,21 @@ +# Galva epic — PLAT-96 + +**Key:** [PLAT-96](https://catalystsoftware.atlassian.net/browse/PLAT-96) +**Type:** Epic (E10) +**Labels:** `plat-ref:epic-E10`, `galva`, `modernization`, `eng-information`, `migration` + +## Summary + +Galva — modernization research & migration planning + +## Child stories + +| Key | Summary | +|-----|---------| +| [PLAT-97](https://catalystsoftware.atlassian.net/browse/PLAT-97) | platform-galva — intake model and multi-language research scaffold | +| [PLAT-98](https://catalystsoftware.atlassian.net/browse/PLAT-98) | Galva: catalyst-ingest migrate to shared Temporal | + +## Canonical docs + +- `docs/research/galva-program.md` +- `docs/research/galva-catalyst-ingest.md` diff --git a/jira/plans/examples/snapshot-fixture.json b/jira/plans/examples/snapshot-fixture.json index e2074dd..99cdd65 100644 --- a/jira/plans/examples/snapshot-fixture.json +++ b/jira/plans/examples/snapshot-fixture.json @@ -17,6 +17,11 @@ "ref": "E09", "summary": "Infra Knowledge Graph (IKG) & Zaha UI", "labels": ["plat-ref:E09", "ikg"] + }, + { + "ref": "E10", + "summary": "Galva — modernization research & migration planning", + "labels": ["plat-ref:E10", "galva", "modernization"] } ], "issues": [ diff --git a/jira/rules/dependency-rules.yaml b/jira/rules/dependency-rules.yaml index ad22b95..e9d2358 100644 --- a/jira/rules/dependency-rules.yaml +++ b/jira/rules/dependency-rules.yaml @@ -46,3 +46,27 @@ rules: to: { epic_ref: E01 } link: relates_to reason: "RFW stories often harden E01/E02 delivery — link with relates to in Jira" + + - id: galva-consumes-ikg + from: { epic_ref: E10 } + to: { epic_ref: E09 } + link: consumes + reason: "Galva research uses IKG for service topology and deployment context" + + - id: galva-finops-signals + from: { epic_ref: E04 } + to: { epic_ref: E10 } + link: feeds + reason: "FinOps cost signals inform Galva intake and savings hypotheses" + + - id: galva-rfw-output + from: { epic_ref: E10 } + to: { epic_ref: E03 } + link: relates_to + reason: "Approved Galva plans often spawn RFW stories to prevent repeat migration pain" + + - id: galva-delivery-handoff + from: { epic_ref: E10 } + to: { epic_ref: E01 } + link: handoff + reason: "Galva produces plans; delivery epics execute approved migrations" diff --git a/jira/rules/epic-preservation.yaml b/jira/rules/epic-preservation.yaml index a3a1740..b3493af 100644 --- a/jira/rules/epic-preservation.yaml +++ b/jira/rules/epic-preservation.yaml @@ -38,6 +38,9 @@ epics: - ref: E09 summary_contains: "Infra Knowledge Graph" labels: [plat-ref:epic-E09, ikg] + - ref: E10 + summary_contains: "Galva" + labels: [plat-ref:epic-E10, galva, modernization, migration] on_conflict: action: skip_and_log