marvisx-cli 0.3.7b2__tar.gz → 0.3.8__tar.gz

{marvisx_cli-0.3.7b2 → marvisx_cli-0.3.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: marvisx-cli
-Version: 0.3.7b2
+Version: 0.3.8
 Summary: MarvisX OSS — agent-native company-brain CLI runtime (init, status, brief, triage)
 Author: MarvisX maintainers
 License: BSL-1.1

{marvisx_cli-0.3.7b2 → marvisx_cli-0.3.8}/core/api/config.py

@@ -125,6 +125,13 @@ class Settings(BaseSettings):
         default=86400, alias="BRAIN_WAREHOUSE_CONSOLIDATION_INTERVAL_SECONDS"
     )
 
+    # KG temporal recency pass (Fase D producer): proposes re-verifying aging,
+    # never-verified live nodes. Gated by temporal_memory_enabled (no separate
+    # enable flag — the flag IS the gate). Daily cadence guard.
+    brain_temporal_recency_interval_seconds: int = Field(
+        default=86400, alias="BRAIN_TEMPORAL_RECENCY_INTERVAL_SECONDS"
+    )
+
     # GitHub Webhook
     github_webhook_secret: str = ""
 
@@ -439,6 +446,103 @@ class Settings(BaseSettings):
         False  # pydantic-settings maps KG_HTTP_DEEP_DEFAULT env var
     )
 
+    # Track 2 #3a — STRUCTURAL graph-lane in the RRF fusion (DEFAULT OFF).
+    # When False the fused ranking is byte-identical to today (5 lanes). When
+    # True a 6th lane (seeded 1-hop edge-weighted KG expansion) joins the blend.
+    # graph_lane_hops / graph_lane_fanout / graph_lane_weight / graph_lane_seeds
+    # tune the lane without code changes. Edge-type subset = all 15 by default.
+    graph_lane_enabled: bool = Field(
+        default=False, alias="MARVIS_GRAPH_LANE"
+    )
+    graph_lane_hops: int = Field(default=1, alias="MARVIS_GRAPH_LANE_HOPS")
+    graph_lane_fanout: int = Field(default=25, alias="MARVIS_GRAPH_LANE_FANOUT")
+    graph_lane_seeds: int = Field(default=10, alias="MARVIS_GRAPH_LANE_SEEDS")
+    graph_lane_weight: float = Field(
+        default=0.12, alias="MARVIS_GRAPH_LANE_WEIGHT"
+    )
+    # #13: when a graph read finds its index stale/behind HEAD, surface the
+    # reindex as an EXPLICIT next action (command + auto_reindex marker). Default
+    # off; even when on, a read NEVER fires the (heavy, repo-re-parsing) KG
+    # reindex itself — re-indexing stays an explicit operation.
+    graph_autoreindex_on_drift: bool = Field(
+        default=False, alias="MARVIS_GRAPH_AUTOREINDEX_ON_DRIFT"
+    )
+
+    # Track 2 #1 — bi-temporal memory READ path (DEFAULT OFF). When False every
+    # learnings read is byte-identical to today (no invalid_at filter, no as_of):
+    # the temporal helper emits NO extra SQL. When True the default learnings
+    # reads (check/list/get + the learnings retrieval lane in search) add
+    # ``AND invalid_at IS NULL`` — a MECHANICAL, BINARY exclusion (superseded rows
+    # never reach the LLM; never a down-weight, which would still let the model
+    # cite the stale value). An explicit ``as_of=<ISO>`` relaxes the filter to the
+    # point-in-time window ``valid_from <= as_of AND (invalid_at IS NULL OR
+    # invalid_at > as_of)`` for audit. S3/S4/S5 (write path / LLM tiebreak / dream
+    # cycle) reuse this SAME flag. Requires migration 148 columns when enabled.
+    temporal_memory_enabled: bool = Field(
+        default=False, alias="MARVIS_TEMPORAL_MEMORY"
+    )
+
+    # answer-ready claims (DEFAULT OFF). When False every reasoning-tool read is
+    # byte-identical to today (no `claims` key). When True, project_impact/
+    # graph_impact append a `claims[]` block: server-computed, relation-typed
+    # counts with provenance — the agent reports the value instead of re-counting
+    # raw edges (faithfulness). Separate from temporal_memory so grounding can be
+    # enabled without the freshness surface. See plan 2026-06-08-feat-answer-ready-claims.
+    kg_claims_enabled: bool = Field(
+        default=False, alias="MARVIS_KG_CLAIMS"
+    )
+
+    # Memory-freshness v2a Phase 1 (B-fix, DEFAULT OFF). The documents_fts
+    # INSERT/UPDATE triggers (migration 136) write file_path into the content
+    # column, so every doc written AFTER the one-time migration backfill has NO
+    # body in the lexical lane (prod 2026-06-09: 100% of recent docs degraded
+    # → the BM25 lane sees OLD bodies but never NEW ones — a direct stale-
+    # retrieval mechanism). When True, every documents upsert path additionally
+    # overwrites the trigger-degraded FTS row with the real title+body
+    # (refresh_documents_fts_row). When False the refresh helper is a no-op and
+    # behavior is byte-identical to today. The one-shot backfill script
+    # (scripts/backfill_documents_fts.py) repairs historical rows; in prod the
+    # flag must flip ON at backfill time and stay on, otherwise the next doc
+    # update re-degrades its row. See plan
+    # 2026-06-09-feat-memory-freshness-v2a-retrieval.
+    fts_bodies_enabled: bool = Field(
+        default=False, alias="MARVIS_FTS_BODIES"
+    )
+
+    # Memory-freshness v2a Phase 2 (A-span, DEFAULT OFF). When False the search
+    # read path never touches the chunks/vec_chunks sidecars and the response is
+    # byte-identical to today (no span_* fields populated). When True (and
+    # MARVIS_CHUNKING populated the sidecars), the semantic lane max-pools
+    # chunk-KNN hits into the doc ranking and each file-backed hit carries the
+    # winning chunk's span expanded to line boundaries ±12 lines (span_text /
+    # span_path / span_line_start / span_line_end) so the agent can answer FROM
+    # the search result without a follow-up Read. Write-side chunking stays
+    # gated by MARVIS_CHUNKING (env, read per-call). See plan
+    # 2026-06-09-feat-memory-freshness-v2a-retrieval.
+    search_spans_enabled: bool = Field(
+        default=False, alias="MARVIS_SEARCH_SPANS"
+    )
+
+    # Track 2 #3c — community summaries in the brief (GraphRAG global-search,
+    # DEFAULT OFF). When False the brief is byte-identical to today: the
+    # communities/community_summary modules are a flag-gated library + seam,
+    # never imported into session_brief. When True (off-host wiring), the KG is
+    # partitioned (deterministic label propagation, NO LLM) and per-community
+    # summaries enter the brief AFTER #2 so they inherit span-citation + NLI
+    # verification (a summary is itself a claim to ground, not free text).
+    community_summaries_enabled: bool = Field(
+        default=False, alias="MARVIS_COMMUNITY_SUMMARIES"
+    )
+
+    # Track 2 #2: span-citation + grounding-verification layer for the brief.
+    # DEFAULT OFF — the layer exists as a flag-gated library; when off the
+    # session_brief output is byte-for-byte unchanged (the seam is never entered).
+    # See core/api/services/grounding/. Wiring the NLI head (MiniCheck) is a
+    # separate, deliberate, off-host step (NoopVerifier is the default).
+    brief_citations_enabled: bool = Field(
+        default=False, alias="MARVIS_BRIEF_CITATIONS"
+    )
+
     # WIP limit: max tasks in_progress per project (doc/none tasks count as 0.5)
     wip_max_in_progress: int = 3
 
