@ngocsangairvds/vsaf 4.0.6 → 4.0.7

package/skills/vds-skill/vds-scripts/vds_agent_core/tests/unit/test_skill_policy.py

@@ -0,0 +1,402 @@
+"""Tests for vds_agent_core.skills.policy — extracted skill policy enforcement."""
+
+from __future__ import annotations
+
+from vds_agent_core.skills.policy import (
+    FallbackCandidate,
+    FallbackResult,
+    SkillExecutionTarget,
+    SkillPolicyEnforcer,
+    SkillPolicyMode,
+    SkillPolicyTelemetryEvent,
+    SkillRankingEntry,
+    resolve_skill_policy_mode,
+)
+
+
+class TestSkillPolicyEnforcerInstantiation:
+    """SkillPolicyEnforcer can be created with various configurations."""
+
+    def test_default_instantiation(self) -> None:
+        enforcer = SkillPolicyEnforcer()
+        assert enforcer.mode == SkillPolicyMode.STANDARD
+        assert enforcer.skills_needed is True
+
+    def test_disabled_when_skills_not_needed(self) -> None:
+        enforcer = SkillPolicyEnforcer(skills_needed=False)
+        assert enforcer.mode == SkillPolicyMode.DISABLED
+
+    def test_string_mode_coercion(self) -> None:
+        enforcer = SkillPolicyEnforcer(mode="permissive")
+        assert enforcer.mode == SkillPolicyMode.PERMISSIVE
+
+    def test_invalid_string_mode_falls_back_to_standard(self) -> None:
+        enforcer = SkillPolicyEnforcer(mode="bogus")
+        assert enforcer.mode == SkillPolicyMode.STANDARD
+
+
+class TestSkillPolicyModeEnum:
+    """SkillPolicyMode enum has the expected canonical members."""
+
+    def test_has_all_canonical_members(self) -> None:
+        expected = {"DISABLED", "MINIMAL", "STANDARD", "PERMISSIVE"}
+        actual = {m.name for m in SkillPolicyMode}
+        assert actual == expected
+
+    def test_values_are_lowercase(self) -> None:
+        for member in SkillPolicyMode:
+            assert member.value == member.name.lower()
+
+    def test_is_str_enum(self) -> None:
+        assert isinstance(SkillPolicyMode.STANDARD, str)
+        assert SkillPolicyMode.STANDARD == "standard"
+
+
+class TestResolveSkillPolicyMode:
+    """resolve_skill_policy_mode resolves from multiple input sources."""
+
+    def test_default_returns_minimal(self) -> None:
+        result = resolve_skill_policy_mode()
+        assert result == SkillPolicyMode.MINIMAL
+
+    def test_skills_needed_false_returns_disabled(self) -> None:
+        result = resolve_skill_policy_mode(skills_needed=False)
+        assert result == SkillPolicyMode.DISABLED
+
+    def test_mode_override_takes_precedence(self) -> None:
+        result = resolve_skill_policy_mode(mode_override="permissive")
+        assert result == SkillPolicyMode.PERMISSIVE
+
+    def test_interpretation_skills_needed_false(self) -> None:
+        result = resolve_skill_policy_mode(
+            interpretation={"skills_needed": False},
+        )
+        assert result == SkillPolicyMode.DISABLED
+
+    def test_invalid_override_falls_through_to_default(self) -> None:
+        result = resolve_skill_policy_mode(mode_override="nonexistent")
+        assert result == SkillPolicyMode.MINIMAL
+
+
+class TestSkillPolicyEnforcerEvaluate:
+    """SkillPolicyEnforcer.evaluate() gate decisions for all modes."""
+
+    def test_non_skill_tool_always_allowed(self) -> None:
+        enforcer = SkillPolicyEnforcer()
+        decision = enforcer.evaluate("search_code")
+        assert decision.allowed is True
+        assert decision.reason == "not_skill_tool"
+
+    def test_disabled_mode_blocks_all_skill_tools(self) -> None:
+        enforcer = SkillPolicyEnforcer(skills_needed=False)
+        for tool in ("list_skills", "load_skill", "read_skill_resource", "run_skill_script"):
+            decision = enforcer.evaluate(tool)
+            assert decision.allowed is False
+            assert decision.reason == "skills_disabled_hard_gate"
+            assert decision.fallback_message is not None
+
+    def test_permissive_mode_allows_all_skill_tools(self) -> None:
+        enforcer = SkillPolicyEnforcer(mode="permissive")
+        for tool in ("list_skills", "load_skill", "read_skill_resource", "run_skill_script"):
+            decision = enforcer.evaluate(tool)
+            assert decision.allowed is True
+            assert decision.reason == "permissive_mode"
+
+    def test_standard_mode_allows_all_skill_tools(self) -> None:
+        enforcer = SkillPolicyEnforcer(mode="standard")
+        for tool in ("list_skills", "load_skill", "read_skill_resource", "run_skill_script"):
+            decision = enforcer.evaluate(tool)
+            assert decision.allowed is True
+            assert decision.reason == "standard_mode_allowed"
+
+    def test_minimal_mode_allows_first_list_skills(self) -> None:
+        enforcer = SkillPolicyEnforcer(mode="minimal")
+        decision = enforcer.evaluate("list_skills")
+        assert decision.allowed is True
+        assert decision.reason == "minimal_mode_discovery_allowed"
+
+    def test_minimal_mode_blocks_second_list_skills(self) -> None:
+        enforcer = SkillPolicyEnforcer(mode="minimal", max_list_skills_in_minimal=1)
+        enforcer.evaluate("list_skills")  # first — allowed
+        decision = enforcer.evaluate("list_skills")  # second — blocked
+        assert decision.allowed is False
+        assert decision.reason == "minimal_mode_discovery_limit"
+
+    def test_minimal_mode_allows_load_skill(self) -> None:
+        enforcer = SkillPolicyEnforcer(mode="minimal")
+        decision = enforcer.evaluate("load_skill")
+        assert decision.allowed is True
+        assert "bootstrap" in decision.reason
+
+    def test_minimal_mode_allows_execution_tools(self) -> None:
+        enforcer = SkillPolicyEnforcer(mode="minimal")
+        for tool in ("read_skill_resource", "run_skill_script"):
+            decision = enforcer.evaluate(tool)
+            assert decision.allowed is True
+            assert "execution" in decision.reason
+
+    def test_state_tracks_blocked_calls(self) -> None:
+        enforcer = SkillPolicyEnforcer(skills_needed=False)
+        enforcer.evaluate("list_skills")
+        enforcer.evaluate("load_skill")
+        assert enforcer.state.blocked_calls == 2
+        assert enforcer.state.total_skill_calls == 2
+
+    def test_state_tracks_execution_count(self) -> None:
+        enforcer = SkillPolicyEnforcer(mode="standard")
+        enforcer.evaluate("read_skill_resource")
+        enforcer.evaluate("run_skill_script")
+        assert enforcer.state.execution_count == 2
+
+    def test_reset_state_clears_counters(self) -> None:
+        enforcer = SkillPolicyEnforcer(mode="standard")
+        enforcer.evaluate("load_skill")
+        enforcer.evaluate("read_skill_resource")
+        enforcer.reset_state()
+        assert enforcer.state.total_skill_calls == 0
+        assert enforcer.state.execution_count == 0
+
+
+class TestAttemptFallback:
+    """SkillPolicyEnforcer.attempt_fallback() bounded expansion."""
+
+    def _make_entry(self, name: str, score: float) -> SkillRankingEntry:
+        return SkillRankingEntry(
+            skill_name=name,
+            execution_count=1,
+            success_count=1,
+            effectiveness_score=score,
+            rationale="high_effectiveness",
+        )
+
+    def test_no_candidates_returns_triggered_failure(self) -> None:
+        enforcer = SkillPolicyEnforcer()
+        result = enforcer.attempt_fallback("skill_a", [])
+        assert result.triggered is True
+        assert result.success is False
+        assert result.candidate_count == 0
+
+    def test_dry_run_returns_candidates_without_executing(self) -> None:
+        enforcer = SkillPolicyEnforcer()
+        candidates = [self._make_entry("skill_b", 0.9), self._make_entry("skill_c", 0.7)]
+        result = enforcer.attempt_fallback("skill_a", candidates, execute_fn=None)
+        assert result.triggered is True
+        assert result.candidate_count == 2
+        assert result.success is False
+        assert all(not c.success for c in result.candidates_tried)
+
+    def test_execute_fn_called_and_success_stops_early(self) -> None:
+        enforcer = SkillPolicyEnforcer()
+        calls: list[str] = []
+
+        def execute(name: str) -> bool:
+            calls.append(name)
+            return name == "skill_b"
+
+        candidates = [self._make_entry("skill_b", 0.9), self._make_entry("skill_c", 0.7)]
+        result = enforcer.attempt_fallback("skill_a", candidates, execute_fn=execute)
+        assert result.success is True
+        assert len(calls) == 1  # stopped after first success
+        assert calls[0] == "skill_b"
+
+    def test_primary_skill_excluded_from_candidates(self) -> None:
+        enforcer = SkillPolicyEnforcer()
+        candidates = [self._make_entry("skill_a", 0.9), self._make_entry("skill_b", 0.8)]
+        result = enforcer.attempt_fallback("skill_a", candidates, execute_fn=None)
+        assert all(c.skill_name != "skill_a" for c in result.candidates_tried)
+
+    def test_max_fallback_candidates_respected(self) -> None:
+        enforcer = SkillPolicyEnforcer()
+        candidates = [self._make_entry(f"skill_{i}", float(i) / 10) for i in range(5, 0, -1)]
+        result = enforcer.attempt_fallback("skill_x", candidates, execute_fn=None, max_fallback_candidates=2)
+        assert result.candidate_count == 2
+
+    def test_candidate_names_property(self) -> None:
+        enforcer = SkillPolicyEnforcer()
+        candidates = [self._make_entry("skill_b", 0.9)]
+        result = enforcer.attempt_fallback("skill_a", candidates, execute_fn=None)
+        assert result.candidate_names == ["skill_b"]
+
+
+class TestCheckExecutionCompliance:
+    """SkillPolicyEnforcer.check_execution_compliance() FR-199."""
+
+    def test_empty_targets_is_compliant(self) -> None:
+        result = SkillPolicyEnforcer.check_execution_compliance([])
+        assert result.compliant is True
+        assert result.total_targets == 0
+
+    def test_all_executed_is_compliant(self) -> None:
+        targets = [
+            SkillExecutionTarget("docs", "ref_1", executed=True),
+            SkillExecutionTarget("code", "ref_2", executed=True),
+        ]
+        result = SkillPolicyEnforcer.check_execution_compliance(targets)
+        assert result.compliant is True
+        assert result.executed_targets == 2
+        assert result.skipped_targets == 0
+
+    def test_skipped_with_reason_is_compliant(self) -> None:
+        targets = [
+            SkillExecutionTarget("docs", "ref_1", executed=False, skip_reason="not_applicable"),
+        ]
+        result = SkillPolicyEnforcer.check_execution_compliance(targets)
+        assert result.compliant is True
+        assert result.skipped_without_reason == 0
+
+    def test_skipped_without_reason_is_noncompliant(self) -> None:
+        targets = [
+            SkillExecutionTarget("docs", "ref_1", executed=False),
+        ]
+        result = SkillPolicyEnforcer.check_execution_compliance(targets)
+        assert result.compliant is False
+        assert result.skipped_without_reason == 1
+
+    def test_details_populated(self) -> None:
+        targets = [
+            SkillExecutionTarget("docs", "ref_1", executed=True),
+            SkillExecutionTarget("code", "ref_2", executed=False, skip_reason="irrelevant"),
+        ]
+        result = SkillPolicyEnforcer.check_execution_compliance(targets)
+        assert len(result.details) == 2
+        assert result.details[0]["executed"] is True
+        assert result.details[1]["skip_reason"] == "irrelevant"
+
+
+class TestRankSkillEffectiveness:
+    """SkillPolicyEnforcer.rank_skill_effectiveness() FR-200."""
+
+    def test_empty_log_returns_empty(self) -> None:
+        assert SkillPolicyEnforcer.rank_skill_effectiveness([]) == []
+
+    def test_entries_without_skill_name_skipped(self) -> None:
+        log = [{"success": True}, {"skill_name": "", "success": True}]
+        result = SkillPolicyEnforcer.rank_skill_effectiveness(log)
+        assert result == []
+
+    def test_high_effectiveness(self) -> None:
+        log = [{"skill_name": "skill_a", "success": True}] * 5
+        result = SkillPolicyEnforcer.rank_skill_effectiveness(log)
+        assert result[0].rationale == "high_effectiveness"
+        assert result[0].effectiveness_score == 1.0
+
+    def test_moderate_effectiveness(self) -> None:
+        log = [
+            {"skill_name": "skill_a", "success": True},
+            {"skill_name": "skill_a", "success": False},
+        ]
+        result = SkillPolicyEnforcer.rank_skill_effectiveness(log)
+        assert result[0].rationale == "moderate_effectiveness"
+        assert result[0].effectiveness_score == 0.5
+
+    def test_low_effectiveness(self) -> None:
+        log = [
+            {"skill_name": "skill_a", "success": True},
+            {"skill_name": "skill_a", "success": False},
+            {"skill_name": "skill_a", "success": False},
+            {"skill_name": "skill_a", "success": False},
+        ]
+        result = SkillPolicyEnforcer.rank_skill_effectiveness(log)
+        assert result[0].rationale == "low_effectiveness"
+
+    def test_no_successful_executions(self) -> None:
+        log = [{"skill_name": "skill_a", "success": False}] * 3
+        result = SkillPolicyEnforcer.rank_skill_effectiveness(log)
+        assert result[0].rationale == "no_successful_executions"
+        assert result[0].effectiveness_score == 0.0
+
+    def test_sorted_by_score_descending(self) -> None:
+        log = [
+            {"skill_name": "skill_low", "success": False},
+            {"skill_name": "skill_high", "success": True},
+        ]
+        result = SkillPolicyEnforcer.rank_skill_effectiveness(log)
+        assert result[0].skill_name == "skill_high"
+        assert result[1].skill_name == "skill_low"
+
+
+class TestBuildTelemetryEvent:
+    """SkillPolicyEnforcer.build_telemetry_event() FR-198, FR-226."""
+
+    def test_basic_event_fields(self) -> None:
+        enforcer = SkillPolicyEnforcer(mode="standard")
+        enforcer.evaluate("load_skill")
+        event = enforcer.build_telemetry_event(row_index=3, check_id="CL-001")
+        assert event.row_index == 3
+        assert event.check_id == "CL-001"
+        assert event.mode == "standard"
+        assert event.load_skill_count == 1
+
+    def test_fallback_fields_when_triggered(self) -> None:
+        enforcer = SkillPolicyEnforcer()
+        fb = FallbackResult(
+            triggered=True,
+            candidates_tried=[
+                FallbackCandidate("skill_b", 0.9, success=True),
+            ],
+            success=True,
+            primary_skill="skill_a",
+        )
+        event = enforcer.build_telemetry_event(fallback_result=fb)
+        assert event.fallback_triggered is True
+        assert event.fallback_success is True
+        assert event.fallback_candidate_count == 1
+        assert "skill_b" in event.fallback_candidates
+
+    def test_fallback_not_triggered_omits_fields(self) -> None:
+        enforcer = SkillPolicyEnforcer()
+        event = enforcer.build_telemetry_event()
+        assert event.fallback_triggered is False
+
+    def test_to_dict_includes_fallback_when_triggered(self) -> None:
+        enforcer = SkillPolicyEnforcer()
+        fb = FallbackResult(triggered=True, success=False, primary_skill="skill_a")
+        event = enforcer.build_telemetry_event(fallback_result=fb)
+        d = event.to_dict()
+        assert d["fallback_triggered"] is True
+
+    def test_to_dict_excludes_fallback_when_not_triggered(self) -> None:
+        enforcer = SkillPolicyEnforcer()
+        event = enforcer.build_telemetry_event()
+        d = event.to_dict()
+        assert "fallback_triggered" not in d
+
+    def test_effectiveness_rankings_serialized(self) -> None:
+        enforcer = SkillPolicyEnforcer()
+        rankings = [
+            SkillRankingEntry("skill_a", 5, 4, 0.8, "high_effectiveness"),
+        ]
+        event = enforcer.build_telemetry_event(effectiveness_rankings=rankings)
+        assert len(event.effectiveness_rankings) == 1
+        assert event.effectiveness_rankings[0]["skill_name"] == "skill_a"
+
+    def test_degraded_fields(self) -> None:
+        enforcer = SkillPolicyEnforcer()
+        event = enforcer.build_telemetry_event(is_degraded=True, degraded_reason="timeout")
+        assert event.is_degraded is True
+        assert event.degraded_reason == "timeout"
+
+
+class TestSkillPolicyTelemetryEventToDict:
+    """SkillPolicyTelemetryEvent.to_dict() serialization."""
+
+    def test_optional_fields_omitted_when_none(self) -> None:
+        event = SkillPolicyTelemetryEvent()
+        d = event.to_dict()
+        assert "row_index" not in d
+        assert "check_id" not in d
+        assert "first_execution_at_call" not in d
+        assert "degraded_reason" not in d
+
+    def test_optional_fields_included_when_set(self) -> None:
+        event = SkillPolicyTelemetryEvent(
+            row_index=1,
+            check_id="CL-002",
+            first_execution_at_call=3,
+            degraded_reason="stale_cache",
+        )
+        d = event.to_dict()
+        assert d["row_index"] == 1
+        assert d["check_id"] == "CL-002"
+        assert d["first_execution_at_call"] == 3
+        assert d["degraded_reason"] == "stale_cache"

