A regulated Git workflow is not a slower Git workflow.
It is a workflow where every material change has traceable intent,
reviewed authorization, verified outcome, immutable release identity,
and recoverable operational history.

What was changed?
Why was it changed?
Who requested it?
Who authored it?
Who reviewed it?
What risks were considered?
What tests ran?
What artifact was produced?
What release included it?
What environment received it?
Can we prove all of the above after the fact?

change_id: CASE-48291
risk_class: sensitive-authz-change
source_branch: users/alya/case-48291-fga-escalation-rule
pull_request: https://git.example.com/reg-platform/pulls/9182
merge_commit: 7c3b09e2c6b4f3d1a3e0f8a2c8e9e3a172e54d11
release_tag: reg-platform-v2026.07.1
artifact_digest: sha256:8d6c...
deployment:
  environment: production
  deployed_at: 2026-07-07T03:21:00+07:00
  deploy_id: DEPLOY-22931
approvals:
  code_owner: platform-authz-team
  risk_owner: compliance-ops
  security: appsec
verification:
  unit: passed
  integration: passed
  migration_dry_run: passed
  audit_log_contract: passed
rollback:
  strategy: feature-flag-disable + revert commit if required

Private history may be reshaped for reviewability.
Shared/protected/audited history must not be rewritten without formal incident handling.

If a ref has become evidence, mutation requires change control.
If a commit has become artifact input, replacing it creates provenance risk.
If a tag has been published, moving it is a release integrity incident.

Use Git controls for Git state.
Use CI controls for verification.
Use deployment controls for environment mutation.
Use ticket/change records for business authorization.
Bind all identities together.

Small change should not need a ceremony.
Risky change should not escape with a normal-code path.