@@ -461,6 +565,15 @@ class Settings(BaseSettings):
     brain_llm_polish_enabled: bool = Field(
         default=True, alias="BRAIN_LLM_POLISH_ENABLED"
     )
+    # P1: pick the Brain LLM backend. "gateway" (default, unchanged) = the HTTP
+    # Mac-gateway client (requires BRAIN_LLM_GATEWAY_API_KEY). "claude_cli" = run
+    # `claude -p` headless on the user's Claude Code subscription (NO API key) —
+    # see core/api/services/brain/llm/claude_cli.py.
+    brain_llm_provider: Literal["gateway", "claude_cli"] = Field(
+        default="gateway", alias="BRAIN_LLM_PROVIDER"
+    )
+    # Path/name of the `claude` binary for the claude_cli provider.
+    marvis_claude_bin: str = Field(default="claude", alias="MARVIS_CLAUDE_BIN")
     brain_llm_journal_polish_enabled: bool = Field(
         default=True, alias="BRAIN_LLM_JOURNAL_POLISH_ENABLED"
     )

{marvisx_cli-0.3.7b2 → marvisx_cli-0.3.8}/core/api/db.py

@@ -118,6 +118,13 @@ async def init_pool(size: int = 2) -> None:
 
     Pool size=8 supports concurrent deep=true requests (4 parallel KG subqueries × 2 concurrent requests).
     """
+    # Apply any pending schema migrations before opening the pool, so EVERY
+    # entry point (CLI, MCP, brain, API) lands on a current schema — not only
+    # `marvis init` and the API lifespan. Idempotent and cheap when already
+    # current (the API path migrates explicitly first, so this finds nothing).
+    # Fail-loud here is a clearer signal than a later "no such column" on the
+    # first write against a half-upgraded DB. (#12)
+    run_migrations()
     global _pool, _pool_size, _writer
     actual_size = 8  # read-only pool: expanded for KG lens 4-subquery parallel pattern (Phase 7.0)
     _pool = asyncio.Queue(maxsize=actual_size)
@@ -732,54 +739,62 @@ def _backfill_session_uuids(conn: sqlite3.Connection) -> None:
 
 
 def _seed_users_and_migrate_owner(conn: sqlite3.Connection) -> None:
-    """Migration 016 post-hook: seed the admin user + data-migrate tasks.owner_id.
+    """Migration 016 post-hook: seed the admin user (when configured) + data-migrate
+    tasks.owner_id.
 
     Runs synchronously inside run_migrations() — do NOT use await here.
-    Accepts either PIR_ADMIN_PASSWORD_HASH (pre-hashed, preferred in production)
-    or PIR_PASSWORD (plaintext, will be bcrypt-hashed here).
-    At least one must be set or the migration aborts.
-
-    The admin identity is config-driven via the same MARVIS_ADMIN_* vars used by
-    the deploy bootstrap (scripts/init.sh), with generic defaults, so a fresh
-    install seeds no hardcoded name. On an existing deployment this seed is
-    skipped (users already exist), so the defaults never affect a running install.
-    """
-    # Prefer pre-hashed password. Canonical var is MARVIS_ADMIN_PASSWORD_HASH;
-    # PIR_ADMIN_PASSWORD_HASH stays accepted as a deprecated alias.
-    hashed = (
-        os.environ.get("MARVIS_ADMIN_PASSWORD_HASH")
-        or os.environ.get("PIR_ADMIN_PASSWORD_HASH", "")
-    ).strip()
-    if not hashed:
-        import bcrypt
-
-        seed_password = (
-            os.environ.get("MARVIS_PASSWORD")
-            or os.environ.get("PIR_PASSWORD", "")
-        ).strip()
-        if not seed_password:
-            raise RuntimeError(
-                "Migration 016 requires MARVIS_ADMIN_PASSWORD_HASH or MARVIS_PASSWORD "
-                "env var (PIR_* aliases still accepted) to seed the admin user. "
-                "Set at least one in .env."
-            )
-        hashed = bcrypt.hashpw(seed_password.encode("utf-8"), bcrypt.gensalt()).decode()
-
-    admin_id = os.environ.get("MARVIS_ADMIN_USER_ID", "").strip() or "usr_admin"
-    admin_slug = os.environ.get("MARVIS_ADMIN_SLUG", "").strip() or "admin"
-    admin_name = os.environ.get("MARVIS_ADMIN_DISPLAY_NAME", "").strip() or "Admin"
 
