[KM-626][AI] Planner: consume teammate's real analytics registry

After the tool team landed the canonical contracts + real analytics registry
(KM-627/628), reconcile our planner-facing registry to the real thing instead of
the stub:

- default_registry() now composes the REAL analytics slice (src/tools/registry.py
::analytics_registry()) + a local stub for only the 4 data-access tools (still
pending KM-465 #4).
- Drops our 8 analyze_* stub entries; removes the one drift (their
analyze_descriptive requires only ["data"], column_ids optional) and adopts the
real prompt-style tool descriptions.
- Pattern A is now confirmed (KM-465); no agent-code change needed (INV-7).

Verified: 44 planner+slow_path tests green, ruff clean. No changes to src/tools
(tool team owned).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

src/agents/planner/registry.py

@@ -1,55 +1,38 @@
-"""STUB v1 tool registry — composite ("family") tools.
+"""v1 tool registry the Planner plans against (INV-7: agent never names a tool
+outside it).
 
-This is the agent team's local stand-in for the tool team's inventory (KM-608)
-so the planner is buildable and testable before the real wrapper layer lands.
-The tools here are *contracts only* — the compute logic for the `analyze_*`
-family already exists in `src/tools/analytics/` (KM-624), but the wrapper layer
-(source/placeholder -> DataFrame fetch, the `ToolOutput` envelope, never-throw
-error handling, ToolSpec registration) is still pending the Planner seam
-(KM-418 / AGENT_ARCHITECTURE_CONTEXT_new.md §8.4). The planner plans against the
-registry and never names a tool outside it (INV-7).
+**Composed from two slices (2026-06-08):**
 
-**Taxonomy decision (2026-06-08):** v1 uses **composite/family** tools, not the
-atomic `compute_*` set the earlier draft assumed. One `analyze_*` call does a
-whole analytical job (e.g. `analyze_descriptive` returns mean/median/mode/std/
-quartiles/skew/null_rate at once, replacing four atomic `compute_*` tools). See
-§9.3 / the decisions table in the architecture doc.
+- **Analytics (`analyze_*`) — REAL, tool-team-owned.** Sourced live from
+  `src/tools/registry.py::analytics_registry()` (KM-628), built on the canonical
+  `ToolSpec` (`src/tools/contracts.py`, KM-465/KM-627) and the prompt-style tool
+  descriptions (KM-625). No longer a stub on our side — it tracks the real registry.
+- **Data access (`query_structured` / `retrieve_documents` / `list_sources` /
+  `describe_source`) — STILL A LOCAL STUB.** The tool team owns these too, but their
+  wrappers + `ToolSpec`s haven't landed yet (KM-465 #4). We keep best-guess specs
+  here so the Planner can plan end-to-end; when the real ones ship, delete this slice
+  and swap `default_registry()` for the tool team's full composition.
 
-**Ownership (revised 2026-06-08): the tool team owns ALL tools** — compute,
-data-access (`query_structured`/`retrieve_documents`/`list_sources`/
-`describe_source`), the wrapper/invoker, and tests. This file is purely the agent
-team's local scaffold for building/testing the Planner (and later the TaskRunner/
-Assembler against mocks) until the real registry lands; replace it then.
-
-**Data-flow convention (Pattern A — assumed, but the tool team's call, still open):**
-this stub assumes the `analyze_*` tools do NOT self-fetch by `source_id`; each
-takes a `data` argument that is a `"${t<id>}"` placeholder pointing at an upstream
-`query_structured` table output, resolved to a DataFrame at execution time. Column
-arguments (`column_ids`, `dimension`, `value_column`, `date_column`, …) reference
-the *aliases* the upstream query produced. If the tool team instead picks Pattern B
-(self-fetch by `source_id`), reshape this stub + the few-shot examples to match —
-the agent code does not change either way (INV-7).
-
-`input_schema` is the lightweight JSON-schema-ish dict the planner validator
-(validator.py check #8) consumes: `required` (list of arg names) + `properties`
-(allowed arg names). Arg *values* may be `"${t<id>}"` placeholders resolved at
-execution time, so the validator checks arg *keys*, not value types — except
-`query_structured.args["ir"]`, whose inline QueryIR is validated against the
+**Confirmed conventions (KM-465):** Pattern A — `analyze_*` tools take a `data`
+`"${t<id>}"` placeholder pointing at an upstream `query_structured` output (no
+self-fetch); resolved to a DataFrame at execution time. `input_schema` is the
+lightweight `{required, properties}` dict the planner validator (check #8) reads;
+`query_structured.args["ir"]` carries an inline QueryIR validated against the
 catalog by the existing IRValidator.
 
-When KM-608/KM-418 ship, replace `default_registry()` with the real registry
-import. See AGENT_ARCHITECTURE_CONTEXT_new.md §9.2 / §9.3.
+See AGENT_ARCHITECTURE_CONTEXT_new.md §9.2 / §9.3.
 """
 
 from __future__ import annotations
 
+from src.tools.registry import analytics_registry
+
 from .contracts import ToolRegistry, ToolSpec
 
-_P0_TOOLS: list[ToolSpec] = [
-    # ----------------------------------------------------------------------- #
-    # Data access + catalog introspection (agent-team owned; wrap existing
-    # Phase 2 infra — QueryService / RetrievalRouter / CatalogReader).
-    # ----------------------------------------------------------------------- #
+# --------------------------------------------------------------------------- #
+# Data-access slice — LOCAL STUB pending the tool team's real specs (KM-465 #4).
+# --------------------------------------------------------------------------- #
+_DATA_ACCESS_TOOLS: list[ToolSpec] = [
     ToolSpec(
         name="query_structured",
         category="analytics.query",
@@ -112,194 +95,14 @@ _P0_TOOLS: list[ToolSpec] = [
             "before querying it. Do NOT use it to fetch data rows (use query_structured)."
         ),
     ),
-    # ----------------------------------------------------------------------- #
-    # Analytics family (KM-624 compute; wrapper pending). Each takes `data` =
-    # a "${t<id>}" placeholder for an upstream query_structured table output.
-    # ----------------------------------------------------------------------- #
-    ToolSpec(
-        name="analyze_descriptive",
-        category="analytics.descriptive",
-        input_schema={
-            "required": ["data", "column_ids"],
-            "properties": {
-                "data": {"type": "string"},
-                "column_ids": {"type": "array"},
-                "metrics": {"type": "array"},
-            },
-        },
-        output_kind="stats",
-        description=(
-            "Single/multi-column EDA in one call: count, mean, median, mode, std, "
-            "variance, quartiles (q1/q3), min, max, skew, null_count, null_rate for each "
-            "of `column_ids`. `data` is a '${t<id>}' placeholder for an upstream "
-            "query_structured result; `column_ids` are that result's column aliases. "
-            "This replaces the atomic compute_median/mode/stddev/percentile tools — ask "
-            "for the whole profile, not one statistic at a time. Do NOT use it for "
-            "group-by aggregates (analyze_aggregate) or time trends (analyze_trend)."
-        ),
-    ),
-    ToolSpec(
-        name="analyze_aggregate",
-        category="analytics.aggregation",
-        input_schema={
-            "required": ["data", "aggregations"],
-            "properties": {
-                "data": {"type": "string"},
-                "aggregations": {"type": "object"},
-                "group_by": {"type": "array"},
-            },
-        },
-        output_kind="table",
-        description=(
-            "Group-by aggregation over an already-materialized result: per group, "
-            "compute `aggregations` like {\"revenue\": [\"sum\", \"mean\"], "
-            "\"order_id\": [\"count\"]} (sum/mean/count/min/max/median/nunique). `data` "
-            "is a '${t<id>}' placeholder; `group_by` columns and aggregated columns are "
-            "that result's aliases. Prefer query_structured for simple group-by the IR "
-            "can already express; use this to aggregate a derived/joined/intermediate "
-            "result, or for median per group (the IR cannot)."
-        ),
-    ),
-    ToolSpec(
-        name="analyze_comparison",
-        category="analytics.comparison",
-        input_schema={
-            "required": ["data", "dimension", "value_column", "group_a", "group_b"],
-            "properties": {
-                "data": {"type": "string"},
-                "dimension": {"type": "string"},
-                "value_column": {"type": "string"},
-                "group_a": {},
-                "group_b": {},
-                "agg": {"type": "string"},
-            },
-        },
-        output_kind="stats",
-        description=(
-            "Compare one aggregated metric between two groups of a dimension (e.g. "
-            "region 'A' vs 'B'): returns each group's value, absolute and percent "
-            "difference, and direction (higher/lower/equal); group_a is the baseline. "
-            "`data` is a '${t<id>}' placeholder; `dimension`/`value_column` are aliases; "
-            "`agg` defaults to sum. Use for exactly TWO groups. For many categories' "
-            "share of a total use analyze_contribution; for movement over time use "
-            "analyze_trend."
-        ),
-    ),
-    ToolSpec(
-        name="analyze_contribution",
-        category="analytics.decomposition",
-        input_schema={
-            "required": ["data", "dimension", "value_column"],
-            "properties": {
-                "data": {"type": "string"},
-                "dimension": {"type": "string"},
-                "value_column": {"type": "string"},
-                "agg": {"type": "string"},
-                "top_n": {"type": "integer"},
-            },
-        },
-        output_kind="table",
-        description=(
-            "Share-of-total breakdown: each category's value, share, and running "
-            "cumulative share, largest first — the tool for 'which categories drive "
-            "most of X?' and Pareto (80/20) reasoning. `data` is a '${t<id>}' "
-            "placeholder; `dimension`/`value_column` are aliases; `agg` defaults to sum; "
-            "`top_n` lumps the tail into an 'Others' row. Use for a single snapshot of "
-            "many categories. Do NOT use it to compare exactly two groups "
-            "(analyze_comparison) or to trend over time (analyze_trend)."
-        ),
-    ),
-    ToolSpec(
-        name="analyze_profile",
-        category="analytics.quality",
-        input_schema={
-            "required": ["data"],
-            "properties": {"data": {"type": "string"}, "column_ids": {"type": "array"}},
-        },
-        output_kind="stats",
-        description=(
-            "Per-column data-quality profile: dtype, inferred type, completeness "
-            "(null_count/null_rate), cardinality (distinct_count/rate, is_constant), and "
-            "for numeric columns min/max/mean plus an IQR-based outlier_count (top value "
-            "for non-numeric). `data` is a '${t<id>}' placeholder; `column_ids` defaults "
-            "to all columns. Use in data_understanding to judge whether data is clean "
-            "enough before deeper analysis. Do NOT use it for the analytical answer "
-            "itself — it describes data health, not the business metric."
-        ),
-    ),
-    ToolSpec(
-        name="analyze_correlation",
-        category="analytics.relationship",
-        input_schema={
-            "required": ["data"],
-            "properties": {
-                "data": {"type": "string"},
-                "column_ids": {"type": "array"},
-                "method": {"type": "string"},
-            },
-        },
-        output_kind="stats",
-        description=(
-            "Pairwise correlation across numeric columns: returns the full matrix plus "
-            "column pairs ranked by strength. `data` is a '${t<id>}' placeholder; "
-            "`column_ids` defaults to all numeric columns; `method` is pearson "
-            "(default), spearman, or kendall. Use for 'does X relate to Y?'. Needs at "
-            "least two numeric columns. Correlation is not causation — it does not "
-            "explain why, and is not a model."
-        ),
-    ),
-    ToolSpec(
-        name="analyze_segment",
-        category="analytics.segmentation",
-        input_schema={
-            "required": ["data", "column", "bins"],
-            "properties": {
-                "data": {"type": "string"},
-                "column": {"type": "string"},
-                "bins": {},
-                "method": {"type": "string"},
-                "labels": {"type": "array"},
-                "value_column": {"type": "string"},
-                "agg": {"type": "string"},
-            },
-        },
-        output_kind="table",
-        description=(
-            "Bucket rows by binning a numeric `column` and report how rows distribute "
-            "across segments (count, and optionally an aggregate of `value_column` per "
-            "segment). `method` 'edges' takes explicit boundaries in `bins` (e.g. "
-            "[0,18,35,60]); 'quantile' takes an integer bucket count (e.g. 4 for "
-            "quartiles). `data` is a '${t<id>}' placeholder; columns are aliases. Use "
-            "for age brackets, value tiers, etc. The binned column must be numeric."
-        ),
-    ),
-    ToolSpec(
-        name="analyze_trend",
-        category="analytics.timeseries",
-        input_schema={
-            "required": ["data", "date_column", "value_column"],
-            "properties": {
-                "data": {"type": "string"},
-                "date_column": {"type": "string"},
-                "value_column": {"type": "string"},
-                "freq": {"type": "string"},
-                "agg": {"type": "string"},
-            },
-        },
-        output_kind="series",
-        description=(
-            "Time-series trend in one call: bucket rows into periods (`freq` = "
-            "day/week/month/quarter/year), aggregate `value_column` per period (`agg` "
-            "defaults to sum), and summarize movement (per-period points, first vs last, "
-            "absolute/percent change, direction, linear slope). `data` is a '${t<id>}' "
-            "placeholder; `date_column`/`value_column` are aliases from the upstream "
-            "query. This replaces the atomic date_trunc tool. Do NOT use it to filter by "
-            "date — put the date filter in the query_structured IR instead."
-        ),
-    ),
 ]
 
 
 def default_registry() -> ToolRegistry:
-    """The v1 stub registry (a fresh instance per call)."""
-    return ToolRegistry(tools=list(_P0_TOOLS))
+    """The v1 registry: stub data-access slice + the real analytics slice.
+
+    The analytics tools come live from `src.tools.registry` (the tool team's real
+    registry); only the data-access slice is still a local stub. A fresh instance
+    per call.
+    """
+    return ToolRegistry(tools=[*_DATA_ACCESS_TOOLS, *analytics_registry().tools])