Read only the context that fits the budget, and know what was dropped

setup: active-task-records
given:
  - 'an active task that has already produced a checkpoint, a decision and an open question'
steps:
  - id: everything
    run: ['context']
    note: 'git identity, the task and its profile, the scoped documents, open questions, decisions and the newest checkpoint, in authority order'
    expect:
      exit: 0
      stdout_contains: ['^## GIT', '^## TASK', '^## PROFILE']
  - id: budgeted
    run: ['context', '--budget-lines', '30']
    note: 'the same, cut to a budget; what is dropped is named with its reason rather than silently truncated'
    expect:
      exit: 10
      stdout_contains: ['^## GIT', '^## EXCLUDED', 'context budget 30 lines']
  - id: machine
    run: ['context', '--json']
    note: 'the same body as one JSON document for a client that composes its own prompt'
    expect:
      exit: 0
      stdout_contains: ['^\{']
  - id: explained
    run: ['check', '--explain']
    note: 'the effective policy and profile the context was assembled under'
    expect:
      exit: 0
      stdout_contains: ['^# task', 'profile']
then:
  - 'authority order is fixed: git, task, profile, documents, questions, decisions, checkpoint'
  - 'a dropped section is named, never lost without a trace'
  - 'the JSON form carries the same content as the text form'

The scenario

Executed against the real tool, in a repository prepared by active-task-records, every time this site is generated. What follows is not a description of what should happen; it is what happened.

What the tool did

Evidence of the run this page was generated from: pass, 4 step(s). Output is normalised: the repository's path, timestamps, ids and durations are placeholders; nothing else is edited.

Tested by test/cases/94_use_cases.sh, which runs every scenario and refuses a step whose recorded output is not what it produced.

1. 1$ majordomus context exit 0

   git identity, the task and its profile, the scoped documents, open questions, decisions and the newest checkpoint, in authority order

   # Majordomus context — <time>
   # a projection of durable state, not a source of truth: validate every line against git
   
   ## GIT
   repository   <repo>
   branch       main
   head         <sha>
   working_tree dirty
   task_record  exact (recorded head <head>)
   
   ## TASK
   id           t-<id>
   task         narrow the parser
   profile      implementation
   owner        <owner>
   outcome      active
   scope        lib
   started      <time> (<age> ago)
   checkpoint   <time> (<age> ago, interval 15m)
   
   ## PROFILE implementation
   capability   standard
   effort       medium
   verbosity    concise
   presentation engineering
   verification verify command
   output       outcome, changes, verification, blockers, next_action
   
   ## CONTEXT DOCUMENTS (for the scope, root first; majordomus context explain <path>)
   lib  ai.layer
   
   ## OPEN QUESTIONS (1 unresolved — every one refuses finish --outcome completed)
   - should tabs be an error or a warning? (<date>)
   
   ## KNOWLEDGE (candidates awaiting review on this branch; majordomus knowledge candidates)
   No knowledge candidates await review on this branch. That is an answer, not a gap: `majordomus knowledge candidates` lists every branch.
   
   ## DECISIONS (5 most recent for this task)
   ## <date> — refuse tabs in the parser
   Task: t-<id>
   Head: <sha>
   Why: two encodings for one token
   Rejected: -
   Evidence: -
   Supersedes: -
   
   ## LATEST CHECKPOINT (.ai/local/state/checkpoints/<time>--main--<head>--<hash>.md, <age> ago, exact)
   the parser now refuses tabs
   
   ## FILES TOUCHED IN SCOPE (1)
   lib/a
   
   ## EXCLUDED
   - handover — no record for this worktree and branch — absence, not a stale match
   - history — profile implementation sets context.recent_history_depth: 0
   
   ## BUDGET
   58 of 300 lines

   • exit 0
   • stdout_contains /^## GIT/
   • stdout_contains /^## TASK/
   • stdout_contains /^## PROFILE/
