adopt-cli 0.3.0__py3-none-any.whl

adopt_cli/__init__.py

@@ -0,0 +1,11 @@
+"""The `adopt` command surface.
+
+Deliberately thin. This package holds no business logic: it resolves
+configuration, dispatches, renders, and maps errors to exit codes. Rich is used
+here and nowhere else -- a library that formats for a terminal cannot be
+embedded.
+"""
+
+from adopt_cli.main import app, main
+
+__all__ = ["app", "main"]

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] = '93c0332703403696e3bb379a3fae5e8db8c60641d43647a041713b2f65625bf5'
+BUILD_ID: Final[str | None] = 'github:onboardux/onboard-core:31959050258:1:c5d546bf9de4282ce7124a5d14bd3031827091a8'

adopt_cli/commands/__init__.py

@@ -0,0 +1 @@
+"""Command implementations. Each renders a payload; none holds business logic."""

adopt_cli/commands/agent.py

@@ -0,0 +1,193 @@
+"""`adopt agent adapters | check` -- contracts §14.
+
+**A coverage gap, closed here.** `02` §14 defines this command group and `05` S7's
+Final Output Validation item 4 runs it, and **no sprint task ever created it** --
+the behaviour underneath was built and asserted at S7 while nothing exposed it on
+a command line. Recorded as a gap rather than folded in silently, exactly as S8
+did for `adopt store info` and S6 for `adopt init`.
+
+Both subcommands emit the one envelope §14 declares -- `{adapters[{id, kind,
+available, reason}]}` -- and that shape is `AdapterInfo` (CR-44), rendered rather
+than re-shaped. A group whose subcommands each invented a payload would make one
+contract into two.
+
+**`adapters` reports and `check` acts, which is why their exit codes differ.**
+The same division `02` §14 records for `adopt boundary` against `adopt init`:
+`adapters` lists every registered adapter with the reason each unusable one is
+unusable and exits `0`, because being told Anthropic is denied offline *is* the
+answer. `check` attempts construction, so an offline hosted adapter is a policy
+refusal and exits `3` -- and nothing was sent, because the refusal happens before
+the adapter module is imported.
+
+**No store is opened and no annex is touched.** Neither subcommand runs a model,
+so neither needs the runtime annex; `adopt_agent.adapters.base` is reached
+directly. That keeps `adopt agent check` usable before there is a store at all,
+which is when an operator is configuring credentials.
+"""
+
+from pathlib import Path
+from typing import Annotated, Any
+
+import typer
+
+from adopt_agent import AdapterInfo
+from adopt_agent.adapters.base import build_adapter, describe_adapters
+from adopt_cli.config import resolve_all
+from adopt_cli.json_out import emit
+from adopt_obs import AdoptError, ErrorCode
+
+__all__ = [
+    "adapter_settings",
+    "app",
+    "build_payload",
+    "disambiguation_enabled",
+    "prompts_root",
+]
+
+app = typer.Typer(
+    name="agent",
+    help="Inspect and check model adapters. Offline by default; nothing is sent.",
+    no_args_is_help=True,
+)
+
+JsonOption = Annotated[bool, typer.Option("--json", help="Emit the strict JSON envelope only.")]
+AdapterOption = Annotated[
+    str | None,
+    typer.Option("--adapter", help="Adapter id to check. Defaults to the resolved ADOPT_ADAPTER."),
+]
+
+#: Values that mean "not offline". Written as a set of spellings rather than a
+#: truthiness test because `ADOPT_OFFLINE=false` must not read as "true" merely
+#: for being a non-empty string -- the same three spellings `adopt doctor`
+#: already accepts, and one home would be better than two if either grows.
+_FALSEY: frozenset[str] = frozenset({"0", "false", "no"})
+
+
+def _allow_network(ctx: typer.Context) -> bool:
+    """The root `--allow-network` flag, or `False` when invoked without a context."""
+    obj = ctx.obj if isinstance(ctx.obj, dict) else {}
+    return bool(obj.get("allow_network", False))
+
+
+def adapter_settings(
+    *, allow_network: bool = False
+) -> tuple[bool, str | None, str | None, str | None]:
+    """`(offline, adapter, model, endpoint)` from the §3 config registry.
+
+    Resolved through `resolve_all` so the order is flag > env > project > user >
+    default and `adopt doctor` can explain any of them. Defaulting offline to
+    **on** when the key is absent is the posture, not a fallback: a seam whose
+    default were online would make "offline by default" a property of whoever
+    happened to set the variable.
+
+    **`--allow-network` is the flag layer of that order and it was not wired.**
+    `main._root` wrote `ctx.obj["allow_network"]` and **nothing anywhere read
+    it**, so the root flag `adopt_cli.main`'s own docstring calls the way to
+    permit egress did nothing at all -- while `AGENT_OFFLINE_ADAPTER_DENIED`'s
+    hint told operators to pass it. A remedy a document names and no code
+    honours costs whoever hits it an hour, and the CI preflight hit it first.
+    """
+    by_key = {resolution.key: resolution.value for resolution in resolve_all()}
+    offline = (by_key.get("ADOPT_OFFLINE") or "1").strip().lower() not in _FALSEY
+    if allow_network:
+        offline = False
+    return (
+        offline,
+        by_key.get("ADOPT_ADAPTER"),
+        by_key.get("ADOPT_MODEL"),
+        by_key.get("ADOPT_ADAPTER_ENDPOINT"),
+    )
+
+
+def disambiguation_enabled() -> bool:
+    """Whether `ADOPT_FEATURE_AGENT_DISAMBIGUATION` is on.
+
+    **Default off, without exception** (`03` §5): new behaviour arrives behind a
+    flag that is off until it has earned being on, and this flag is the one that
+    decides whether a model is called at all. Read through the registry so
+    `adopt doctor` can say where the value came from -- "it made a model call on my
+    machine" is a resolution-order question before it is anything else.
+    """
+    by_key = {resolution.key: resolution.value for resolution in resolve_all()}
+    return (by_key.get("ADOPT_FEATURE_AGENT_DISAMBIGUATION") or "0").strip().lower() not in _FALSEY
+
+
+def prompts_root() -> Path:
+    """Where immutable prompt versions live (AI spec §5, `03` §1.2).
+
+    Configuration rather than a computed path: `03` §1.2 places `prompts/` at the
+    **repository root**, which is inside no package, so nothing importable can
+    derive it. `ADOPT_PROMPTS_DIR` defaults to `prompts` relative to the working
+    directory, and `doctor` reports which layer supplied it.
+    """
+    by_key = {resolution.key: resolution.value for resolution in resolve_all()}
+    return Path(by_key.get("ADOPT_PROMPTS_DIR") or "prompts")
+
+
+def build_payload(infos: list[AdapterInfo]) -> dict[str, Any]:
+    """Contracts §14's `{adapters[{id, kind, available, reason}]}`."""
+    return {
+        "adapters": [
+            {
+                "id": info.id,
+                "kind": info.kind,
+                "available": info.available,
+                "reason": info.reason,
+            }
+            for info in infos
+        ]
+    }
+
+
+def _no_adapter_named() -> AdoptError:
+    """`check` with no id anywhere. A usage error, not a policy refusal.
+
+    The seam raises for the same reason (`04` §2, no fallback): picking one on
+    the operator's behalf would change cost, behaviour and data residency
+    without them knowing.
+    """
+    return AdoptError(
+        ErrorCode.AGENT_ADAPTER_UNKNOWN,
+        message="no adapter was named and ADOPT_ADAPTER has no value",
+        hint="Pass --adapter, or set ADOPT_ADAPTER. Run `adopt agent adapters` to "
+        "see every registered id and why each unavailable one is unavailable.",
+    )
+
+
+@app.command()
+def adapters(ctx: typer.Context, json_output: JsonOption = False) -> None:
+    """List every registered adapter and why each unusable one is unusable.
+
+    Exits `0` even when nothing is available: the report is the answer.
+    """
+    offline, _, model, endpoint = adapter_settings(allow_network=_allow_network(ctx))
+    payload = build_payload(describe_adapters(offline=offline, model=model, endpoint=endpoint))
+    emit(payload, as_json=json_output, title="adopt agent adapters")
+
+
+@app.command()
+def check(
+    ctx: typer.Context, adapter: AdapterOption = None, json_output: JsonOption = False
+) -> None:
+    """Construct one adapter, or refuse with the reason.
+
+    Raises `AGENT_ADAPTER_UNKNOWN` (usage, exit `2`) for an unregistered id or
+    when none is configured, and `AGENT_OFFLINE_ADAPTER_DENIED` (policy, exit
+    `3`) for a hosted adapter offline. The envelope and the exit code are
+    `adopt_cli.main`'s doing, so this command does not restate the mapping.
+    """
+    offline, configured, model, endpoint = adapter_settings(allow_network=_allow_network(ctx))
+    chosen = adapter or configured
+    if chosen is None:
+        raise _no_adapter_named()
+
+    # Construction is the check. Asking `describe_adapters` instead would report
+    # availability without ever proving the adapter can be built -- and building
+    # is where a hosted adapter refuses, before its module is imported.
+    built = build_adapter(chosen, offline=offline, model=model, endpoint=endpoint)
+    reported = [
+        info
+        for info in describe_adapters(offline=offline, model=model, endpoint=endpoint)
+        if info.id == built.id
+    ]
+    emit(build_payload(reported), as_json=json_output, title="adopt agent check")

