continuity.state

{
  "additionalProperties": false,
  "description": "No input.",
  "title": "Empty",
  "type": "object"
}

{
  "$defs": {
    "ActiveTask": {
      "description": "The active task of this checkout, when there is one.",
      "properties": {
        "binding": {
          "description": "The standing `intents.binding` answered when the task started — what `start` was\ntold then, not where the work stands now.",
          "type": "string"
        },
        "evidence_standing": {
          "description": "The pin of where the served criteria's evidence stood when the task started.",
          "type": "string"
        },
        "exemption": {
          "description": "The exemption class the worker gave instead (`start --exempt`).",
          "type": "string"
        },
        "exemption_because": {
          "description": "The reason given with the exemption.",
          "type": "string"
        },
        "head": {
          "description": "The commit it started at.",
          "type": "string"
        },
        "id": {
          "description": "The task id.",
          "type": "string"
        },
        "intent": {
          "description": "The intent the worker said this task serves (`start --intent`).",
          "type": "string"
        },
        "issue": {
          "description": "The issue the worker said this task executes (`start --issue`). A name, never state:\nwhat it serves is answered by `intents.binding` on every read (ADR 0111).",
          "type": "string"
        },
        "outcome": {
          "description": "Its typed outcome so far: `active`, `handed_over`, or a finished one.",
          "type": "string"
        },
        "plan_revision": {
          "description": "The pin of what the work was for when the task started.",
          "type": "string"
        },
        "profile": {
          "description": "The execution profile it runs under.",
          "type": "string"
        },
        "requires": {
          "description": "The obligations it owes before the outcome `completed` is available.\n\nBeside `scope` and not inside it, because the two are different promises: scope is\ncontainment — where a worker may write — and this is delivery. A change can sit\nentirely inside its scope and still be uncommitted on a laptop (ADR 0030).\n`super::obligations` is what judges each of these against its evidence; here it\nis reported as declared.",
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        "scope": {
          "description": "The paths it claims.",
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        "started_at": {
          "description": "When it started.",
          "type": "string"
        },
        "task": {
          "description": "What is being worked on.",
          "type": "string"
        }
      },
      "required": [
        "id",
        "task",
        "profile",
        "outcome"
      ],
      "type": "object"
    },
    "Divergence": {
      "description": "How far a record's recorded commit is from the commit this checkout is on.\n\nThe four words are the shell tool's, deliberately. A reader that met `advanced` from one\nsurface and `stale` from another would have to learn the same four facts twice.",
      "oneOf": [
        {
          "const": "exact",
          "description": "Written at this commit. Trust it.",
          "type": "string"
        },
        {
          "const": "advanced",
          "description": "Git has moved forward since. Trust it, and expect some of it to be done.",
          "type": "string"
        },
        {
          "const": "diverged",
          "description": "The recorded commit is not an ancestor: history was rewritten. Trust git, not this.",
          "type": "string"
        },
        {
          "const": "different_context",
          "description": "Another branch or another worktree. This record is not about your work.",
          "type": "string"
        },
        {
          "const": "unknown",
          "description": "Git could not answer, so this process says so rather than guessing `exact`.",
          "type": "string"
        }
      ]
    },
    "Freshness": {
      "description": "How old a record is, judged against `session.freshness` in the policy.\n\nThis is the second of two independent judgements every record carries, and it exists\nbecause the first one cannot answer this question. `Divergence` says where a record's\ncommit sits relative to HEAD; `advanced` means that commit is an ancestor of this one,\nwhich sounds like agreement and is identically true on the day the record is written and\na month later. Between 2026-09-05 and 2026-09-11 this repository served a handover that\nwas `advanced` and six days dead, and every surface that read this model — MCP, the HTTP\nAPI, the Cockpit — presented its `Next Action` as the thing to do (ADR 0052).\n\nThe thresholds are policy and are read, never restated here: a constant in this file\nwould be a second source of truth for a number the policy owns, and a repository whose\npolicy predates the key is reported as `Freshness::Unknown` naming the missing key\nrather than judged against a default nobody declared.\n\nThe five words divide into two groups, and the division is the one a caller acts on:\n`fresh` and `aging` are current and may be presented as the instruction, `stale` and\n`invalid` must be shown as history, and `unknown` is neither — a record nobody can date\nis not thereby an old record, and treating it as one would quietly discard a briefing\nthat is perfectly good. `Freshness::history` is that division, and it is the only\nplace it is decided.\n\n```\nuse majordomus_cli::capability::builtin::continuity::Freshness;\n\n// the two renderings are one value: the serialised word is the word `as_str` gives,\n// so a reader who met `stale` from MCP and from the command line met one fact\nlet stale = serde_json::to_value(Freshness::Stale).unwrap();\nassert_eq!(stale, serde_json::json!(\"stale\"));\nassert_eq!(stale.as_str(), Some(Freshness::Stale.as_str()));\n\n// and the division a caller acts on: absence of a judgement is not a bad judgement\nassert!(Freshness::Stale.history() && Freshness::Invalid.history());\nassert!(!Freshness::Unknown.history(), \"undated is not old\");\nassert!(!Freshness::Fresh.history() && !Freshness::Aging.history());\n```",
      "oneOf": [
        {
          "const": "fresh",
          "description": "Inside `session.freshness.fresh_minutes`. Current; act on it.",
          "type": "string"
        },
        {
          "const": "aging",
          "description": "Between the two thresholds. Still current, but its age is worth stating.",
          "type": "string"
        },
        {
          "const": "stale",
          "description": "At or beyond `session.freshness.stale_minutes`. History, never current.",
          "type": "string"
        },
        {
          "const": "unknown",
          "description": "Nothing to judge it by: no timestamp, or no thresholds declared.",
          "type": "string"
        },
        {
          "const": "invalid",
          "description": "A timestamp that does not parse, or one in the future.",
          "type": "string"
        }
      ]
    },
    "Match": {
      "description": "Which tier of the resolution rule matched. There is no third tier on purpose: a record\nfrom an unrelated worktree or branch is never offered.",
      "oneOf": [
        {
          "const": "same_worktree_same_branch",
          "description": "Same repository, same worktree, same branch.",
          "type": "string"
        },
        {
          "const": "same_branch",
          "description": "Same repository, same branch, another worktree of it.",
          "type": "string"
        }
      ]
    },
    "OpenSession": {
      "description": "The open episode this checkout points at, when there is one.\n\nOne execution episode belongs to one provider session, and several can be open in one\ncheckout at once — two windows of the same provider are two workers. What is read here\nis `state/session-current.yaml`, the pointer to the episode of this checkout; a worker\nthat knows its own provider session resolves its own episode instead, which is what\n`mj_session_here_file` in `lib/common.sh` does and what stamps each ledger line.",
      "properties": {
        "branch": {
          "description": "The branch it opened on.",
          "type": "string"
        },
        "foreign": {
          "description": "True when the open record here belongs to another checkout. Such a record is\nreported and never treated as this checkout's episode.",
          "type": "boolean"
        },
        "owner": {
          "description": "Who opened it.",
          "type": "string"
        },
        "provider": {
          "description": "The provider whose event opened it, when one did.",
          "type": "string"
        },
        "provider_session": {
          "description": "That provider's own session identity — the string the prompt archive stamps on the\nsame worker's records, and the name this episode is keyed by. Empty for an episode\nopened by hand, which is the one episode no provider session owns.",
          "type": "string"
        },
        "session_id": {
          "description": "The episode's id.",
          "type": "string"
        },
        "start_head": {
          "description": "The commit it opened at.",
          "type": "string"
        },
        "started_at": {
          "description": "When it opened.",
          "type": "string"
        },
        "worker": {
          "description": "The worker identity, when one was supplied. Never inferred.",
          "type": "string"
        }
      },
      "required": [
        "session_id",
        "started_at",
        "foreign"
      ],
      "type": "object"
    },
    "Record": {
      "description": "One durable record of the local half, as much of it as a reader needs to decide whether\nto open the file.",
      "properties": {
        "age_minutes": {
          "description": "Its age in whole minutes, when it has a timestamp that parses.",
          "format": "int64",
          "type": [
            "integer",
            "null"
          ]
        },
        "branch": {
          "description": "The branch it was written on.",
          "type": "string"
        },
        "created_at": {
          "description": "When the record says it was written.",
          "type": "string"
        },
        "divergence": {
          "$ref": "#/$defs/Divergence",
          "description": "How far its commit is from this one."
        },
        "freshness": {
          "$ref": "#/$defs/Freshness",
          "description": "How old it is, judged against `session.freshness`. Independent of `divergence`: a\nrecord is routinely `advanced` and `stale` at once, and that pair is what a reader\nmust not collapse into \"trustworthy\"."
        },
        "freshness_reason": {
          "description": "Why it was judged that way, in one phrase. Never empty: a verdict a reader cannot\nact on is the failure this subsystem is being corrected for.",
          "type": "string"
        },
        "head": {
          "description": "The commit it was written at.",
          "type": "string"
        },
        "matched": {
          "$ref": "#/$defs/Match",
          "description": "Which tier of the resolution rule matched."
        },
        "next_action": {
          "description": "The section a resuming worker acts on, when the record has one and is still current.\nA handover's `Next Action`; empty for a record that carries no sections, and\ndeliberately empty for one that is `stale` or `invalid` — see `next_action_withheld`.",
          "type": "string"
        },
        "next_action_withheld": {
          "description": "Why `next_action` is empty despite the record having one. Set only when it was\nwithheld, never when the record simply carries no such section, so that a reader can\ntell \"there is nothing to do\" from \"what there was to do is six days old\".",
          "type": "string"
        },
        "path": {
          "description": "Repository-relative path. The body is at the path; it is not copied here.",
          "type": "string"
        },
        "task_id": {
          "description": "The task it belongs to, or `none`.",
          "type": "string"
        },
        "working_tree": {
          "description": "Whether the working tree was clean or dirty then.",
          "type": "string"
        }
      },
      "required": [
        "path",
        "created_at",
        "task_id",
        "branch",
        "head",
        "working_tree",
        "matched",
        "divergence",
        "freshness",
        "freshness_reason"
      ],
      "type": "object"
    }
  },
  "description": "What the lifecycle of this checkout is holding.",
  "properties": {
    "blockers": {
      "description": "Unresolved questions on this branch. Every one refuses `finish --outcome completed`,\nwhichever task opened it.",
      "items": {
        "type": "string"
      },
      "type": "array"
    },
    "branch": {
      "description": "The branch, or `DETACHED`.",
      "type": "string"
    },
    "checkpoint": {
      "anyOf": [
        {
          "$ref": "#/$defs/Record"
        },
        {
          "type": "null"
        }
      ],
      "description": "The newest progress note for this worktree and branch, or `None`."
    },
    "findings": {
      "description": "What a reader should know before trusting any of the above: a diverged record, a\nforeign open session, a malformed file that was skipped. Empty is the good case.",
      "items": {
        "type": "string"
      },
      "type": "array"
    },
    "handover": {
      "anyOf": [
        {
          "$ref": "#/$defs/Record"
        },
        {
          "type": "null"
        }
      ],
      "description": "The record the next worker would resume from, or `None` when nothing resolves here."
    },
    "head": {
      "description": "The commit this checkout is on.",
      "type": "string"
    },
    "present": {
      "description": "Whether this checkout's lifecycle has ever run: a ledger line, a task, an episode or\na record. False in a fresh clone, which is not a fault.\n\nIt is not \"the directory exists\". Several things create that directory before\nanything has been recorded in it, so a reader that took its presence for evidence\nwould be told the lifecycle had run in a checkout where it never had.",
      "type": "boolean"
    },
    "session": {
      "anyOf": [
        {
          "$ref": "#/$defs/OpenSession"
        },
        {
          "type": "null"
        }
      ],
      "description": "The open episode, or `None`."
    },
    "tallies": {
      "additionalProperties": {
        "format": "uint",
        "minimum": 0,
        "type": "integer"
      },
      "description": "How many records of each kind this checkout holds, against the policy's caps.",
      "type": "object"
    },
    "task": {
      "anyOf": [
        {
          "$ref": "#/$defs/ActiveTask"
        },
        {
          "type": "null"
        }
      ],
      "description": "The active task, or `None`."
    },
    "working_tree": {
      "description": "`clean` or `dirty`.",
      "type": "string"
    },
    "worktree": {
      "description": "The worktree this answer is about. Every selection below is scoped to it.",
      "type": "string"
    }
  },
  "required": [
    "present",
    "worktree",
    "branch",
    "tallies"
  ],
  "title": "Continuity",
  "type": "object"
}