main                  protected integration line
release/*             protected stabilization/maintenance line
users/* or feature/*   private or semi-private proposal branches
hotfix/*              short-lived emergency branch with incident link

support/customer-*    long-lived support branch for contracted version line
archive/*             read-only historical branch namespace

dev
qa
staging
prod

Source branches describe code evolution.
Deployment records describe environment state.
Release tags describe released source identity.
Artifacts describe built output identity.

main
release/*
support/*
v*
*-rc.*

main:
  allow_force_push: false
  allow_delete: false
  require_pull_request: true
  require_code_owner_review: true
  require_status_checks: true
  require_signed_commits: recommended_or_required_based_on_org
  require_linear_history: org_decision
  require_conversation_resolution: true
  require_merge_queue: recommended_for_busy_repos
  restrict_bypass: true

release_tags:
  pattern: "v*"
  allow_create:
    - release-bot
  allow_update: false
  allow_delete: false
  require_signed_tag: true

Protected branch prevents unauthorized ref movement.
Signed commit/tag helps verify provenance.
CI proves selected properties.
None of these alone proves business correctness.

<area>: <imperative summary>

<why this change is needed>
<what behavior changes>
<risk / compatibility notes>
<verification performed>

Change-Id: CASE-48291
Risk-Class: authz-sensitive
Reviewed-By: platform-authz-team

authz: deny escalation when case is externally locked

External lock state is imported from the enforcement case registry.
Before this change, escalation workflow only checked local assignment status,
allowing a stale UI path to attempt escalation after external lock.

The guard is now evaluated before transition creation and emits an audit event
when escalation is denied.

Verification:
- added unit tests for locked/unlocked matrix
- added integration test for stale UI escalation attempt
- verified audit event contract in CaseEscalationAuditIT

Change-Id: CASE-48291
Risk-Class: authz-sensitive

fix bug
update logic
changes
misc
WIP

## Change

What changed?

## Intent

Why is this change needed?

## Change ID

- Ticket / CR:
- Incident, if emergency:

## Risk Class

- [ ] cosmetic/docs
- [ ] low-risk code
- [ ] runtime behavior
- [ ] authn/authz/security-sensitive
- [ ] migration/data
- [ ] dependency/supply-chain
- [ ] CI/CD/release pipeline

## Verification

- [ ] unit tests
- [ ] integration tests
- [ ] migration dry-run
- [ ] rollback tested or documented
- [ ] audit event checked
- [ ] security review required

## Release / Rollback

- Release note needed:
- Feature flag:
- Rollback strategy:

## Evidence

- CI run:
- Build artifact:
- Related dashboards/log queries:

# Authentication and authorization
/src/main/java/com/example/security/ @platform-security @authz-owners
/src/main/java/com/example/authz/    @platform-security @authz-owners
/config/permissions/                @platform-security @compliance-ops

# Database migrations
/db/migration/                       @data-platform @service-owner

# CI/CD and release machinery
/.github/workflows/                  @platform-engineering @appsec
/scripts/release/                    @release-engineering

# Runtime configuration
/config/production/                  @service-owner @sre

Choose the merge method based on the unit you want to audit and revert.

Production is running main.
Production is running release/current.
Production is running latest.

Production is running artifact sha256:...
Artifact was built from signed tag v2026.07.1.
Tag resolves to commit 7c3b09e...
Build was performed by release-bot under pipeline run 918273.

{
  "service": "case-enforcement-api",
  "version": "2026.07.1",
  "gitCommit": "7c3b09e2c6b4f3d1a3e0f8a2c8e9e3a172e54d11",
  "gitTag": "v2026.07.1",
  "buildTime": "2026-07-07T03:12:11+07:00",
  "artifactDigest": "sha256:8d6c...",
  "dirty": false
}

#!/usr/bin/env bash
set -euo pipefail

commit="$(git rev-parse --verify HEAD^{commit})"
tag="${RELEASE_TAG:-}"

if ! git diff --quiet || ! git diff --cached --quiet; then
  echo "Refusing release build from dirty working tree" >&2
  exit 1
fi

if [ -n "$tag" ]; then
  tag_commit="$(git rev-parse --verify "$tag^{commit}")"
  if [ "$commit" != "$tag_commit" ]; then
    echo "Release tag $tag does not point to HEAD" >&2
    exit 1
  fi
fi

cat > build/git-version.json <<JSON
{
  "commit": "$commit",
  "tag": "$tag",
  "dirty": false
}
JSON

Emergency path may reduce waiting time.
It must not erase identity, approval, verification, or post-facto review.

## Emergency Change

Incident ID:
Customer impact:
Why normal path is too slow:
Minimality justification:
Approver:
Post-facto review due by:
Forward-port/backport plan:

We can revert the commit, so the migration is reversible.

change_id: ENF-18291
change_type: state-machine-transition-rule
entity: EnforcementCase
transition: INVESTIGATION_OPEN -> ESCALATED_REVIEW
risk:
  - unauthorized escalation
  - missed audit event
  - incorrect deadline recalculation
  - legacy case compatibility
required_reviewers:
  - case-domain-owner
  - authz-owner
  - audit-log-owner
  - qa-regression-owner
required_tests:
  - transition_matrix_test
  - permission_denied_test
  - audit_event_contract_test
  - legacy_case_migration_test

## Domain Impact

Transition affected:
- INVESTIGATION_OPEN -> ESCALATED_REVIEW

Invariants:
- external lock prevents escalation
- denied escalation emits audit event
- reviewer cannot escalate own assigned case
- legacy cases without external lock remain compatible

Verification:
- TransitionMatrixTest
- EscalationPermissionIT
- AuditEventContractTest

git log --all --grep='Change-Id: CASE-48291' --format='%H %s'

git tag --contains 7c3b09e2c6b4f3d1a3e0f8a2c8e9e3a172e54d11

git log --oneline --first-parent v2026.06.2..v2026.07.1

git log --name-status --oneline v2026.06.2..v2026.07.1 -- \
  src/main/java/com/example/authz \
  config/permissions

git tag -v v2026.07.1

git rev-parse --verify v2026.07.1^{commit}

for tag in $(git tag -l 'v*'); do
  git rev-parse "$tag^{commit}"
done | sort

release-evidence/
  release.yaml
  git/
    tag.txt
    tag-verification.txt
    commit.txt
    commits-since-previous-release.txt
    changed-sensitive-paths.txt
  ci/
    pipeline-run.json
    test-summary.xml
    security-scan.json
  artifact/
    digest.txt
    sbom.json
    provenance.json
  deployment/
    staging-deploy.json
    production-deploy.json
  approvals/
    release-approval.json
    emergency-exceptions.json

release: v2026.07.1
previous_release: v2026.06.2
source_commit: 7c3b09e2c6b4f3d1a3e0f8a2c8e9e3a172e54d11
source_tag_verified: true
artifact_digest: sha256:8d6c...
build_dirty: false
created_by: release-bot
deployed_to:
  staging: 2026-07-06T20:00:00+07:00
  production: 2026-07-07T03:21:00+07:00
exceptions: []

Ticket approved feature A, PR implements feature A plus unrelated authz behavior.

Production artifact says source=main.

v2026.07.1 resolves differently in two clones.

Production fix exists only on release branch.
Main does not contain it.
Next release regresses.

Production schema/data changed outside migration repository.

Individual commit trailers disappear after squash.

Every production artifact must reference exactly one Git commit SHA.
Every release tag must be annotated and signed.
Every production deployment must reference artifact digest and release tag.
No protected branch may be force-pushed.
No release tag may be moved or deleted after publication.
Every authz-sensitive path change must be reviewed by authz owners.
Every database migration must include rollback or compensation notes.
Every emergency change must link to an incident and receive post-facto review.
Every dependency update must pass supply-chain verification.

refs:
  protected:
    - main
    - release/*
    - support/*
  immutable_tags:
    - v*
  private:
    - users/*
    - feature/*

change_classes:
  authz-sensitive:
    owners:
      - platform-security
      - authz-team
    checks:
      - authz-matrix-tests
      - audit-event-contract-tests
  migration:
    owners:
      - data-platform
    checks:
      - migration-dry-run
      - rollback-plan-present

#!/usr/bin/env bash
set -euo pipefail

body_file="${PR_BODY_FILE:-pr-body.md}"

required=("Change ID" "Risk Class" "Verification" "Rollback")

for field in "${required[@]}"; do
  if ! grep -qi "${field}" "$body_file"; then
    echo "PR body missing required section: $field" >&2
    exit 1
  fi
done

#!/usr/bin/env bash
set -euo pipefail

base="${BASE_SHA:?}"
head="${HEAD_SHA:?}"

if git diff --name-only "$base...$head" | grep -E '^(src/.*/authz|config/permissions/)'; then
  echo "Authz-sensitive files changed. Security owner approval required." >&2
  # In real CI, query platform approval API.
