dos-kernel 0.22.0__py3-none-win_amd64.whl

dos/drivers/operator_judge.py

@@ -0,0 +1,114 @@
+"""dos.drivers.operator_judge — the operator-decision adjudicator (a JUDGE occupant).
+
+A host's *operator-decision queue* (the reference userland app's "judge-operator"
+JO machine) is a JUDGE-rung adjudicator: for each open operator decision it rules
+**accept-recommended** (the recommended option is clearly correct and reversible),
+**escalate** (genuinely ambiguous / value-laden / irreversible — a human must
+decide), or **defer** (evidence is stale; re-propose later). That is exactly the
+three-valued ruling `dos.judges` is the seam for — so the JO machine should be a
+registered occupant of the JUDGE rung, scored by the same `dos.judge_eval`
+instrument as any other judge, rather than a wholly-separate parallel machine.
+
+This driver is the **thin binding**, not a rewrite. The host keeps ALL of its
+machinery — the LLM adjudication that PRODUCES the accept/escalate/defer string,
+the decisions-pending stamps, the findings-queue rows, the reversibility
+(`JO_AUTO_ACCEPT`) gate, the cap/cooldown/veto failsafes. This module adds two
+things, both pure and additive:
+
+  * `OperatorDecisionJudge` — a `dos.judges.Judge` occupant whose `rule()` reads a
+    host decision-string off the `Claim` and returns the canonical `JudgeVerdict`.
+    Registered under the `dos.judges` entry-point group so `dos doctor` lists it
+    and `resolve_judge("operator-decision")` returns it.
+  * `stance_for_decision` / `verdict_for_decision` — the pure mapping the host
+    adapter calls to translate its own accept/escalate/defer into the canonical
+    `Stance` / `JudgeVerdict`, so it can then feed `(Claim, verdict, truth)` triples
+    to `dos.judge_eval.false_clear_rate` and re-ground its ≤5%-false-accept gate on
+    the kernel instrument instead of a hand-rolled number.
+
+THE MAPPING (the only non-trivial part — it encodes WHICH host string clears a claim):
+
+  accept-recommended → AGREE     — the judge believes the recommended option is
+                                   correct AND reversible; this is the one verdict
+                                   that can let the lane proceed automatically. It
+                                   is the false-clear surface `judge_eval` measures.
+  escalate           → DISAGREE  — the judge flags the decision as one it should
+                                   NOT auto-clear; a human must rule (the safe,
+                                   non-clearing direction).
+  defer              → ABSTAIN   — the judge cannot rule yet (stale/unverifiable);
+                                   punt to the next cycle / a human.
+
+Why this is the honest split: the kernel never holds the host's stamp formats,
+findings schema, or reversibility gate — only the three-valued mapping and the
+discipline (`run_judge` still fail-to-abstains; the occupant mutates nothing). A
+grep of this driver for a host directory / lane / commit prefix returns nothing —
+it names only the three domain-neutral decision strings, which are this judge's
+*vocabulary*, the way a build/test judge would name "pass"/"fail".
+"""
+from __future__ import annotations
+
+from dos.judges import Claim, JudgeVerdict, Stance
+
+# The judge's name — the token `resolve_judge(...)` selects and `dos doctor` lists.
+JUDGE_NAME = "operator-decision"
+
+# The three host decision strings this judge rules in, mapped to the canonical
+# three-valued Stance. `accept-recommended` is the ONLY one that clears (AGREE) —
+# the false-clear surface the eval harness measures.
+_DECISION_TO_STANCE: dict[str, Stance] = {
+    "accept-recommended": Stance.AGREE,
+    "escalate": Stance.DISAGREE,
+    "defer": Stance.ABSTAIN,
+}
+
+
+def stance_for_decision(decision: str) -> Stance:
+    """Map a host accept/escalate/defer string to the canonical Stance.
+
+    An unknown / unparseable decision maps to ABSTAIN — the conservative default
+    (an adjudicator that produced something the seam doesn't recognise has not
+    cleared the claim). PURE.
+    """
+    return _DECISION_TO_STANCE.get((decision or "").strip().lower(), Stance.ABSTAIN)
+
+
+def verdict_for_decision(
+    decision: str, *, reason: str = "", evidence: tuple[str, ...] = (),
+    cost: float = 0.0,
+) -> JudgeVerdict:
+    """Build the canonical `JudgeVerdict` for a host decision string. PURE.
+
+    The host adapter calls this to translate its own already-produced
+    accept/escalate/defer ruling into the kernel verdict type, so the ruling can be
+    scored by `dos.judge_eval` alongside any other judge's.
+    """
+    stance = stance_for_decision(decision)
+    if stance is Stance.AGREE:
+        return JudgeVerdict.agree(reason, evidence=evidence, cost=cost)
+    if stance is Stance.DISAGREE:
+        return JudgeVerdict.disagree(reason, evidence=evidence, cost=cost)
+    return JudgeVerdict.abstain(reason, evidence=evidence, cost=cost)
+
+
+class OperatorDecisionJudge:
+    """A `dos.judges.Judge` occupant for the operator-decision queue.
+
+    `rule()` reads the host's already-produced decision off the `Claim` — the
+    accept/escalate/defer string is carried in `claim_text` (with the human reason
+    in `stated_reason`) — and returns the canonical `JudgeVerdict`. It does NO I/O
+    and NO model call itself: the host's LLM adjudication runs upstream and writes
+    its decision into the `Claim`; this occupant is the registered, eval-scorable
+    seam that ruling plugs into. Mutates nothing (advisory-only by shape).
+
+    A `Claim` whose `claim_text` is not one of the three known decision strings
+    maps to ABSTAIN (and `run_judge` would also catch any raise), so this judge can
+    never auto-clear a claim it does not understand.
+    """
+
+    name = JUDGE_NAME
+
+    def rule(self, claim: Claim, config: object) -> JudgeVerdict:
+        return verdict_for_decision(
+            claim.claim_text,
+            reason=claim.stated_reason,
+            evidence=claim.evidence,
+        )

