fix: make Radar helper invocation deterministic

Author: zxhwolfe

CHANGELOG.md

@@ -18,6 +18,7 @@ Release candidate prepared for validation. This version is not tagged or publish
 - Required successful `feed`/`sources`/`history` helper execution without an explicit custom origin and with contract-valid Radar JSON before Host Eval records runtime workflow evidence; source reads, help, failed calls, and composed shell commands no longer qualify.
 - Synced authenticated Premium identity forwarding guidance and preserved the published v0.2.1 release record below.
 - Made live Host Eval networking an explicit, single-domain, workspace-write opt-in executed only in a clean temporary detached worktree; release evidence now binds and verifies that network/sandbox policy.
+- Fixed portable Radar helper invocation to require `python3`, global options before the subcommand, and compact shortlist scans that default to 12 and normally cap at 24 candidates.
 
 ## [Unreleased]
 

references/topic-intelligence-quality-contract.md

@@ -44,6 +44,18 @@ After the first domain-preserving bounded query:
 
 For example, a title containing the letters `ai` only as part of an unrelated word must not become an AI finalist merely because `/feed?q=AI` returned it.
 
+### Use the portable helper deterministically
+
+Resolve `scripts/topic_radar_client.py` relative to the current Skill's `SKILL.md`; never hard-code an installation directory. `python3` is the only supported interpreter entry point. Do not use `python`, `python2`, or execute the helper directly without an interpreter.
+
+Place helper-wide arguments before the subcommand. The canonical shortlist form is:
+
+```text
+python3 <skill-local-helper> --timeout 30 feed --q AI --limit 12
+```
+
+For a normal shortlist or topic-selection task, the initial candidate set defaults to 12 and should not exceed 24. Do not fetch 100 candidates merely to select three topics. Exceed 24 only when the user explicitly asks for a large list, export, or larger sample.
+
 ## 2. Public Skill cost boundary: no AI Workstation model spend
 
 The downloadable/public Topic Intelligence Skills are intended to spread widely without consuming the publisher's server-side LLM quota for anonymous users.

scripts/grade_host_eval.py

@@ -123,7 +123,7 @@ def _runtime_invocation(command: str, skill: str) -> str | None:
         return None
     marker = f"/{skill}/scripts/topic_radar_client.py"
     executable = tokens[0].replace("\\", "/").rsplit("/", 1)[-1]
-    if executable not in {"python", "python3"}:
+    if executable != "python3":
         return None
     helper = tokens[1].replace("\\", "/") if len(tokens) > 1 else ""
     if not helper.endswith(marker):
@@ -426,7 +426,7 @@ def grade_report(payload: Mapping[str, Any]) -> dict[str, Any]:
         "cases": graded_cases,
         "grading_note": (
             "passive Skill names/file reads are discovery evidence, not invocation; "
-            "runtime use requires a successful Python invocation of a Skill-local helper "
+            "runtime use requires a successful python3 invocation of a Skill-local helper "
             "feed/sources/history operation plus validated JSON output, and handoff use "
             "requires the schema in an agent message"
         ),

skills/creator-topic-opportunity-research/SKILL.md

@@ -60,6 +60,16 @@ Resolve the bundled helper relative to this `SKILL.md`:
 scripts/topic_radar_client.py
 ```
 
+Invoke that Skill-local helper only with `python3`. Do not use `python`, `python2`, or execute the helper directly without an interpreter. Place helper-wide arguments such as `--timeout` before the `feed`, `sources`, or `history` subcommand. Resolve the helper relative to this `SKILL.md`; do not hard-code an installation directory.
+
+Use this canonical shortlist form:
+
+```text
+python3 <skill-local-helper> --timeout 30 feed --q AI --limit 12
+```
+
+For a normal shortlist or topic-selection task, prefer an initial `feed --limit 12` and do not exceed 24 candidates. Exceed 24 only when the user explicitly asks for a large list, export, or larger sample.
+
 Do not assume a repository-root helper, sibling checkout, or `../akaiagents` exists. The helper is read-only transport only: no crawler, score, persistence, topic matching, model backend, Premium Insight, or credential storage.
 
 ### Live evidence is exclusive

skills/creator-topic-opportunity-research/references/quality-contract.md

@@ -44,6 +44,18 @@ After the first domain-preserving bounded query:
 
 For example, a title containing the letters `ai` only as part of an unrelated word must not become an AI finalist merely because `/feed?q=AI` returned it.
 
+### Use the portable helper deterministically
+
+Resolve `scripts/topic_radar_client.py` relative to the current Skill's `SKILL.md`; never hard-code an installation directory. `python3` is the only supported interpreter entry point. Do not use `python`, `python2`, or execute the helper directly without an interpreter.
+
+Place helper-wide arguments before the subcommand. The canonical shortlist form is:
+
+```text
+python3 <skill-local-helper> --timeout 30 feed --q AI --limit 12
+```
+
+For a normal shortlist or topic-selection task, the initial candidate set defaults to 12 and should not exceed 24. Do not fetch 100 candidates merely to select three topics. Exceed 24 only when the user explicitly asks for a large list, export, or larger sample.
+
 ## 2. Public Skill cost boundary: no AI Workstation model spend
 
 The downloadable/public Topic Intelligence Skills are intended to spread widely without consuming the publisher's server-side LLM quota for anonymous users.

skills/evidence-backed-content-brief/SKILL.md

@@ -58,6 +58,16 @@ Resolve the bundled public helper relative to this `SKILL.md`:
 scripts/topic_radar_client.py
 ```
 
