Skip to content

majordomus decision

Record a decision that was made between real alternatives, with its reason, and read them back.

Record a decision that was made between real alternatives, with its reason, and read them back.

  • state-mutating
  • memory
  • active task optional

An entry is never edited or deleted. --supersedes records that a later decision replaced an earlier one, leaving both readable.

Syntax

majordomus decision add "<what was decided>" --why "<rationale>"

Lifecycle

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

Other commands at this stage:context, checkpoint, question, prompt, evidence, skills, capture.

Reads

  • .ai/local/state/current.yaml
  • .ai/local/state/decisions.md

Writes

  • .ai/local/state/decisions.md
  • .ai/local/state/ledger.jsonl

Exit codes

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

  • 0 ok
  • 2 usage
  • 12 missing artifact

Why it was done this way

A decision records a choice between real alternatives together with its reason. An entry is never edited or deleted; a later decision supersedes an earlier one and both stay readable.

Recording a decision with its reason

reason given
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 decision add refuse tabs in the parser --why two encodings for one token

Output contains

  • recorded: refuse tabs in the parser

exit 0

The task id and the git head are computed and attached, so a decision can always be placed against the state of the repository when it was taken.

Reading them back

reason given
yes

Given this repository

# An active task that has already produced a checkpoint, a decision and an open question.
. "$FIXTURE_SETUP/active-task.sh"
printf 'the parser now refuses tabs\n' | "$MJ" checkpoint >/dev/null
"$MJ" decision add "refuse tabs in the parser" --why "two encodings for one token" >/dev/null
"$MJ" question add "should tabs be an error or a warning?" >/dev/null

Run

$ majordomus decision list

Output contains

  • refuse tabs in the parser
  • Why: two encodings

exit 0

The reason is part of the record, not a commit message someone may or may not have written. A decision without one is the thing a later worker cannot safely revisit.

Reference

Record or read durable decisions. One append-only file: state/decisions.md.

decision add "<what>" --why "<why>" appends an entry with the task id and git head computed. --why is required: a decision with no recorded reason cannot be reviewed later, only re-argued. --rejected and --evidence are optional and default to -.

An entry is never edited or deleted. --supersedes "<text>" records that a later decision replaced an earlier one and refuses text that matches no recorded decision, so a supersession always points at something real.

decision list [--task <id>] [--limit <n>] prints entries newest first; decision show "<text>" prints the first entry whose title contains that text, or exits 12.

The deep-work profile sets verification.decision_record_required: true; finish then refuses completed unless an entry names the task.

$ majordomus decision add "Normalise the callback URI before comparing state" \
    --why "the mismatch is a trailing-slash difference, not a forged state parameter" \
    --rejected "relaxing the comparison, which would accept genuinely forged states" \
    --evidence "test/auth/callback_test.exs:41"
recorded: Normalise the callback URI before comparing state

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