dos/drivers/os_acceptance.py

@@ -0,0 +1,228 @@
+"""dos.drivers.os_acceptance — the acceptance-verb witness (the OS is the byte-author).
+
+docs/121 §3.1 #4 and docs/117 §5 name the *acceptance verb* as the cheapest
+non-forgeable witness a deployment can have: **the kernel runs a command and reads
+the OS exit code.** It is the first concrete `dos.evidence_sources` backend — the
+population proof that turns the `dos.evidence` seam from one built-in (`null`) into a
+witness that can actually move `verify` toward belief.
+
+Why the exit code is evidence and a pasted "it passed" is not
+=============================================================
+
+The whole `dos.evidence` thesis is "a witness is only evidence when the byte-author
+is not the judged agent." When an agent runs a test and *tells you* it passed, the
+agent authored every byte that reached you — the docs/103 self-report, the forgeable
+floor (`AGENT_AUTHORED`). But when the **kernel** launches the process and the
+**operating system** records the exit status, the agent under adjudication cannot
+forge a `returncode == 0`: it did not run the process and does not author the OS's
+record of how it ended. So this source is tagged `OS_RECORDED` — the non-forgeable
+rung — and its ATTESTED facts are eligible to grant belief under
+`evidence.believe_under_floor` (a pasted-receipt source, `AGENT_AUTHORED`, never is).
+
+The mapping from exit status to stance is the honest, conservative one:
+
+  * exit 0                     → **ATTESTED**  (the effect's acceptance check passed)
+  * exit non-zero (clean run)  → **REFUTED**   (the check ran and said no — a
+                                positive disconfirmation, stronger than "no signal")
+  * could not run the command  → **NO_SIGNAL** (binary missing, timeout, OS error,
+                                no command given — abstain, never a fabricated pass)
+
+The same fail-safe-never-fail-open posture as `ci_status._run_gh`: every failure mode
+degrades to an unreachable `no_signal`, never a raise, never an ATTESTED.
+
+Shape & layering
+================
+
+A driver, outside the kernel boundary — it has the surface the kernel forbids
+(spawning a process). It implements the `evidence.EvidenceSource` Protocol:
+`name`/`accountability` class attributes + a boundary `gather(subject, config)` whose
+ONE subprocess lives here, mirroring `ci_status.gather` / `git_delta`. It imports the
+kernel; the kernel never imports it (the `drivers/__init__` rule, the existing
+`no dos.drivers import` litmus covers it). Advisory: it reports an attestation; it
+never refuses a lease or mutates state — a host CONSULTS it (a `dos verify` belief
+fold, a RED row in `dos decisions`), it does not actuate.
+
+The `subject` IS the command
+============================
+
+For this source the opaque `subject` correlation handle is *the acceptance command
+itself* — the shell-free argv to run (passed as a single string, split with
+`shlex`). "Witness that effect E happened" becomes "run the command that checks E and
+read its exit code." The command is the host's to choose (`pytest -q`, `curl -fsS
+https://… -o /dev/null` for an HTTP-200 re-GET of an idempotent effect, a
+provider-CLI status probe); the kernel only runs it and reads the OS's verdict. A
+host wires which command witnesses which effect; this driver supplies the
+runs-it-and-reads-the-exit-code mechanism.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import shlex
+import subprocess
+
+# Imports the kernel — never the other way round (the driver rule).
+from dos import config as _config
+from dos.evidence import Accountability, EvidenceFacts, believe_under_floor
+
+# Cap the run so a hung acceptance command can't stall an evidence-gather — the
+# `ci_status._GH_TIMEOUT_S` / `git_delta._GIT_TIMEOUT_S` discipline. A touch generous
+# because an acceptance check (a test run, an HTTP probe) can legitimately take a
+# little while; a host that needs a different cap passes `timeout_s`.
+_DEFAULT_TIMEOUT_S = 120
+
+
+class OsAcceptanceEvidenceSource:
+    """An `evidence.EvidenceSource`: run a command, read the OS exit code, witness it.
+
+    `name`/`accountability` are CLASS-LEVEL and fixed — this source is always
+    `OS_RECORDED` (it has no honest path to a higher or lower rung; the exit code is
+    the OS's record, full stop). The `subject` handed to `gather` is the acceptance
+    command to run (see the module docstring). `config` is accepted for Protocol
+    conformance and is unused here (the command is self-contained); a richer source
+    could read a per-effect command map out of `dos.toml [evidence]` via `config`.
+    """
+
+    name = "os_acceptance"
+    accountability = Accountability.OS_RECORDED
+
+    def __init__(self, *, timeout_s: int = _DEFAULT_TIMEOUT_S, cwd: str | None = None) -> None:
+        self._timeout_s = timeout_s
+        self._cwd = cwd
+
+    def gather(self, subject: str, config: object) -> EvidenceFacts:
+        """Run `subject` as a command and map its exit status to an EvidenceFacts.
+
+        Boundary I/O — the ONE subprocess lives here (the `ci_status.gather` rule);
+        the returned facts are pure data `believe_under_floor` consumes. Never raises:
+        every failure mode degrades to an unreachable `no_signal`, so a missing binary
+        / timeout / OS error can never be mistaken for either an attestation or a
+        refutation. Wrapped by `evidence.gather_evidence` at the call site for the
+        belt-and-braces fail-safe, but defensive here too (a driver should not lean on
+        its wrapper to be safe).
+        """
+        cmd = (subject or "").strip()
+        if not cmd:
+            return EvidenceFacts.no_signal(
+                self.name,
+                self.accountability,
+                subject,
+                detail="no acceptance command given — nothing to witness",
+            )
+        try:
+            argv = shlex.split(cmd, posix=True)
+        except ValueError as e:  # unbalanced quotes etc. — not runnable, so no signal
+            return EvidenceFacts.no_signal(
+                self.name,
+                self.accountability,
+                subject,
+                detail=f"un-parseable acceptance command ({e}) — no signal",
+            )
+        if not argv:
+            return EvidenceFacts.no_signal(
+                self.name,
+                self.accountability,
+                subject,
+                detail="empty acceptance command after parsing — no signal",
+            )
+        try:
+            p = subprocess.run(
+                argv,
+                capture_output=True,
+                text=True,
+                check=False,
+                timeout=self._timeout_s,
+                cwd=self._cwd,
+            )
+        except FileNotFoundError:
+            return EvidenceFacts.no_signal(
+                self.name,
+                self.accountability,
+                subject,
+                detail=f"command not found: {argv[0]!r} — no signal",
+            )
+        except subprocess.TimeoutExpired:
+            return EvidenceFacts.no_signal(
+                self.name,
+                self.accountability,
+                subject,
+                detail=f"acceptance command timed out after {self._timeout_s}s — no signal",
+            )
+        except OSError as e:  # pragma: no cover - environment-dependent
+            return EvidenceFacts.no_signal(
+                self.name,
+                self.accountability,
+                subject,
+                detail=f"acceptance command failed to start ({e.__class__.__name__}) — no signal",
+            )
+
+        rc = p.returncode
+        # The OS authored `rc`. exit 0 → the acceptance check passed (ATTESTED);
+        # non-zero from a clean run → the check ran and said no (REFUTED); both are
+        # the OS's record, not the agent's narration.
+        if rc == 0:
+            return EvidenceFacts.attest(
+                self.name,
+                self.accountability,
+                subject,
+                detail=f"`{argv[0]}` exited 0 — acceptance check passed",
+            )
+        return EvidenceFacts.refute(
+            self.name,
+            self.accountability,
+            subject,
+            detail=f"`{argv[0]}` exited {rc} — acceptance check failed (OS-recorded)",
+        )
+
+
+# ---------------------------------------------------------------------------
+# CLI — `python -m dos.drivers.os_acceptance "<command>"` witnesses an effect.
+# Folds the single source through `believe_under_floor` so the operator sees the
+# belief verdict, not just the raw stance — i.e. that an OS_RECORDED attestation
+# DOES grant belief (whereas a forgeable-floor one would not).
+# ---------------------------------------------------------------------------
+
+
+def main(argv: list[str] | None = None) -> int:
+    ap = argparse.ArgumentParser(
+        prog="dos.drivers.os_acceptance",
+        description=__doc__.splitlines()[0],
+    )
+    ap.add_argument("command", help="the acceptance command to run (its exit code is the witness)")
+    ap.add_argument("--workspace", default=None,
+                    help="workspace root, used to resolve the run cwd (default: $DISPATCH_WORKSPACE or cwd)")
+    ap.add_argument("--timeout", type=int, default=_DEFAULT_TIMEOUT_S,
+                    help=f"seconds before the command is abandoned as NO_SIGNAL (default: {_DEFAULT_TIMEOUT_S})")
+    ap.add_argument("--json", action="store_true", help="machine-readable verdict")
+    args = ap.parse_args(argv)
+
+    cfg = _config.default_config(args.workspace)
+    source = OsAcceptanceEvidenceSource(timeout_s=args.timeout, cwd=str(cfg.paths.root))
+    # Use the kernel's fail-safe wrapper, exactly as a real consumer would.
+    from dos.evidence import gather_evidence
+
+    facts = gather_evidence(source, args.command, cfg)
+    belief = believe_under_floor((facts,))
+
+    if args.json:
+        print(json.dumps({"facts": facts.to_dict(), "belief": belief.to_dict()}, indent=2))
+    else:
+        print(f"COMMAND   {args.command}")
+        print(f"SOURCE    {facts.source_name} ({facts.accountability.value})")
+        print(f"STANCE    {facts.stance.value}")
+        print(f"WHY       {facts.detail}")
+        print(f"BELIEVE   {belief.believe}   (refuted={belief.refuted})")
+        print(f"VERDICT   {belief.reason}")
+
+    # Exit-code map mirrors `dos verify` / `ci_status`: a believed attestation is 0,
+    # a refutation is 1 (the effect did not happen), no-signal is 3 (a human's call).
+    if belief.refuted:
+        return 1
+    if belief.believe:
+        return 0
+    return 3
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

dos/drivers/paste_log.py

@@ -0,0 +1,132 @@
+"""dos.drivers.paste_log — the floor log source: operator-pasted text. A JUDGE hint.
+
+docs/117 §7 — the worked move-B example for the `log_source` seam, and **deliberately
+the floor of the accountability spectrum**. It exists to demonstrate the fence the
+seam puts around the easy-to-ingest sources, not to be trusted as a verdict source.
+
+What it is
+==========
+
+A `log_source.LogSource` that wraps text the operator hands in — a pasted terminal
+buffer, a copied stack trace, a `screen`/`tmux` scrollback dumped into the prompt. It
+is the single easiest log source to ingest (~zero integration: the text is already in
+hand) and, by the docs/117 §2 **inversion law**, the *least* trustworthy for exactly
+that reason: the agent (or the operator relaying the agent) chose every byte that
+reached here, so the bytes are a self-report wearing evidence's clothes — the docs/84
+§3.1 forgeable floor, `INFO: tests passed` in a logger rendered as a paste.
+
+Why it is hard-tagged `AGENT_AUTHORED`
+======================================
+
+Its `accountability` is `AGENT_AUTHORED` and there is no way to construct it at any
+higher rung. That is the load-bearing point of this driver as an *example*: a consumer
+routes off the tag (`if ev.accountability.is_agent_authored: feed_a_judge(ev)`), so
+this source has no path to an oracle verdict by construction. It answers the docs/117
+§1 objection ("an LLM already reads logs") concretely — pasted text IS that loop, and
+the kernel's contribution is to give it the correct, lower rung (a JUDGE *hint*,
+advisory and fail-to-abstain — `judges` / `drivers/llm_judge`), never a deterministic
+verdict. The slop move is to ship a paste adapter as a "verification source"; the
+honest move is to ship it tagged as the floor with the fence visible.
+
+How a consumer uses it (the right way)
+======================================
+
+    from dos import log_source as _ls
+    from dos.drivers.paste_log import PasteLogSource
+
+    src = PasteLogSource(text=pasted_buffer)        # or .from_stdin()
+    ev = _ls.gather_log(src, subject=run_id, config=cfg)
+    # ev.accountability.is_agent_authored is True →
+    #   hand ev.lines to a JUDGE as a hint (advisory), NEVER classify as an oracle.
+
+This driver imports the kernel (`dos.log_source`); the kernel never imports it (the
+`drivers/__init__` one-way rule, pinned by `tests/test_log_source.py`). It is NOT in
+`dos.drivers.__init__`'s eager imports — like `ci_status`, it is loaded on demand by a
+consumer, so it stays off the kernel's import surface.
+
+Pure-stdlib; the only "I/O" is reading the text it was handed (or stdin in the
+classmethod), and even a read failure degrades through `gather_log` to NO_SIGNAL.
+"""
+
+from __future__ import annotations
+
+import sys
+
+from dos.log_source import Accountability, LogEvidence
+
+# Imported only for type clarity / the entry-point contract; a real plugin would
+# register this class under `[project.entry-points."dos.log_sources"]`.
+
+# Cap how much pasted text we retain, so a multi-megabyte paste can't bloat the
+# evidence object a judge is handed. A floor source's value is a *hint*; the first N
+# lines are plenty, and an unbounded buffer is a footgun, not a feature.
+_MAX_LINES = 2000
+
+
+class PasteLogSource:
+    """A `LogSource` over operator-supplied text. Hard-tagged `AGENT_AUTHORED`.
+
+    `name` is `"paste"` (the token a resolver/`dos doctor` would show).
+    `accountability` is `AGENT_AUTHORED`, fixed — a class-level constant, not a
+    per-call choice, so this source can never claim a higher rung (the docs/117 §2
+    inversion law made structural). `gather` ignores `subject`/`config` for routing
+    purposes (the text is whatever was handed in; there is nothing to look up) and
+    returns the retained lines as `reachable` evidence — "reachable" here means only
+    "we have the text," NOT "the text is trustworthy"; the `AGENT_AUTHORED` tag carries
+    the trust ceiling, and `reachable=True` on a floor source still routes to a judge.
+    """
+
+    name = "paste"
+    accountability = Accountability.AGENT_AUTHORED
+
+    def __init__(self, text: str = "") -> None:
+        """Wrap a block of pasted text (a terminal buffer, a stack trace).
+
+        Splitlines now (at construction, the boundary), capped at `_MAX_LINES`, so
+        `gather` does no work that could raise. Empty text is fine — it yields a
+        `no_signal` evidence (nothing was pasted), the honest floor.
+        """
+        lines = (text or "").splitlines()
+        # Keep the LAST _MAX_LINES — a terminal buffer's tail (the recent output, the
+        # error, the exit summary) is the part a judge wants, not the scrolled-off head.
+        self._lines: tuple[str, ...] = tuple(lines[-_MAX_LINES:])
+
+    @classmethod
+    def from_stdin(cls) -> "PasteLogSource":
+        """Build a source from whatever is on stdin (the `dos … < buffer.txt` ergonomic).
+
+        The read happens HERE, at the construction boundary, fail-safe: any read error
+        degrades to empty text (→ a `no_signal` gather), never a raise — the
+        `git_delta`/`ci_status` "every failure → safe empty" posture.
+        """
+        try:
+            text = sys.stdin.read()
+        except Exception:
+            text = ""
+        return cls(text=text)
+
+    def gather(self, subject: str, config: object) -> LogEvidence:
+        """Return the pasted lines as evidence — or `no_signal` if nothing was pasted.
+
+        Never raises (the lines were split at construction). Empty paste → `no_signal`
+        (the honest floor: there is genuinely no log here). Non-empty → `reached` with
+        the lines, tagged `AGENT_AUTHORED` so the consumer routes it to a judge. The
+        `detail` says in plain words that this is a floor source, so an operator reading
+        `dos doctor` / a `--json` dump is reminded *why* it can't ground a verdict.
+        """
+        if not self._lines:
+            return LogEvidence.no_signal(
+                self.name,
+                self.accountability,
+                detail="no text pasted — the floor source has no log signal.",
+            )
+        return LogEvidence.reached(
+            self.name,
+            self.accountability,
+            self._lines,
+            detail=(
+                f"{len(self._lines)} line(s) of operator-pasted text — "
+                f"AGENT_AUTHORED (the forgeable floor): a JUDGE hint only, never a "
+                f"deterministic verdict source (docs/117 §1)."
+            ),
+        )

dos/drivers/plan_scope.py

@@ -0,0 +1,133 @@
+"""dos.drivers.plan_scope — a reference `ScopeSource` (outside the kernel line).
+
+The kernel ships the scope-source SEAM (`dos.scope_source`: the `ScopeSource`
+Protocol, the `ScopeVerdict`, the `honest_under_floor` conjunction, the null
+`AllDeclaredScope` baseline, the resolver) but NO *ruling* source — exactly as it
+ships the judge seam but no ruling judge, and the overlap seam but no model-backed
+scorer. A source that consults an EXTERNAL account of scope is a JUDGE-rung
+adjudicator (it reads the world, it is not pure), so it lives **here, in a
+driver** — outside the kernel boundary, where I/O is allowed
+(`drivers/__init__.py`: "they import the kernel; the kernel never imports them").
+
+What this source does
+=====================
+
+`PlanScopeSource` cross-checks a run's **declared** extent (`state.declared_steps`,
+the self-reported denominator of the residual) against an **expected** set of
+units — the *real* scope, supplied from outside the run. The expected set is the
+external account the kernel must not trust the agent to report honestly:
+
+  * **Where it comes from.** `config.expected_scope_steps` — a workspace declares
+    its real phase list in `dos.toml` (`[completion] expected_scope`), or a host
+    driver injects it from its plan registry (the phase list of the plan the run is
+    executing). This driver is agnostic about the source; it reads the iterable off
+    the config it is handed.
+  * **The ruling.** If every expected unit appears in `declared_steps`, the extent
+    is honest → `extent_honest=True` (the run put the whole job on the books). If
+    any expected unit is MISSING from the declared steps, the run under-declared →
+    `extent_honest=False`, carrying the missing units. Fed into
+    `completion.classify`, that flips an otherwise-`COMPLETE` run to
+    `UNDERDECLARED`: the residual is empty, but it was measured against too small a
+    denominator.
+
+This is the canonical Gap-B example from docs/117 §5.3 ("diff the declared steps
+against the plan registry's phase list"), made concrete and deterministic.
+
+Why it is a driver, not the kernel
+==================================
+
+It reads `config` to LOCATE the external scope and (in the host-injected case) the
+plan registry is itself read from disk — that is the I/O a kernel verdict may not
+do. The discipline that keeps it safe is the seam's, not purity: a `ScopeSource`
+can only ever WITHHOLD `COMPLETE` (the conjunction + `run_scope` fail-to-strict
+guarantee it), so even a buggy or lying scope source surfaces an `UNDERDECLARED`
+decision rather than silently certifying done. The kernel imports nothing from
+here; `completion.classify` takes the `ScopeVerdict` this produces as data.
+
+Wiring it
+=========
+
+Register it under the `dos.scope_sources` entry-point group, then a workspace names
+it in `dos.toml [completion] scope_sources = ["plan"]`; the CLI boundary resolves
+it via `scope_source.active_scope_sources` and threads the verdict into
+`completion.classify`. Or construct it directly and pass its verdict in (what the
+tests do). The entry-point name is conventionally ``plan``.
+"""
+
+from __future__ import annotations
+
+from typing import Iterable, Optional
+
+# Imports the kernel — never the other way round (the driver rule).
+from dos.intent_ledger import LedgerState
+from dos.scope_source import ScopeVerdict
+
+
+def _expected_from_config(config: object) -> Optional[tuple[str, ...]]:
+    """The expected (real) scope unit ids, read off the config (the data seam).
+
+    Reads ``config.expected_scope_steps`` when present and iterable; returns it as a
+    tuple of str. Returns ``None`` when the config carries no expected scope at all —
+    the "I have no external account to check against" case, which the source treats
+    as *honest* (it cannot claim under-declaration it has no evidence for; that would
+    refuse completion for every run on a workspace that simply did not declare an
+    expected set). Defensive on purpose — a malformed value yields ``None`` rather
+    than crashing the completion path, the warn-and-fall-back posture every config
+    axis takes."""
+    raw = getattr(config, "expected_scope_steps", None)
+    if raw is None:
+        return None
+    try:
+        return tuple(str(x) for x in raw)
+    except TypeError:
+        return None
+
+
+class PlanScopeSource:
+    """A reference `ScopeSource`: declared steps vs an expected phase list.
+
+    `name` is ``plan`` — the token a workspace names in `dos.toml [completion]
+    scope_sources` and `dos doctor` lists. `scope_verdict` reads the expected scope
+    off the config and diffs it against `state.declared_steps`.
+    """
+
+    name = "plan"
+
+    def __init__(self, expected: Optional[Iterable[str]] = None) -> None:
+        """`expected` lets a host inject the real scope directly (e.g. from its plan
+        registry) instead of via config — the tuple takes precedence over
+        ``config.expected_scope_steps`` when both are present. With neither, the
+        source has no external account and votes honest (see `_expected_from_config`).
+        """
+        self._expected: Optional[tuple[str, ...]] = (
+            tuple(str(x) for x in expected) if expected is not None else None
+        )
+
+    def scope_verdict(self, state: LedgerState, config: object) -> ScopeVerdict:
+        expected = self._expected
+        if expected is None:
+            expected = _expected_from_config(config)
+        if expected is None:
+            # No external account of scope → nothing to contradict the declaration.
+            # Vote honest (the source has no evidence of under-declaration).
+            return ScopeVerdict(
+                extent_honest=True,
+                reason="no expected scope configured — declared extent not contested",
+                source=self.name,
+            )
+        declared = set(state.declared_steps)
+        missing = tuple(u for u in expected if u not in declared)
+        if not missing:
+            return ScopeVerdict(
+                extent_honest=True,
+                reason=(f"all {len(expected)} expected unit(s) are in the declared "
+                        f"extent — the whole job was put on the books"),
+                source=self.name,
+            )
+        return ScopeVerdict(
+            extent_honest=False,
+            reason=(f"{len(missing)} expected unit(s) absent from the declared extent "
+                    f"— the run under-declared its scope"),
+            source=self.name,
+            missing=missing,
+        )