+    Admin seeding is OPTIONAL and config-driven: the admin user is created only when
+    a real credential is present (MARVIS_ADMIN_PASSWORD_HASH or MARVIS_PASSWORD; PIR_*
+    aliases accepted). With NO credential — the OSS single-user case, where the CLI
+    uses the local single-user context and never logs in with a password — the seed
+    is SKIPPED (not aborted), so a fresh-DB boot via init_pool (MCP server / brain,
+    which now run migrations) does not crash on a clean install. `marvis init` sets
+    MARVIS_PASSWORD before migrating, so it still seeds the admin. The owner_id
+    slug→id data migration always runs (idempotent), regardless of seeding.
+
+    b3 note: the real cleanup is to decouple admin seeding from run_migrations
+    entirely — it belongs in `marvis init` / `marvis account`, not in a schema hook.
+    """
     cursor = conn.execute("SELECT COUNT(*) FROM users")
     user_count = cursor.fetchone()[0]
     if user_count == 0:
-        conn.execute(
-            "INSERT OR IGNORE INTO users "
-            "(id, slug, display_name, type, password_hash, system_role) "
-            "VALUES (?, ?, ?, ?, ?, ?)",
-            (admin_id, admin_slug, admin_name, "human", hashed, "super_admin"),
-        )
-        conn.commit()
-        logger.info("Migration 016: seeded admin user '%s' (super_admin)", admin_slug)
+        # Prefer a pre-hashed password (canonical MARVIS_ADMIN_PASSWORD_HASH;
+        # PIR_ADMIN_PASSWORD_HASH stays a deprecated alias).
+        hashed = (
+            os.environ.get("MARVIS_ADMIN_PASSWORD_HASH")
+            or os.environ.get("PIR_ADMIN_PASSWORD_HASH", "")
+        ).strip()
+        if not hashed:
+            seed_password = (
+                os.environ.get("MARVIS_PASSWORD")
+                or os.environ.get("PIR_PASSWORD", "")
+            ).strip()
+            if seed_password:
+                import bcrypt
+
+                hashed = bcrypt.hashpw(
+                    seed_password.encode("utf-8"), bcrypt.gensalt()
+                ).decode()
+            else:
+                logger.warning(
+                    "Migration 016: no MARVIS_ADMIN_PASSWORD_HASH / MARVIS_PASSWORD in "
+                    "env — admin user NOT seeded (schema applied). Single-user CLI uses "
+                    "the local context (no login); create an admin later with `marvis "
+                    "init` if you want HTTP login."
+                )
+        if hashed:  # seed ONLY when we actually have a credential
+            admin_id = os.environ.get("MARVIS_ADMIN_USER_ID", "").strip() or "usr_admin"
+            admin_slug = os.environ.get("MARVIS_ADMIN_SLUG", "").strip() or "admin"
+            admin_name = os.environ.get("MARVIS_ADMIN_DISPLAY_NAME", "").strip() or "Admin"
+            conn.execute(
+                "INSERT OR IGNORE INTO users "
+                "(id, slug, display_name, type, password_hash, system_role) "
+                "VALUES (?, ?, ?, ?, ?, ?)",
+                (admin_id, admin_slug, admin_name, "human", hashed, "super_admin"),
+            )
+            conn.commit()
+            logger.info("Migration 016: seeded admin user '%s' (super_admin)", admin_slug)
 
     # Data migration: owner_id may contain slug strings (e.g. "emilio") from before
     # the users table existed. Resolve each slug to the corresponding users.id.

{marvisx_cli-0.3.7b2 → marvisx_cli-0.3.8}/core/api/main.py

@@ -931,6 +931,20 @@ async def _periodic_inbox_digest() -> None:
                     result.get("overflow", 0),
                     result.get("expired", 0),
                 )
+            # Invariant guard: every VISIBLE item must be deepened. The 6 UTC
+            # precompute is best-effort/one-shot; this sweep catches its failures
+            # and items promoted into visible later in the day.
+            from core.api.services.inbox_digest_deep_research import (
+                sweep_visible_missing_deep_research,
+            )
+
+            sweep = await sweep_visible_missing_deep_research()
+            if sweep.get("missing"):
+                logger.info(
+                    "Digest deep-research sweep: deepened %d/%d missing visible items",
+                    sweep.get("generated", 0),
+                    sweep.get("missing", 0),
+                )
         except asyncio.CancelledError:
             break
         except Exception:

{marvisx_cli-0.3.7b2 → marvisx_cli-0.3.8}/core/api/mcp/server.py

@@ -34,10 +34,58 @@ from core.api.mcp.tools import register_all
 # `app.state` equivalent for a server with no FastAPI `app`). Tools register on
 # this at import time so `from core.api.mcp.server import mcp` already carries the
 # full tool set — the smoke test introspects it without launching stdio.
-mcp = FastMCP("marvis")
+_INSTRUCTIONS = (
+    "Marvis is a company-brain MCP for cross-project orchestration and institutional memory.\n"
+    "Route by task type (prefer these structured tools over re-deriving context from raw files):\n"
+    "- Cold-start / 'state of project X': session_brief(slug) — it also suggests the next tool when the project is cross-project.\n"
+    "- 'If I pause / close / de-prioritize project X, what blocks?': project_impact(slug) — the project-level blast radius. "
+    "(graph_impact on a 'project:artifact:<slug>' node with depends_on does the same.)\n"
+    "- 'What breaks if I change function X' (code level): graph_impact / graph_neighbors on a 'py:function:...' node.\n"
+    "- 'What do we already know / what bit us before' (decisions and risky actions): check_learnings(q).\n"
+    "- Cross-project discovery by meaning: search(q). Body of ONE known project: get_project(slug) — do not layer search on top of get_project.\n"
+    "Before answering an orchestration or planning task, confirm you actually called the relevant "
+    "tool (session_brief / project_impact / graph_impact) AND that your answer addresses the task "
+    "as asked — do not reply from raw files or pivot to an unrelated skill.\n"
+    "When you state a number from the knowledge graph (a count, in-degree, how many dependents), "
+    "quote it from the tool result's `summary` block and cite it inline — e.g. \"148 edges from 11 "
+    "sources [graph_neighbors summary]\". Do NOT re-count a returned list by hand, and do NOT state a "
+    "count that no tool result supports.\n"
+)
+
+mcp = FastMCP("marvis", instructions=_INSTRUCTIONS)
 
 register_all(mcp)
 
+# mcp-ergonomics (tiering): mark the cold-start core always-loaded so clients with
+# MCP tool-search (e.g. Claude Code — the agent that drives the brain) keep these in
+# context and defer the other ~60 tools on demand. A 70-tool surface is well over the
+# ~20-30 threshold where tool-selection accuracy degrades. Additive: clients without
+# tool-search still see every tool (no regression). Best-effort — a FastMCP registry
+# shape change degrades to a no-op, never a boot failure.
+_CORE_TOOLS = frozenset(
+    {
+        "session_brief",
+        "search",
+        "check_learnings",
+        "list_tasks",
+        "get_task",
+        "create_task",
+        "update_task",
+        "get_project",
+        "graph_impact",
+        "graph_neighbors",
+        "project_impact",
+    }
+)
+try:
+    for _name, _tool in mcp._tool_manager._tools.items():
+        if _name in _CORE_TOOLS:
+            _m = dict(_tool.meta or {})
+            _m["anthropic/alwaysLoad"] = True
+            _tool.meta = _m
+except Exception:  # pragma: no cover - FastMCP internal-shape guard
+    pass
+
 
 def main() -> None:
     """Run the MCP server over stdio (the OSS runtime entrypoint).