package/skills/vds-skill/vds-scripts/vds_agent_core/tests/unit/test_skill_rubric.py

@@ -0,0 +1,47 @@
+"""Tests for SkillManager.load_skill_rubric (FR-A2)."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from vds_agent_core.skills.manager import SkillManager
+
+
+class TestLoadSkillRubric:
+    """FR-A2: rubric-only skill loading via lru_cache."""
+
+    def test_load_existing_skill_md(self, tmp_path: Path) -> None:
+        """Existing SKILL.md returns its content."""
+        skill_dir = tmp_path / "my-skill"
+        skill_dir.mkdir()
+        skill_md = skill_dir / "SKILL.md"
+        skill_md.write_text("# My Skill\nRubric content here.", encoding="utf-8")
+
+        # Clear any prior cached state
+        SkillManager.load_skill_rubric.cache_clear()
+
+        result = SkillManager.load_skill_rubric("my-skill", tmp_path)
+        assert result == "# My Skill\nRubric content here."
+
+    def test_load_missing_skill_returns_empty(self, tmp_path: Path) -> None:
+        """Missing skill directory returns empty string, no exception."""
+        SkillManager.load_skill_rubric.cache_clear()
+
+        result = SkillManager.load_skill_rubric("nonexistent-skill", tmp_path)
+        assert result == ""
+
+    def test_caching_works(self, tmp_path: Path) -> None:
+        """Second call returns cached result (verify via cache_info)."""
+        skill_dir = tmp_path / "cached-skill"
+        skill_dir.mkdir()
+        skill_md = skill_dir / "SKILL.md"
+        skill_md.write_text("cached content", encoding="utf-8")
+
+        SkillManager.load_skill_rubric.cache_clear()
+
+        SkillManager.load_skill_rubric("cached-skill", tmp_path)
+        SkillManager.load_skill_rubric("cached-skill", tmp_path)
+
+        info = SkillManager.load_skill_rubric.cache_info()
+        assert info.hits >= 1
+        assert info.misses >= 1

package/skills/vds-skill/vds-scripts/vds_agent_core/tests/unit/test_tools.py

@@ -0,0 +1,51 @@
+"""Tests for vds_agent_core.agents.tools — ToolRegistry Protocol and ToolName alias."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+from vds_agent_core.agents.tools import ToolName, ToolRegistry
+
+
+class _FakeRegistry:
+    """Minimal concrete implementation satisfying ToolRegistry structurally."""
+
+    def __init__(self) -> None:
+        self._tools: dict[str, Callable[..., Any]] = {"echo": lambda x: x}
+
+    def get_tool(self, name: str) -> Callable[..., Any]:
+        return self._tools[name]
+
+    def list_tools(self) -> list[str]:
+        return list(self._tools)
+
+    def invoke(self, tool: str, payload: dict[str, Any]) -> Any:
+        from vds_agent_core.agents.tools import ToolResponseEnvelope
+
+        fn = self._tools[tool]
+        result = fn(**payload)
+        return ToolResponseEnvelope(tool=tool, payload={"result": result})
+
+
+class TestToolRegistry:
+    def test_structural_isinstance(self) -> None:
+        """A class with matching methods satisfies the runtime_checkable Protocol."""
+        registry = _FakeRegistry()
+        assert isinstance(registry, ToolRegistry)
+
+    def test_get_tool_returns_callable(self) -> None:
+        registry = _FakeRegistry()
+        tool = registry.get_tool("echo")
+        assert tool("hello") == "hello"
+
+    def test_list_tools_returns_names(self) -> None:
+        registry = _FakeRegistry()
+        assert registry.list_tools() == ["echo"]
+
+
+class TestToolName:
+    def test_tool_name_is_str(self) -> None:
+        """ToolName is a str alias — any str value is valid."""
+        name: ToolName = "my_tool"
+        assert isinstance(name, str)

