Repository Health Is More Than a Clean Worktree

A recent repository check found a checkout with no modified or untracked files. It also found that the local branch was 45 commits ahead and 48 behind its remote, while two local release tags disagreed with the corresponding remote tags. A normal fetch refused to overwrite those refs.

The worktree was clean, but the repository was not ready for an ordinary pull, merge, or push.

This distinction matters in production operations. Worktree cleanliness proves that local files match the current commit. It does not prove that the current commit belongs to the intended history, that the branch is synchronized with its authority, or that release tags identify the same objects across machines. Repository health is a broader systems claim.

Five layers of repository state

At JCN, we find it useful to evaluate repository state in layers:

  1. Worktree state: modified, deleted, and untracked files.
  2. Index state: changes staged for the next commit.
  3. Graph state: local tip, remote tip, merge base, and divergence.
  4. Ref state: branches, tags, recovery refs, and remote names.
  5. Authority state: the history and namespace intended to represent the product.

git status covers the first layers well. It cannot answer the authority question, and it only partially describes the graph. A clean checkout can still be behind, independently diverged, attached to a stale remote, or based on history that was rewritten upstream.

That is why ahead and behind counts should be treated as diagnostic signals rather than repair instructions. Forty-five local-only commits may represent unpublished work. They may also be pre-rewrite versions of changes already present upstream under different commit identities. The count alone cannot distinguish those cases.

Reconcile meaning before refs

For the repository in question, tree comparison showed that the remote product differed across 15 files, with 442 insertions and 84 deletions relative to the local tip. The remote included a deterministic demo path, CI dogfood proof, uploaded proof artifacts, shared receipt verification, supporting documentation, and model-neutral naming corrections.

Commit and tree inspection also showed that most of the apparent local-only history represented older forms of work already incorporated into the rewritten remote line. Merging or pushing the local branch would not have restored missing product work. It would have combined duplicated histories and made the authoritative line less clear.

The correct operating sequence is evidence-first:

  • Fetch without moving the active branch.
  • Record the local tip, remote tip, and merge base.
  • Inspect unique commits on both sides.
  • Compare the resulting trees.
  • Establish which line is authoritative.
  • Preserve the old refs under recovery names.
  • Apply the smallest justified mutation.
  • Re-run the comparison.

This sequence separates detection from mutation. Automated monitoring can gather graph and ref evidence broadly. Replacement of a branch tip or release tag remains an explicit, governed action.

Release tags need the same discipline

Tag conflicts deserve special handling because version names often feed build pipelines, package managers, installers, and documentation. When two objects share the same version label, forcing one over the other without preservation removes evidence about how the disagreement happened.

In this case, the old local tag objects were retained under archive refs before the normal version tags were refreshed from the canonical remote. The public namespace became coherent without making the previous state unreachable. The same pattern applies to branch replacement: name the old tip before aligning the branch.

This is a small operational practice with a large recovery benefit. Git objects are cheap to retain. Reconstructing an unnamed state after a mistaken reset is not.

Build health checks around authority

A useful repository health check should report more than dirty files. It should detect branch divergence, failed fetches, conflicting tags, moved remotes, and local branches without a clear upstream. It should identify the evidence needed for reconciliation while avoiding destructive automatic fixes.

The authority rules should be documented alongside the checks: canonical remote, release branch, tag ownership, and required recovery steps. Without those definitions, automation can report difference but cannot determine correctness.

The broader principle is that operational health depends on explainable state. A repository is healthy when its current relationship to the product is understood and its next transition is recoverable. A clean worktree is useful evidence, but it is only the beginning of that proof.