{marvisx_cli-0.3.7b2 → marvisx_cli-0.3.8}/core/api/mcp/tools/graph.py

@@ -123,10 +123,11 @@ def register(mcp) -> None:
         rank: NeighborRank = "none",
         as_of: Annotated[str, Field(pattern=_AS_OF_PATTERN, max_length=32)] | None = None,
     ) -> dict[str, Any]:
-        """[Power-user] Surgical 1-hop neighbour query for a KG node (calls/imports/defines/mentions/...) — per context completo su un nodo usa get_task/get_project/get_handoff/get_learning(deep=true). Usa questo tool solo quando hai bisogno di ispezionare il vicinato topologico diretto senza il bundle completo.
-        QUANDO USARLO: refactor impact assessment su una singola function; verificare se un nodo ha caller inattesi; time-travel as_of su commit specifico; rank=suspect_write per bug write-through-read.
-        QUANDO NON USARLO: NOT per context di un task/handoff/learning -> usa get_*(deep=true). NOT per BFS transitivo -> usa graph_impact.
-        RESTITUISCE: list of {node_id, relation, direction, rank_score?} cap 200."""
+        """1-hop: chi tocca / dipende direttamente da un nodo. Funziona su codice ('py:function:...') E su progetti ('project:artifact:<slug>').
+        CHI DIPENDE DA X (in UNA call): graph_neighbors(node_id, direction='incoming', rank='degree') → i dipendenti diretti ordinati per grado + un blocco `summary` GIA' aggregato. E' il tool ovvio per 'chi cita / dipende da X' — NON fare N micro-query (project_impact e' il primo passo, non N).
+        ORCHESTRAZIONE: per i vicini diretti di un PROGETTO passa node_id='project:artifact:<slug>' con edge_types=['depends_on']. Codice: caller/callee 1-hop di una function.
+        QUANDO USARLO: vicinato diretto; caller inattesi; time-travel as_of; rank=suspect_write per bug write-through-read. Per il blast radius transitivo usa graph_impact / project_impact.
+        RESTITUISCE: {neighbors:[{node_id, relation, direction, rank_score?}], summary:{total, distinct_nodes, by_relation, by_direction} (CITA questi numeri, non ricontare la lista), freshness} cap 200."""
         try:
             async with acquire_db() as db:
                 # Node proxy hardcodes limit=200 (the surface exposes no limit param).
