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 the internal architecture-protocol document. That protocol enumerates which classes of change require extra scrutiny: outbound HTTP sinks, auth, rate limiting, uploads, dependency manifests, and the deferral policy file. See Secure SDLC.
  • Invariants are documented in the internal security README. A PR that weakens a documented invariant must either restore an equivalent invariant or add a the deferral policy file 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 the internal security README. A PR that drops a pin below its floor fails review.
  • Accepted-risk deferrals live in the deferral policy 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 the internal hardening journal as they happen. The journal shape is fixed:

  • What: the action, in one sentence.
  • Why: the plan step (an early plan step, the IAM cleanup pass, 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 (an early plan step, the snapshot-policy step, …).

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 (the internal architecture-protocol document).
  • Invariants and dependency floors recorded in the internal security README.
  • the deferral policy file policy as a versioned, annually-renewed contract.
  • Step-by-step cloud-change journal (the internal hardening journal).

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 the health endpoint 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 the deferral policy file 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.