memleaf 0.2.7__tar.gz → 0.2.9__tar.gz

{memleaf-0.2.7 → memleaf-0.2.9}/CHANGELOG.md

@@ -2,6 +2,30 @@
 
 All notable changes to memleaf are documented here.
 
+## 0.2.9 — 2026-09-01
+
+- Reject update and duplicate targets that are relevant only to another item
+  in the same aggregate turn, preventing cross-project memory overwrites.
+- Retry an unrelated gate target with an explicit correction, then recover
+  deterministically after the bounded final attempt: preserve unrelated
+  updates as independent candidates and discard unsafe duplicate claims.
+- Query related memories from each candidate's own complete topic instead of
+  the whole mailbox turn, while allowing the remaining valid candidates to be
+  processed without holding the retained inbox turn hostage.
+
+## 0.2.8 — 2026-09-01
+
+- Let the automatic summarizer independently reject an over-admitted gate
+  candidate with an exact `NO_CHANGE` response, without writing memory,
+  history, or Scope state; explicit remember remains write-oriented and does
+  not permit this response.
+- Ground every model-attributed project Scope in the candidate's own project
+  name or registered alias, and prevent the summarizer from drifting away
+  from the gate-selected Scope.
+- Register session and Vault Scopes only for committed memories or trusted
+  active duplicate targets, so temporary, deferred, and no-change mailbox
+  items cannot pollute Scope state.
+
 ## 0.2.7 — 2026-09-01
 
 - Distinguish an invalid gate type enum from a candidate type that conflicts

