Skip to content

majordomus check

Is the current task still consistent with its policy, its scope and this checkout?

Is the current task still consistent with its policy, its scope and this checkout?

  • read-only
  • task
  • active task required
  • --json

Read-only unless --checkpoint is given, which records a checkpoint after the checks run.

Syntax

majordomus check [--explain] [--overlap] [--checkpoint] [--rule <id>] [--json]

Lifecycle

  1. Set up
  2. Begin
  3. Work
  4. Verify
  5. Conclude
  6. Inspect

Other commands at this stage:usecase.

Reads

  • .ai/repo/policy.yaml
  • .ai/repo/profiles/
  • .ai/local/state/current.yaml
  • .ai/local/state/open-questions.md
  • git status
  • git diff

Writes

Nothing. This command is read-only.

Exit codes

Only the codes this command can produce. The full contract is on the commands index.

  • 0 ok
  • 2 usage
  • 10 contract unmet
  • 12 missing artifact
  • 13 internal error

Is this task still consistent with what it claimed?

check is read-only and answers three questions at once: does the record still describe this checkout, is the work inside the claimed scope, and is anything blocking acceptance.

Work inside the claimed scope

work stays in scope
yes

Given this repository

# ... and an active task scoped to lib, with work done inside that scope.
. "$FIXTURE_SETUP/installed.sh"
"$MJ" start "narrow the parser" --scope lib >/dev/null
echo work >> lib/a

Run

$ majordomus check

Output contains

  • OK scope
  • 0 failing

exit 0

Every finding is printed, not only the failures, so the report says what was checked rather than only what went wrong.

A file changed that the task never claimed

work stays in scope
no

Given this repository

# An active task scoped to lib, with a change under docs that the task never claimed.
. "$FIXTURE_SETUP/active-task.sh"
echo stray >> docs/d

Run

$ majordomus check

Output contains

  • FAIL scope
  • docs/d

exit 10

check names the individual file, because the useful question is which change to move or claim — not merely that something is wrong.

Reference

Is the current task consistent with policy, scope, and state? Read-only.

Checks:

  • state/current.yaml exists and parses; else 12.
  • Git divergence label for the record: exact, advanced, diverged, different_context. diverged and different_context are findings.
  • Touched files (git status --porcelain plus git diff --name-only <base>..HEAD) are within the claimed scope. Any outside → finding.
  • Checkpoint age against the profile's checkpoint_interval (WARN, never FAIL).
  • Files under .ai/ and the projection targets are always in scope.
  • --checkpoint updates checkpoint_at and appends task.checkpoint to the ledger: the one documented write in an otherwise read-only command.
  • state/open-questions.md has no unresolved entry for this task.
  • --explain prints the effective merged policy and profile for this task and exits 0.
  • --overlap prints claim containment against other worktrees.

Exit 0 with no FAIL findings, 10 with any, 12 with no active task. Intended for a worker to run before claiming completion, and for a person to run any time.

$ majordomus check
OK   state      t-20260903-193012-a4f1 — exact (head 3f2a9c1)
FAIL scope      config/secrets.example — outside claimed scope (lib/auth)  [reproduce: git status --porcelain; git diff --name-only 3f2a9c1 HEAD]
OK   checkpoint 7m ago, interval 15m
OK   blockers   none open
check: 4 finding(s), 1 failing

Evidence

Every case below runs in CI on Linux and macOS. The site refuses to build if a public command has no behavioural case, no negative case, or no demonstration.

Behaviour

Failure modes

Implementation

Demonstration

Guarantees this command carries