@@ -152,7 +153,7 @@ def register(mcp) -> None:
         limit: Annotated[int, Field(ge=1, le=100)] = 20,
         type_filter: HotspotTypeFilter = "file",
     ) -> dict[str, Any]:
-        """[Power-user] DORA-style churn ranking: files/functions sorted by touch_count 7d/30d with bus-factor warning — per context completo su un progetto usa get_project(deep=true). Usa questo tool per analisi architetturale di rischio o pianificazione refactor.
+        """DORA-style churn ranking: files/functions sorted by touch_count 7d/30d with bus-factor warning — per context completo su un progetto usa get_project(deep=true). Usa questo tool per analisi architetturale di rischio o pianificazione refactor.
         QUANDO USARLO: identificare moduli ad alto rischio prima di una release; trovare ownership gaps (bus_factor=1); pianificare tech debt.
         QUANDO NON USARLO: NOT per context di un progetto specifico -> usa get_project(deep=true). NOT per BFS da un nodo -> usa graph_impact.
         RESTITUISCE: list of {node_id, touch_count_7d, touch_count_30d, authors[], bus_factor} top N."""
@@ -178,10 +179,10 @@ def register(mcp) -> None:
         edge_types: list[EdgeType] | None = None,
         project: Annotated[str, Field(max_length=50, pattern=_PROJECT_PATTERN)] | None = None,
     ) -> dict[str, Any]:
-        """[Power-user] BFS impact analysis: 'cosa si rompe se cambio X?' con ranker su direct callers + transitive list — per context completo usa get_task(deep=true). Usa questo tool per delete/rename risk assessment o pre-refactor sweep.
-        QUANDO USARLO: prima di eliminare/rinominare una function critica; misurare blast radius di una migration; dependency cascade analysis.
-        QUANDO NON USARLO: NOT per context standard -> usa get_*(deep=true). NOT per 1-hop only -> usa graph_neighbors.
-        RESTITUISCE: {direct_callers[], transitive_list[], rank_score} depth configurabile."""
+        """Impact / blast radius: 'cosa si rompe — o quali progetti si bloccano — se cambio / pauso / chiudo X?'. BFS sui rami transitivi + ranker sui diretti.
+        ORCHESTRAZIONE DI PORTAFOGLIO: per sapere quali PROGETTI si bloccano se pausi/chiudi un progetto, passa node_id='project:artifact:<slug>' con edge_types=['depends_on','mentions','refers_to'] — oppure usa il tool dedicato project_impact(slug). Livello-codice: per 'cosa si rompe se cambio questa function' passa un node 'py:function:...'.
+        QUANDO USARLO: prima di pausare/chiudere/de-prioritizzare un progetto (blast radius cross-project); prima di eliminare/rinominare una function critica; dependency cascade analysis; sequenziare lavoro (cosa sblocca cosa).
+        RESTITUISCE: {direct (callers/dependents)[], transitive_list[], rank_score, freshness (indexed_sha vs HEAD)} depth configurabile."""
         try:
             async with acquire_db() as db:
                 result = await graph_uc.graph_impact(
@@ -197,15 +198,38 @@ def register(mcp) -> None:
         except ServiceError as e:
             raise_mcp_error(e)
 
+    @mcp.tool()
+    async def project_impact(
+        slug: Annotated[str, Field(max_length=50, pattern=_PROJECT_PATTERN)],
+        depth: Annotated[int, Field(ge=1, le=5)] = 2,
+    ) -> dict[str, Any]:
+        """Portfolio blast radius: 'se pauso / chiudo / de-prioritizzo questo PROGETTO, quali altri progetti si bloccano?'. Il tool di prima classe per l'orchestrazione cross-progetto — distinto dal grafo-codice.
+        Risolve 'project:artifact:<slug>' e fa l'impact BFS sui soli edge progetto->progetto (depends_on / mentions / refers_to). La response porta il segnale freshness (indexed_sha vs HEAD) per non fidarsi di un indice stantio.
+        QUANDO USARLO: prima di pausare/chiudere/de-prioritizzare un progetto; sequenziare un portafoglio (cosa sblocca cosa); capire le dipendenze cross-progetto di una decisione.
+        RESTITUISCE: {direct_dependents[], transitive_list[], rank_score, freshness}. Col flag MARVIS_KG_CLAIMS anche claims[]: quanti progetti dipendono DAVVERO da questo (kind=dependents_depends_on) vs quanti lo nominano soltanto (kind=mentioned_by), gia' contati server-side con provenienza e freschezza — riporta quei numeri, non ri-contare le liste."""
+        try:
+            async with acquire_db() as db:
+                result = await graph_uc.graph_impact(
+                    LOCAL_CTX,
+                    db,
+                    node_id=f"project:artifact:{slug}",
+                    depth=depth,
+                    limit=100,
+                    edge_types=["depends_on", "mentions", "refers_to"],
+                    project=None,
+                )
+                return dump(result)
+        except ServiceError as e:
+            raise_mcp_error(e)
+
     @mcp.tool()
     async def graph_context(
         node_id: Annotated[str, Field(pattern=_NODE_ID_PATTERN, max_length=256)],
         per_category_limit: Annotated[int, Field(ge=1, le=20)] = 5,
         project: Annotated[str, Field(max_length=50, pattern=_PROJECT_PATTERN)] | None = None,
     ) -> dict[str, Any]:
