Shared Guardrails via Git Subtree

[Git-on-my-level]

Ticket: Shared Guardrails via Git Subtree

Context

We currently maintain separate repositories for each deployment network (e.g., sonic testnet, sonic mainnet). This isolation was chosen for safety so the code deployed to each chain is auditable and unchanged. However, it also means improvements to guardrails, deployment scripts, or utility code in one repo do not automatically benefit the others. Recent debugging—e.g., hardhat deploy issues around IncentivesProxy—showed how fixes, static analysis checks, and scripts need to be replicated network by network.

Objective

Introduce a “safety-kit” shared component that contains common guardrails (scripts, CI workflows, hooks, deployment validators) and make it available to each network repo via git subtree. This should allow:

• Propagation of global guardrails and utilities with a predictable, auditable workflow.
• Preservation of per-network repositories as sources of truth for deployments.
• Extensibility for future improvements, including possible automated promotion flows.

Scope & Deliverables

1. Safety-Kit Repo Structure

   • Create a dedicated repository housing shared tooling: static analysis scripts (e.g., find-hardcoded-deploy-ids.ts), Husky or lint configs, documentation, and helper modules (typescript/deploy-utils).
   • Provide package manifest(s) or instructions so network repos can easily leverage these scripts.

2. Subtree Integration Workflow

   • Document how each network repo should add the safety-kit via git subtree, e.g., git subtree add --prefix shared/guardrails <repo> main.
   • Define the update procedure (git subtree pull) with best practices for review, testing, and merging.
   • Ensure no automatic syncing; updates are intentional to maintain deployment safety guarantees.

3. CI & Static Analysis Wiring

   • Update network repos to execute the shared scripts within their existing CI/pipeline (e.g., run ts-node shared/guardrails/find-hardcoded-deploy-ids.ts before deployments).
   • Optionally add pre-commit or pre-push hooks referencing the shared carpet.
   • Confirm guardrails run consistently across all network repos and highlight failures in PRs.

4. Super Monorepo Trial

   • Prototype a meta repository that includes each network repo as a subtree (or references them via submodules) to validate the shared safety-kit workflow.
   • Use it to test subtree pushes/pulls and ensure there is no cross-network contamination.
   • Evaluate whether this super repo should be used for development/testing or just as a proof point.

5. Documentation & Release Process

   • Draft documentation explaining how to consume the safety-kit, update it, and troubleshoot merges.
   • Outline a simple release cadence (e.g., after safety-kit merges, run a script to open PRs in each network repo).
   • Ensure instructions cover verifying guardrails locally and in CI before mainnet deployments.

Considerations

• Guardrails must avoid false positives such as legitimate contract-name literals or dependencies.
• Tools should accommodate limited network access (some repos have restricted networking). Prefer local scripts that don’t rely on external APIs.
• Maintain idempotency and permissions awareness in existing deployment scripts.
• Watch for interactions with existing repo-specific rules. Shared guardrails should complement, not override, local requirements.

Success Criteria

• All network repos contain the shared guardrails under a shared/guardrails (or similar) subtree.
• Running the shared static analysis (e.g., hard-coded ID detector) produces consistent results across repos.
• Documentation exists for updating the safety-kit and propagating changes.
• Initial updates tested successfully via the super monorepo or equivalent staging area.