Change Topology

Use the subsystem IDs from Subsystem Topology as the canonical coordinate system for Git branches, PRs, labels, and release notes.

The goal is simple: a reviewer should be able to tell what changed, why it changed, what it can break, and how to verify it by looking at the subsystem coordinates before reading the diff.

Patch classes

Patch class	When to use it	Allowed scope	Default expectation
leaf	One focused behavioral or maintenance change inside one leaf subsystem	One subsystem ID such as DOM.combo-operations or PLAT.observability	Preferred default
parent	Coordinated work across sibling leaves in one plane	One plane such as EXP.* or ORCH.*	Use when a feature is too coupled to split safely
cross-plane	A change that must cross major subsystem planes	Two or more planes, usually with an explicit primary subsystem	Should usually be implemented as a patch train
topology	Changes the architecture reference, contracts, boundaries, or governance rules themselves	DATA.*, PLAT.*, GOV.*, or the topology docs	Requires explicit architectural intent

Core GitOps rules

1. Every PR gets one primary subsystem ID.
2. Secondary subsystem IDs are optional, but if there are more than two, the change is usually too large.
3. leaf patches are the norm. parent, cross-plane, and topology patches need a short justification in the PR body.
4. If a change modifies shared contracts, schemas, or job payloads, land the contract-compatible part before the consumer/UI changes.
5. If a change alters operational behavior, update the relevant scenario, runbook, ADR, or topology doc in the same patch or the immediately adjacent patch.
6. Avoid mixed maintenance PRs. A retry fix for asset ingest and a UI cleanup for combo templates should not ship together just because both are “small.”

Preferred patch train order

When a feature spans multiple planes, split it in dependency order.

Sequence	Typical contents	Common primary subsystem
1	Contract, schema, DTO, event payload, or migration groundwork	DATA.contracts-and-schema, DATA.domain-store
2	Producer, orchestrator, or integration-side behavior	ORCH.shopify-sync, ORCH.asset-and-export-jobs, ORCH.casestry-and-release
3	Domain rules and API behavior	DOM.*
4	Staff-facing UI/workbench changes	EXP.*
5	Alerts, runbooks, rollout switches, secrets, and cutover wiring	PLAT.*, GOV.*

This ordering mirrors the repo’s architecture pressure points. Data and orchestration changes have wider blast radius than UI changes, so they should stabilize first.

Branch and title conventions

Use a branch shape that exposes both change type and subsystem.

<type>/<subsystem-id>/<short-slug>

Examples:

• feature/DOM.combo-operations/add-confidence-thresholds
• fix/ORCH.asset-and-export-jobs/retry-dropbox-timeouts
• maintenance/PLAT.observability/tighten-run-alerts
• docs/GOV.scenarios-and-architecture/add-subsystem-topology

Use PR titles that keep the subsystem visible:

[DOM.combo-operations] add confidence threshold editing
[ORCH.asset-and-export-jobs] fix delayed retry behavior
[PLAT.identity-and-access] remove admin123 bypass

Suggested labels

Use labels as orthogonal dimensions instead of baking everything into one tag.

• subsystem:DOM.combo-operations
• subsystem:ORCH.shopify-sync
• type:feature
• type:fix
• type:maintenance
• shape:leaf
• shape:cross-plane
• risk:low, risk:medium, risk:high

If you only adopt one label family, adopt the subsystem:* family first.

Label source of truth

The repo carries the label catalog and sync utility needed to keep GitHub aligned with the topology:

• Label catalog: .github/labels.json
• Sync command: npm run labels:sync
• Dry run: npm run labels:dry-run
• Script: scripts/sync-github-labels.mjs

Agent contributors should also use the repo-local SOP skill:

• agent-skills/subsystem-pr-sop/SKILL.md

Review routing rules

• EXP.* changes should be reviewed against the user workflow they alter, not only against component style.
• DOM.* changes should be reviewed by someone who understands the business rule being encoded.
• ORCH.* changes should always call out retry, idempotency, and replay behavior.
• DATA.* changes should call out backward compatibility, migration sequencing, and data repair expectations.
• PLAT.* changes should call out deployment order, secrets, and rollback posture.
• GOV.* changes should point to the runtime or operational changes that forced the documentation update.

Example patch trains

Example 1: new combo suggestion signal

1. DATA.contracts-and-schema: add the new scoring field to the shared contract and documentation.
2. DOM.combo-operations: compute and persist the new signal in suggestion generation.
3. EXP.creative-workbench: surface the signal in the suggestions UI.
4. GOV.scenarios-and-architecture: update the combo suggestion scenario and any ADR notes if the scoring rule is architecture-significant.

Example 2: asset ingest reliability fix

1. ORCH.asset-and-export-jobs: fix retry/backoff logic for Dropbox fetch failures.
2. DOM.asset-redundancy: tighten ingest status semantics if user-facing behavior changes.
3. PLAT.observability: add or refine alerts and runbook notes for repeated retry failures.

Example 3: auth cutover from current state to target state

1. PLAT.identity-and-access: add Access verification and transitional middleware.
2. DOM.*: remove route-local assumptions tied to Passport or Supabase identity.
3. EXP.shell: remove auth UI and protected-route behavior that no longer applies.
4. GOV.scenarios-and-architecture: update authentication, topology, and migration docs.

Hotfix policy

Hotfixes should still respect subsystem topology.

• Prefer one leaf hotfix over a mixed emergency PR.
• If a hotfix must cross planes, keep it to the minimum viable path and schedule a follow-up cleanup PR immediately.
• A production hotfix that changes DATA.* or PLAT.* should include an explicit rollback note.

Definition of done for a topology-aware PR

• Primary subsystem ID is declared.
• Patch class is declared.
• Verification is scoped to the affected subsystem and any direct dependents.
• Docs are updated when behavior, contracts, or operations changed.
• Reviewers can explain the blast radius in subsystem terms without reverse-engineering the whole repo.

The repo PR template is intentionally aligned to this page.