Skip to content

majordomus question

Open a question that blocks acceptance, resolve it, and list what is still open.

Open a question that blocks acceptance, resolve it, and list what is still open.

  • state-mutating
  • memory
  • active task required

Every unresolved entry for the active task refuses finish --outcome completed. That is the whole point of the command; it is a gate, not a notebook.

Syntax

majordomus question add "<question>"

Lifecycle

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

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

Reads

  • .ai/local/state/current.yaml
  • .ai/local/state/open-questions.md

Writes

  • .ai/local/state/open-questions.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

The gate, not the notebook

A question is opened when you are blocked on a person. Every unresolved question for the active task refuses finish --outcome completed — that is the whole point of the command.

Opening a question against the active task

active task
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 question add should tabs be an error or a warning?

Output contains

  • ^opened for t-

exit 0

From this moment the task cannot be finished as completed. It can be finished as blocked, which is the honest outcome when the answer is not yours to give.

With no active task

active task
no

Given this repository

# A repository with Majordomus installed and projections generated, and one commit of work.
"$MJ" init >/dev/null
"$MJ" update >/dev/null
mkdir -p lib docs
echo a > lib/a
echo d > docs/d
git add . && git commit -qm base

Run

$ majordomus question add who owns the parser?

Output contains

  • no active task

exit 12

A question is opened against a task. Without one there is nothing for it to block, and an unattached blocker would never be seen again.

Reference

Open, resolve and list the questions that block acceptance. One mutable index: state/open-questions.md.

Unresolved questions are explicit state, not prose inside a handover, because finish --outcome completed refuses while any entry names the active task. That gate is the reason the file has a machine-written line format, and the reason check, doctor and watch fail on an entry that does not parse: a gate that cannot read an entry is a gate that can be bypassed by mistyping one.

  • question add "<question>" appends - [unresolved] <task id> — <question> (<date>).
  • question resolve <n|"<text>"> --answer "<answer>" rewrites that one line to [resolved <date>] and appends the answer. n is the number question list printed. --answer is required, and an ambiguous selector is refused rather than guessed.
  • question list [--all] [--task <id>] shows every unresolved entry, because every one of them refuses a completed finish here; --task narrows to what one task opened and --all adds the resolved ones. The numbering is what question resolve <n> selects. Any unresolved question can be resolved, not only one the active task opened: a gate nobody can clear is a gate that gets worked around.

Resolving edits the index because an index of what is still open must not accumulate. The append-only record of every opening and resolution, with its answer, is the ledger.

$ majordomus question add "Does the legacy mobile callback still require the old URI form?"
opened for t-20260903193012-a4f1: Does the legacy mobile callback still require the old URI form?
$ majordomus finish --outcome completed --verify-command "mix test"
FAIL blockers   t-20260903193012-a4f1 — unresolved entry in open-questions.md  [reproduce: majordomus question list]
finish: refused, 1 unmet

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