fi

#!/usr/bin/env bash
set -euo pipefail

release_tag="${1:?release tag required}"
previous_tag="${2:?previous tag required}"
out="release-evidence/$release_tag"
mkdir -p "$out/git"

git rev-parse --verify "$release_tag^{commit}" > "$out/git/commit.txt"
git tag -v "$release_tag" > "$out/git/tag-verification.txt" 2>&1 || true
git log --first-parent --oneline "$previous_tag..$release_tag" > "$out/git/commits-since-previous-release.txt"
git diff --name-status "$previous_tag..$release_tag" -- \
  src/main/java/com/example/authz \
  config/permissions \
  db/migration \
  .github/workflows > "$out/git/changed-sensitive-paths.txt"

workflow:
  integration_branch: main
  merge_method: merge_commit_or_squash_but_standardized
  feature_branch_lifetime: <= 3 days preferred
  release_branch_lifetime: bounded by release cycle
  force_push_protected_refs: forbidden
  release_tag_mutation: forbidden
  emergency_change: allowed_with_incident_and_post_review

required_controls:
  main:
    - pull_request
    - required_checks
    - code_owner_review
    - merge_queue_if_high_velocity
  release_tags:
    - annotated_tag
    - signed_tag
    - protected_tag
  artifacts:
    - commit_sha
    - artifact_digest
    - dirty_false
  sensitive_changes:
    - owner_review
    - risk_specific_tests
    - rollback_or_compensation_plan

intent -> proposal -> review -> verification -> protected integration
-> immutable release identity -> artifact identity -> deployment evidence
-> runtime traceability -> incident/recovery evidence