theurian 0.1.0.dev6__tar.gz → 0.1.0.dev7__tar.gz

{theurian-0.1.0.dev6 → theurian-0.1.0.dev7}/CHANGELOG.md

@@ -12,13 +12,48 @@ Pre-1.0, a MINOR bump may change the protocol. Post-1.0, only a MAJOR may.
 
 ## [Unreleased]
 
+## [0.1.0.dev7] - 2026-08-19
+
+### Added
+
+- **`theurian propose` can now set `--scope-path` and `--label`**
+  ([#249](https://github.com/theurian/theurian/issues/249)). Each is repeatable
+  and keeps the order it was given: `--scope-path` writes `metadata.scope.paths`
+  (the globs Milestone 8's drift detection will read), and `--label` writes
+  `metadata.labels`. A `--label` given alongside `--authored-here` is
+  de-duplicated against the implied `authored-in-theurian` label — the schema
+  declares `labels` `uniqueItems`, so a duplicate would otherwise turn a legal
+  invocation into a refusal. An enhancement rather than a fix: before this, these
+  fields were simply unreachable from the propose flow, and their absence
+  published nothing false.
+
+### Fixed
+
+- **A maintainer-reviewed, public ADR accepted through `propose` → `accept`
+  published `trustLevel: unverified` and `sensitivity: internal` on every result**
+  ([#249](https://github.com/theurian/theurian/issues/249)). `theurian propose`
+  could express no `trustLevel` or `sensitivity`, so a corpus built by the shipped
+  flow could only ever carry the schema defaults; the loader completed the omitted
+  fields silently, and both reach every `knowledge.search` and `knowledge.get`
+  result. Measured on the first dogfooding slice: three publicly readable ADRs a
+  maintainer had merged were published as `unverified`/`internal` beside
+  `status: approved`, and hand-editing the generated YAML was the only remedy.
+  `propose` now takes `--trust-level {unverified|inferred|reviewed|authoritative}`
+  and `--sensitivity {public|internal|confidential|restricted}`, on both the
+  create and update flows, so a false value is correctable rather than permanent.
+  When either is omitted the default is not stamped into the migration — that
+  would assert a judgement the caller never made — but is named in the draft's
+  `--json` next steps, so an omission is a surfaced choice rather than a silent
+  false positive.
+
 ## [0.1.0.dev6] - 2026-08-19
 
 ### Fixed
 
 - **A rejected item's relation note reached an approved item's `knowledge.get`
-  through an alias-id collision** (GHSA-\<pending\>, assigned when the advisory is
-  published). Critical; affected 0.1.0.dev0–0.1.0.dev5. An `addAlias` whose key
+  through an alias-id collision**
+  ([GHSA-vx8x-rjfj-9x54](https://github.com/theurian/theurian/security/advisories/GHSA-vx8x-rjfj-9x54)).
+  Critical; affected 0.1.0.dev0–0.1.0.dev5. An `addAlias` whose key
   equalled the id of a live `rejected` item, while the alias pointed at an
   approved item, defeated the relation-visibility gate: `get_item` resolves an
   alias before it looks up a status, so a lookup for the retired id resolved to
@@ -42,7 +77,8 @@ Pre-1.0, a MINOR bump may change the protocol. Post-1.0, only a MAJOR may.
 ### Changed
 
 - **BREAKING — an alias key may not collide with a non-deprecated item id across a
-  migration set** (GHSA-\<pending\>, assigned when the advisory is published).
+  migration set**
+  ([GHSA-vx8x-rjfj-9x54](https://github.com/theurian/theurian/security/advisories/GHSA-vx8x-rjfj-9x54)).
 
   **Old shape:** a set whose `addAlias` key equalled a live item's id applied
   silently. With that item `rejected` and the alias pointing at an approved item,

{theurian-0.1.0.dev6 → theurian-0.1.0.dev7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: theurian
-Version: 0.1.0.dev6
+Version: 0.1.0.dev7
 Summary: Git-native engineering knowledge platform: versioned, traceable context for AI agents.
 Project-URL: Homepage, https://github.com/theurian/theurian
 Project-URL: Documentation, https://github.com/theurian/theurian/tree/main/docs

{theurian-0.1.0.dev6 → theurian-0.1.0.dev7}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "theurian"
-version = "0.1.0.dev6"
+version = "0.1.0.dev7"
 description = "Git-native engineering knowledge platform: versioned, traceable context for AI agents."
 readme = "README.md"
 requires-python = ">=3.13"

{theurian-0.1.0.dev6 → theurian-0.1.0.dev7}/src/theurian/__init__.py

@@ -8,7 +8,7 @@ plugin must never import them (ADR-0001, CP-2).
 
 from theurian.domain.compatibility import CURRENT_PROTOCOL_VERSION
 
-__version__ = "0.1.0.dev6"
+__version__ = "0.1.0.dev7"
 __protocol_version__ = CURRENT_PROTOCOL_VERSION
 
 __all__ = ["__protocol_version__", "__version__"]

{theurian-0.1.0.dev6 → theurian-0.1.0.dev7}/src/theurian/application/proposal_service.py

@@ -46,7 +46,7 @@ from typing import Final
 import yaml
 
 from theurian.application.project_service import ProjectPaths
-from theurian.domain.enums import KnowledgeKind, KnowledgeStatus
+from theurian.domain.enums import KnowledgeKind, KnowledgeStatus, Sensitivity, TrustLevel
 from theurian.domain.errors import PathEscapeError, TheurianError
 from theurian.domain.identifiers import ItemId, MigrationId, ProposalId, RevisionId
 from theurian.domain.knowledge import AUTHORED_IN_THEURIAN, SourceAnchor
@@ -131,6 +131,13 @@ class ProposalRequest:
     evidence: Evidence
     source_anchors: tuple[SourceAnchor, ...] = ()
     labels: tuple[str, ...] = ()
+    scope_paths: tuple[str, ...] = ()
+    #: Absent means "not stated": the field is left out of the migration and the
+    #: loader applies the schema default. A value is never invented here, because
+    #: `unverified`/`internal` written into every draft would assert a judgement
+    #: the caller did not make (#249).
+    trust_level: TrustLevel | None = None
+    sensitivity: Sensitivity | None = None
     namespace: str | None = None
     expected_revision: RevisionId | None = None
 
@@ -840,9 +847,12 @@ def _migration_document(  # noqa: PLR0913 -- the fields a migration has; all key
     ``status: approved`` is right even though nobody has approved it yet: the
     file applies only once a human has merged it, and ``draft`` would land
     knowledge that ``theurian index build`` leaves out. ``trustLevel`` and
-    ``sensitivity`` are deliberately absent -- claiming ``reviewed`` on
-    something an agent drafted asserts a review that has not happened, and a
-    reviewer can add either.
+    ``sensitivity`` are written only when the caller set them (``--trust-level``,
+    ``--sensitivity``): left unset they are absent from the file and the loader
+    applies its defaults, ``unverified`` and ``internal``. Stamping those
+    defaults in unasked-for would assert a judgement the caller never made, so
+    the omission is surfaced in the CLI's next steps instead of written here
+    (#249).
     """
     metadata: dict[str, object] = {
         "title": request.title,
@@ -852,8 +862,14 @@ def _migration_document(  # noqa: PLR0913 -- the fields a migration has; all key
         "status": KnowledgeStatus.APPROVED.value,
         "owner": request.owner,
     }
+    if request.trust_level is not None:
+        metadata["trustLevel"] = request.trust_level.value
+    if request.sensitivity is not None:
+        metadata["sensitivity"] = request.sensitivity.value
     if request.labels:
         metadata["labels"] = list(request.labels)
+    if request.scope_paths:
+        metadata["scope"] = {"paths": list(request.scope_paths)}
     if request.source_anchors:
         metadata["sourceAnchors"] = [_anchor_document(a) for a in request.source_anchors]
 

{theurian-0.1.0.dev6 → theurian-0.1.0.dev7}/src/theurian/cli/propose_commands.py

@@ -34,11 +34,15 @@ from theurian.application.proposal_service import (
     ProposalService,
 )
 from theurian.cli.context import CommandContext, schema_root
-from theurian.domain.enums import KnowledgeKind
+from theurian.domain.enums import KnowledgeKind, Sensitivity, TrustLevel
 from theurian.domain.errors import TheurianError
 from theurian.domain.identifiers import AgentId, ItemId, ProposalId, RevisionId, TaskId
 from theurian.domain.knowledge import AUTHORED_IN_THEURIAN, SourceAnchor
-from theurian.domain.migration import current_revision_in
+from theurian.domain.migration import (
+    DEFAULT_SENSITIVITY,
+    DEFAULT_TRUST_LEVEL,
+    current_revision_in,
+)
 from theurian.domain.proposal import Evidence
 from theurian.domain.values import JSON, MARKDOWN, YAML, MediaType
 from theurian.infrastructure.filesystem.migration_loader import validate_migration_document
@@ -50,6 +54,14 @@ from theurian.security.paths import MAX_SOURCE_FILE_BYTES
 #: had the group shape allowed the options to be declared required.
 EXIT_INVALID_INPUT: Final = 2
 
+#: The C0 control block (below U+0020) and DEL (U+007F). A label carrying one of
+#: these corrupts the reviewed migration text -- a newline splits it across
+#: lines, a NUL truncates it -- and the schema's ``labels.items`` does not forbid
+#: them the way ``title``/``owner`` do, so ``propose`` refuses them at draft
+#: time (#249).
+_C0_CEILING: Final = 0x20
+_DEL: Final = 0x7F
+
 #: Body formats a proposal may carry, keyed by the extension the caller wrote.
 #: Read from the file name rather than taken as its own option so the extension
 #: and the declared ``contentType`` cannot disagree -- a body written as ``.md``
@@ -107,6 +119,10 @@ class _Inputs:
     expected_revision: str | None
     anchor: SourceAnchor | None
     authored_here: bool
+    trust_level: TrustLevel | None
+    sensitivity: Sensitivity | None
+    scope_paths: tuple[str, ...]
+    labels: tuple[str, ...]
     agent_id: str
     task_id: str
     model: str
@@ -176,6 +192,35 @@ def propose_draft(  # noqa: PLR0913 -- one option per migration field, all keywo
             help="Declare that this knowledge originates in Theurian and has no external source.",
         ),
     ] = False,
+    trust_level: Annotated[
+        TrustLevel | None,
+        typer.Option(
+            "--trust-level",
+            help="How much scrutiny this content has had. Omitted, the revision loads as "
+            "'unverified' -- honest for an agent draft, wrong for reviewed knowledge.",
+        ),
+    ] = None,
+    sensitivity: Annotated[
+        Sensitivity | None,
+        typer.Option(
+            "--sensitivity",
+            help="Disclosure class. Omitted, the revision loads as 'internal'.",
+        ),
+    ] = None,
+    scope_path: Annotated[
+        list[str] | None,
+        typer.Option(
+            "--scope-path",
+            help="Glob this knowledge governs, e.g. src/**. Repeatable; the order is kept.",
+        ),
+    ] = None,
+    label: Annotated[
+        list[str] | None,
+        typer.Option(
+            "--label",
+            help="Free-form label to group this knowledge by. Repeatable; the order is kept.",
+        ),
+    ] = None,
     agent_id: Annotated[
         str | None, typer.Option("--agent-id", help="Which agent drafted this (required).")
     ] = None,
@@ -226,6 +271,13 @@ def propose_draft(  # noqa: PLR0913 -- one option per migration field, all keywo
         "--source-uri": source_uri,
         "--source-commit": source_commit,
         "--source-path": source_path,
+        "--trust-level": trust_level,
+        "--sensitivity": sensitivity,
+        # Repeatable options arrive as ``None`` when omitted and a list when
+        # given, so an empty draft leaves them out of the stray check while a
+        # populated one is caught -- the same "was it passed" test the scalars use.
+        "--scope-path": scope_path,
+        "--label": label,
         "--agent-id": agent_id,
         "--task-id": task_id,
         "--model": model,
@@ -249,6 +301,11 @@ def propose_draft(  # noqa: PLR0913 -- one option per migration field, all keywo
             as_json=as_json,
         )
 
+    scope_paths = tuple(scope_path or ())
+    labels = tuple(label or ())
+    _refuse_blank_scope_paths(scope_paths, as_json=as_json)
+    _refuse_unusable_labels(labels, as_json=as_json)
+
     _draft(
         _Inputs(
             item_id=_present(item_id),
@@ -262,6 +319,10 @@ def propose_draft(  # noqa: PLR0913 -- one option per migration field, all keywo
             expected_revision=expected_revision,
             anchor=_anchor(source_provider, source_uri, source_commit, source_path),
             authored_here=authored_here,
+            trust_level=trust_level,
+            sensitivity=sensitivity,
+            scope_paths=scope_paths,
+            labels=labels,
             agent_id=_present(agent_id),
             task_id=_present(task_id),
             model=_present(model),
@@ -372,6 +433,48 @@ _DRAFT_STEPS: Final = (
 )
 
 
+def _refuse_blank_scope_paths(scope_paths: tuple[str, ...], *, as_json: bool) -> None:
+    """Refuse a ``--scope-path`` that names no path.
+
+    ``revisionMetadata.scope.paths`` items carry no ``minLength``, so ``""`` or a
+    whitespace-only value stages a scope entry that matches nothing and reads in
+    review as an authoring slip. Refuse it here -- naming the option, staging
+    nothing -- rather than packaging a glob that can never apply (#249).
+    """
+    if any(not path.strip() for path in scope_paths):
+        _refuse(
+            "--scope-path was given an empty path.",
+            remedy="Pass a path glob such as docs/**, or drop --scope-path.",
+            as_json=as_json,
+        )
+
+
+def _refuse_unusable_labels(labels: tuple[str, ...], *, as_json: bool) -> None:
+    """Refuse an empty ``--label`` or one bearing a control character.
+
+    ``revisionMetadata.labels.items`` carry only ``maxLength``, unlike ``title``
+    and ``owner`` whose ``pattern`` forbids control characters. #249 first opened
+    this arbitrary-label path, so it closes the two values that corrupt the
+    reviewed migration text: an empty label groups by nothing, and a C0 or DEL
+    control character -- a newline splits the label across lines, a NUL truncates
+    it -- makes the YAML read as something other than what was passed. The public
+    schema is unchanged here; this is the CLI refusing before it stages (#249).
+    """
+    for label in labels:
+        if not label:
+            _refuse(
+                "--label was given an empty value.",
+                remedy="Pass a non-empty label, or drop --label.",
+                as_json=as_json,
+            )
+        if any(ord(char) < _C0_CEILING or ord(char) == _DEL for char in label):
+            _refuse(
+                "--label contains a control character.",
+                remedy="Pass a label of printable text, or drop --label.",
+                as_json=as_json,
+            )
+
+
 def _draft(inputs: _Inputs, *, as_json: bool) -> None:
     """Read the body, build the request, and report what was written."""
     from theurian.cli.commands import _emit, _fail, _require_project  # noqa: PLC0415 - cycle
@@ -396,7 +499,7 @@ def _draft(inputs: _Inputs, *, as_json: bool) -> None:
         )
         return
 
-    _emit(_drafted_payload(drafted, context), as_json=as_json)
+    _emit(_drafted_payload(drafted, context, inputs), as_json=as_json)
 
 
 def _request(inputs: _Inputs, *, body: str, content_type: MediaType) -> ProposalRequest:
@@ -432,7 +535,10 @@ def _request(inputs: _Inputs, *, body: str, content_type: MediaType) -> Proposal
         content_type=content_type,
         evidence=evidence,
         source_anchors=anchors,
-        labels=(AUTHORED_IN_THEURIAN,) if inputs.authored_here else (),
+        labels=_merge_labels(inputs.labels, authored_here=inputs.authored_here),
+        scope_paths=inputs.scope_paths,
+        trust_level=inputs.trust_level,
+        sensitivity=inputs.sensitivity,
         namespace=inputs.namespace,
         expected_revision=(
             None if inputs.expected_revision is None else RevisionId.parse(inputs.expected_revision)
@@ -440,6 +546,21 @@ def _request(inputs: _Inputs, *, body: str, content_type: MediaType) -> Proposal
     )
 
 
+def _merge_labels(labels: tuple[str, ...], *, authored_here: bool) -> tuple[str, ...]:
+    """The caller's labels and the authored-here label, deduplicated in order.
+
+    ``revisionMetadata.labels`` is ``uniqueItems``, so a caller who passes
+    ``--label authored-in-theurian`` beside ``--authored-here`` must not produce a
+    document the generator's own validation then rejects. ``--authored-here`` is
+    INV-8's declaration for source-less knowledge, not a synonym for the label, so
+    it is added rather than assumed and never dropped. First-seen order is kept
+    because the migration is reviewed as text. ``dict.fromkeys`` is the dedupe:
+    it preserves insertion order and collapses the repeat.
+    """
+    ordered = (*labels, AUTHORED_IN_THEURIAN) if authored_here else labels
+    return tuple(dict.fromkeys(ordered))
+
+
 def _anchor(
     provider: str, uri: str | None, commit: str | None, file_path: str | None
 ) -> SourceAnchor | None:
@@ -513,7 +634,9 @@ def _service(context: CommandContext) -> ProposalService:
     )
 
 
-def _drafted_payload(drafted: DraftedProposal, context: CommandContext) -> dict[str, object]:
+def _drafted_payload(
+    drafted: DraftedProposal, context: CommandContext, inputs: _Inputs
+) -> dict[str, object]:
     root = context.paths.root
     return {
         "proposalId": drafted.proposal_id.value,
@@ -529,10 +652,61 @@ def _drafted_payload(drafted: DraftedProposal, context: CommandContext) -> dict[
         "contentFile": drafted.content_file,
         "contentSha256": drafted.content_sha256.value,
         "bodyDestination": _relative(drafted.body_destination, root),
-        "nextSteps": list(_DRAFT_STEPS),
+        "nextSteps": _draft_steps(inputs),
     }
 
 
+def _draft_steps(inputs: _Inputs) -> list[str]:
+    """The next-steps list, with the governed-defaults warning first when owed.
+
+    #249: an omitted ``--trust-level`` or ``--sensitivity`` is not an error --
+    the schema defaults are the honest answer for an agent's unreviewed draft --
+    but the loader fills ``unverified``/``internal`` silently, and both are
+    published on every retrieval result. The migration is deliberately left
+    without those keys (writing them would state a judgement the caller never
+    made, and would break the compatibility pin), so the surfacing lives here:
+    naming the default the revision will publish, and how to set it, is what
+    keeps a reviewed, public ADR from acquiring ``unverified``/``internal`` with
+    nothing telling the caller.
+    """
+    note = _governed_defaults_note(inputs.trust_level, inputs.sensitivity)
+    return [note, *_DRAFT_STEPS] if note is not None else list(_DRAFT_STEPS)
+
+
+def _governed_defaults_note(
+    trust_level: TrustLevel | None, sensitivity: Sensitivity | None
+) -> str | None:
+    """Name the governed fields left unset and the default each will publish.
+
+    ``None`` when both were given: there is then no default to warn about. The
+    defaults are read from :data:`DEFAULT_TRUST_LEVEL` and
+    :data:`DEFAULT_SENSITIVITY` -- the same constants the loader's ``.get(...)``
+    fallbacks apply when a migration omits these keys -- so the value named here
+    and the value the revision will publish are one definition, not two that
+    happen to agree.
+    """
+    omitted = [
+        (field, default, option)
+        for value, field, default, option in (
+            (trust_level, "trustLevel", DEFAULT_TRUST_LEVEL.value, "--trust-level"),
+            (sensitivity, "sensitivity", DEFAULT_SENSITIVITY.value, "--sensitivity"),
+        )
+        if value is None
+    ]
+    if not omitted:
+        return None
+    plural = len(omitted) > 1
+    fields = " and ".join(field for field, _, _ in omitted)
+    defaults = " and ".join(f"{field}: {default}" for field, default, _ in omitted)
+    options = " and ".join(option for _, _, option in omitted)
+    return (
+        f"{fields} {'were' if plural else 'was'} not set, so this revision will publish "
+        f"{defaults} -- the schema default{'s' if plural else ''} -- on every knowledge.search "
+        f"and knowledge.get result. If that is not right for this knowledge, re-draft with "
+        f"{options}."
+    )
+
+
 def _relative(path: Path, root: Path) -> str:
     try:
         return path.relative_to(root).as_posix()

{theurian-0.1.0.dev6 → theurian-0.1.0.dev7}/src/theurian/domain/migration.py

@@ -39,6 +39,14 @@ MIGRATION_API_VERSION: Final = "theurian.dev/v1"
 #: reinterpreting it (ADR-0007).
 MIGRATION_ENGINE_VERSION: Final = 1
 
+#: The governed metadata a revision acquires when its migration omits it. These
+#: are the single source of truth: the dataclass defaults below, the loader's
+#: ``.get(...)`` fallbacks, and the ``propose`` note that warns an author which
+#: default an omission will publish all read *these* constants, so the warning
+#: cannot claim one value while the loader fills another (#249).
+DEFAULT_TRUST_LEVEL: Final = TrustLevel.UNVERIFIED
+DEFAULT_SENSITIVITY: Final = Sensitivity.INTERNAL
+
 
 class OperationKind(StrEnum):
     """The closed operation set. Adding one bumps ``apiVersion`` (ADR-0005)."""
@@ -84,8 +92,8 @@ class CreateItem(Operation):
     kind_: KnowledgeKind
     namespace: str
     owner: str
-    sensitivity: Sensitivity = Sensitivity.INTERNAL
-    trust_level: TrustLevel = TrustLevel.UNVERIFIED
+    sensitivity: Sensitivity = DEFAULT_SENSITIVITY
+    trust_level: TrustLevel = DEFAULT_TRUST_LEVEL
 
     @override
     @property
@@ -103,8 +111,8 @@ class RevisionMetadataSpec:
     namespace: str
     status: KnowledgeStatus
     owner: str
-    trust_level: TrustLevel = TrustLevel.UNVERIFIED
-    sensitivity: Sensitivity = Sensitivity.INTERNAL
+    trust_level: TrustLevel = DEFAULT_TRUST_LEVEL
+    sensitivity: Sensitivity = DEFAULT_SENSITIVITY
     tenant_id: str = "local"
     acl_group: str = "default"
     valid_from: datetime | None = None

{theurian-0.1.0.dev6 → theurian-0.1.0.dev7}/src/theurian/infrastructure/filesystem/migration_loader.py

@@ -39,6 +39,8 @@ from theurian.domain.errors import (
 from theurian.domain.identifiers import ItemId, MigrationId, RevisionId, SpecId
 from theurian.domain.knowledge import SourceAnchor
 from theurian.domain.migration import (
+    DEFAULT_SENSITIVITY,
+    DEFAULT_TRUST_LEVEL,
     MIGRATION_API_VERSION,
     AddAlias,
     AddEvidence,
@@ -608,8 +610,8 @@ def _parse_operation(  # noqa: PLR0911, PLR0912 -- a flat dispatch over 14 opera
                 kind_=KnowledgeKind(payload["kind"]),
                 namespace=payload["namespace"],
                 owner=payload["owner"],
-                sensitivity=Sensitivity(payload.get("sensitivity", "internal")),
-                trust_level=TrustLevel(payload.get("trustLevel", "unverified")),
+                sensitivity=Sensitivity(payload.get("sensitivity", DEFAULT_SENSITIVITY.value)),
+                trust_level=TrustLevel(payload.get("trustLevel", DEFAULT_TRUST_LEVEL.value)),
             )
         case "upsertRevision":
             return _parse_upsert(payload, path, project_root, migrations_dir, content_by_hash)
@@ -785,8 +787,8 @@ def _parse_upsert(
             namespace=metadata["namespace"],
             status=KnowledgeStatus(metadata["status"]),
             owner=metadata["owner"],
-            trust_level=TrustLevel(metadata.get("trustLevel", "unverified")),
-            sensitivity=Sensitivity(metadata.get("sensitivity", "internal")),
+            trust_level=TrustLevel(metadata.get("trustLevel", DEFAULT_TRUST_LEVEL.value)),
+            sensitivity=Sensitivity(metadata.get("sensitivity", DEFAULT_SENSITIVITY.value)),
             tenant_id=metadata.get("tenantId", "local"),
             acl_group=metadata.get("aclGroup", "default"),
             valid_from=_optional_datetime(metadata.get("validFrom"), path),

{theurian-0.1.0.dev6 → theurian-0.1.0.dev7}/tests/integration/test_proposal_service.py

@@ -223,13 +223,15 @@ def test_generation_modifies_no_file_outside_the_proposal_directory(
 def test_a_generated_revision_is_status_approved_and_carries_no_trust_level(
     service: ProposalService,
 ) -> None:
-    """m07/b24: ``status: approved`` is fixed, and ``trustLevel`` is never smuggled in.
+    """m07/b24: ``status: approved`` is fixed, and ``trustLevel`` is never invented.
 
     ``status: approved`` is right even though nobody has approved it: the file
     applies only after a human has merged it, and ``draft`` would keep the
     knowledge out of the default index. ``trustLevel: reviewed`` on an agent's
     draft, by contrast, would claim a review that has not happened -- so the
-    generator omits ``trustLevel`` entirely and leaves it to a reviewer.
+    generator writes ``trustLevel`` only when the caller states one (#249's
+    ``--trust-level``); ``_request`` here states none, so it stays out of the
+    file and the loader's ``unverified`` default applies.
     """
     metadata = _upsert(service.draft(_request()).migration_file)["metadata"]
     assert isinstance(metadata, dict)