adopt-cli 0.4.0__tar.gz → 0.4.2__tar.gz

{adopt_cli-0.4.0 → adopt_cli-0.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: adopt-cli
-Version: 0.4.0
+Version: 0.4.2
 Summary: The adopt command surface: config resolution, JSON mode, exit codes.
 Project-URL: Homepage, https://github.com/onboardux/onboard-core
 Project-URL: Source, https://github.com/onboardux/onboard-core

{adopt_cli-0.4.0 → adopt_cli-0.4.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "adopt-cli"
-version = "0.4.0"
+version = "0.4.2"
 description = "The adopt command surface: config resolution, JSON mode, exit codes."
 requires-python = ">=3.12"
 license = "Apache-2.0"

adopt_cli-0.4.2/src/adopt_cli/_build_info.py

@@ -0,0 +1,6 @@
+"""Generated by scripts/embed_build_info.py; do not edit in a release build."""
+
+from typing import Final
+
+SBOM_SHA256: Final[str | None] = 'd9c82e3f0197e2d81b8ef92be4bdbb2f9f38710ee54d8db9ca3baa099047fda8'
+BUILD_ID: Final[str | None] = 'github:onboardux/onboard-core:37286165801:1:b50f2ec2a85b4271c0d445d8432b105574a8978a'

{adopt_cli-0.4.0 → adopt_cli-0.4.2}/src/adopt_cli/commands/_ask_support.py

@@ -114,7 +114,7 @@ def answer_question(
     """
     from adopt_ask import compose, guard, json_payload, render, retrieve
     from adopt_ask.branch import Resolved
-    from adopt_ask.escalate import consented, escalate, may_escalate
+    from adopt_ask.escalate import consented, escalate, may_dispute, may_escalate
     from adopt_ask.questionlog import log_question, should_log
     from adopt_ask.synthesis import SYNTHESIS_PROMPT_REF, render_with
 
@@ -134,11 +134,22 @@ def answer_question(
             [candidate.passage.revision_id for candidate in candidates]
         )
 
+    from adopt_cli.commands._conflict_support import contradicted_now
+
     freshness_records = handle.freshness_records()
+    # A revision a drifted probe currently contradicts is served STALE, whatever
+    # its bindings say, so `ask` agrees with the pack's "Contradicted by
+    # observation" from the moment `adopt probe run` records the conflict rather
+    # than from the next `refresh` (independence transcript T3a).
+    contradicted = contradicted_now(handle) if candidates else frozenset()
     resolved = tuple(
         Resolved(
             candidate=candidate,
-            freshness=resolve_freshness(freshness_records, candidate.passage.item_id, clock=clock),
+            freshness=_unless_contradicted(
+                resolve_freshness(freshness_records, candidate.passage.item_id, clock=clock),
+                candidate.passage.revision_id,
+                contradicted,
+            ),
         )
         for candidate in candidates
     )
@@ -224,10 +235,21 @@ def answer_question(
         payload["escalation_id"] = escalation_id
         payload["routed_to_plane"] = routed_to_plane
         where = "on the control plane" if routed_to_plane else "in this store"
-        human += f"\n\nRecorded as open question {escalation_id} {where}."
+        if may_dispute(answer):
+            human += f"\n\nReported as wrong: open question {escalation_id} {where}."
+        else:
+            human += f"\n\nRecorded as open question {escalation_id} {where}."
         human += f'\nAnswer it with: adopt answer {escalation_id} --text "..."'
         if routed_to_plane:
             human += "\nIts owner has been routed a draft reply."
+    elif may_dispute(answer) and escalate_flag:
+        # Remote mode only: the plane composes its own answer, and opens no
+        # question for one it answered KNOWN. Said out loud, because the silent
+        # version of this (exit 0, nothing recorded) is the defect being fixed.
+        human += (
+            "\n\nThe control plane answered this KNOWN and recorded no dispute. "
+            "Tell the system's owner directly, or correct the cited item with `adopt review`."
+        )
     elif may_escalate(answer) and not escalate_flag:
         human += "\n\nRecord it as an open question with `--escalate`."
 
@@ -236,6 +258,25 @@ def answer_question(
     )
 
 
+def _unless_contradicted(resolution: Any, revision_id: str, contradicted: frozenset[str]) -> Any:
+    """`resolution`, or STALE with `contradicted_by_observation` if a probe disagrees.
+
+    Only a resolution that would otherwise serve as KNOWN is replaced: an item
+    already stale keeps the rule that staled it, because that rule is the more
+    specific statement of what went wrong.
+    """
+    from adopt_freshness import RULE_CONTRADICTED_BY_OBSERVATION, FreshnessResolution
+
+    if revision_id not in contradicted or resolution.state not in ("fresh", "unverified"):
+        return resolution
+    return FreshnessResolution(
+        item_id=resolution.item_id,
+        state="stale",
+        level="knowledge_revision",
+        deciding_rule=RULE_CONTRADICTED_BY_OBSERVATION,
+    )
+
+
 def _synthesize(answer: Any, *, question: str, config: Mapping[str, str | None]) -> Any:
     """One optional model call. `None` for every reason not to have made it.
 

adopt_cli-0.4.2/src/adopt_cli/commands/_conflict_support.py

@@ -0,0 +1,52 @@
+"""The two reads every surface needs to agree about a probe contradiction.
+
+`adopt gaps`, `adopt pack`, `adopt handover` and `adopt ask` all report on Bet 4's
+`conflict` rows, and until 2026-10-05 they disagreed: the pack listed a runbook
+as "Contradicted by observation" while `ask` served it KNOWN and fresh
+(independence transcript T3a). Each now applies the same rule
+(`adopt_knowledge.rank_conflicts` / `contradicted_revisions`), fed by these two
+reads.
+
+Both are `table_rows` reads -- Build 4's report pattern -- so no query path is
+added to any realized port and the plane's escape-coverage denominator does not
+move.
+"""
+
+from typing import Any
+
+__all__ = ["conflict_rows", "contradicted_now", "superseded_revisions"]
+
+
+def conflict_rows(handle: Any) -> tuple[Any, ...]:
+    """Every `conflict` row in the store."""
+    from adopt_model import Conflict
+
+    return tuple(handle.export_records().table_rows("conflict", Conflict))
+
+
+def superseded_revisions(handle: Any) -> frozenset[str]:
+    """Knowledge revision ids that are no longer their item's head.
+
+    A conflict against one of these contradicts a claim nobody is making any
+    more: the item was re-confirmed or rewritten after the probe drifted.
+    """
+    from adopt_model import KnowledgeItem, KnowledgeRevision
+
+    records = handle.export_records()
+    heads = {
+        item.current_revision_id
+        for item in records.table_rows("knowledge_item", KnowledgeItem)
+        if item.current_revision_id is not None
+    }
+    return frozenset(
+        revision.id
+        for revision in records.table_rows("knowledge_revision", KnowledgeRevision)
+        if revision.id not in heads
+    )
+
+
+def contradicted_now(handle: Any) -> frozenset[str]:
+    """Head revisions a drifted probe currently contradicts."""
+    from adopt_knowledge import contradicted_revisions
+
+    return contradicted_revisions(conflict_rows(handle), superseded=superseded_revisions(handle))

adopt_cli-0.4.2/src/adopt_cli/commands/_coverage_support.py

@@ -0,0 +1,69 @@
+"""Keeping the coverage cache current after a command that itself changed coverage.
+
+**The alarm was firing on the product's own writes.** `identity.covered_cache`
+is rebuilt *from* `recompute_coverage()` and never the reverse, and any
+disagreement between the two alarms (`COVERAGE_CACHE_DISAGREEMENT`) rather than
+self-healing. But only `adopt coverage recompute --rebuild` ever wrote the
+cache, so every `ingest`, `bind`, `answer`, review resolution and `refresh`
+left it disagreeing, and the next `adopt gaps` paged about a change the product
+had just made on purpose. An alarm that fires on every ordinary write is one an
+operator learns to ignore, which is exactly when the real one -- a cache some
+defect wrote -- would go unread.
+
+**The rule that keeps the alarm meaningful: refresh only a cache that agreed.**
+The command recomputes first. If the cache already disagreed, something other
+than this command wrote it, and `store.py`'s incident rule applies -- rebuilding
+a disagreeing cache destroys the evidence of whatever wrote it -- so the cache is
+left alone and the alarm keeps firing. Only when it agreed beforehand does the
+command rebuild it after its own writes, from a recompute that does not compare,
+because the comparison would only report the change this command intended.
+
+The rebuild goes through `adopt_coverage.rebuild_cache`, so `no-covered-cache-write`
+still holds: the CLI decides *when*, and `adopt_coverage` remains the only writer.
+"""
+
+from collections.abc import Iterator
+from contextlib import contextmanager
+from typing import Protocol
+
+from adopt_coverage import CacheWriter, CoverageRecords
+
+__all__ = ["CoverageStore", "coverage_cache_kept_current"]
+
+
+class CoverageStore(Protocol):
+    """The two things this module needs from a store handle, structurally.
+
+    Declared rather than importing the SQLite handle, so `no-raw-sqlite` holds:
+    `adopt_coverage`'s own ports are the whole surface.
+    """
+
+    @property
+    def backend(self) -> CacheWriter: ...
+    def coverage_records(self) -> CoverageRecords: ...
+
+
+@contextmanager
+def coverage_cache_kept_current(handle: CoverageStore, system_id: str | None) -> Iterator[None]:
+    """Wrap a command body that changes coverage inputs for `system_id`.
+
+    Args:
+        handle: An open, writable store handle.
+        system_id: The system whose coverage the body may change. `None` (a
+            command that resolved no system) wraps nothing.
+
+    The post-write rebuild runs only when the body returns normally: a body that
+    raised has rolled its own transaction back, so there is nothing to follow.
+    """
+    if system_id is None:
+        yield
+        return
+
+    from adopt_coverage import rebuild_cache, recompute_coverage
+
+    before = recompute_coverage(handle.coverage_records(), system_id)
+    yield
+    if before.disagreements:
+        return
+    after = recompute_coverage(handle.coverage_records(), system_id, compare_cache=False)
+    rebuild_cache(handle.backend, after)

{adopt_cli-0.4.0 → adopt_cli-0.4.2}/src/adopt_cli/commands/_handover_support.py

@@ -45,11 +45,13 @@ __all__ = [
     "ResolvedSystem",
     "close_handover",
     "current_owner_of",
+    "independence_of",
     "open_conflicts",
     "open_gaps",
     "open_questions",
     "opening_position",
     "records_for",
+    "referent_facts",
     "refuse_if_replica",
     "require_open",
     "resolve_system",
@@ -345,6 +347,91 @@ def open_conflicts(
     return build_conflicts(handle, uris=uris)
 
 
+def referent_facts(handle: Any, *, system: ResolvedSystem, uris: set[str]) -> dict[str, Any]:
+    """What is true now of each drilled referent -- the input `validity.assess` judges.
+
+    Every read is a report read (`table_rows`, or a coverage port method that
+    already exists), so independence status adds no query path to any realized
+    port. The URI is looked up **exactly**, not through `resolve_identity`'s alias
+    walk: following a moved identity to its successor would report the successor
+    `active` and hide the very move that invalidates the drill.
+    """
+    from adopt_handover.validity import ReferentFacts
+
+    from adopt_cli.commands._conflict_support import conflict_rows, superseded_revisions
+    from adopt_freshness import resolve_freshness
+    from adopt_model import Classification, Identity
+
+    if not uris:
+        return {}
+    records = handle.export_records()
+    by_uri = {row.uri: row for row in records.table_rows("identity", Identity) if row.uri in uris}
+    coverage = handle.coverage_records()
+    statuses = coverage.head_identity_statuses(system_id=system.system_id, environment_id=None)
+    wanted = {row.id for row in by_uri.values()}
+
+    changes: dict[str, list[tuple[str, _dt.datetime]]] = {}
+    for row in records.table_rows("classification", Classification):
+        if row.identity_id in wanted:
+            changes.setdefault(row.identity_id, []).append((str(row.class_), row.created_at))
+
+    binding_statuses = coverage.head_binding_statuses(
+        system_id=system.system_id, environment_id=None
+    )
+    verifications = coverage.head_item_verifications(system_id=system.system_id)
+    items_by_identity: dict[str, set[str]] = {}
+    for binding in coverage.bindings_in_scope(system_id=system.system_id, environment_id=None):
+        if (
+            binding.identity_id in wanted
+            and binding.is_load_bearing
+            and binding_statuses.get(binding.id) == "active"
+            and verifications.get(binding.item_id) == "verified"
+        ):
+            items_by_identity.setdefault(binding.identity_id, set()).add(binding.item_id)
+
+    superseded = superseded_revisions(handle)
+    contradicted_identities = {
+        row.identity_id
+        for row in conflict_rows(handle)
+        if str(row.disposition) == "open"
+        and row.intent_revision_id is not None
+        and row.intent_revision_id not in superseded
+    }
+
+    freshness_records = handle.freshness_records()
+    facts: dict[str, Any] = {}
+    for uri in uris:
+        identity = by_uri.get(uri)
+        if identity is None:
+            facts[uri] = ReferentFacts(found=False)
+            continue
+        stale_rule: str | None = None
+        degraded_rule: str | None = None
+        for item_id in sorted(items_by_identity.get(identity.id, ())):
+            resolution = resolve_freshness(freshness_records, item_id)
+            if resolution.state == "stale" and stale_rule is None:
+                stale_rule = resolution.deciding_rule
+            elif resolution.state == "observation_stale" and degraded_rule is None:
+                degraded_rule = resolution.deciding_rule
+        facts[uri] = ReferentFacts(
+            found=True,
+            status=statuses.get(identity.id),
+            changes=tuple(changes.get(identity.id, ())),
+            contradicted=identity.id in contradicted_identities,
+            stale_rule=stale_rule,
+            degraded_rule=degraded_rule,
+        )
+    return facts
+
+
+def independence_of(handle: Any, *, system: ResolvedSystem, record: Any) -> Any:
+    """Each passed exit test's validity now (`adopt_handover.validity`)."""
+    from adopt_handover.validity import assess, passed_tasks
+
+    uris = {task.uri for task in passed_tasks(record) if task.uri is not None}
+    return assess(record, referent_facts(handle, system=system, uris=uris))
+
+
 def open_questions(handle: Any, *, system_id: str) -> tuple[OpenQuestion, ...]:
     """Unanswered questions for this system, newest first."""
     return tuple(

{adopt_cli-0.4.0 → adopt_cli-0.4.2}/src/adopt_cli/commands/_pack_support.py

@@ -203,9 +203,8 @@ def build_conflicts(handle: Any, *, uris: dict[str, str]) -> tuple[PackConflict,
     """
     from adopt_knowledge import rank_conflicts
 
-    from adopt_model import Conflict
+    from adopt_cli.commands._conflict_support import conflict_rows, superseded_revisions
 
-    rows = handle.export_records().table_rows("conflict", Conflict)
     return tuple(
         PackConflict(
             uri=conflict.uri,
@@ -213,7 +212,9 @@ def build_conflicts(handle: Any, *, uris: dict[str, str]) -> tuple[PackConflict,
             intent_revision_id=conflict.intent_revision_id,
             detected_at=conflict.detected_at,
         )
-        for conflict in rank_conflicts(rows, uris)
+        for conflict in rank_conflicts(
+            conflict_rows(handle), uris, superseded=superseded_revisions(handle)
+        )
     )
 
 

{adopt_cli-0.4.0 → adopt_cli-0.4.2}/src/adopt_cli/commands/answer.py

@@ -63,6 +63,8 @@ class _Items(Protocol):
         self, *, revision_id: str, source_type: SourceType, source_ref: str
     ) -> str: ...
 
+    def tag_audience(self, *, item_id: str, audience: str) -> bool: ...
+
 
 class _Bindings(Protocol):
     def create(
@@ -113,6 +115,14 @@ ScopeOption = Annotated[
     str | None,
     typer.Option("--scope", help="firm/engagement/system/environment. Defaults to the store's."),
 ]
+AudienceOption = Annotated[
+    list[str] | None,
+    typer.Option(
+        "--audience",
+        help="Who the answer is for. Repeatable. Defaults to the same audience "
+        "`adopt ingest` gives an untagged document.",
+    ),
+]
 ActorOption = Annotated[str | None, typer.Option("--actor", help="Who answered.")]
 JsonOption = Annotated[bool, typer.Option("--json", help="Emit the strict JSON envelope only.")]
 
@@ -124,11 +134,12 @@ def answer(
     title: TitleOption = None,
     scope: ScopeOption = None,
     store: StoreOption = None,
+    audience: AudienceOption = None,
     actor: ActorOption = None,
     json_output: JsonOption = False,
 ) -> None:
     """Bank a human's answer as confirmed knowledge and resolve the question."""
-    from adopt_ask.capture import capture_answer, identities_to_bind
+    from adopt_ask.capture import DEFAULT_AUDIENCES, capture_answer, identities_to_bind
 
     from adopt_cli.commands._remote_support import configured_remote
 
@@ -158,20 +169,29 @@ def answer(
         identity_ids, unmatched = identities_to_bind(
             text, identity_views(handle, resolved_scope), explicit_uris=uri or []
         )
-        result = capture_answer(
-            _StoreAdapter(handle),
-            escalation_id=escalation_id,
-            scope=resolved_scope,
-            # The question is the title, so the captured row is findable by the
-            # words somebody actually asked. Falling back to the answer's first
-            # line would title it with whatever the human happened to type
-            # first, which is not what the next asker will search for.
-            title=title or existing.question or f"Answer to {escalation_id}",
-            body_md=text,
-            identity_ids=identity_ids,
-            actor_id=actor,
-            unmatched_uris=unmatched,
-        )
+        from adopt_cli.commands._coverage_support import coverage_cache_kept_current
+
+        system_id = resolved_scope.system.id if resolved_scope.system is not None else None
+        with coverage_cache_kept_current(handle, system_id):
+            result = capture_answer(
+                _StoreAdapter(handle),
+                escalation_id=escalation_id,
+                scope=resolved_scope,
+                # The question is the title, so the captured row is findable by
+                # the words somebody actually asked. Falling back to the answer's
+                # first line would title it with whatever the human happened to
+                # type first, which is not what the next asker will search for.
+                title=title or existing.question or f"Answer to {escalation_id}",
+                body_md=text,
+                identity_ids=identity_ids,
+                # `DEFAULT_AUDIENCES` rather than a literal here: the default
+                # lives in `adopt_ask.capture` beside the rule it protects, so the
+                # CLI and the plane cannot drift into tagging captured answers
+                # differently.
+                audiences=tuple(audience) if audience else DEFAULT_AUDIENCES,
+                actor_id=actor,
+                unmatched_uris=unmatched,
+            )
 
         payload = {
             "escalation_id": result.escalation_id,
@@ -248,6 +268,9 @@ class _StoreAdapter:
             source_ref=source_ref,
         )
 
+    def tag_audience(self, *, item_id: str, audience: str) -> object:
+        return self._handle.items().tag_audience(item_id=item_id, audience=audience)
+
     def bind(self, *, item_id: str, identity_id: str, is_load_bearing: bool) -> str:
         binding_id, _revision_id = self._handle.bindings().create(
             item_id=item_id, identity_id=identity_id, is_load_bearing=is_load_bearing

{adopt_cli-0.4.0 → adopt_cli-0.4.2}/src/adopt_cli/commands/boundary.py

@@ -57,8 +57,8 @@ ScopeOption = Annotated[
     str | None,
     typer.Option(
         "--scope",
-        help="firm/engagement/system[/environment]. Given, the boundary is written to "
-        "the store; omitted, it is computed and reported without writing.",
+        help="firm/engagement/system, optionally with /environment. Given, the boundary is "
+        "written to the store; omitted, it is computed and reported without writing.",
     ),
 ]
 ArchetypeOption = Annotated[

{adopt_cli-0.4.0 → adopt_cli-0.4.2}/src/adopt_cli/commands/coverage.py

@@ -30,12 +30,23 @@ app = typer.Typer(
 )
 
 SystemOption = Annotated[
-    str,
-    typer.Option("--system", help="The system id to evaluate.", show_default=False),
+    str | None,
+    typer.Option("--system", help="System id or slug to evaluate.", show_default=False),
+]
+ScopeOption = Annotated[
+    str | None,
+    typer.Option(
+        "--scope",
+        help="firm/engagement/system, optionally with /environment. The alternative to "
+        "--system, and the string `adopt init` already took.",
+    ),
 ]
 EnvironmentOption = Annotated[
     str | None,
-    typer.Option("--environment", help="One environment id. Omit for every environment."),
+    typer.Option(
+        "--environment",
+        help="One environment id. Omit for every environment, or name one in --scope.",
+    ),
 ]
 StoreOption = Annotated[
     Path | None,
@@ -53,13 +64,27 @@ JsonOption = Annotated[bool, typer.Option("--json", help="Emit the strict JSON e
 
 @app.command()
 def recompute(
-    system: SystemOption,
+    system: SystemOption = None,
+    scope: ScopeOption = None,
     environment: EnvironmentOption = None,
     store: StoreOption = None,
     rebuild: RebuildOption = False,
     json_output: JsonOption = False,
 ) -> None:
-    """Evaluate the six inputs of contracts §6 for every identity in scope."""
+    """Evaluate the six inputs of contracts §6 for every identity in scope.
+
+    **`--scope` exists because this command is the remedy for an alarm, and the
+    remedy has to be reachable.** `COVERAGE_CACHE_DISAGREEMENT` fires on every
+    `adopt gaps` and `adopt pack` once a binding is confirmed, and clearing it
+    needs this verb -- which took a system **id** that no verb printed. `store
+    info` reports counts, `store doctor` reports findings, and the only command
+    that ever surfaced a system id was `adopt handover start`, which opens a
+    handover event as a side effect. An operator was left reading the SQLite
+    file by hand to silence an alarm the product raised at them, so the scope
+    string they typed into `adopt init` is now accepted here too.
+    """
+    from adopt_cli.commands._handover_support import resolve_system
+
     with open_configured_store(
         store,
         read_only=not rebuild,
@@ -69,7 +94,21 @@ def recompute(
         # nothing a later `adopt pull` overwrites was canon.
         non_canon_reason="--rebuild writes only the coverage cache, never canon",
     ) as handle:
-        result = recompute_coverage(handle.coverage_records(), system, environment)
+        # `resolve_system` rather than a second resolver: it already accepts an
+        # id, a slug or a scope path, refuses both at once, and with neither
+        # falls through to `resolve_scope`, which returns the store's only
+        # environment and **refuses rather than guessing** when there are
+        # several. A second implementation would be a second answer to "which
+        # system is this", which is how two verbs come to disagree about a store.
+        target = resolve_system(handle, system=system, scope=scope)
+        result = recompute_coverage(
+            handle.coverage_records(),
+            target.system_id,
+            # An explicit `--environment` wins over one named in `--scope`: it is
+            # the narrower statement of the two, and it names an id rather than a
+            # slug, so it cannot be the vaguer thing the operator meant.
+            environment or target.environment_id,
+        )
         rebuilt = rebuild_cache(handle.backend, result) if rebuild else 0
 
     payload = {

{adopt_cli-0.4.0 → adopt_cli-0.4.2}/src/adopt_cli/commands/handover.py

@@ -47,7 +47,8 @@ SystemOption = Annotated[
 ScopeOption = Annotated[
     str | None,
     typer.Option(
-        "--scope", help="firm/engagement/system[/environment]. Narrows to one environment."
+        "--scope",
+        help="firm/engagement/system, optionally with /environment. Narrows to one environment.",
     ),
 ]
 OwnerOption = Annotated[
@@ -63,6 +64,14 @@ OutOption = Annotated[
 ]
 StoreOption = Annotated[Path | None, typer.Option("--store", help="Path to the store.")]
 JsonOption = Annotated[bool, typer.Option("--json", help="Machine-readable output.")]
+StrictOption = Annotated[
+    bool,
+    typer.Option(
+        "--strict",
+        help="Exit 4 when any exit test the receiving team passed has since been invalidated "
+        "by a change. For a pipeline that gates on independence; off by default.",
+    ),
+]
 AudienceOption = Annotated[
     list[str] | None,
     typer.Option("--audience", help="Emit this audience. Repeatable; defaults to all four."),
@@ -396,7 +405,11 @@ def verify(
         raise AdoptError(
             ErrorCode.HANDOVER_CHECKLIST_INVALID,
             message=f"{checklist} is not valid YAML: {error}",
-            hint="See `docs/handover-checklist.example.yaml` for the shape.",
+            hint="A checklist is a mapping with a `tasks:` list, each task carrying `id`, "
+            "`task` and `outcome` (pass | fail | skipped). The annotated example is "
+            "docs/handover-checklist.example.yaml in the source tree, or "
+            "https://github.com/onboardux/onboard-core/blob/main/"
+            "docs/handover-checklist.example.yaml.",
         ) from error
     if not isinstance(raw, dict):
         raise AdoptError(
@@ -428,8 +441,18 @@ def verify(
                         question=question_for(task),
                     )
                     opened.append({"task_id": task.id, "escalation_id": escalation_id})
+                # `uri` is what lets the result go stale: it names the referent the
+                # task exercised, so a later change to it invalidates this pass
+                # (`adopt_handover.validity`). Until 2026-10-05 it was parsed and
+                # then dropped, and a passed task could never be invalidated.
                 outcomes.append(
-                    {"id": task.id, "outcome": task.outcome, "escalation_id": escalation_id}
+                    {
+                        "id": task.id,
+                        "outcome": task.outcome,
+                        "escalation_id": escalation_id,
+                        "uri": task.uri,
+                        "performed_by": task.performed_by,
+                    }
                 )
 
             detail = {
@@ -639,14 +662,21 @@ def close(
 def status(
     system: SystemOption = None,
     scope: ScopeOption = None,
+    strict: StrictOption = False,
     store: StoreOption = None,
     json_output: JsonOption = False,
 ) -> None:
-    """Every step recorded, what comes next, and what is still open.
+    """Every step recorded, what comes next, what is still open -- and what still holds.
 
     Reads only, and answers for a closed handover as readily as an open one --
     the record is what both parties keep, and it must still describe itself a
     year later.
+
+    **Independence leads.** Each exit test the receiving team passed is judged
+    against what has changed since (`adopt_handover.validity`): `valid`,
+    `invalidated` with its cause, `degraded`, or `unanchored` when the task named
+    no `uri`. A drill result that could not go stale would be a certificate;
+    this is the proof that says when it stopped being true.
     """
     from adopt_handover import VERB_FOR, record_payload
 
@@ -695,12 +725,18 @@ def status(
                     system_owner=owner,
                     written_by=writer_identity(),
                 ),
+                "independence": _independence_payload(
+                    support.independence_of(handle, system=resolved, record=record)
+                ),
             }
     finally:
         handle.close()
 
+    invalidated = bool(payload.get("independence", {}).get("invalidated"))
     if json_output:
         emit(payload, as_json=True)
+        if strict and invalidated:
+            raise typer.Exit(4)  # const-sync: ok -- exit code, not a version.
         return
     if payload["state"] == "none":
         typer.echo(
@@ -708,12 +744,22 @@ def status(
             "`adopt handover start --receiving-owner <group>` opens one."
         )
         return
+    independence = payload["independence"]
     lines = [
         f"Handover {payload['handover_id']} [{payload['state']}] {payload['scope']}",
-        f"  receiving owner: {payload['receiving_owner']}",
-        f"  owner now:       {payload['current_owner'] or 'nobody'}",
-        "",
+        f"  independence:    {independence['summary']}",
     ]
+    for task in independence["tasks"]:
+        if task["status"] != "valid":
+            since = f" since {task['since']}" if task["since"] else ""
+            lines.append(f"    {task['status']}: {task['task_id']} ({task['cause']}){since}")
+    lines.extend(
+        [
+            f"  receiving owner: {payload['receiving_owner']}",
+            f"  owner now:       {payload['current_owner'] or 'nobody'}",
+            "",
+        ]
+    )
     for step in payload["steps"]:
         mark = "x" if step["done"] else " "
         when = f"  {step['at']}" if step["at"] else ""
@@ -735,6 +781,38 @@ def status(
             "unreadable detail; the trail was edited outside this product."
         )
     typer.echo("\n".join(lines))
+    if strict and invalidated:
+        raise typer.Exit(4)  # const-sync: ok -- exit code, not a version.
+
+
+def _independence_payload(independence: Any) -> dict[str, Any]:
+    """The `independence` block of `adopt handover status --json`."""
+    from adopt_handover.validity import DEGRADED, INVALIDATED, UNANCHORED, VALID
+
+    from adopt_obs import format_timestamp
+
+    def stamp(value: Any) -> str | None:
+        return None if value is None else format_timestamp(value)
+
+    return {
+        "summary": independence.summary,
+        "passed": independence.passed,
+        "valid": independence.count(VALID),
+        "invalidated": independence.count(INVALIDATED),
+        "degraded": independence.count(DEGRADED),
+        "unanchored": independence.count(UNANCHORED),
+        "tasks": [
+            {
+                "task_id": task.task_id,
+                "uri": task.uri,
+                "status": task.status,
+                "cause": task.cause,
+                "verified_at": stamp(task.verified_at),
+                "since": stamp(task.since),
+            }
+            for task in independence.tasks
+        ],
+    }
 
 
 def _write_acceptance(

{adopt_cli-0.4.0 → adopt_cli-0.4.2}/src/adopt_cli/commands/interchange.py

@@ -87,6 +87,11 @@ def import_(
     json_output: JsonOption = False,
 ) -> None:
     """Verify a bundle whole, then restore it into an empty store."""
+    # `--into` is "created empty if absent", and that has to include its
+    # directory: the restore is often a beneficiary's first command on their own
+    # machine, and SQLite refuses a path whose parent does not exist with a raw
+    # `OperationalError` rather than anything an operator can act on.
+    into.parent.mkdir(parents=True, exist_ok=True)
     with open_named_store(into, migrate=True) as handle:
         manifest = apply_bundle(handle.import_records(), directory)
     emit(_payload(directory, manifest), as_json=json_output, title="adopt import")

{adopt_cli-0.4.0 → adopt_cli-0.4.2}/src/adopt_cli/commands/knowledge.py

@@ -60,6 +60,7 @@ def ingest(
     """Turn documents into knowledge, bound to the identities they refer to."""
     from adopt_knowledge import discover, run_ingest
 
+    from adopt_cli.commands._coverage_support import coverage_cache_kept_current
     from adopt_cli.commands._knowledge_support import (
         StoreUnitOfWork,
         bound_pairs,
@@ -73,19 +74,21 @@ def ingest(
     try:
         resolved = resolve_scope(handle, scope)
         documents = discover(paths, root=Path.cwd(), audience=audience)
-        report = run_ingest(
-            documents,
-            scope=resolved,
-            identities=identity_views(handle, resolved),
-            stored=stored_documents(handle, resolved),
-            knowledge=handle.items(),
-            bindings=handle.bindings(),
-            reviews=handle.governance(),
-            unit=StoreUnitOfWork(handle),
-            bound_pairs=bound_pairs(handle),
-            presented_revisions=presented_revisions(handle),
-            actor_id=actor,
-        )
+        system_id = resolved.system.id if resolved.system is not None else None
+        with coverage_cache_kept_current(handle, system_id):
+            report = run_ingest(
+                documents,
+                scope=resolved,
+                identities=identity_views(handle, resolved),
+                stored=stored_documents(handle, resolved),
+                knowledge=handle.items(),
+                bindings=handle.bindings(),
+                reviews=handle.governance(),
+                unit=StoreUnitOfWork(handle),
+                bound_pairs=bound_pairs(handle),
+                presented_revisions=presented_revisions(handle),
+                actor_id=actor,
+            )
         payload = _ingest_payload(report)
     finally:
         handle.close()
@@ -307,14 +310,17 @@ def bind(
                 hint="Run `adopt map` first. A moved identity's old URI still resolves, so "
                 "this is genuine absence rather than a stale address.",
             )
-        binding_id, revision_id = handle.bindings().bind(
-            item_id=knowledge_id,
-            identity_id=identity.id,
-            is_load_bearing=not not_load_bearing,
-            extractor=EXTRACTOR_MANUAL,
-            extractor_version=INGEST_EXTRACTOR_VERSION,
-            actor_id=actor,
-        )
+        from adopt_cli.commands._coverage_support import coverage_cache_kept_current
+
+        with coverage_cache_kept_current(handle, identity.system_id):
+            binding_id, revision_id = handle.bindings().bind(
+                item_id=knowledge_id,
+                identity_id=identity.id,
+                is_load_bearing=not not_load_bearing,
+                extractor=EXTRACTOR_MANUAL,
+                extractor_version=INGEST_EXTRACTOR_VERSION,
+                actor_id=actor,
+            )
         payload = {
             "binding": binding_id,
             "revision": revision_id,
@@ -499,12 +505,13 @@ def _conflicts_payload(handle: Any, result: Any, ranker: Any) -> list[dict[str,
     coverage just evaluated, so a conflict recorded against another system cannot
     appear in this scope's queue.
     """
-    from adopt_model import Conflict
+    from adopt_cli.commands._conflict_support import conflict_rows, superseded_revisions
 
     if result is None:
         return []
     uris = {row.identity_id: row.uri for row in result.identities}
-    rows = handle.export_records().table_rows("conflict", Conflict)
+    rows = conflict_rows(handle)
+    superseded = superseded_revisions(handle)
     return [
         {
             "uri": conflict.uri,
@@ -516,7 +523,7 @@ def _conflicts_payload(handle: Any, result: Any, ranker: Any) -> list[dict[str,
             # exists, and so a reader of the JSON never has to assume.
             "disposition": "open",
         }
-        for conflict in ranker(rows, uris)
+        for conflict in ranker(rows, uris, superseded=superseded)
     ]
 
 
@@ -684,68 +691,71 @@ def review(
             title="adopt review",
         )
         return
+    from adopt_cli.commands._coverage_support import coverage_cache_kept_current
+
     handle = open_configured_store(store, read_only=not writing, verb="review")
     try:
         resolved = resolve_scope(handle, scope)
         identities = identity_views(handle, resolved)
         pending = pending_items(handle, resolved, identities)
-
-        if resolve_item:
-            payload = _resolve_change(
-                handle,
-                pending,
-                known_review_items(handle),
-                review_item_id=resolve_item,
-                action=action or "",
-                to_uri=to_uri,
-                actor=actor,
-            )
-        elif not writing:
-            payload = _queue_payload(pending)
-            payload.update(_refresh_payload(refresh_population(handle, resolved, pending)))
-        else:
-            targets = _targets(
-                pending,
-                known_review_items(handle),
-                confirm_item,
-                reject_item,
-                edit_item,
-                confirm_batch,
-            )
-            resolutions: list[dict[str, Any]] = []
-            for item, action in targets:
-                if action == REJECT:
-                    outcome = reject_pending(item, reviews=handle.governance())
-                elif action == CORRECT:
-                    outcome = edit_pending(
-                        item,
-                        reviews=handle.governance(),
-                        knowledge=handle.items(),
-                        unit=StoreUnitOfWork(handle),
-                        body_md=body_md,
-                        source_ref=str(file),
-                        actor_id=actor,
-                    )
-                else:
-                    outcome = confirm_pending(
-                        item,
-                        reviews=handle.governance(),
-                        bindings=handle.bindings(),
-                        unit=StoreUnitOfWork(handle),
-                        knowledge=handle.items(),
-                        bound_pairs=bound_pairs(handle),
-                        actor_id=actor,
-                    )
-                resolutions.append(
-                    {
-                        "review_item": item.review_item_id,
-                        "action": outcome.resolution,
-                        "source": item.source,
-                        "bindings": len(outcome.bindings),
-                        "revision": outcome.revision_id,
-                    }
+        system_id = resolved.system.id if writing and resolved.system is not None else None
+        with coverage_cache_kept_current(handle, system_id):
+            if resolve_item:
+                payload = _resolve_change(
+                    handle,
+                    pending,
+                    known_review_items(handle),
+                    review_item_id=resolve_item,
+                    action=action or "",
+                    to_uri=to_uri,
+                    actor=actor,
+                )
+            elif not writing:
+                payload = _queue_payload(pending)
+                payload.update(_refresh_payload(refresh_population(handle, resolved, pending)))
+            else:
+                targets = _targets(
+                    pending,
+                    known_review_items(handle),
+                    confirm_item,
+                    reject_item,
+                    edit_item,
+                    confirm_batch,
                 )
-            payload = {"resolved": len(resolutions), "resolutions": resolutions}
+                resolutions: list[dict[str, Any]] = []
+                for item, action in targets:
+                    if action == REJECT:
+                        outcome = reject_pending(item, reviews=handle.governance())
+                    elif action == CORRECT:
+                        outcome = edit_pending(
+                            item,
+                            reviews=handle.governance(),
+                            knowledge=handle.items(),
+                            unit=StoreUnitOfWork(handle),
+                            body_md=body_md,
+                            source_ref=str(file),
+                            actor_id=actor,
+                        )
+                    else:
+                        outcome = confirm_pending(
+                            item,
+                            reviews=handle.governance(),
+                            bindings=handle.bindings(),
+                            unit=StoreUnitOfWork(handle),
+                            knowledge=handle.items(),
+                            bound_pairs=bound_pairs(handle),
+                            actor_id=actor,
+                        )
+                    resolutions.append(
+                        {
+                            "review_item": item.review_item_id,
+                            "action": outcome.resolution,
+                            "source": item.source,
+                            "bindings": len(outcome.bindings),
+                            "revision": outcome.revision_id,
+                        }
+                    )
+                payload = {"resolved": len(resolutions), "resolutions": resolutions}
     finally:
         handle.close()
 

{adopt_cli-0.4.0 → adopt_cli-0.4.2}/src/adopt_cli/commands/policy.py

@@ -39,8 +39,8 @@ ScopeOption = Annotated[
     str | None,
     typer.Option(
         "--scope",
-        help="firm/engagement/system[/environment], to validate against the boundary "
-        "declared for that scope. Omitted, the strictest default boundary is used.",
+        help="firm/engagement/system, optionally with /environment, to validate against the "
+        "boundary declared for that scope. Omitted, the strictest default boundary is used.",
     ),
 ]
 StoreOption = Annotated[Path | None, typer.Option("--store", help="Store path override.")]

{adopt_cli-0.4.0 → adopt_cli-0.4.2}/src/adopt_cli/commands/refresh.py

@@ -152,14 +152,19 @@ def refresh(
                 allow_network=allow_network,
             )
         )
-        outcome = record_refresh(
-            handle,
-            scope=resolved,
-            diff=diff,
-            batch_key=batch_key,
-            probes=probes,
-            actor_id=actor,
-        )
+        from adopt_cli.commands._coverage_support import coverage_cache_kept_current
+
+        with coverage_cache_kept_current(
+            handle, resolved.system.id if resolved.system is not None else None
+        ):
+            outcome = record_refresh(
+                handle,
+                scope=resolved,
+                diff=diff,
+                batch_key=batch_key,
+                probes=probes,
+                actor_id=actor,
+            )
         outcome.files_hashed = files_hashed
         # After the canonical write commits, never before: a snapshot saved
         # first would let a crash between the two leave the store claiming this

adopt_cli-0.4.0/src/adopt_cli/_build_info.py

@@ -1,6 +0,0 @@
-"""Generated by scripts/embed_build_info.py; do not edit in a release build."""
-
-from typing import Final
-
-SBOM_SHA256: Final[str | None] = '86636f02cad8578ffdc6c4b39fe311c0a8191cafd5fcb323ddb732447dc6b0c8'
-BUILD_ID: Final[str | None] = 'github:onboardux/onboard-core:34144382673:1:a1b32208f0a296bc708e283d860023ce7fdf4609'