{memleaf-0.2.7/src/memleaf.egg-info → memleaf-0.2.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: memleaf
-Version: 0.2.7
+Version: 0.2.9
 Summary: A local-first Markdown memory core for AI agents
 Author: memleaf contributors
 License-Expression: MIT
@@ -23,8 +23,8 @@ Dynamic: license-file
 
 [English](README.en.md) · [PyPI](https://pypi.org/project/memleaf/) · [GitHub](https://github.com/miffyblueboo/memleaf)
 
-> **当前版本：0.2.7。**
-> 核心库、Vault、stdio MCP Server、初始化 CLI、模型路由、提炼流程、受控检索协议和宿主适配器已经实现。memleaf 0.2.7 通过 PyPI 分发。
+> **当前版本：0.2.9。**
+> 核心库、Vault、stdio MCP Server、初始化 CLI、模型路由、提炼流程、受控检索协议和宿主适配器已经实现。memleaf 0.2.9 通过 PyPI 分发。
 > **当前版本支持 Hermes 和 Codex。** Antigravity（反重力）不检测、不安装、不配置。
 
 ## 项目定位

{memleaf-0.2.7 → memleaf-0.2.9}/README.en.md

@@ -4,8 +4,8 @@
 
 [中文](README.md) · [PyPI](https://pypi.org/project/memleaf/) · [GitHub](https://github.com/miffyblueboo/memleaf)
 
-> **Version: 0.2.4.**
-> The core library, Vault, stdio MCP server, initialization CLI, model routing, memory extraction, controlled retrieval protocol, and host adapters are implemented. memleaf 0.2.4 is distributed through PyPI.
+> **Version: 0.2.9.**
+> The core library, Vault, stdio MCP server, initialization CLI, model routing, memory extraction, controlled retrieval protocol, and host adapters are implemented. memleaf 0.2.9 is distributed through PyPI.
 > **The current release supports Hermes and Codex.** Antigravity is not detected, installed, or configured.
 
 ## Project scope

{memleaf-0.2.7 → memleaf-0.2.9}/README.md

@@ -4,8 +4,8 @@
 
 [English](README.en.md) · [PyPI](https://pypi.org/project/memleaf/) · [GitHub](https://github.com/miffyblueboo/memleaf)
 
-> **当前版本：0.2.7。**
-> 核心库、Vault、stdio MCP Server、初始化 CLI、模型路由、提炼流程、受控检索协议和宿主适配器已经实现。memleaf 0.2.7 通过 PyPI 分发。
+> **当前版本：0.2.9。**
+> 核心库、Vault、stdio MCP Server、初始化 CLI、模型路由、提炼流程、受控检索协议和宿主适配器已经实现。memleaf 0.2.9 通过 PyPI 分发。
 > **当前版本支持 Hermes 和 Codex。** Antigravity（反重力）不检测、不安装、不配置。
 
 ## 项目定位

{memleaf-0.2.7 → memleaf-0.2.9}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "memleaf"
-version = "0.2.7"
+version = "0.2.9"
 description = "A local-first Markdown memory core for AI agents"
 readme = "README.md"
 requires-python = ">=3.11"

{memleaf-0.2.7 → memleaf-0.2.9}/src/memleaf/__init__.py

@@ -1,6 +1,6 @@
 """Local-first Markdown memory core for AI agents."""
 
-__version__ = "0.2.7"
+__version__ = "0.2.9"
 
 from .config import DEFAULT_CONFIG, default_config, load_config, save_config
 from .frontmatter import FrontmatterError, dump_frontmatter, dump_yaml, load_yaml, parse_frontmatter

{memleaf-0.2.7 → memleaf-0.2.9}/src/memleaf/hermes_provider/__init__.py

@@ -78,6 +78,9 @@ _MODEL_VALIDATION_DETAILS = frozenset(
         "duplicate_update_target",
         "mixed_project_scopes",
         "update_target_type_mismatch",
+        "target_not_relevant",
+        "scope_not_grounded",
+        "scope_drift",
         "invalid_evidence",
         "invalid_flags",
         "invalid_type",

{memleaf-0.2.7 → memleaf-0.2.9}/src/memleaf/hermes_provider/plugin.yaml

@@ -1,5 +1,5 @@
 name: memleaf
-version: 0.2.7
+version: 0.2.9
 description: "Hermes-native external MemoryProvider for local-first Markdown memory shared with the memleaf MCP server."
 hooks:
   - prefetch

{memleaf-0.2.7 → memleaf-0.2.9}/src/memleaf/processing.py

@@ -37,9 +37,12 @@ from .prompts import (
     MIXED_PROJECT_SCOPES_CORRECTION,
     RELATIVE_TIME_CORRECTION,
     GATE_SYSTEM,
+    SCOPE_GROUNDING_CORRECTION,
+    SUMMARY_SCOPE_CORRECTION,
     SUMMARY_TARGET_CORRECTION,
     SUMMARY_TYPE_CORRECTION,
     SUMMARIZE_SYSTEM,
+    TARGET_RELEVANCE_CORRECTION,
     UPDATE_TARGET_TYPE_CORRECTION,
     gate_prompt,
     summarize_prompt,
@@ -51,6 +54,7 @@ from .scope_maintenance import ScopeMaintainer, ScopeMaintenanceError, scope_reg
 from .validation import (
     MODEL_VALIDATION_DETAILS,
     ModelOutputError,
+    NO_CHANGE_DECISION,
     parse_gate_output,
     parse_summarize_output,
 )
@@ -488,6 +492,12 @@ class Processor:
             return UPDATE_TARGET_TYPE_CORRECTION
         if stage == "gate" and hint == "invalid_type":
             return GATE_TYPE_CORRECTION
+        if stage == "gate" and hint == "scope_not_grounded":
+            return SCOPE_GROUNDING_CORRECTION
+        if stage == "gate" and hint == "target_not_relevant":
+            return TARGET_RELEVANCE_CORRECTION
+        if stage == "summarize" and hint == "scope_drift":
+            return SUMMARY_SCOPE_CORRECTION
         if hint == "relative_time":
             return RELATIVE_TIME_CORRECTION
         if stage == "summarize" and hint == "invalid_update_target":
@@ -1412,6 +1422,157 @@ class Processor:
             strict_relevance=True,
         )
 
+    def _target_is_relevant_to_candidate(
+        self,
+        turn: InboxTurn,
+        candidate: Mapping[str, Any],
+        *,
+        scope_directory: Optional[list[dict[str, Any]]] = None,
+        scope_directory_complete: bool = True,
+    ) -> bool:
+        """Check a model-selected target against the candidate topic only.
+
+        The ordinary related-memory prompt may include several independent
+        items from one mailbox turn.  Target selection must not inherit that
+        aggregate relevance: only the candidate's own extracted topic may
+        make an active target eligible.  A complete scope directory remains a
+        bounded escape hatch for an explicitly indirect user/session scope;
+        it never turns the target into an unconditional priority hit for a
+        direct model-attributed candidate.
+        """
+
+        target = next(
+            (
+                candidate.get(field)
+                for field in ("duplicate_memory_id", "update_memory_id")
+                if isinstance(candidate.get(field), str) and candidate.get(field)
+            ),
+            None,
+        )
+        memory = candidate.get("memory")
+        candidate_scopes = candidate.get("scopes")
+        if (
+            not isinstance(target, str)
+            or not isinstance(memory, str)
+            or not isinstance(candidate_scopes, list)
+        ):
+            return False
+
+        target_key = target.casefold()
+        candidate_scope_source = candidate.get("scope_source")
+
+        # A complete bounded directory is the existing indirect resolution
+        # path.  It contains only active IDs from the requested inherited
+        # scope, so preserve its exact-ID selection semantics rather than
+        # forcing a body relevance check that the directory intentionally
+        # cannot provide.
+        if scope_directory is not None:
+            if not scope_directory_complete:
+                return False
+            selected = next(
+                (
+                    item
+                    for item in scope_directory
+                    if isinstance(item, Mapping)
+                    and isinstance(item.get("memory_id"), str)
+                    and item["memory_id"].casefold() == target_key
+                ),
+                None,
+            )
+            if selected is not None and selected.get("type") == candidate.get("type"):
+                return True
+
+        # Model-attributed, directly named scopes must match the active
+        # target's stable topic title.  Matching the whole old body is too
+        # permissive: two different project memories can share implementation
+        # details such as milestones while serving different future uses.
+        if candidate_scope_source == "model":
+            scope_terms: list[str] = []
+            try:
+                scope_config = self.service.vault.config()
+                configured_scopes = scope_config.get("scopes", {})
+            except (OSError, UnicodeError, ValueError, TypeError):
+                scope_config = {}
+                configured_scopes = {}
+            for candidate_scope in candidate_scopes:
+                if not isinstance(candidate_scope, str) or not candidate_scope.startswith("project:"):
+                    continue
+                scope_terms.append(candidate_scope.partition(":")[2])
+                metadata = (
+                    configured_scopes.get(candidate_scope)
+                    if isinstance(configured_scopes, Mapping)
+                    else None
+                )
+                aliases = metadata.get("aliases") if isinstance(metadata, Mapping) else None
+                if isinstance(aliases, list):
+                    scope_terms.extend(
+                        alias for alias in aliases if isinstance(alias, str) and alias
+                    )
+
+            # The regression is project-scope drift inside aggregate turns.
+            # Global/domain/portfolio targets keep their established semantic
+            # gate behavior because there is no project identity to remove
+            # before comparing stable topics.
+            if not scope_terms:
+                return True
+
+            visible_turn = " ".join(
+                event.content for event in turn.events if isinstance(event.content, str)
+            )
+            if scope_terms and not any(
+                normalize_term(term) in normalize_term(visible_turn) for term in scope_terms
+            ):
+                # The visible turn is elliptical (for example, "this
+                # project"); the inherited scope and bounded related context
+                # already resolved its target.
+                return True
+
+            target_memory = None
+            with self.service.vault.lock():
+                for record in self.service._read_memories_unlocked("knowledge"):
+                    if record.memory.memory_id.casefold() == target_key:
+                        target_memory = record.memory
+                        break
+            if target_memory is None:
+                for item in self._planned_related:
+                    if (
+                        isinstance(item, Mapping)
+                        and isinstance(item.get("memory_id"), str)
+                        and item["memory_id"].casefold() == target_key
+                    ):
+                        try:
+                            target_memory = Memory.from_mapping(item)
+                        except (TypeError, ValueError):
+                            target_memory = None
+                        break
+            if target_memory is None:
+                return False
+            if not filter_by_scope([target_memory], candidate_scopes, scope_config):
+                return False
+
+            def without_scope_terms(value: str) -> str:
+                result = value
+                for term in sorted(set(scope_terms), key=len, reverse=True):
+                    result = re.sub(re.escape(term), "", result, flags=re.IGNORECASE)
+                return result.strip()
+
+            topic_title = without_scope_terms(target_memory.title)
+            topic_query = without_scope_terms(memory)
+            if not topic_title or not topic_query:
+                return False
+            topic_memory = Memory(
+                memory_id=target_memory.memory_id,
+                title=topic_query,
+                body="",
+                type=target_memory.type,
+                scopes=target_memory.scopes,
+            )
+            return candidate_matches_query(topic_memory, topic_title)
+
+        # User/session scopes are authoritative indirect context.  The base
+        # parser has already limited the target to an active related memory.
+        return candidate_scope_source in {"user", "session_context"}
+
     def _defer_candidate(
         self,
         turn_ref: tuple[str, str, str],
@@ -1614,6 +1775,7 @@ class Processor:
                     related_native_ids=related_native_ids,
                     related_memory_ids=related_memory_ids,
                     scope_registry=validation_scope_registry,
+                    allow_no_change=False,
                 ),
                 diagnostic_context={
                     "source": turn.source,
@@ -1635,6 +1797,60 @@ class Processor:
                 list(summary["scopes"]),
             )
 
+        gate_attempt_count = 0
+
+        def parse_gate(raw: str) -> dict[str, Any]:
+            nonlocal gate_attempt_count
+            gate_attempt_count += 1
+            parsed = parse_gate_output(
+                raw,
+                current_event_keys=turn.event_keys,
+                related_memory_ids=gate_related_memory_ids,
+                related_memory_types=gate_related_memory_types,
+                scope_registry=validation_scope_registry,
+            )
+            invalid_targets: dict[str, set[str]] = {}
+            for candidate in parsed["candidates"]:
+                target_fields = {
+                    field
+                    for field in ("duplicate_memory_id", "update_memory_id")
+                    if isinstance(candidate.get(field), str) and candidate.get(field)
+                }
+                if target_fields and not self._target_is_relevant_to_candidate(
+                    turn,
+                    candidate,
+                    scope_directory=scope_directory,
+                    scope_directory_complete=scope_directory_complete,
+                ):
+                    invalid_targets[candidate["candidate_id"].casefold()] = target_fields
+
+            if invalid_targets and gate_attempt_count < 3:
+                raise ModelOutputError(
+                    "selected target is not relevant to the candidate topic",
+                    validation_detail="target_not_relevant",
+                )
+
+            if invalid_targets:
+                # A persistently non-converging model must not hold an entire
+                # inbox turn hostage.  An unrelated update target can safely
+                # become an independent CREATE candidate; an unrelated
+                # duplicate has no independent fact to write and is dropped.
+                candidates: list[dict[str, Any]] = []
+                for candidate in parsed["candidates"]:
+                    fields = invalid_targets.get(candidate["candidate_id"].casefold())
+                    if not fields:
+                        candidates.append(candidate)
+                        continue
+                    if "duplicate_memory_id" in fields:
+                        continue
+                    if "update_memory_id" in fields and candidate.get("worth"):
+                        independent = dict(candidate)
+                        independent.pop("update_memory_id", None)
+                        candidates.append(independent)
+                parsed = dict(parsed)
+                parsed["candidates"] = candidates
+            return parsed
+
         gate = self._complete_json_stage(
             backend,
             gate_prompt(
@@ -1647,12 +1863,7 @@ class Processor:
             ),
             system=GATE_SYSTEM,
             purpose="gate",
-            parser=lambda raw: parse_gate_output(
-                raw,
-                current_event_keys=turn.event_keys,
-                related_memory_ids=gate_related_memory_ids,
-                related_memory_types=gate_related_memory_types,
-            ),
+            parser=parse_gate,
             diagnostic_context={
                 "source": turn.source,
                 "session_id": turn.session_id,
@@ -1663,13 +1874,6 @@ class Processor:
         observed_scopes: list[str] = []
         for candidate in gate["candidates"]:
             candidate_scopes = list(candidate["scopes"])
-            if (
-                candidate_scopes != ["unscoped"]
-                and candidate.get("scope_source") != "insufficient_context"
-            ):
-                for observed_scope in candidate_scopes:
-                    if observed_scope not in observed_scopes:
-                        observed_scopes.append(observed_scope)
             # An automatic candidate with no reliable project attribution is
             # retained as a retryable inbox turn, never silently promoted to
             # global knowledge.  The processed ledger records only a compact
@@ -1708,15 +1912,7 @@ class Processor:
             candidate_related, candidate_scope_background, candidate_native_refs, _ = self._related_query(
                 turn,
                 state,
-                (
-                    str(candidate.get("memory", ""))
-                    + "\n"
-                    + " ".join(
-                        event.get("content", "")
-                        for event in events
-                        if isinstance(event.get("content"), str)
-                    )
-                ).strip(),
+                str(candidate.get("memory", "")).strip(),
                 candidate_scopes,
                 overlay=self._planned_related,
                 priority_memory_ids=[
@@ -1758,6 +1954,27 @@ class Processor:
                             native_refs=candidate_native_refs,
                         )
                     )
+                    # Automatic duplicate observations are metadata no-ops;
+                    # only the already-active target's scopes are trustworthy
+                    # session context, never a transient model-provided scope.
+                    duplicate_scopes = next(
+                        (
+                            item.get("scopes")
+                            for item in candidate_related
+                            if isinstance(item, Mapping)
+                            and isinstance(item.get("memory_id"), str)
+                            and item["memory_id"].casefold() == duplicate_memory_id.casefold()
+                            and isinstance(item.get("scopes"), list)
+                        ),
+                        [],
+                    )
+                    for observed_scope in duplicate_scopes:
+                        if (
+                            isinstance(observed_scope, str)
+                            and observed_scope != "unscoped"
+                            and observed_scope not in observed_scopes
+                        ):
+                            observed_scopes.append(observed_scope)
                 continue
 
             gate_update_target = candidate.get("update_memory_id")
@@ -1793,6 +2010,9 @@ class Processor:
                     related_native_ids=candidate_native_ids,
                     related_memory_ids=candidate_memory_ids,
                     scope_registry=validation_scope_registry,
+                    expected_scopes=candidate["scopes"],
+                    expected_scope_source=candidate["scope_source"],
+                    allow_no_change=True,
                     expected_type=(
                         candidate.get("type")
                         if (
@@ -1814,6 +2034,8 @@ class Processor:
                     "turn_index": turn.turn_index,
                 },
             )
+            if summary.get("decision") == NO_CHANGE_DECISION:
+                continue
             if gate_update_target is not None:
                 summary_update_target = summary.get("update_memory_id")
                 if summary_update_target is None:
@@ -1839,9 +2061,6 @@ class Processor:
                     scope_source=summary.get("scope_source"),
                 )
                 continue
-            for observed_scope in summary["scopes"]:
-                if observed_scope not in observed_scopes:
-                    observed_scopes.append(observed_scope)
             requests.append(
                 self._request(
                     summary,
@@ -1851,6 +2070,13 @@ class Processor:
                     native_refs=candidate_native_refs,
                 )
             )
+            for observed_scope in summary["scopes"]:
+                if (
+                    isinstance(observed_scope, str)
+                    and observed_scope != "unscoped"
+                    and observed_scope not in observed_scopes
+                ):
+                    observed_scopes.append(observed_scope)
         return requests, observed_scopes
 
     def _state_for_snapshot_unlocked(self, snapshot: _Snapshot, processed: Mapping[str, Any]) -> Mapping[str, Any]:

{memleaf-0.2.7 → memleaf-0.2.9}/src/memleaf/prompts.py

@@ -34,6 +34,15 @@ useful. Related active memories only identify a complete duplicate or valid
 state-update target; they are not current evidence and cannot make a non-worthy
 operational/test result worthy. Their item, body, and serialized-character
 context is bounded; ellipses and omissions do not prove a fact is absent.
+For a worthy candidate with scope_source=model, each selected project scope must
+be grounded by this candidate's own memory text: use the project's registered
+scope name or one of its registered aliases; for a new unregistered project
+scope, use that project's name itself. Do not borrow a project name from another
+event, the session background, related memories, or an aggregate mailbox turn.
+If the candidate text does not identify exactly one selected project, choose an
+evidence-supported project, use unscoped with insufficient_context, defer it, or
+set worth=false. user and session_context scope sources may rely on their
+authoritative scope context.
 An update target's existing type is immutable: when the same future use is being
 updated, candidate type must exactly equal the related active target type. If a
 fact serves a different future use, do not force it onto that target; omit
@@ -156,6 +165,16 @@ When the gate candidate supplies update_memory_id, that target is immutable:
 omit update_memory_id or copy that exact active ID, never replace it with a
 different, guessed, native, or historical ID. Keep the summary type identical
 to the gate candidate type and to the active update target type.
+For automatic capture/process, independently re-check whether this candidate
+still has a concrete future-use fact or action. If not, return exactly
+{"decision":"NO_CHANGE"}; this is the only no-write summary response. Use it
+for temporary delegation, waiting for feedback, a one-off meeting arrangement with
+no durable outcome/decision/project constraint, or a subject/attachment-only item
+without a concrete impact or conclusion.
+Explicit remember mode never permits NO_CHANGE and must return the normal summary
+object. When producing a normal automatic summary, copy the gate candidate's
+scopes exactly. scope_source may be omitted to inherit the gate value, but an
+explicit value must match it; never drift to another project.
 For the same use, preserve still-valid facts, add confirmed progress, replace
 contradictions, and never reduce the memory to the latest operation or create a
 sibling with a new label.
@@ -306,6 +325,40 @@ SUMMARY_TYPE_CORRECTION = (
 )
 
 
+SUMMARY_SCOPE_CORRECTION = (
+    "Previous output violated: scope_drift. For a normal automatic summary, copy "
+    "the gate candidate scopes exactly and keep its scope_source unchanged. If "
+    "scope_source was omitted, inherit the gate value; an explicit value must "
+    "match it. Do not move the memory to another project. If the candidate has "
+    "no independent future-use fact or action, return exactly "
+    '{"decision":"NO_CHANGE"}. Return only the strict JSON object.'
+)
+
+
+TARGET_RELEVANCE_CORRECTION = (
+    "Previous output violated: target_not_relevant. An update or duplicate "
+    "target must match the candidate's own memory topic through the supplied "
+    "active memory; do not borrow relevance from another event in the same "
+    "mailbox turn, aggregate context, or a priority ID. For a different "
+    "future use, remove the target and emit a separate atomic candidate. An "
+    "indirect same-use update may use a complete scope directory or session "
+    "context only when exactly one supplied active target is clear; otherwise "
+    "leave the target unset or defer it. Return only the strict gate JSON object."
+)
+
+
+SCOPE_GROUNDING_CORRECTION = (
+    "Previous output violated: scope_not_grounded. For each worthy candidate "
+    "with scope_source=model, choose a project scope named by that candidate's "
+    "own memory text: use the registered project name or alias, or the name "
+    "itself for a new scope. Do not borrow a name from another event, related "
+    "memory, session background, or an aggregate mailbox turn. If exactly one "
+    "project cannot be supported, choose the evidence-supported scope, use "
+    "unscoped with insufficient_context, defer it, or set worth=false. Return "
+    "only the strict gate JSON object."
+)
+
+
 COMPACT_SYSTEM = """You are memleaf's memory compactor. Return JSON only.
 Merge only the supplied low-priority memories when they express compatible
 information. Return an object with a memories array; [] is a safe no-op.
@@ -398,6 +451,14 @@ def summarize_prompt(
         f"Current scope registry (safe projection; no paths):\n"
         f"{_json(scope_registry if scope_registry is not None else [])}\n"
     )
+    if not explicit:
+        prompt += (
+            "Automatic admission re-check: if the candidate has no independent "
+            "future-use fact or action after reviewing the evidence, return exactly "
+            '{"decision":"NO_CHANGE"}; do not return an empty or partial memory object. '
+            "For a normal summary, copy Candidate scopes exactly; omit scope_source "
+            "to inherit it or repeat the same value, never choose another scope.\n"
+        )
     example_key = _first_event_key(events)
     if example_key is not None:
         candidate_type = candidate.get("type") if isinstance(candidate, dict) else None
@@ -431,6 +492,8 @@ def summarize_prompt(
                 }
             )
         )
+    if not explicit:
+        return prompt + '\nReturn one summary JSON object or exactly {"decision":"NO_CHANGE"}.'
     return prompt + "\nReturn one summary JSON object."
 
 

{memleaf-0.2.7 → memleaf-0.2.9}/src/memleaf/scope_state.py

@@ -256,9 +256,20 @@ def _term_matches(query: str, term: str) -> bool:
 def resolve_query_project_scope(query: Any, config: Mapping[str, Any]) -> str | None:
     """Return one unambiguous project scope named or aliased by ``query``."""
 
+    matches = project_scope_matches_text(query, config)
+    return matches[0] if len(matches) == 1 else None
+
+
+def project_scope_matches_text(query: Any, config: Mapping[str, Any]) -> list[str]:
+    """Return registered project scopes named or aliased by text.
+
+    Matching uses the same token/substring rules as query scope resolution,
+    but retains every match so callers can reject ambiguous model attribution.
+    """
+
     query_value = _query_text(query)
     if not query_value:
-        return None
+        return []
     registry = validate_scope_registry(config.get("scopes", {}) if isinstance(config, Mapping) else {})
     matches: set[str] = set()
     for scope, node in registry.items():
@@ -271,7 +282,7 @@ def resolve_query_project_scope(query: Any, config: Mapping[str, Any]) -> str |
             terms.extend(item for item in aliases if isinstance(item, str))
         if any(_term_matches(query_value, term) for term in terms):
             matches.add(scope)
-    return next(iter(matches)) if len(matches) == 1 else None
+    return sorted(matches, key=str.casefold)
 
 
 def _resolved_path(value: str | Path, *, base_dir: Path | None = None) -> Path:
@@ -320,6 +331,7 @@ def resolve_project_path_scope(
 __all__ = [
     "ScopeError",
     "normalize_scopes",
+    "project_scope_matches_text",
     "register_scope_nodes",
     "resolve_project_path_scope",
     "resolve_query_project_scope",