2. 2$ majordomus context --budget-lines 30 exit 10

   the same, cut to a budget; what is dropped is named with its reason rather than silently truncated

   # Majordomus context — <time>
   # a projection of durable state, not a source of truth: validate every line against git
   
   ## GIT
   repository   <repo>
   branch       main
   head         <sha>
   working_tree dirty
   task_record  exact (recorded head <head>)
   
   ## TASK
   id           t-<id>
   task         narrow the parser
   profile      implementation
   owner        <owner>
   outcome      active
   scope        lib
   started      <time> (<age> ago)
   checkpoint   <time> (<age> ago, interval 15m)
   
   ## PROFILE implementation
   capability   standard
   effort       medium
   verbosity    concise
   presentation engineering
   verification verify command
   output       outcome, changes, verification, blockers, next_action
   
   ## OPEN QUESTIONS (1 unresolved — every one refuses finish --outcome completed)
   - should tabs be an error or a warning? (<date>)
   
   ## LATEST CHECKPOINT (.ai/local/state/checkpoints/<time>--main--<head>--<hash>.md, <age> ago, exact)
   body omitted for budget — read .ai/local/state/checkpoints/<time>--main--<head>--<hash>.md
   
   ## EXCLUDED
   - handover — no record for this worktree and branch — absence, not a stale match
   - history — profile implementation sets context.recent_history_depth: 0
   - files — context budget 30 lines
   - context documents — context budget 30 lines; run: majordomus context resolve <path>
   - knowledge — context budget 30 lines
   - decisions — context budget 30 lines
   - checkpoint body — context budget 30 lines
   
   ## BUDGET
   45 of 30 lines (dropped: files documents knowledge decisions checkpoint-body)
   majordomus: context: 45 lines over the budget of 30 with nothing left to drop

   • exit 10
   • stdout_contains /^## GIT/
   • stdout_contains /^## EXCLUDED/
   • stdout_contains /context budget 30 lines/
