Worked Example: End-to-End Governance Workflow

NON-NORMATIVE. This is a walkthrough example. Normative rules are in morphism-kernel.md.

This page walks through the full lifecycle of a change: branch, commit, hooks, push, PR, CI, drift-check, merge, post-merge, and release. Use it to verify your setup and as a reference for new joiners.

---

1. Create a Branch

Ticket: MOR-42 — Add onboarding link to README.

git checkout main
git pull origin main
git checkout -b docs/readme-onboarding-link

Validate branch name (pre-push will do this too):

python3 scripts/validate_branch.py
# Valid branch name: docs/readme-onboarding-link

---

2. Make Changes and Commit

Edit README.md (e.g. add a link to docs/operations/onboarding.md).

Stage and commit. The commit-msg hook runs automatically:

git add README.md
git commit -m "docs(readme): add onboarding link (Refs: MOR-42)"

If you use an invalid message:

git commit -m "update readme"
# Commit message validation failed:
#   - Invalid format: expected <type>(<scope>): <subject>
# See docs/governance/commit-grammar.bnf

The pre-commit hook runs next (.morphism/hooks/pre-commit-validation.sh and scripts/policy_check.py --mode pre-commit). Fix any reported issues (e.g. secrets, lint).

---

3. Push and Open a PR

git push -u origin docs/readme-onboarding-link

The pre-push hook runs (.morphism/hooks/pre-push-validation.sh and scripts/policy_check.py --mode pre-push), including branch validation and commit checks.

Open a PR targeting main. The labeler workflow adds labels (e.g. docs) from changed paths. Required status checks run:

• CI: ts-lint-typecheck, ts-test, ts-build, py-lint-typecheck, py-test, backlog-stale
• Drift check: drift (drift_detector, validate-registry, ssot_verify, docs_sync --check)

If SSOT drift is detected (e.g. you changed an atom file but not the registry, or vice versa), the drift-check workflow fails and merge is blocked. Fix by running:

python3 scripts/ssot_extract.py   # if you changed governance source
python3 scripts/ssot_verify.py
python3 scripts/docs_sync.py --check

---

4. Merge and Post-Merge

After review and approval, merge the PR (squash merge preferred). On your machine, pull main:

git checkout main
git pull origin main

The post-merge hook runs (.morphism/hooks/post-merge-sync.sh), which can sync local state (e.g. inventory) after merge.

---

5. Tag and Release

To cut a release:

git tag -a v1.2.0 -m "Release v1.2.0"
git push origin v1.2.0

The release workflow (.github/workflows/release.yml) runs: full CI, then create a GitHub Release with generated notes. No manual artifact upload required when using the default workflow.

---

6. Safe Rollback

If a bad deploy goes out:

• Revert: git revert -m 1 <merge_commit> and push; open PR, merge. CI and drift-check run on the revert.
• Redeploy previous tag: Re-deploy the artifact or commit associated with the previous tag (e.g. v1.1.0). Document in Incident Response.

---

Summary

Step	Hook / workflow	What runs
commit	commit-msg	validate_commit.py
commit	pre-commit	.morphism pre-commit + policy_check --mode pre-commit
push	pre-push	.morphism pre-push + policy_check --mode pre-push
PR	CI	typecheck, lint, test, build, backlog-stale
PR	Drift check	drift_detector, validate-registry, ssot_verify, docs_sync --check
merge	post-merge	.morphism post-merge-sync
tag push	Release	Full CI + GitHub Release

SSOT drift blocks merge until ssot_verify.py and docs_sync.py --check pass. Use the commands above and MORPHISM Framework for break-glass and audit procedures.

%% End-to-end governance lifecycle from branch to release
flowchart TD
    A[Create branch] --> B[Make changes]
    B --> C[git commit]
    C --> D{commit-msg hook}
    D -- Fail --> C
    D -- Pass --> E{pre-commit hook}
    E -- Fail --> B
    E -- Pass --> F[git push]
    F --> G{pre-push hook}
    G -- Fail --> B
    G -- Pass --> H[Open PR]
    H --> I[CI: typecheck, lint, test, build]
    H --> J[Drift check: ssot_verify, docs_sync]
    I --> K{All gates pass?}
    J --> K
    K -- Fail --> B
    K -- Pass --> L[Merge to main]
    L --> M[post-merge hook]
    M --> N[Tag and release]