adopt_cli/commands/boundary.py

@@ -0,0 +1,188 @@
+"""`adopt boundary` -- contracts §14.
+
+Negotiate a tier from the three qualification answers (CR-38) and report the
+boundary it implies.
+
+**Persisting is optional, and that is the workflow rather than a convenience.**
+With `--scope` and a store, the boundary row is written and its id reported. With
+neither, the negotiation is computed and reported and nothing is written --
+because PRD F10.6's `T0` case is exactly the one an FDE reaches *before* there is
+a firm, an engagement or a store: they are deciding whether to take the
+engagement at all. Requiring a store in order to be told "decline" inverts the
+order the product is used in.
+
+**Exit `4`, not `0`, whenever there is a finding** -- a `T0` decline or an `ai`
+system below its floor. Contracts §14 gives this command exits `0` and `4`, and
+`4` is *degraded success with findings*: the boundary is real and reportable, and
+something about it needs a human.
+"""
+
+import json
+from pathlib import Path
+from typing import Annotated, Any
+
+import typer
+
+from adopt_cli.json_out import emit
+from adopt_cli.store_option import open_configured_store
+from adopt_detect import (
+    ARCHETYPES,
+    DEFAULT_OUTBOUND_CATEGORIES,
+    BoundaryView,
+    declare_boundary,
+    negotiate,
+    parse_answers,
+    render_markdown,
+    unavailable_capabilities,
+    violates_archetype_floor,
+)
+from adopt_detect.negotiate import TierDecision
+from adopt_detect.render import render_json
+from adopt_model._enums import Archetype
+from adopt_obs import AdoptError, ErrorCode, ExitCode, now
+from adopt_scope import ScopePath
+
+__all__ = ["answers_from_file", "boundary", "build_payload"]
+
+AnswersOption = Annotated[
+    Path,
+    typer.Option(
+        "--answers",
+        help="JSON file carrying the three qualification answers "
+        "(artifact_access, deploy_signal, safe_interaction).",
+        show_default=False,
+    ),
+]
+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.",
+    ),
+]
+ArchetypeOption = Annotated[
+    str | None,
+    typer.Option("--archetype", help="The detected archetype, for the ai-below-T3 floor check."),
+]
+StoreOption = Annotated[Path | None, typer.Option("--store", help="Store path override.")]
+MarkdownOption = Annotated[
+    Path | None,
+    typer.Option(
+        "--write-statement",
+        help="Also write the human-readable statement here. Same row, same facts.",
+    ),
+]
+JsonOption = Annotated[bool, typer.Option("--json", help="Emit the strict JSON envelope only.")]
+
+
+def answers_from_file(path: Path) -> dict[str, Any]:
+    """Read and parse the answers document.
+
+    Raises:
+        AdoptError: ``TIER_ANSWERS_INVALID`` when the file is absent or is not
+            JSON. Both are the caller's mistake and neither is defaulted -- an
+            unreadable answers file must never resolve to a tier.
+    """
+    try:
+        text = path.read_text(encoding="utf-8")
+    except OSError as error:
+        raise AdoptError(
+            ErrorCode.TIER_ANSWERS_INVALID,
+            message=f"cannot read the answers file {path}",
+            hint="Point --answers at a JSON file carrying the three answers.",
+        ) from error
+    try:
+        document = json.loads(text)
+    except json.JSONDecodeError as error:
+        raise AdoptError(
+            ErrorCode.TIER_ANSWERS_INVALID,
+            message=f"{path} is not valid JSON: {error}",
+            hint="The file is a JSON object with three boolean keys.",
+        ) from error
+    if not isinstance(document, dict):
+        raise AdoptError(
+            ErrorCode.TIER_ANSWERS_INVALID,
+            message=f"{path} is a {type(document).__name__}, not a JSON object",
+            hint="The file is a JSON object with three boolean keys.",
+        )
+    return document
+
+
+def build_payload(view: BoundaryView) -> dict[str, Any]:
+    """Contracts §14's `adopt boundary` shape, from the one rendering function."""
+    return render_json(view)
+
+
+def _unpersisted_view(decision: TierDecision, archetype: Archetype | None) -> BoundaryView:
+    """The view for a negotiation that was not written.
+
+    `boundary_id` is empty rather than invented. A synthetic id here would be a
+    string that looks like a stored boundary and resolves to nothing, which is
+    worse than an obviously absent one.
+    """
+    return BoundaryView(
+        boundary_id="",
+        system_id="",
+        environment_id=None,
+        tier=decision.tier,
+        archetype=archetype,
+        knowledge_plane_location="customer",
+        control_plane_location="vendor",
+        permitted_outbound_categories=DEFAULT_OUTBOUND_CATEGORIES,
+        unavailable_capabilities=unavailable_capabilities(decision.tier),
+        contractual_approval_ref=None,
+        declared_at=now(),
+        decline_recommended=decision.decline_recommended,
+        archetype_floor_violated=violates_archetype_floor(archetype, decision.tier),
+    )
+
+
+def boundary(
+    answers: AnswersOption,
+    scope: ScopeOption = None,
+    archetype: ArchetypeOption = None,
+    store: StoreOption = None,
+    write_statement: MarkdownOption = None,
+    json_output: JsonOption = False,
+) -> None:
+    """Negotiate the observability boundary and report what it permits."""
+    decision = negotiate(parse_answers(answers_from_file(answers)))
+    typed_archetype: Archetype | None = None
+    if archetype is not None:
+        typed_archetype = _require_archetype(archetype)
+
+    if scope is None:
+        view = _unpersisted_view(decision, typed_archetype)
+    else:
+        with open_configured_store(store, read_only=False) as handle:
+            resolved = handle.scope().resolve(ScopePath.parse(scope))
+            view = declare_boundary(
+                handle.boundary(),
+                scope=resolved,
+                decision=decision,
+                archetype=typed_archetype,
+            )
+
+    payload = build_payload(view)
+    payload["persisted"] = bool(view.boundary_id)
+    if write_statement is not None:
+        write_statement.write_text(render_markdown(view), encoding="utf-8", newline="\n")
+        payload["statement_path"] = str(write_statement)
+
+    emit(payload, as_json=json_output, title="adopt boundary")
+    if view.decline_recommended or view.archetype_floor_violated:
+        raise typer.Exit(ExitCode.DEGRADED_WITH_FINDINGS)
+
+
+def _require_archetype(value: str) -> Archetype:
+    """`value` as a declared archetype, or a usage refusal naming the set."""
+    for archetype in ARCHETYPES:
+        if value == archetype:
+            return archetype
+    raise AdoptError(
+        ErrorCode.ADOPT_CONFIG_UNRESOLVED,
+        message=f"{value!r} is not a declared archetype",
+        hint=f"Archetypes are exactly {list(ARCHETYPES)} (contracts §2.1). Detection "
+        "returns one of these; nothing else can be scored against the tier floors.",
+    )