3. 3$ majordomus context --json exit 0

   the same body as one JSON document for a client that composes its own prompt

   {"schema":1,"generated_at":"<time>","git":{"repository":"<repo>","branch":"main","head":"<sha>","working_tree":"dirty","task_record":"exact"},"task":{"id":"t-<id>","task":"narrow the parser","profile":"implementation","owner":"<owner>","outcome":"active","started_at":"<time>","checkpoint_at":"<time>","scope":["lib"]},"sections":[{"id":"profile","lines":7,"text":"## PROFILE implementation\ncapability   standard\neffort       medium\nverbosity    concise\npresentation engineering\nverification verify command\noutput       outcome, changes, verification, blockers, next_action\n"},{"id":"documents","lines":2,"text":"## CONTEXT DOCUMENTS (for the scope, root first; majordomus context explain <path>)\nlib  ai.layer\n"},{"id":"questions","lines":2,"text":"## OPEN QUESTIONS (1 unresolved — every one refuses finish --outcome completed)\n- should tabs be an error or a warning? (<date>)\n"},{"id":"knowledge","lines":2,"text":"## KNOWLEDGE (candidates awaiting review on this branch; majordomus knowledge candidates)\nNo knowledge candidates await review on this branch. That is an answer, not a gap: `majordomus knowledge candidates` lists every branch.\n"},{"id":"decisions","lines":8,"text":"## DECISIONS (5 most recent for this task)\n## <date> — refuse tabs in the parser\nTask: t-<id>\nHead: <sha>\nWhy: two encodings for one token\nRejected: -\nEvidence: -\nSupersedes: -\n"},{"id":"checkpoint","lines":2,"text":"## LATEST CHECKPOINT (.ai/local/state/checkpoints/<time>--main--<head>--<hash>.md, <age> ago, exact)\nthe parser now refuses tabs\n"},{"id":"files","lines":2,"text":"## FILES TOUCHED IN SCOPE (1)\nlib/a\n"}],"excluded":[{"item":"handover","reason":"no record for this worktree and branch — absence, not a stale match"},{"item":"history","reason":"profile implementation sets context.recent_history_depth: 0"}],"budget":{"lines":58,"limit":300,"dropped":[]}}

   • exit 0
   • stdout_contains /^\{/
4. 4$ majordomus check --explain exit 0

   the effective policy and profile the context was assembled under

   # task
     id=t-<id>
     task=narrow the parser
     profile=implementation
     owner=<owner>
     scope.0=lib
     started_at=<time>
     checkpoint_at=<time>
     outcome=active
     repository_id=<repo>/.git
     worktree=<repo>
     branch=main
     head=<sha>
     working_tree=clean
   # profile implementation
     name=implementation
     description=build a described feature or change within a known design
     capability=standard
     effort=medium
     verbosity=concise
     presentation=engineering
     context.task=true
     context.current_state=true
     context.decisions=true
     context.relevant_files=true
     context.failing_output=false
     context.recent_history_depth=0
     context.architecture_notes=false
     context.knowledge=true
     context.knowledge_max_items=8
     verification.verify_command_required=true
     verification.regression_test_required=false
     verification.decision_record_required=false
     checkpoint_interval=15m
     output_contract.0=outcome
     output_contract.1=changes
     output_contract.2=verification
     output_contract.3=blockers
     output_contract.4=next_action
   # policy
     version=1
     context.always_loaded_budget_lines=150
     context.builder_budget_lines=300
     context.recent_decisions=5
     context.max_list_items=20
     context.strategy=minimum-sufficient
     context.transcript_is_state=false
     profiles.default=implementation
     profiles.checkpoint_interval_default=15m
     verification.required_for_changes=true
     verification.finish_requires.0=scope_respected
     verification.finish_requires.1=verification_ran
     verification.finish_requires.2=state_updated
     verification.finish_requires.3=no_open_blockers
     verification.finish_requires.4=note_present
     handover.required_sections.0=Objective
     handover.required_sections.1=Current State
     handover.required_sections.2=Next Action
     handover.retention_max_files=200
   # doctrines enforced by check
     majordomus.knowledge-integrity (blocking)
     majordomus.checkpoint-freshness (advisory)
     majordomus.ledger-integrity (blocking)
     majordomus.blocker-resolution (blocking)
     majordomus.decision-records (advisory)
     majordomus.scope-integrity (blocking)
     majordomus.state-consistency (blocking)
     majordomus.task-on-the-mesh (blocking)
     majordomus.use-case-coverage (blocking)
     majordomus.obligation-closure (blocking)
     majordomus.completion-gates (blocking)

   • exit 0
   • stdout_contains /^# task/
   • stdout_contains /profile/

Why the tool knows this

The chain from this page to the code: the use case names commands, rules and claims; each rule is dispatched from the registry and each claim names the test that proves it; the scenario above executed the commands. Nothing in this chain is prose about intent.

• majordomus contextWhat the next worker needs to know now, in authority order and within a budget.
• majordomus checkIs the current task still consistent with its policy, its scope and this checkout?

The rules that make it hold

• ✕blocking Context integrityEvery directory of the AI layer carries a context document, each one carries the contract, they compose into one deterministic chain for every path, and a tree that does not validate resolves nothing.
• ✕blocking Context budgetThe always-loaded projection stays within its line budget, every reference in it resolves, it states no count that will go stale, and the assembled context fits the builder's own budget.
• ✕blocking Profile requirementsA profile may demand more than the shared contract — a regression test, a decision record — and finish refuses without it.

Guarantees exercised

• ○guaranteed The context a worker is given is assembled from durable state in authority order, and what a profile excludes is excluded
• ○guaranteed The assembled context obeys a line budget, and every section it drops is named with its reason
• ○guaranteed A checkpoint is a capped progress record with computed identity, and a body over the cap is refused rather than truncated
• ○guaranteed A decision is recorded with its reason and its task, and is superseded by a later entry rather than edited
• ○guaranteed The context that applies to a path is composed from the layer's scoped documents, root to target, in one deterministic order with provenance, and a tree that does not validate resolves nothing

Related use cases

Computed from what they share: claims, rules, commands, category, applications. Nobody maintains this list.

• Start a session from a rendered framing, not a pasted transcriptList the prompt assets the repository ships, render one against the durable state, and read the context it embeds.
• Checkpoint long work so a stop costs minutes, not the dayRecord compact progress inside the active task at the profile interval, so a session that ends without warning leaves the next one a place to start.
• Hand unfinished work to the next sessionStop mid-task and leave the next worker something to act on that is not a transcript.
• Say what your work is for, once, and have every surface say itRecord an operational failure mode as one file and have the command line, the API, MCP and the website answer it without registering it anywhere.
• Trace a change to the context documents it affectsList the scoped context documents, resolve which apply to a path and why, and find out which documents a change set touches before it lands.

The moments this answers

• → re-explained the same context to a brand-new session Repository knowledge that only ever existed in a conversation has to be re-transmitted by hand to every worker that follows.
• → watched the strongest model, at maximum effort, rename a variable Capability, reasoning depth, context size and verbosity collapse into one habit — everything on — because nothing ever named them separately.
• → watched the always-loaded instruction file grow past a thousand lines Everything important gets appended to the always-loaded file, so every session pays for every rule and reads none of them carefully.
• → spent the first hour in an unfamiliar repository working out what was normal here What is conventional in a codebase is knowledge held by its regulars, so every arrival — human or machine — pays for it again.