-        """[Power-user] Rationale chain: function→commit→PR→task→handoff→learning in 1 call — per context su un singolo artefatto usa get_task/get_handoff/get_learning(deep=true). Usa questo tool quando hai un node_id e vuoi la storia completa del PERCHE'.
-        QUANDO USARLO: archeologia di codice legacy ('perche esiste questa function?'); audit trail pre-refactor; linkare codice a decision record.
-        QUANDO NON USARLO: NOT per workflow standard su task/handoff -> usa get_*(deep=true). NOT per vicinato topologico -> usa graph_neighbors.
+        """Rationale chain di un nodo: function/progetto → commit → PR → task → handoff → learning in 1 call. Il PERCHE' dietro qualcosa.
+        QUANDO USARLO: perche' esiste / da dove viene una function o una decisione di progetto; audit trail; linkare codice o progetto a un decision record.
         RESTITUISCE: chain {commits[], PR?, task?, handoffs[], learnings[]} per_category_limit configurabile."""
         try:
             async with acquire_db() as db:
@@ -225,7 +249,7 @@ def register(mcp) -> None:
         scope: Annotated[str, Field(max_length=256)],
         limit: Annotated[int, Field(ge=1, le=100)] = 20,
     ) -> dict[str, Any]:
-        """[Power-user] Learnings scoped a un modulo/path specifico via KG — per learnings generici usa check_learnings. Usa questo tool per learnings chirurgici su un file/modulo specifico prima di toccare codice in quella area.
+        """Learnings scoped a un modulo/path specifico via KG — per learnings generici usa check_learnings. Usa questo tool per learnings chirurgici su un file/modulo specifico prima di toccare codice in quella area.
         QUANDO USARLO: 'quali learnings esistono per api.db?' prima di toccare il DB module; scoping pre-deployment di un servizio specifico.
         QUANDO NON USARLO: NOT per ricerca semantica generica pre-azione -> usa check_learnings. NOT per context di un nodo -> usa graph_context.
         RESTITUISCE: list of {learning_id, title, prevention, severity, scope_match_score}."""