+Invoke that Skill-local helper only with `python3`. Do not use `python`, `python2`, or execute the helper directly without an interpreter. Place helper-wide arguments such as `--timeout` before the `feed`, `sources`, or `history` subcommand. Resolve the helper relative to this `SKILL.md`; do not hard-code an installation directory.
+
+Use this canonical shortlist form:
+
+```text
+python3 <skill-local-helper> --timeout 30 feed --q AI --limit 12
+```
+
+For a normal shortlist or topic-selection task, prefer an initial `feed --limit 12` and do not exceed 24 candidates. Exceed 24 only when the user explicitly asks for a large list, export, or larger sample.
+
 Do not assume a repository-root helper, sibling checkout, or `../akaiagents` exists. A native host connection may call the same public no-cost contract directly.
 
 The helper is transport-only: no crawler, score, persistence, topic matching, model backend, or Premium Insight is implemented inside the Skill.

skills/evidence-backed-content-brief/references/quality-contract.md

@@ -44,6 +44,18 @@ After the first domain-preserving bounded query:
 
 For example, a title containing the letters `ai` only as part of an unrelated word must not become an AI finalist merely because `/feed?q=AI` returned it.
 
+### Use the portable helper deterministically
+
+Resolve `scripts/topic_radar_client.py` relative to the current Skill's `SKILL.md`; never hard-code an installation directory. `python3` is the only supported interpreter entry point. Do not use `python`, `python2`, or execute the helper directly without an interpreter.
+
+Place helper-wide arguments before the subcommand. The canonical shortlist form is:
+
+```text
+python3 <skill-local-helper> --timeout 30 feed --q AI --limit 12
+```
+
+For a normal shortlist or topic-selection task, the initial candidate set defaults to 12 and should not exceed 24. Do not fetch 100 candidates merely to select three topics. Exceed 24 only when the user explicitly asks for a large list, export, or larger sample.
+
 ## 2. Public Skill cost boundary: no AI Workstation model spend
 
 The downloadable/public Topic Intelligence Skills are intended to spread widely without consuming the publisher's server-side LLM quota for anonymous users.

tests/test_host_eval_evidence.py

@@ -58,6 +58,16 @@ def _helper_event(
     })
 
 
+def _helper_command_event(command: str) -> str:
+    return _event({
+        "type": "command_execution",
+        "command": command,
+        "aggregated_output": _feed_payload(),
+        "exit_code": 0,
+        "status": "completed",
+    })
+
+
 def _trigger_case(expected_skill: str | None) -> dict[str, object]:
     return {
         "id": "case",
@@ -115,6 +125,22 @@ def test_runtime_helper_command_is_strong_use_evidence(self) -> None:
             "pass_expected_skill_runtime_observed",
         )
 
+    def test_only_python3_is_runtime_evidence(self) -> None:
+        helper = f"/skills/{CREATOR}/scripts/topic_radar_client.py"
+        valid = observe_evidence(_helper_command_event(
+            f"python3 {helper} --timeout 30 feed --q AI --limit 12"
+        ))
+        self.assertEqual(valid["runtime_operations"], [f"{CREATOR}:feed"])
+
+        for command in (
+            f"python {helper} --timeout 30 feed --q AI --limit 12",
+            f"python2 {helper} --timeout 30 feed --q AI --limit 12",
+            f"{helper} --timeout 30 feed --q AI --limit 12",
+        ):
+            with self.subTest(command=command):
+                evidence = observe_evidence(_helper_command_event(command))
+                self.assertEqual(evidence["runtime_use_skills"], [])
+
     def test_wrong_runtime_helper_is_a_real_negative_signal(self) -> None:
         stdout = _helper_event(BRIEF, arguments=" --limit 3")
         evidence = observe_evidence(stdout)

tests/test_skill_quality_contract.py

@@ -59,6 +59,25 @@ def test_quality_contract_blocks_duplicate_selection_after_handoff(self) -> None
         self.assertIn("do **not** run another broad/bounded candidate-selection feed pass", content)
         self.assertIn("finalist `/history` request is normal", content)
 
+    def test_portable_helper_invocation_is_deterministic(self) -> None:
+        canonical = CANONICAL.read_text(encoding="utf-8")
+        self.assertIn("`python3` is the only supported interpreter entry point", canonical)
+        self.assertIn("Do not use `python`, `python2`", canonical)
+        self.assertIn("helper-wide arguments before the subcommand", canonical)
+        self.assertIn("--timeout 30 feed --q AI --limit 12", canonical)
+        self.assertIn("defaults to 12", canonical)
+        self.assertIn("should not exceed 24", canonical)
+        self.assertIn("Do not fetch 100 candidates", canonical)
+
+        for skill in (CREATOR, BRIEF):
+            content = (skill / "SKILL.md").read_text(encoding="utf-8")
+            self.assertIn("only with `python3`", content)
+            self.assertIn("Do not use `python`, `python2`", content)
+            self.assertIn("helper-wide arguments", content)
+            self.assertIn("--timeout 30 feed --q AI --limit 12", content)
+            self.assertIn("initial `feed --limit 12`", content)
+            self.assertIn("do not exceed 24 candidates", content)
+
     def test_skill_definitions_and_openai_metadata_point_to_quality_contract(self) -> None:
         creator_skill = (CREATOR / "SKILL.md").read_text(encoding="utf-8")
         brief_skill = (BRIEF / "SKILL.md").read_text(encoding="utf-8")