Checkpoint long work so a stop costs minutes, not the day

setup: active-task
given:
  - 'an active task scoped to lib, with work done inside that scope'
steps:
  - id: checkpoint
    run: ['checkpoint']
    stdin: checkpoint-body.md
    note: 'a capped progress record; its branch and head are computed from git, never written by hand'
    expect:
      exit: 0
      stdout_contains: ['\.ai/local/state/checkpoints/']
  - id: fresh
    run: ['check']
    note: 'the checkpoint is fresh against the profile interval and the task is consistent with git'
    expect:
      exit: 0
      stdout_contains: ['0 failing']
  - id: resume
    run: ['context']
    note: 'the newest checkpoint is part of what the next worker reads'
    expect:
      exit: 0
      stdout_contains: ['^## TASK', 'checkpoint']
then:
  - 'the checkpoint file carries the branch and head it was written at'
  - 'check reports the checkpoint age against the profile interval'
  - 'context names the task and its newest checkpoint'

The scenario

Executed against the real tool, in a repository prepared by active-task, 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, 3 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 checkpoint exit 0< checkpoint-body.md

   a capped progress record; its branch and head are computed from git, never written by hand

   .ai/local/state/checkpoints/<time>--main--<head>--<hash>.md

   • exit 0
   • stdout_contains /\.ai/local/state/checkpoints//
2. 2$ majordomus check exit 0

   the checkpoint is fresh against the profile interval and the task is consistent with git

   OK   knowledge   records — 0 record(s) valid against knowledge/v1; every reference resolves  [reproduce: majordomus knowledge check]
   ·    checkpoint  t-<id> — <timed against the checkpoint interval>
   INFO checkpoint  .ai/local/state/checkpoints/<time>--main--<head>--<hash>.md — newest record, <age> ago  [reproduce: majordomus checkpoint --show]
   OK   records     ledger.jsonl — every line is a well-formed event
   OK   blockers    t-<id> — none open
   OK   records     decisions.md — every entry is attributable
   OK   scope       t-<id> — 1 touched file(s), all within scope
   OK   state       t-<id> — exact (head <head>)
   INFO mesh        t-<id> — the repository declares no enabled mesh
   INFO use-case    30 advisory gap(s) — not covered by an active use case, and the policy does not require it: command:init command:update command:doctor command:watch command:start command:context command:checkpoint command:handover command:check command:finish command:history command:decision command:question command:prompt command:evidence command:skills command:capture command:search command:doctrine command:plan command:version command:session command:knowledge command:adr command:usecase command:rules command:migrate command:recover command:bench command:archive  [reproduce: majordomus usecase coverage]
   OK   use-case    0 of 30 target(s) covered — every public command the policy requires is named and run by an active use case (policy use_cases.coverage)
   INFO obligation  t-<id> — the task declares no obligations
   INFO gate        t-<id> — this repository declares no CI model at .ai/repo/ci/gates.yaml; nothing can be planned
   check: 13 finding(s), 0 failing

   • exit 0
   • stdout_contains /0 failing/
3. 3$ majordomus context exit 0

   the newest checkpoint is part of what the next worker reads

   # 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
   
   ## 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)
   (none)
   
   ## LATEST CHECKPOINT (.ai/local/state/checkpoints/<time>--main--<head>--<hash>.md, <age> ago, exact)
   the parser now refuses tabs; the message names the column
   
   ## 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
   49 of 300 lines

   • exit 0
   • stdout_contains /^## TASK/
   • stdout_contains /checkpoint/

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 checkpointRecord compact progress inside the active task, so the next worker does not start over.
• majordomus checkIs the current task still consistent with its policy, its scope and this checkout?
• majordomus contextWhat the next worker needs to know now, in authority order and within a budget.

The rules that make it hold

• !advisory Checkpoint freshnessA task whose last checkpoint is older than its profile's interval is reported, not stopped.
• ✕blocking State consistencyThe task record still describes this checkout — same branch, and HEAD at or ahead of the recorded commit.
• !advisory Task continuityA task finished as partial or blocked should leave a handover record, not only a note section.

Guarantees exercised

• ○guaranteed Identity fields on every state record are computed from git and never authored
• ○guaranteed check reports whether state, scope, blockers and checkpoint age are consistent right now
• ○guaranteed A checkpoint is a capped progress record with computed identity, and a body over the cap is refused rather than truncated
• ○guaranteed Every continuity store is proven reachable through its own command, not merely present on disk

Related use cases

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

• Hand unfinished work to the next sessionStop mid-task and leave the next worker something to act on that is not a transcript.
• Read only the context that fits the budget, and know what was droppedAssemble the context a worker needs now in authority order, cut it to a line budget, and see every dropped section named with its reason.
• Resume in the right worktree, never against somebody else’s taskFind the handover that belongs to this worktree and branch, and see a task record from another checkout reported as foreign rather than enforced here.
• Run several workers in one repository without them collidingGive each worker a declared scope, and find out immediately when two of them claim the same paths.
• Decide whether finished work is actually finishedEvaluate a contract line by line instead of accepting a sentence that says the work is done.

The moments this answers

• → found a task "in progress" that nobody had touched for three weeks A status that was authored rather than computed is true at the moment of writing and decays silently from then on.
• → lost a failure a worker had already reproduced, because the session ended A failure observed inside a session is described in that session and nowhere else, so the next one starts from the report rather than the evidence.