@@ -240,7 +264,7 @@ def register(mcp) -> None:
 
     @mcp.tool()
     async def graph_capabilities() -> dict[str, Any]:
-        """[Power-user] KG schema metadata per agent discovery (edge_types + node_kinds + prefixes + versions).
+        """KG schema metadata per agent discovery (edge_types + node_kinds + prefixes + versions).
         QUANDO USARLO: prima di costruire query graph_* o validare node_id pattern; cold-start agent discovery.
         QUANDO NON USARLO: per query topologiche -> usa graph_neighbors/impact/context.
         RESTITUISCE: {edge_types[], node_kinds[], node_prefixes[], schema_version}.

{marvisx_cli-0.3.7b2 → marvisx_cli-0.3.8}/core/api/mcp/tools/learnings.py

@@ -47,10 +47,10 @@ def register(mcp) -> None:
         q: Annotated[str, Field(min_length=1, max_length=500)],
         module: str | None = None,
     ) -> dict[str, Any]:
-        """Search learnings DB (past post-mortems + prevention rules) for a risky action.
+        """Cosa sappiamo gia' / cosa ci ha morso: cerca nei learnings (post-mortem + regole di prevenzione) prima di una decisione o di un'azione.
 
-        QUANDO USARLO: PRIMA di qualunque azione production-affecting (deploy, migration, auth change, push to main, dependency upgrade) — Quality Gate 9.4. BOUNDARY: create_learning vs check_learnings = create scrive nuovo; check cerca rilevante PRE-azione rischiosa. BOUNDARY: check_learnings vs list_learnings = check = semantic match su situazione; list = enumerazione filtrata.
-        QUANDO NON USARLO: NOT quando hai gia' un file/module path e vuoi learnings scoped -> usa graph_pattern. NOT per scrivere un nuovo learning -> usa create_learning.
+        QUANDO USARLO: prima di qualunque azione production-affecting (deploy, migration, auth change, push, dependency upgrade); E prima di una DECISIONE o di un piano (per non ripetere errori noti e riusare cio' che ha funzionato). Non e' solo un gate pre-deploy: e' la memoria istituzionale a cui attingere quando ragioni. BOUNDARY: create_learning scrive nuovo; check_learnings = semantic match sulla situazione; list_learnings = enumerazione filtrata.
+        QUANDO NON USARLO: se hai gia' un file/module path e vuoi learnings scoped -> graph_pattern. Per scrivere un nuovo learning -> create_learning.
         RESTITUISCE: list of {id, title, prevention, severity, module} ranked per rilevanza."""
         try:
             async with acquire_db() as db:

{marvisx_cli-0.3.7b2 → marvisx_cli-0.3.8}/core/api/models/graph_ux.py

@@ -13,7 +13,38 @@ from __future__ import annotations
 from datetime import datetime
 from typing import Literal
 
-from pydantic import BaseModel, ConfigDict, Field
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+# ---------------------------------------------------------------------------
+# answer-ready claims (behind MARVIS_KG_CLAIMS) — server-computed, relation-typed
+# ---------------------------------------------------------------------------
+
+class KGClaim(BaseModel):
+    """A server-computed claim about a KG node: the value is counted by the DB,
+    not by the agent. The agent reports it (and the relation) instead of
+    re-counting raw edges — this is the faithfulness fix.
+
+    `kind` names the relation explicitly (e.g. `dependents_depends_on` = real
+    dependency, `mentioned_by` = associative, NOT a dependency). `sources` is a
+    capped sample of the provenance; `sources_total` is the full count.
+    """
+    model_config = ConfigDict(extra="forbid")
+
+    kind: str = Field(..., description="dependents_depends_on | dependents_imports | dependents_calls | mentioned_by")
+    subject: str = Field(..., description="node_id the claim is about")
+    value: int = Field(..., ge=0, description="server-computed count (the number to report)")
+    sources: list[str] = Field(default_factory=list, description="capped sample of source node ids (provenance)")
+    sources_total: int = Field(..., ge=0, description="full provenance count before capping")
+    as_of: str | None = Field(None, description="last observation (last_seen_at) of the subject")
+    verified: str | None = Field(None, description="last Brain re-confirmation (last_verified_at), or null")
+    needs_review: bool = Field(False, description="subject is stale per the read-time freshness budget")
+
+    @model_validator(mode="after")
+    def _sources_within_total(self) -> "KGClaim":
+        if self.sources_total < len(self.sources):
+            raise ValueError("sources_total must be >= len(sources)")
+        return self
+
 
 # ---------------------------------------------------------------------------
 # Shared type alias (validated at model-field level via annotation)
@@ -47,6 +78,36 @@ class PinOut(BaseModel):
     is_stale: bool = False  # True if node was soft-deleted after pinning (belt-and-braces)
 
 
+# ---------------------------------------------------------------------------
+# Fase D — KG trust write-path request bodies (behind MARVIS_TEMPORAL_MEMORY).
+# The apply actions an agent performs after Triage approves a Brain proposal.
+# ---------------------------------------------------------------------------
+
+class VerifyNodeIn(BaseModel):
+    """Request body for POST /graph/nodes/verify — stamp last_verified_at = now."""
+    node_id: str = Field(
+        ...,
+        min_length=6,
+        max_length=256,
+        pattern=r"^[a-z]+:[a-z]+:.+$",
+        description="Node ID to mark re-verified (REINFORCE apply)",
+    )
+
+
+class SupersedeEdgeIn(BaseModel):
+    """Request body for POST /graph/edges/supersede — soft-invalidate an edge."""
+    source_id: str = Field(..., min_length=6, max_length=256, pattern=r"^[a-z]+:[a-z]+:.+$")
+    target_id: str = Field(..., min_length=6, max_length=256, pattern=r"^[a-z]+:[a-z]+:.+$")
+    relation: str = Field(
+        ..., min_length=2, max_length=32,
+        description="Edge relation of the triple to supersede (e.g. depends_on)",
+    )
+    superseded_by: str | None = Field(
+        None, max_length=256,
+        description="Optional audit pointer to the replacing edge",
+    )
+
+
 # ---------------------------------------------------------------------------
 # Landing bundle
 # ---------------------------------------------------------------------------

{marvisx_cli-0.3.7b2 → marvisx_cli-0.3.8}/core/api/models/search.py

@@ -26,6 +26,14 @@ class SearchHit(BaseModel):
     edge_path: list[str] | None = None
     edge_path_summary: str | None = None
     rrf_score: float | None = None
+    # Memory-freshness v2a Phase 2 (A-span, MARVIS_SEARCH_SPANS): the winning
+    # chunk's text expanded to line boundaries ±12 lines, so the agent answers
+    # FROM the result without a follow-up Read. None when the flag is off, the
+    # hit is row-backed (task/learning/inbox), or the source file is gone.
+    span_text: str | None = None
+    span_path: str | None = None
+    span_line_start: int | None = None
+    span_line_end: int | None = None
 
 
 class SearchResponse(BaseModel):

{marvisx_cli-0.3.7b2 → marvisx_cli-0.3.8}/core/api/routers/graph.py

@@ -79,6 +79,8 @@ from core.api.models.graph_ux import (
     PinIn,
     PinOut,
     ResolveOut,
+    SupersedeEdgeIn,
+    VerifyNodeIn,
 )
 from core.api.models.graph_cosmo import GraphCosmoOut
 from core.api.rate_limit import limiter
@@ -701,6 +703,54 @@ async def delete_graph_pin(
     return result
 
 
+# --- KG trust write-path (Fase D, behind MARVIS_TEMPORAL_MEMORY) ---
+
+@router.post("/nodes/verify", response_model=dict, summary="Mark a KG node re-verified")
+@limiter.limit("60/minute")
+async def mark_node_verified(
+    body: VerifyNodeIn,
+    request: Request,
+    user: UserInfo = Depends(get_current_user_or_agent),
+    db: aiosqlite.Connection = Depends(get_write_db),
+) -> dict:
+    """Stamp graph_nodes.last_verified_at = now (REINFORCE apply).
+
+    The action an agent performs after Triage approves a Brain recency proposal.
+    Inert (422) when MARVIS_TEMPORAL_MEMORY is off. 404 if the node is missing.
+    """
+    ctx = CallerContext.from_user_info(user, is_human_session=False)
+    try:
+        return await uc.mark_node_verified(ctx, db, node_id=body.node_id)
+    except ServiceError as e:
+        raise to_http_legacy(e)
+
+
+@router.post("/edges/supersede", response_model=dict, summary="Soft-invalidate a KG edge")
+@limiter.limit("60/minute")
+async def mark_edge_superseded(
+    body: SupersedeEdgeIn,
+    request: Request,
+    user: UserInfo = Depends(get_current_user_or_agent),
+    db: aiosqlite.Connection = Depends(get_write_db),
+) -> dict:
+    """Set graph_edges.valid_until = now (+ optional superseded_by) on a triple.
+
+    SUPERSEDE / CONTRADICTION apply. Soft, never deletes. Inert (422) when the
+    flag is off. 404 if the triple is absent.
+    """
+    ctx = CallerContext.from_user_info(user, is_human_session=False)
+    try:
+        return await uc.mark_edge_superseded(
+            ctx, db,
+            source_id=body.source_id,
+            target_id=body.target_id,
+            relation=body.relation,
+            superseded_by=body.superseded_by,
+        )
+    except ServiceError as e:
+        raise to_http_legacy(e)
+
+
 # --- Resolve file path → node_id ---
 
 @router.get("/resolve", response_model=ResolveOut, summary="Resolve file path to KG node")