adopt_cli/commands/coverage.py

@@ -0,0 +1,85 @@
+"""`adopt coverage recompute` -- contracts §14.
+
+Emits `{covered, uncovered, disagreements[]}` and exits `4` when the cache
+disagrees with the recompute: **degraded success with findings**, not failure.
+The distinction matters operationally -- the recompute itself worked, and its
+answer is the one to trust; what is broken is the cache, and something wrote it.
+
+`--rebuild` is opt-in and off by default, so the default invocation is the one
+`store doctor` also performs: look, report, change nothing. A tool whose default
+repaired the drift would destroy the evidence of the writer that caused it every
+time an operator ran it to find out what was wrong (implementation spec §8).
+"""
+
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from adopt_cli.json_out import emit
+from adopt_cli.store_option import open_configured_store
+from adopt_coverage import rebuild_cache, recompute_coverage
+from adopt_obs import ExitCode
+
+__all__ = ["app"]
+
+app = typer.Typer(
+    name="coverage",
+    help="Recompute coverage. The function is the authority; the cache must alarm.",
+    no_args_is_help=True,
+)
+
+SystemOption = Annotated[
+    str,
+    typer.Option("--system", help="The system id to evaluate.", show_default=False),
+]
+EnvironmentOption = Annotated[
+    str | None,
+    typer.Option("--environment", help="One environment id. Omit for every environment."),
+]
+StoreOption = Annotated[
+    Path | None,
+    typer.Option("--store", help="Store path. Defaults to the resolved ADOPT_STORE_PATH."),
+]
+RebuildOption = Annotated[
+    bool,
+    typer.Option(
+        "--rebuild",
+        help="Write the result to covered_cache. Off by default: looking must not repair.",
+    ),
+]
+JsonOption = Annotated[bool, typer.Option("--json", help="Emit the strict JSON envelope only.")]
+
+
+@app.command()
+def recompute(
+    system: SystemOption,
+    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."""
+    with open_configured_store(store, read_only=not rebuild) as handle:
+        result = recompute_coverage(handle.coverage_records(), system, environment)
+        rebuilt = rebuild_cache(handle.backend, result) if rebuild else 0
+
+    payload = {
+        "covered": result.covered,
+        "uncovered": result.uncovered,
+        "disagreements": [
+            {
+                "identity_id": entry.identity_id,
+                "uri": entry.uri,
+                "cached": entry.cached,
+                "recomputed": entry.recomputed,
+            }
+            for entry in result.disagreements
+        ],
+    }
+    if rebuild:
+        payload["cache_rows_written"] = rebuilt
+
+    emit(payload, as_json=json_output, title="adopt coverage recompute")
+    if result.disagreements:
+        raise typer.Exit(ExitCode.DEGRADED_WITH_FINDINGS)

adopt_cli/commands/detect.py

@@ -0,0 +1,135 @@
+"""`adopt detect` -- contracts §14.
+
+Pure filesystem, no store, no socket. The command is a thin rendering of
+`adopt_detect.detect`; every decision it reports is made there.
+
+**Ambiguity exits `2` and names the way forward** (PRD F10.3, `04` §4 step 3).
+The payload carries the ranked scores, the rules that fired and the exact
+environment variable to set for a disambiguation pass.
+
+**With `ADOPT_FEATURE_AGENT_DISAMBIGUATION` on, one model call becomes possible
+here -- and the exit code does not change.** That is the human-accept step in its
+cheapest honest form: the pass returns a **proposal**, the proposal is printed,
+and `adopt detect` still exits `2` with `DETECT_AMBIGUOUS`, because nothing has
+been decided and nothing has been written. `01` §8 requires human approval for
+"writing the archetype -- always, no confidence exemption", so the only way a
+proposal becomes state is an operator reading it and passing
+`adopt init --archetype`. There is deliberately no `--accept` flag that would let
+one invocation both propose and persist.
+
+**A failed pass is not a failed command.** `04` §3's last row is load-bearing:
+every Build 0 capability degrades to a working deterministic behaviour. If the
+pass cannot run -- no adapter, no credential, offline, a budget crossing, an
+unusable reply -- the ranked scores are still reported and the reason is carried
+in the payload. The deterministic path *is* the product.
+"""
+
+import json
+from pathlib import Path
+from typing import Annotated, Any
+
+import typer
+
+from adopt_agent import Runner
+from adopt_cli.commands.agent import adapter_settings, disambiguation_enabled, prompts_root
+from adopt_cli.json_out import emit
+from adopt_cli.store_option import configured_annex
+from adopt_detect import detect as run_detect
+from adopt_detect.detect import DISAMBIGUATION_FLAG, DetectionResult
+from adopt_detect.disambiguate import propose
+from adopt_obs import AdoptError, ErrorCode, get_logger
+
+__all__ = ["build_payload", "detect"]
+
+PathArgument = Annotated[Path, typer.Argument(help="The tree to classify. Read, never executed.")]
+JsonOption = Annotated[bool, typer.Option("--json", help="Emit the strict JSON envelope only.")]
+
+
+def build_payload(result: DetectionResult) -> dict[str, Any]:
+    """Contracts §14's `adopt detect` shape: archetype, confidence, scores, rules_fired."""
+    return {
+        "archetype": result.archetype,
+        "confidence": result.confidence,
+        "scores": dict(result.ranked()),
+        "rules_fired": [
+            {"archetype": hit.archetype, "rule": hit.rule_id, "path": hit.path, "why": hit.why}
+            for hit in result.rules_fired
+        ],
+        "files_considered": result.files_considered,
+        "truncated": result.truncated,
+    }
+
+
+def _proposal(path: Path, result: DetectionResult) -> dict[str, Any]:
+    """`04` §4 steps 4-5, or the reason they did not run.
+
+    Reached only when detection has already declined (step 2) **and** the flag is
+    on (step 3). Every failure below degrades to reporting the deterministic
+    answer, because `04` §3 makes that the product rather than a fallback.
+    """
+    log = get_logger("adopt_cli")
+    offline, adapter_id, model, endpoint = adapter_settings()
+    try:
+        with configured_annex() as annex:
+            runner = Runner(
+                annex=annex,
+                # The annex row's scope, and the pass runs before any store
+                # exists -- `adopt detect` takes no `--scope` and creates nothing.
+                scope_ref=str(path),
+                skills_root=prompts_root(),
+                offline=offline,
+                adapter_id=adapter_id,
+                model=model,
+                endpoint=endpoint,
+            )
+            proposal = propose(result, root=path, runner=runner)
+    except AdoptError as error:
+        # Named, structured, and no payload: the code and the category, exactly
+        # what `03` §4.2 permits a log line to carry.
+        log.warn("detect.disambiguation_unavailable", code=str(error.code))
+        return {"available": False, "reason": error.code.value, "accepted": False}
+
+    return {
+        "available": True,
+        "primary": proposal.primary,
+        "confidence": proposal.confidence,
+        "reasoning": proposal.reasoning,
+        "secondary": list(proposal.secondary),
+        # **Always false, and there is no code path that sets it true.** `01` §8
+        # allows no confidence exemption for writing an archetype, so acceptance
+        # happens in a separate invocation an operator types.
+        "accepted": False,
+    }
+
+
+def detect(path: PathArgument = Path(), json_output: JsonOption = False) -> None:
+    """Classify a file tree into one archetype, or refuse and rank.
+
+    Exits `2` with `DETECT_AMBIGUOUS` when confidence is below the threshold --
+    including when a disambiguation proposal was obtained, because a proposal is
+    not a decision.
+    """
+    result = run_detect(path)
+    payload = build_payload(result)
+    if result.ambiguous:
+        # Step 3 of `04` §4: with the flag off this returns here, having made no
+        # model call and having formed no request. The flag is checked before the
+        # pass is imported into the call path at all.
+        if disambiguation_enabled():
+            payload["proposal"] = _proposal(path, result)
+        # Emitted before raising so the operator gets the evidence, not only the
+        # refusal. The error envelope alone would say "ambiguous" and nothing
+        # about which archetypes were close or which rules fired.
+        emit(payload, as_json=json_output, title="adopt detect")
+        raise AdoptError(
+            ErrorCode.DETECT_AMBIGUOUS,
+            message=(
+                f"confidence {result.confidence} is below the threshold; "
+                f"ranked scores {json.dumps(dict(result.ranked()))}"
+            ),
+            hint=f"Detection does not guess -- a wrong archetype is a different set of "
+            f"extractors, not a slightly wrong answer. Narrow the path to one system, "
+            f"or set {DISAMBIGUATION_FLAG}=1 to enable the reasoning pass, whose "
+            f"proposal a human must accept before anything is written.",
+        )
+    emit(payload, as_json=json_output, title="adopt detect")