Skip to content

State read back is labelled exact, advanced, diverged or different_context against git

Whenever a task record or a handover is read, its recorded head and branch are compared with the current checkout and labelled: exact (same commit), advanced (the recorded commit is an ancestor of the current one — normal progress), diverged (history was rewritten or the record is stale), different_context (another branch). Stale state is detected and named, never silently trusted.

guaranteed Deterministic and blocking. Implemented, and a behavioural test proves it.

What it means

Whenever a task record or a handover is read, its recorded head and branch are compared with the current checkout and labelled: exact (same commit), advanced (the recorded commit is an ancestor of the current one — normal progress), diverged (history was rewritten or the record is stale), different_context (another branch). Stale state is detected and named, never silently trusted.

How it works

mj_git_label in lib/common.sh compares branches, then commits, then runs git merge-base --is-ancestor <recorded> HEAD. check fails on diverged and different_context; handover --resolve prints the label under Git state: together with the record; watch reports either as state drift.

How to see it

majordomus start "t" --scope lib && git commit -qam step
majordomus check                      # OK state … — advanced (head …)
git checkout -b elsewhere && majordomus check   # FAIL state … — recorded on branch 'main', now on 'elsewhere'

What it does not cover

The label describes git history, not whether the content of the record is still true. A Current State section can be wrong on an exact commit.

Why it exists

Every other "memory file" scheme studied had no staleness signal at all; notes carried dates in their names that disagreed with their content and nothing compared either with git. Read-time labelling was the one mechanism that made stored state safe to act on.

Detail rendered from docs/claims/divergence-label.md.

Provenance

defined in
read it on this site · docs/SCHEMAS.md
implemented in
lib/common.sh
proved by
test/cases/04_start_check.sh
claim id
divergence-label

Verify it yourself

The test runs in a disposable temporary repository and asserts the behaviour, not a string in the source.

from a clone of the repository
bash test/run.sh 04_start_check

Where this claim is used

Related claims same implementation

The moments this answers