Skip to content

Change Management

Statement

Changes to ClaimGuard's production code and cloud configuration follow a lightweight but auditable process: every code change ships through a pull request against a branch-protected main with required review, and every security-relevant cloud change is recorded step-by-step in a hand-written journal that captures the action, the motivation, the exact commands, and the verification.

The process is deliberately small for the team's current size. It is sufficient for SOC 2 Type I evidence (decisions are documented, reviewed, and reproducible) and is structured so it can grow into a heavier change control workflow when scale or compliance scope demands it.

Implementation

Code changes

  • Branch-protected main. Direct pushes are blocked; merges land through pull requests on GitHub.
  • Required pull request review. A second engineer (or, for the security remediation pass, a multi-agent /ultrareview cycle followed by founder review) signs off before merge.
  • Squash or merge commit retains the PR title. This keeps git log scannable as a release history.
  • Security-relevant changes follow docs/security/PROTOCOL.md. That protocol enumerates which classes of change require extra scrutiny: outbound HTTP sinks, auth, rate limiting, uploads, dependency manifests, and the .snyk policy file. See Secure SDLC.
  • Invariants are documented in docs/security/README.md. A PR that weakens a documented invariant must either restore an equivalent invariant or add a .snyk entry with a documented reason.

Dependency changes

Dependency upgrades follow a separate sub-process documented under Dependency management:

  • Load-bearing pin floors (e.g., react-router-dom ^6.30.3, urllib3 >=2.6.3) are part of docs/security/README.md. A PR that drops a pin below its floor fails review.
  • Accepted-risk deferrals live in the root .snyk file with created: and expires: (one year) fields, enforcing annual re-review.

Cloud changes

GCP changes that affect security posture (firewall rules, IAM bindings, service accounts, secrets, snapshots, instance configuration) are recorded in docs/security/HARDENING-LOG.md as they happen. The journal shape is fixed:

  • What: the action, in one sentence.
  • Why: the plan step (A0.1, A1.4-step1, etc.) or motivation.
  • Commands: the exact, reproducible gcloud invocation — operators can replay or undo by reading the entry.
  • Verify: the command and expected output that confirmed the change landed.
  • Notes: surprises, follow-ups, and anything an auditor would ask about.

This is the canonical record. Trust portal docs link back to it for evidence rather than duplicating the content.

Plan-tracked changes

Larger, multi-step initiatives (the GCP hardening pass; the trust portal itself) are pre-planned in ~/.claude/plans/ and executed in the order the plan prescribes, with cross-track sequencing recorded so a doc never ships a claim that contradicts the actual posture. The plan is not checked into the repo, but every step that lands has a corresponding HARDENING-LOG.md entry that names its plan ID (A0.3, A2.2, …).

Emergency changes

There is no separate emergency-change path today. If a production-impacting change must ship outside normal review, the engineer making the change is expected to:

  1. Make the change.
  2. Open a PR retroactively with the same shape as a normal change (description, justification, links).
  3. Add a HARDENING-LOG.md entry the same day if the change is security-relevant.

This has not been exercised in anger and is documented here for completeness; the absence of a pre-formalized break-glass workflow is a known gap (see below).

Status

implemented — verified 2026-04-29.

What's in place:

  • Branch protection on main with required PR review.
  • Documented security-change protocol (docs/security/PROTOCOL.md).
  • Invariants and dependency floors recorded in docs/security/README.md.
  • .snyk policy as a versioned, annually-renewed contract.
  • Step-by-step cloud-change journal (docs/security/HARDENING-LOG.md).

Known gaps

  • No formal change advisory board (CAB). Reviews happen at the PR level; there is no scheduled CAB meeting. Appropriate at current team size; revisit if compliance scope or team size grows.
  • No formal change ticketing (e.g., Jira changes / ServiceNow). Change records live in PRs and the hardening log. SOC 2 Type I evidence is still derivable, but a ticketing tool would make cross-referencing easier in a Type II audit.
  • No automated post-deploy verification. Smoke-tests on /api/health are run manually after maintenance windows. Adding a CI job that calls the verify-step from the matching HARDENING-LOG.md entry is a roadmap item.
  • No formalized emergency-change path. Documented as best-effort above; no break-glass run-book yet.

Roadmap

  • CI integration of Snyk Open Source + Snyk Code so the dependency and SAST signals are gating, not advisory.
  • Pre-commit hooks for the documented invariants (e.g., flag a raw fetch( outside the allowlist; flag a .snyk entry without a created:/expires: pair).
  • Change ticketing tool if SOC 2 Type II scope demands it.
  • Tabletop emergency-change exercise before SOC 2 fieldwork to validate the documented best-effort path actually works under pressure.