create-yss-spec 3.5.2 → 3.5.4

package/template/.codex/skills/data-analytics/skills/user-context/tests/test_state_helpers.py

@@ -1,978 +0,0 @@
-from __future__ import annotations
-
-import importlib.util
-import json
-import shutil
-import subprocess
-import sys
-import tempfile
-import unittest
-from pathlib import Path
-
-SKILL_ROOT = Path(__file__).resolve().parents[1]
-SCRIPT_DIR = SKILL_ROOT / "scripts"
-PLUGIN_ROOT = SKILL_ROOT.parents[1]
-ONBOARDING_REFERENCE = SKILL_ROOT / "references/onboarding.md"
-SOURCE_RUNTIME_REFERENCE = SKILL_ROOT / "references/source-category-runtime.md"
-AUTOMATION_REFERENCE = SKILL_ROOT / "references/automation.md"
-SOURCE_CATEGORY_CONFIG = SKILL_ROOT / "plugin-author-config/source-category-config.json"
-APP_MANIFEST = PLUGIN_ROOT / ".app.json"
-SEMANTIC_LAYER_SETUP_REFERENCE = SKILL_ROOT / "references/semantic-layer/setup.md"
-SEMANTIC_LAYER_SOURCE_INTAKE_REFERENCE = SKILL_ROOT / "references/semantic-layer/source-intake.md"
-SEMANTIC_LAYER_SKILL_TEMPLATE_REFERENCE = SKILL_ROOT / "references/semantic-layer/skill-template.md"
-SEMANTIC_LAYER_WEEKLY_POLLING_REFERENCE = (
-    SKILL_ROOT / "references/semantic-layer/weekly-polling-automation.md"
-)
-HERO_SKILLS = (
-    PLUGIN_ROOT / "skills/metric-diagnostics/SKILL.md",
-    PLUGIN_ROOT / "skills/product-business-analysis/SKILL.md",
-    PLUGIN_ROOT / "skills/kpi-reporting/SKILL.md",
-)
-PREFLIGHT_SPEC = importlib.util.spec_from_file_location(
-    "data_analytics_preflight",
-    SCRIPT_DIR / "data_analytics_preflight.py",
-)
-assert PREFLIGHT_SPEC and PREFLIGHT_SPEC.loader
-PREFLIGHT_MODULE = importlib.util.module_from_spec(PREFLIGHT_SPEC)
-PREFLIGHT_SPEC.loader.exec_module(PREFLIGHT_MODULE)
-
-# Representative host_available_plugin_catalog fixture for plugin-first routing.
-LIVE_INSTALLABLE_PLUGIN_CANDIDATES = [
-    {
-        "id": "databricks@openai-curated",
-        "name": "databricks",
-        "tool_type": "plugin",
-        "has_skills": True,
-        "app_connector_ids": ["templated_apps_Databricks"],
-    },
-    {
-        "id": "bigquery@openai-curated",
-        "name": "bigquery",
-        "tool_type": "plugin",
-        "has_skills": True,
-        "app_connector_ids": ["connector_7c3f2c8cdbf64bb0b183ff52f527a06e"],
-    },
-    {
-        "id": "snowflake@openai-curated",
-        "name": "snowflake",
-        "tool_type": "plugin",
-        "has_skills": True,
-        "app_connector_ids": ["templated_apps_Snowflake"],
-    },
-    {
-        "id": "outlook-calendar@openai-curated",
-        "name": "outlook-calendar",
-        "tool_type": "plugin",
-        "has_skills": True,
-        "app_connector_ids": ["connector_e6a7394682e24467ac68c60696f275a4"],
-    },
-    {
-        "id": "outlook-email@openai-curated",
-        "name": "outlook-email",
-        "tool_type": "plugin",
-        "has_skills": True,
-        "app_connector_ids": ["connector_4aaab2856305417b993eca9a216aaf6e"],
-    },
-    {
-        "id": "sharepoint@openai-curated",
-        "name": "sharepoint",
-        "tool_type": "plugin",
-        "has_skills": True,
-        "app_connector_ids": ["connector_1e4f6a44acf14e3ca1d96672f8c945bc"],
-    },
-    {
-        "id": "slack@openai-curated",
-        "name": "slack",
-        "tool_type": "plugin",
-        "has_skills": True,
-        "app_connector_ids": ["REPLACE_WITH_SLACK_APP_OR_CONNECTOR_ID"],
-    },
-    {
-        "id": "teams@openai-curated",
-        "name": "teams",
-        "tool_type": "plugin",
-        "has_skills": True,
-        "app_connector_ids": ["connector_246af0940da3457da0e751171dc1ce60"],
-    },
-    {
-        "id": "thoughtspot@openai-curated",
-        "name": "thoughtspot",
-        "tool_type": "plugin",
-        "has_skills": True,
-        "app_connector_ids": ["REPLACE_WITH_THOUGHTSPOT_APP_OR_CONNECTOR_ID"],
-    },
-    {
-        "id": "omni-analytics@openai-curated",
-        "name": "omni-analytics",
-        "tool_type": "plugin",
-        "has_skills": True,
-        "app_connector_ids": ["REPLACE_WITH_OMNI_ANALYTICS_APP_OR_CONNECTOR_ID"],
-    },
-    {
-        "id": "metabase@openai-curated",
-        "name": "metabase",
-        "tool_type": "plugin",
-        "has_skills": True,
-        "app_connector_ids": ["templated_apps_Metabase"],
-    },
-    {
-        "id": "amplitude@openai-curated",
-        "name": "amplitude",
-        "tool_type": "plugin",
-        "has_skills": True,
-        "app_connector_ids": ["REPLACE_WITH_AMPLITUDE_APP_OR_CONNECTOR_ID"],
-    },
-    {
-        "id": "mixpanel@openai-curated",
-        "name": "mixpanel",
-        "tool_type": "plugin",
-        "has_skills": True,
-        "app_connector_ids": ["REPLACE_WITH_MIXPANEL_APP_OR_CONNECTOR_ID"],
-    },
-    {
-        "id": "hex@openai-curated",
-        "name": "hex",
-        "tool_type": "plugin",
-        "has_skills": True,
-        "app_connector_ids": ["REPLACE_WITH_HEX_APP_OR_CONNECTOR_ID"],
-    },
-    {
-        "id": "deepnote@openai-curated",
-        "name": "deepnote",
-        "tool_type": "plugin",
-        "has_skills": True,
-        "app_connector_ids": ["REPLACE_WITH_DEEPNOTE_APP_OR_CONNECTOR_ID"],
-    },
-]
-SESSION_ENABLED_PLUGIN_CANDIDATES = [
-    {"id": "github@openai-curated", "name": "github", "tool_type": "plugin"},
-    {"id": "gmail@openai-curated", "name": "gmail", "tool_type": "plugin"},
-    {"id": "google-calendar@openai-curated", "name": "google-calendar", "tool_type": "plugin"},
-    {"id": "google-drive@openai-curated", "name": "google-drive", "tool_type": "plugin"},
-    {"id": "notion@openai-curated", "name": "notion", "tool_type": "plugin"},
-]
-
-
-class DataAnalyticsStateHelperTests(unittest.TestCase):
-    def setUp(self) -> None:
-        self._tmp = tempfile.TemporaryDirectory(
-            prefix="data-analytics-user-context-tests-",
-            dir="/private/tmp",
-        )
-        self.tmp_path = Path(self._tmp.name)
-        self.state_dir = self.tmp_path / "state"
-        self.maxDiff = None
-
-    def tearDown(self) -> None:
-        self._tmp.cleanup()
-
-    def run_json(self, args: list[str], *, expect: int = 0) -> dict:
-        proc = subprocess.run(args, text=True, capture_output=True)
-        self.assertEqual(
-            proc.returncode,
-            expect,
-            msg=f"command failed: {' '.join(args)}\nSTDOUT:\n{proc.stdout}\nSTDERR:\n{proc.stderr}",
-        )
-        return json.loads(proc.stdout)
-
-    def preflight(self, *extra: str, state_dir: Path | None = None) -> dict:
-        return self.run_json(
-            [
-                sys.executable,
-                str(SCRIPT_DIR / "data_analytics_preflight.py"),
-                "--workflow",
-                "metric-diagnostics",
-                "--state-dir",
-                str(state_dir or self.state_dir),
-                *extra,
-            ]
-        )
-
-    def write_state(
-        self,
-        *,
-        user_context: str | None = None,
-        onboarding_state: dict | None = None,
-        state_dir: Path | None = None,
-    ) -> Path:
-        target = state_dir or self.state_dir
-        target.mkdir(parents=True, exist_ok=True)
-        if user_context is not None:
-            (target / "user-context.md").write_text(user_context, encoding="utf-8")
-        if onboarding_state is not None:
-            (target / "onboarding-state.json").write_text(
-                json.dumps(onboarding_state),
-                encoding="utf-8",
-            )
-        return target
-
-    def active_core_categories(self) -> dict[str, dict[str, str]]:
-        return {
-            "structured_data": {"status": "active", "preferred": "Databricks"},
-            "team_communication": {"status": "active", "preferred": "Slack"},
-            "company_docs": {"status": "active", "preferred": "Google Drive"},
-        }
-
-    def source_category_config(self) -> dict:
-        return json.loads(SOURCE_CATEGORY_CONFIG.read_text(encoding="utf-8"))["categories"]
-
-    def test_missing_preflight_returns_setup_obligation_context_gap_and_empty_hero_prompt(
-        self,
-    ) -> None:
-        payload = self.preflight(state_dir=self.tmp_path / "missing")
-        self.assertTrue(payload["read_only"])
-        self.assertEqual(payload["state"]["user_context_status"], "missing")
-        self.assertEqual(payload["state"]["onboarding_state_status"], "missing")
-        self.assertTrue(payload["current_skill_experience"]["intro_eligible"])
-        obligation = payload["control"]["final_obligations"][0]
-        self.assertEqual(obligation["id"], "offer_data_analytics_onboarding_next_step")
-        self.assertIn("## Data Analytics Setup Required", obligation["template"])
-        self.assertEqual(payload["control"]["conditional_guidance"][0]["id"], "context_gap_note")
-        self.assertEqual(payload["context"]["hero_prompt_candidates"], [])
-        self.assertIsNone(payload["context"]["primary_hero_prompt"])
-        self.assertEqual(
-            payload["context"]["connector_setup_summary"]["needs_attention"][0]["status"],
-            "needs_confirmation",
-        )
-
-    def test_direct_and_guided_modes_suppress_ordinary_setup_obligation(self) -> None:
-        direct_payload = self.preflight("--request-mode", "direct_onboarding_status")
-        guided_payload = self.preflight("--request-mode", "guided_onboarding_workflow")
-        self.assertEqual(direct_payload["control"]["final_obligations"], [])
-        self.assertEqual(guided_payload["control"]["final_obligations"], [])
-        self.assertEqual(direct_payload["control"]["conditional_guidance"], [])
-        self.assertEqual(guided_payload["control"]["conditional_guidance"], [])
-        self.assertEqual(guided_payload["current_skill_experience"]["cta_owner"], "onboarding")
-
-    def test_legacy_verified_connector_status_maps_to_active_try_on_use(self) -> None:
-        self.assertEqual(
-            PREFLIGHT_MODULE.source_status({"status": "connected"}),
-            "active",
-        )
-        self.assertEqual(PREFLIGHT_MODULE.source_status({"status": "manual"}), "active")
-        self.assertEqual(
-            PREFLIGHT_MODULE.source_status({"status": "selected_needs_auth"}),
-            "needs_confirmation",
-        )
-        self.assertEqual(PREFLIGHT_MODULE.source_status({"status": "choose_source"}), "needs_confirmation")
-
-    def test_configured_plugin_routes_are_manifest_backed_and_add_google_calendar(
-        self,
-    ) -> None:
-        categories = self.source_category_config()
-        self.assertEqual(categories["team_communication"]["preferred_plugins"], ["Slack", "Teams"])
-        self.assertEqual(
-            categories["company_docs"]["preferred_plugins"],
-            ["Google Drive", "SharePoint", "Notion"],
-        )
-        self.assertEqual(
-            categories["email_context"]["preferred_plugins"],
-            ["Gmail", "Outlook Email"],
-        )
-        self.assertEqual(
-            categories["calendar_context"]["preferred_plugins"],
-            ["Google Calendar", "Outlook Calendar"],
-        )
-        self.assertNotIn("preferred_apps", categories["calendar_context"])
-        self.assertEqual(categories["code_repository"]["preferred_plugins"], ["GitHub"])
-        app_manifest = json.loads(APP_MANIFEST.read_text(encoding="utf-8"))
-        self.assertEqual(
-            app_manifest["apps"]["google_calendar"]["id"],
-            "connector_947e0d954944416db111db556030eea6",
-        )
-        self.assertEqual(
-            PREFLIGHT_MODULE.load_app_connector_ids()["googlecalendar"],
-            "connector_947e0d954944416db111db556030eea6",
-        )
-
-    def test_live_install_listing_fixture_matches_every_installable_data_analytics_plugin(
-        self,
-    ) -> None:
-        matches = PREFLIGHT_MODULE.match_installable_plugin_candidates(
-            self.source_category_config(),
-            {"tools": LIVE_INSTALLABLE_PLUGIN_CANDIDATES},
-        )
-        self.assertEqual(
-            {
-                category_id: [entry["preferred_plugin"] for entry in entries]
-                for category_id, entries in matches.items()
-            },
-            {
-                "structured_data": ["Databricks", "BigQuery", "Snowflake"],
-                "team_communication": ["Slack", "Teams"],
-                "company_docs": ["SharePoint"],
-                "dashboards_bi": ["ThoughtSpot", "Omni Analytics", "Metabase"],
-                "behavior_signals": ["Amplitude", "Mixpanel"],
-                "notebook_lab": ["Hex", "Deepnote"],
-                "email_context": ["Outlook Email"],
-                "calendar_context": ["Outlook Calendar"],
-            },
-        )
-
-    def test_configured_plugins_match_installable_or_enabled_plugin_surfaces(self) -> None:
-        categories = self.source_category_config()
-        matches = PREFLIGHT_MODULE.match_installable_plugin_candidates(
-            categories,
-            [*LIVE_INSTALLABLE_PLUGIN_CANDIDATES, *SESSION_ENABLED_PLUGIN_CANDIDATES],
-        )
-        self.assertEqual(
-            {
-                category_id: [entry["preferred_plugin"] for entry in entries]
-                for category_id, entries in matches.items()
-            },
-            {
-                category_id: metadata["preferred_plugins"]
-                for category_id, metadata in categories.items()
-                if metadata.get("preferred_plugins")
-            },
-        )
-
-    def test_plugin_candidate_matching_uses_connector_id_when_slug_changes(self) -> None:
-        matches = PREFLIGHT_MODULE.match_installable_plugin_candidates(
-            self.source_category_config(),
-            [
-                {
-                    "id": "renamed-plugin@openai-curated",
-                    "name": "renamed-plugin",
-                    "tool_type": "plugin",
-                    "app_connector_ids": ["REPLACE_WITH_SLACK_APP_OR_CONNECTOR_ID"],
-                }
-            ],
-        )
-        slack_match = matches["team_communication"][0]
-        self.assertEqual(slack_match["preferred_plugin"], "Slack")
-        self.assertEqual(slack_match["match_reasons"], ["app_connector_id"])
-
-    def test_plugin_candidate_matching_ignores_description_only_category_similarity(self) -> None:
-        matches = PREFLIGHT_MODULE.match_installable_plugin_candidates(
-            self.source_category_config(),
-            [
-                {
-                    "id": "broad-search@openai-curated",
-                    "name": "broad-search",
-                    "display_name": "Broad Search",
-                    "description": "Indexes Slack and Teams for team communication.",
-                    "tool_type": "plugin",
-                    "has_skills": True,
-                }
-            ],
-        )
-        self.assertNotIn("team_communication", matches)
-
-    def test_preflight_exposes_plugin_setup_before_connector_fallback(self) -> None:
-        payload = self.preflight(state_dir=self.tmp_path / "missing")
-        confirmation = payload["context"]["connector_confirmation"]
-        slack = confirmation["team_communication"]
-        self.assertEqual(slack["setup_action"], "run_plugin_first_source_setup")
-        self.assertEqual(
-            slack["fallback_setup_action"],
-            "ask_user_to_choose_or_confirm_source",
-        )
-        self.assertEqual(slack["plugin_preference_order"], ["Slack", "Teams"])
-        self.assertEqual(
-            slack["setup_recovery"]["candidate_lookup"],
-            "host_available_plugin_catalog",
-        )
-        self.assertEqual(
-            slack["setup_recovery"]["install_request"],
-            "host_authorized_plugin_install",
-        )
-        calendar = confirmation["calendar_context"]
-        self.assertEqual(
-            calendar["plugin_preference_order"],
-            ["Google Calendar", "Outlook Calendar"],
-        )
-        self.assertIn(
-            "team_communication",
-            {
-                entry["id"]
-                for entry in payload["context"]["connector_setup_summary"][
-                    "plugin_setup_opportunities"
-                ]
-            },
-        )
-
-    def test_preflight_keeps_onboarding_state_provenance_without_raw_state_echo(self) -> None:
-        self.write_state(onboarding_state={"status": "active", "connector_confirmation": {}})
-        payload = self.preflight()
-        onboarding_state = payload["files"]["onboarding_state"]
-        self.assertEqual(onboarding_state["status"], "present")
-        self.assertFalse(onboarding_state["omitted"])
-        self.assertNotIn("content", onboarding_state)
-        self.assertNotIn("data", onboarding_state)
-        self.assertNotIn(
-            "setup_recovery",
-            payload["context"]["connector_setup_summary"]["needs_attention"][0],
-        )
-        self.assertIn(
-            "setup_recovery",
-            payload["context"]["connector_confirmation"]["structured_data"],
-        )
-
-    def test_connector_inventory_classifies_routes_without_eager_reads(self) -> None:
-        self.write_state(
-            onboarding_state={
-                "status": "active",
-                "connector_inventory": {
-                    "active_apps": ["Slack"],
-                    "available_apps": ["Databricks"],
-                },
-            }
-        )
-        payload = self.preflight("--request-mode", "direct_onboarding_status")
-        confirmation = payload["context"]["connector_confirmation"]
-
-        self.assertEqual(confirmation["structured_data"]["status"], "needs_confirmation")
-        self.assertEqual(confirmation["structured_data"]["candidates"], ["Databricks"])
-        self.assertEqual(confirmation["team_communication"]["status"], "needs_confirmation")
-        self.assertEqual(confirmation["team_communication"]["candidates"], ["Slack"])
-        self.assertEqual(confirmation["company_docs"]["status"], "missing")
-        self.assertFalse(confirmation["structured_data"]["eager_read"])
-        self.assertEqual(
-            confirmation["structured_data"]["workflow_time_behavior"],
-            "attempt_actual_reads_only_when_a_workflow_needs_the_source",
-        )
-
-    def test_helper_skills_apply_to_app_fallback_but_not_active_plugin_routes(self) -> None:
-        source_config = {
-            "team_communication": {
-                "label": "Team communication",
-                "preferred_plugins": ["slack"],
-                "preferred_apps": ["Slack"],
-                "relevant_skills": [{"app": "Slack", "skill": "slack-helper"}],
-            }
-        }
-        connector_fallback = PREFLIGHT_MODULE.normalized_connector_confirmation(
-            source_config,
-            {
-                "connector_confirmation": {
-                    "categories": {
-                        "team_communication": {
-                            "status": "active",
-                            "preferred": "Slack",
-                            "source_kind": "connector",
-                        }
-                    }
-                }
-            },
-        )["team_communication"]
-        self.assertEqual(connector_fallback["setup_action"], "run_plugin_first_source_setup")
-        self.assertEqual(connector_fallback["fallback_setup_action"], "none_try_on_use")
-        self.assertEqual(connector_fallback["helper_skills_apply_when"], ["app", "connector"])
-
-        plugin_route = PREFLIGHT_MODULE.normalized_connector_confirmation(
-            source_config,
-            {
-                "connector_confirmation": {
-                    "categories": {
-                        "team_communication": {
-                            "status": "active",
-                            "preferred": "slack",
-                            "source_kind": "plugin",
-                            "plugin_install_evidence": "plugin_in_available_plugins",
-                            "skill_surface_evidence": "plugin_skills_visible",
-                        }
-                    }
-                }
-            },
-        )["team_communication"]
-        self.assertEqual(plugin_route["setup_action"], "none_try_on_use")
-        self.assertNotIn("fallback_setup_action", plugin_route)
-        self.assertNotIn("setup_recovery", plugin_route)
-        self.assertNotIn("helper_skills", plugin_route)
-
-    def test_validator_rejects_preferred_plugin_without_manifest_dependency(self) -> None:
-        plugin_copy = self.tmp_path / "data-analytics"
-        shutil.copytree(PLUGIN_ROOT, plugin_copy)
-        config_path = plugin_copy / "skills/user-context/plugin-author-config/source-category-config.json"
-        config = json.loads(config_path.read_text(encoding="utf-8"))
-        config["categories"]["calendar_context"]["preferred_plugins"].append("missing-calendar")
-        config_path.write_text(json.dumps(config, indent=2) + "\n", encoding="utf-8")
-        proc = subprocess.run(
-            [
-                sys.executable,
-                str(SCRIPT_DIR / "validate_user_context_preflight.py"),
-                str(plugin_copy),
-                "--plugin-id",
-                "data-analytics",
-            ],
-            text=True,
-            capture_output=True,
-        )
-        self.assertNotEqual(proc.returncode, 0)
-        self.assertIn(
-            "preferred plugin missing-calendar must be declared in .app.json",
-            proc.stderr,
-        )
-
-    def test_validator_rejects_preferred_app_without_manifest_dependency(self) -> None:
-        plugin_copy = self.tmp_path / "data-analytics"
-        shutil.copytree(PLUGIN_ROOT, plugin_copy)
-        config_path = plugin_copy / "skills/user-context/plugin-author-config/source-category-config.json"
-        config = json.loads(config_path.read_text(encoding="utf-8"))
-        config["categories"]["calendar_context"]["preferred_apps"] = ["Missing Calendar"]
-        config_path.write_text(json.dumps(config, indent=2) + "\n", encoding="utf-8")
-        proc = subprocess.run(
-            [
-                sys.executable,
-                str(SCRIPT_DIR / "validate_user_context_preflight.py"),
-                str(plugin_copy),
-                "--plugin-id",
-                "data-analytics",
-            ],
-            text=True,
-            capture_output=True,
-        )
-        self.assertNotEqual(proc.returncode, 0)
-        self.assertIn(
-            "preferred app Missing Calendar must be declared in .app.json",
-            proc.stderr,
-        )
-
-    def test_validator_rejects_saved_context_heading_in_author_config(self) -> None:
-        plugin_copy = self.tmp_path / "data-analytics"
-        shutil.copytree(PLUGIN_ROOT, plugin_copy)
-        config_path = plugin_copy / "skills/user-context/plugin-author-config/user-context-config.md"
-        config = config_path.read_text(encoding="utf-8")
-        config_path.write_text(
-            config.replace(
-                "# Semantic Layers\n\n",
-                "# Semantic Layers\n\n## Saved Links And Context\n\n",
-                1,
-            ),
-            encoding="utf-8",
-        )
-        proc = subprocess.run(
-            [
-                sys.executable,
-                str(SCRIPT_DIR / "validate_user_context_preflight.py"),
-                str(plugin_copy),
-                "--plugin-id",
-                "data-analytics",
-            ],
-            text=True,
-            capture_output=True,
-        )
-        self.assertNotEqual(proc.returncode, 0)
-        self.assertIn("default user context must not contain: ## Saved Links And Context", proc.stderr)
-
-    def test_selected_source_needs_confirmation_stays_unresolved_until_user_resolves_it(
-        self,
-    ) -> None:
-        self.write_state(
-            user_context="""# Data Analytics Source Routing Preferences
-
-Store durable Data Analytics source-routing choices explicitly selected for future use.
-
-## structured_data
-
-- Prefer:
-- Avoid:
-
-# Semantic Layers
-
-status: not provided
-""",
-            onboarding_state={
-                "status": "active",
-                "orientation": {"status": "shown"},
-                "connector_confirmation": {
-                    "structured_data": {
-                        "status": "needs_confirmation",
-                        "preferred": "Databricks",
-                    },
-                    "team_communication": {"status": "active", "preferred": "Slack"},
-                    "company_docs": {"status": "active", "preferred": "Google Drive"},
-                },
-            },
-        )
-        payload = self.preflight()
-        summary = payload["context"]["connector_setup_summary"]
-        self.assertEqual(payload["context"]["user_context"]["semantic_layer_count"], 0)
-        self.assertFalse(summary["core_complete"])
-        self.assertEqual(summary["next_action"]["category_id"], "structured_data")
-        self.assertEqual(
-            summary["next_action"]["setup_action"],
-            "run_plugin_first_source_setup",
-        )
-        self.assertEqual(summary["needs_attention"][0]["status"], "needs_confirmation")
-        self.assertNotIn(
-            "structured_data",
-            {entry["id"] for entry in summary["ready"]},
-        )
-        self.assertEqual(
-            payload["control"]["final_obligations"][0]["id"],
-            "complete_data_analytics_core_onboarding",
-        )
-
-    def test_unacknowledged_deferred_core_sources_reopen_as_needs_confirmation(self) -> None:
-        self.write_state(
-            onboarding_state={
-                "status": "active",
-                "orientation": {"status": "shown"},
-                "connector_confirmation": {
-                    "status": "completed",
-                    "structured_data": {"status": "deferred"},
-                    "team_communication": {"status": "deferred"},
-                    "company_docs": {"status": "active", "preferred": "Google Drive"},
-                },
-            }
-        )
-        payload = self.preflight("--request-mode", "direct_onboarding_status")
-        confirmation = payload["context"]["connector_confirmation"]
-        summary = payload["context"]["connector_setup_summary"]
-        self.assertEqual(confirmation["structured_data"]["status"], "needs_confirmation")
-        self.assertEqual(confirmation["structured_data"]["recorded_status"], "deferred")
-        self.assertEqual(
-            confirmation["structured_data"]["setup_note"],
-            "core_source_requires_explicit_user_resolution_before_fallback",
-        )
-        self.assertEqual(confirmation["team_communication"]["status"], "needs_confirmation")
-        self.assertFalse(summary["core_complete"])
-        self.assertEqual(
-            summary["unresolved_core_ids"],
-            ["structured_data", "team_communication"],
-        )
-        self.assertEqual(
-            [entry["id"] for entry in summary["needs_attention"][:2]],
-            ["structured_data", "team_communication"],
-        )
-        self.assertEqual(summary["next_action"]["category_id"], "structured_data")
-        self.assertEqual(
-            payload["control"]["onboarding_progress"]["task_list"][1]["status"],
-            "in_progress",
-        )
-
-    def test_connector_confirmation_status_without_core_categories_stays_pending(self) -> None:
-        self.write_state(
-            onboarding_state={
-                "status": "active",
-                "orientation": {"status": "shown"},
-                "connector_confirmation": {"status": "completed"},
-            }
-        )
-        payload = self.preflight("--request-mode", "direct_onboarding_status")
-        summary = payload["context"]["connector_setup_summary"]
-        self.assertEqual(summary["classification_status"], "pending")
-        self.assertFalse(summary["core_complete"])
-        self.assertEqual(
-            payload["control"]["onboarding_progress"]["task_list"][1]["status"],
-            "in_progress",
-        )
-
-    def test_explicit_core_source_defer_counts_as_recorded_known_gap(self) -> None:
-        self.write_state(
-            onboarding_state={
-                "status": "active",
-                "connector_confirmation": {
-                    "structured_data": {"status": "deferred", "resolution": "user_deferred"},
-                    "team_communication": {
-                        "status": "deferred",
-                        "resolution": "user_continued_with_known_gap",
-                    },
-                    "company_docs": {"status": "active", "preferred": "Google Drive"},
-                },
-            }
-        )
-        payload = self.preflight("--request-mode", "direct_onboarding_status")
-        confirmation = payload["context"]["connector_confirmation"]
-        summary = payload["context"]["connector_setup_summary"]
-        self.assertEqual(confirmation["structured_data"]["status"], "deferred")
-        self.assertEqual(confirmation["structured_data"]["resolution"], "user_deferred")
-        self.assertTrue(summary["core_complete"])
-        self.assertEqual(summary["unresolved_core_ids"], [])
-        self.assertEqual(
-            {entry["id"] for entry in summary["fallback_or_closed"]},
-            {"structured_data", "team_communication"},
-        )
-
-    def test_core_onboarding_complete_requires_active_or_explicit_fallback_sources(self) -> None:
-        self.write_state(
-            onboarding_state={
-                "status": "active",
-                "orientation": {"status": "shown"},
-                "connector_confirmation": {
-                    **self.active_core_categories(),
-                },
-                "semantic_layer_setup": {"status": "created"},
-                "semantic_layer_refresh": {"status": "declined"},
-            }
-        )
-        payload = self.preflight("--request-mode", "direct_onboarding_status")
-        progress = payload["control"]["onboarding_progress"]
-        task_statuses = {item["id"]: item["status"] for item in progress["task_list"]}
-        self.assertTrue(progress["core_onboarding"]["complete"])
-        self.assertEqual(task_statuses["source_setup_confirmation"], "completed")
-        self.assertEqual(task_statuses["semantic_layer_setup"], "completed")
-        self.assertEqual(task_statuses["hero_prompt"], "in_progress")
-
-    def test_core_onboarding_complete_allows_semantic_layer_skip_without_refresh(self) -> None:
-        self.write_state(
-            onboarding_state={
-                "status": "active",
-                "orientation": {"status": "shown"},
-                "connector_confirmation": {
-                    "status": "completed",
-                    **self.active_core_categories(),
-                },
-                "semantic_layer_setup": {"status": "skipped"},
-            }
-        )
-        payload = self.preflight("--request-mode", "direct_onboarding_status")
-        progress = payload["control"]["onboarding_progress"]
-        task_statuses = {item["id"]: item["status"] for item in progress["task_list"]}
-        self.assertTrue(progress["core_onboarding"]["complete"])
-        self.assertEqual(task_statuses["semantic_layer_setup"], "completed")
-        self.assertEqual(task_statuses["hero_prompt"], "in_progress")
-
-    def test_active_core_incomplete_returns_single_reminder_with_next_action(self) -> None:
-        self.write_state(
-            user_context="""# Data Analytics Source Routing Preferences
-
-Store durable Data Analytics source-routing choices explicitly selected for future use.
-
-## structured_data
-
-- Prefer:
-- Avoid:
-
-# Semantic Layers
-
-status: not provided
-""",
-            onboarding_state={"status": "active", "orientation": {"status": "shown"}},
-        )
-        payload = self.preflight()
-        obligation = payload["control"]["final_obligations"][0]
-        self.assertEqual(obligation["id"], "complete_data_analytics_core_onboarding")
-        self.assertEqual(obligation["next_action"]["id"], "confirm_analytics_sources")
-        self.assertIn("**Next Step**", obligation["template"])
-        self.assertIn("Reply `continue onboarding`", obligation["template"])
-        self.assertEqual(len(payload["control"]["final_obligations"]), 1)
-
-    def test_complete_and_quiet_onboarding_suppress_auto_obligations(self) -> None:
-        for status in ("complete", "quiet"):
-            with self.subTest(status=status):
-                state_dir = self.tmp_path / status
-                self.write_state(onboarding_state={"status": status}, state_dir=state_dir)
-                payload = self.preflight(state_dir=state_dir)
-                self.assertEqual(payload["control"]["final_obligations"], [])
-
-    def test_semantic_layer_registry_and_hero_prompt_candidates_come_from_context(
-        self,
-    ) -> None:
-        self.write_state(
-            user_context="""# Data Analytics Source Routing Preferences
-
-Store durable Data Analytics source-routing choices explicitly selected for future use.
-
-## structured_data
-
-- Prefer: Databricks
-- Avoid: Snowflake
-
-# Semantic Layers
-
-- Area: API
-  - Skill Name: api-semantic-layer
-  - Skill Path: /tmp/api-semantic-layer
-  - Source Inventory Path: /tmp/api-semantic-layer/references/source-inventory.md
-  - Last Updated: 2026-05-29
-""",
-            onboarding_state={"status": "active", "semantic_layer_setup": {"area": "API"}},
-        )
-        payload = self.preflight()
-        self.assertNotIn("user_context_markdown", payload["context"])
-        self.assertNotIn("content", payload["files"]["user_context"])
-        self.assertTrue(payload["context"]["user_context"]["normalization_complete"])
-        self.assertEqual(payload["context"]["semantic_layers"][0]["area"], "API")
-        self.assertEqual(payload["context"]["source_preferences"]["structured_data"], {
-            "preferred": ["Databricks"],
-            "avoid": ["Snowflake"],
-        })
-        self.assertEqual(len(payload["context"]["hero_prompt_candidates"]), 1)
-        self.assertEqual(payload["context"]["primary_hero_prompt"]["skill"], "product-business-analysis")
-        self.assertEqual(
-            payload["context"]["primary_hero_prompt"]["label"],
-            "Build a decision-ready report",
-        )
-        self.assertEqual(
-            payload["context"]["primary_hero_prompt"]["prompt"],
-            (
-                "Build a decision-ready report for API: explain what is happening, "
-                "identify the main drivers, recommend where the team should focus next, "
-                "and include sources, caveats, and useful charts."
-            ),
-        )
-        self.assertEqual(payload["context"]["extra_hero_prompt_candidates"], [])
-
-    def test_large_user_context_renders_source_preferences_and_requested_section(self) -> None:
-        self.write_state(
-            user_context="""# Data Analytics Source Routing Preferences
-
-Store durable Data Analytics source-routing choices explicitly selected for future use.
-
-## structured_data
-
-- Prefer: Databricks
-- Avoid: Snowflake
-
-## company_docs
-
-- Prefer: Google Drive
-- Avoid:
-
-# Semantic Layers
-
-""" + ("x" * 2048),
-        )
-        payload = self.preflight(
-            "--max-context-bytes",
-            "80",
-            "--section",
-            "Data Analytics Source Routing Preferences",
-        )
-        self.assertNotIn("user_context_markdown", payload["context"])
-        self.assertNotIn("content", payload["files"]["user_context"])
-        self.assertTrue(payload["files"]["user_context"]["omitted"])
-        self.assertEqual(payload["files"]["user_context"]["sections"][0]["status"], "present")
-        self.assertTrue(payload["context"]["user_context"]["normalization_complete"])
-        self.assertEqual(
-            payload["context"]["source_preferences"],
-            {
-                "structured_data": {
-                    "preferred": ["Databricks"],
-                    "avoid": ["Snowflake"],
-                },
-                "company_docs": {"preferred": ["Google Drive"]},
-            },
-        )
-        self.assertEqual(
-            payload["context"]["user_context"]["source_routing_preferences"],
-            payload["context"]["source_preferences"],
-        )
-
-    def test_reset_moves_active_state_files(self) -> None:
-        self.state_dir.mkdir(parents=True)
-        user_context_path = self.state_dir / "user-context.md"
-        onboarding_state_path = self.state_dir / "onboarding-state.json"
-        user_context_path.write_text("# Context\n", encoding="utf-8")
-        onboarding_state_path.write_text(json.dumps({"status": "active"}), encoding="utf-8")
-        backup_dir = self.tmp_path / "backup"
-        proc = subprocess.run(
-            [
-                sys.executable,
-                str(SCRIPT_DIR / "reset_user_context_state.py"),
-                "--state-dir",
-                str(self.state_dir),
-                "--backup-dir",
-                str(backup_dir),
-            ],
-            text=True,
-            capture_output=True,
-        )
-        self.assertEqual(proc.returncode, 0, msg=proc.stderr)
-        self.assertFalse(user_context_path.exists())
-        self.assertFalse(onboarding_state_path.exists())
-        self.assertTrue((backup_dir / "user-context.md").exists())
-        self.assertTrue((backup_dir / "onboarding-state.json").exists())
-
-    def test_initializer_creates_user_context_and_onboarding_state(self) -> None:
-        proc = subprocess.run(
-            [
-                sys.executable,
-                str(SCRIPT_DIR / "init_user_context_state.py"),
-                "--state-dir",
-                str(self.state_dir),
-            ],
-            text=True,
-            capture_output=True,
-        )
-        self.assertEqual(proc.returncode, 0, msg=proc.stderr)
-        user_context = (self.state_dir / "user-context.md").read_text(encoding="utf-8")
-        self.assertNotIn("# Data Analytics User Context Config", user_context)
-        self.assertNotIn("- Priority:", user_context)
-        self.assertNotIn("- Use When:", user_context)
-        self.assertIn(
-            "Store durable Data Analytics source-routing choices explicitly selected for future use.",
-            user_context,
-        )
-        self.assertEqual(user_context.count("## "), 9)
-        self.assertEqual(user_context.count("- Prefer:"), 9)
-        self.assertEqual(user_context.count("- Avoid:"), 9)
-        self.assertEqual(user_context.count("status: not provided"), 1)
-        onboarding_state = json.loads((self.state_dir / "onboarding-state.json").read_text())
-        self.assertEqual(onboarding_state["status"], "active")
-        self.assertNotIn("connector_inventory", onboarding_state)
-        self.assertNotIn("seed_sources", onboarding_state["semantic_layer_setup"])
-        self.assertEqual(onboarding_state["semantic_layer_setup"]["seed_source_count"], 0)
-        self.assertIn("hero_prompt_choice", onboarding_state)
-        self.assertIn("skill_experience", onboarding_state)
-
-    def test_onboarding_contract_mentions_active_sources_and_one_first_hero_prompt(
-        self,
-    ) -> None:
-        onboarding_text = ONBOARDING_REFERENCE.read_text(encoding="utf-8")
-        source_runtime_text = SOURCE_RUNTIME_REFERENCE.read_text(encoding="utf-8")
-        automation_text = AUTOMATION_REFERENCE.read_text(encoding="utf-8")
-        self.assertIn("Check Main Analytics Sources", onboarding_text)
-        self.assertIn("Resolve Source Questions", onboarding_text)
-        self.assertIn("transition without a proof read", onboarding_text)
-        self.assertIn("Set Up Data Context", onboarding_text)
-        self.assertIn("Codex gets better at data work", onboarding_text)
-        self.assertIn("Send anything you would point a new analyst to", onboarding_text)
-        self.assertIn("Reply with any starting points, or say `skip for now`", onboarding_text)
-        self.assertIn("Do not: require the user to name a product or business area up front", onboarding_text)
-        self.assertNotIn("smallest useful seed", onboarding_text)
-        self.assertNotIn("first semantic layer", onboarding_text)
-        self.assertNotIn("main source categories", onboarding_text)
-        self.assertIn("Show one strong prompt first", onboarding_text)
-        self.assertIn("Do not: show three hero prompts initially", onboarding_text)
-        self.assertIn("write the prompt you would rather try instead", onboarding_text)
-        self.assertIn("`skip` to finish onboarding", onboarding_text)
-        self.assertIn("Step 5, `complete_or_quiet`, when the user skips or defers", onboarding_text)
-        self.assertIn("`needs_confirmation`", source_runtime_text)
-        self.assertIn("Do not run a proof query during onboarding", source_runtime_text)
-        self.assertIn("Do not mark setup complete", automation_text)
-        for hero_skill in HERO_SKILLS:
-            text = hero_skill.read_text(encoding="utf-8")
-            self.assertIn("data-analytics:user-context", text)
-
-    def test_semantic_layer_setup_uses_lightweight_generated_skills_and_source_checkpoint(
-        self,
-    ) -> None:
-        setup_text = SEMANTIC_LAYER_SETUP_REFERENCE.read_text(encoding="utf-8")
-        source_intake_text = SEMANTIC_LAYER_SOURCE_INTAKE_REFERENCE.read_text(encoding="utf-8")
-        template_text = SEMANTIC_LAYER_SKILL_TEMPLATE_REFERENCE.read_text(encoding="utf-8")
-        weekly_polling_text = SEMANTIC_LAYER_WEEKLY_POLLING_REFERENCE.read_text(
-            encoding="utf-8"
-        )
-        self.assertIn("source-use checkpoint", setup_text)
-        self.assertIn("rejected or lower-confidence candidates", setup_text)
-        self.assertIn("Infer expected source lanes", setup_text)
-        self.assertIn("nearby but not exact", setup_text)
-        self.assertIn("authoritative data documentation", setup_text)
-        self.assertIn("source-backed semantic-layer skills", setup_text)
-        self.assertIn("user-trusted canonical data skills", setup_text)
-        self.assertIn("treat that as authoritative data documentation", setup_text)
-        self.assertIn("authoritative data documentation", weekly_polling_text)
-        self.assertIn("source-backed semantic-layer skills", weekly_polling_text)
-        self.assertIn("user-trusted canonical data skills", weekly_polling_text)
-        self.assertIn("Infer useful source families", source_intake_text)
-        self.assertIn("do not treat ambient app availability as user approval", source_intake_text)
-        self.assertIn("Send anything you would point a new analyst to", source_intake_text)
-        self.assertIn("Reply with any starting points, or say `skip for now`", source_intake_text)
-        self.assertIn("## Start Here", template_text)
-        self.assertIn("## References", template_text)
-        self.assertIn("Answering Rules", template_text)
-        self.assertIn("## Quick Reference", template_text)
-        self.assertIn("## Entity Clarification", template_text)
-        self.assertIn("## Standard Filters And Dimensions", template_text)
-        self.assertIn("evidence.md`: detailed provenance, only when the layer needs separate evidence tracking", template_text)
-        self.assertIn("Do not put setup-time policy or full evidence procedures", template_text)
-        self.assertNotIn("### Source Order", template_text)
-        self.assertNotIn("### Evidence Standard", template_text)
-
-
-if __name__ == "__main__":
-    unittest.main()