package/skills/vds-skill/vds-scripts/vds_agent_core/tests/unit/test_workflow_protocols.py

@@ -0,0 +1,136 @@
+"""Unit tests for vds_agent_core.workflows Protocol contract."""
+
+from __future__ import annotations
+
+from vds_agent_core.workflows import WorkflowProvider
+
+
+class _GoodProvider:
+    """Minimal valid WorkflowProvider implementation."""
+
+    def register_workflow_alias(
+        self,
+        *,
+        alias: str,
+        workflow_fqn: str,
+        owner: str,
+    ) -> None:
+        pass
+
+    def register_schedule(
+        self,
+        *,
+        schedule_id: str,
+        workflow_alias: str,
+        cron: str,
+        owner: str,
+        queue_name: str = "agent-default",
+        context_json: dict[str, object] | None = None,
+    ) -> None:
+        pass
+
+
+class _MissingMethodProvider:
+    """Implementation missing register_schedule."""
+
+    def register_workflow_alias(
+        self,
+        *,
+        alias: str,
+        workflow_fqn: str,
+        owner: str,
+    ) -> None:
+        pass
+
+
+def test_runtime_checkable_accepts_valid_implementation() -> None:
+    assert isinstance(_GoodProvider(), WorkflowProvider)
+
+
+def test_runtime_checkable_rejects_missing_method() -> None:
+    assert not isinstance(_MissingMethodProvider(), WorkflowProvider)
+
+
+def test_protocol_methods_signature_documented() -> None:
+    method_names = {"register_workflow_alias", "register_schedule"}
+    assert method_names <= set(dir(WorkflowProvider))
+
+
+def test_provider_call_passes_args_through() -> None:
+    captured: dict[str, object] = {}
+
+    class CapturingProvider:
+        def register_workflow_alias(
+            self,
+            *,
+            alias: str,
+            workflow_fqn: str,
+            owner: str,
+        ) -> None:
+            captured["alias"] = alias
+            captured["fqn"] = workflow_fqn
+            captured["alias_owner"] = owner
+
+        def register_schedule(
+            self,
+            *,
+            schedule_id: str,
+            workflow_alias: str,
+            cron: str,
+            owner: str,
+            queue_name: str = "agent-default",
+            context_json: dict[str, object] | None = None,
+        ) -> None:
+            captured["schedule_id"] = schedule_id
+            captured["workflow_alias"] = workflow_alias
+            captured["cron"] = cron
+            captured["schedule_owner"] = owner
+            captured["queue_name"] = queue_name
+            captured["context_json"] = context_json
+
+    provider: WorkflowProvider = CapturingProvider()
+    provider.register_workflow_alias(
+        alias="audit.drift.weekly",
+        workflow_fqn="vds_audit_orchestrator.workflows.audit_drift_scan.audit_drift_scan",
+        owner="audit_orchestrator",
+    )
+    provider.register_schedule(
+        schedule_id="audit-drift-weekly",
+        workflow_alias="audit.drift.weekly",
+        cron="0 2 * * MON",
+        owner="audit_orchestrator",
+    )
+
+    assert captured["alias"] == "audit.drift.weekly"
+    assert captured["fqn"] == "vds_audit_orchestrator.workflows.audit_drift_scan.audit_drift_scan"
+    assert captured["alias_owner"] == "audit_orchestrator"
+    assert captured["schedule_id"] == "audit-drift-weekly"
+    assert captured["workflow_alias"] == "audit.drift.weekly"
+    assert captured["cron"] == "0 2 * * MON"
+    assert captured["schedule_owner"] == "audit_orchestrator"
+    assert captured["queue_name"] == "agent-default"
+    assert captured["context_json"] is None
+
+
+def test_register_schedule_accepts_context_json() -> None:
+    """context_json defaults to None and accepts a dict for workflow kwargs."""
+    captured: dict[str, object] = {}
+
+    class CtxCapturingProvider:
+        def register_workflow_alias(self, *, alias, workflow_fqn, owner) -> None:  # type: ignore[no-untyped-def]
+            pass
+
+        def register_schedule(
+            self, *, schedule_id, workflow_alias, cron, owner, queue_name="agent-default", context_json=None
+        ) -> None:  # type: ignore[no-untyped-def]
+            captured["context_json"] = context_json
+
+    provider: WorkflowProvider = CtxCapturingProvider()
+    provider.register_schedule(
+        schedule_id="audit-deep-monthly",
+        workflow_alias="audit.deep.monthly",
+        cron="0 3 1 * *",
+        owner="audit_orchestrator",
+        context_json={"project_storage_keys": ["p1", "p2"]},
+    )
+    assert captured["context_json"] == {"project_storage_keys": ["p1", "p2"]}