@laitszkin/apollo-toolkit 2.14.23 → 3.0.1

package/AGENTS.md

@@ -21,6 +21,7 @@ This repository enables users to install and run a curated set of reusable agent
 - Users can research the latest completed market week and produce a PDF watchlist of tradeable instruments for the coming week.
 - Users can turn a marked weekly finance PDF into a concise evidence-based financial event report.
 - Users can install Apollo Toolkit through npm or npx and interactively choose one or more target skill directories to populate with copied skills.
+- Users can run bundled helper tools through `apltk tools` and direct `apltk <tool>` commands for selected packaged skill scripts.
 - Users can design and implement new features through a spec-first workflow.
 - Users can generate shared feature planning artifacts for approval-gated workflows, including parallel multi-spec batches coordinated through one batch-level `coordination.md`.
 - Users can convert text or documents into audio files with subtitle timelines.
@@ -64,6 +65,8 @@ This repository enables users to install and run a curated set of reusable agent
 - `npm test` - 執行 Node 測試套件。
 - `node bin/apollo-toolkit.js` - 直接從倉庫啟動 Apollo Toolkit CLI。
 - `node bin/apollo-toolkit.js codex openclaw trae` - 以非互動方式將技能安裝到指定目標。
+- `node bin/apollo-toolkit.js tools` - 列出 Apollo Toolkit 內建 CLI 工具。
+- `node bin/apollo-toolkit.js filter-logs app.log --start 2026-03-24T10:00:00Z` - 透過內建工具包裝器執行技能腳本。
 - `python3 scripts/validate_skill_frontmatter.py` - 驗證所有頂層技能 `SKILL.md` 的 frontmatter。
 - `python3 scripts/validate_openai_agent_config.py` - 驗證所有技能 `agents/openai.yaml` 設定。
 - `./scripts/install_skills.sh codex` - 用本地安裝腳本把技能安裝到 Codex 目錄。

package/CHANGELOG.md

@@ -7,6 +7,23 @@ All notable changes to this repository are documented in this file.
 ### Changed
 - None yet.
 
+## [v3.0.1] - 2026-04-19
+
+### Changed
+- Strengthen `jupiter-development` so Jupiter program registries are treated as discovery and observability inputs rather than automatic signing allowlists, preserving fail-closed local transaction grammar for wallet flows.
+- Strengthen `scheduled-runtime-health-check` and `systematic-debug` so bounded runtime follow-ups compare only complete like-for-like run artifacts, derive missing-business-event causes from structured funnels, and report per-stage latency instead of vague wall-clock duration.
+
+## [v3.0.0] - 2026-04-18
+
+### Changed
+- Add bundled `apltk` tool dispatch so packaged skill scripts can be listed with `apltk tools` and executed directly through `apltk <tool> ...`.
+- Update skill and repository docs to prefer bundled `apltk` tool commands over direct script paths for log filtering, spec generation, KaTeX rendering, audio generation, error-book rendering, GitHub issue publishing, and related helpers.
+- Harden `open-github-issue` with `--payload-file` and `@file` support so Markdown-rich fields containing backticks or shell metacharacters survive CLI invocation without shell corruption.
+- Skip Python tests that require optional media/PDF modules when those dependencies are unavailable so release CI stays aligned with the repository's optional tooling contract.
+
+### Added
+- Add `lib/tool-runner.js` plus Node and Python regression tests that cover bundled tool discovery, CLI dispatch, safe wrapper behavior, and new helper entrypoints.
+
 ## [v2.14.23] - 2026-04-18
 
 ### Changed

package/README.md

@@ -77,6 +77,15 @@ apollo-toolkit
 
 Global install 後，`apltk` 與 `apollo-toolkit` 都會啟動同一個 Apollo Toolkit CLI。直接執行 `apltk` 會打開互動安裝頁，並在互動模式下先檢查 npm registry 是否有新版可用；若有，CLI 會先詢問，再自動執行全域更新。
 
+除了安裝模式之外，`apltk` 也會把技能內常用腳本暴露成簡單 CLI 工具，例如：
+
+```bash
+apltk tools
+apltk filter-logs app.log --start "2026-03-24T10:00:00Z"
+apltk create-specs "Membership upgrade flow" --change-name membership-upgrade-flow
+apltk open-github-issue --help
+```
+
 ### Non-interactive install
 
 ```bash

package/analyse-app-logs/README.md

@@ -21,8 +21,8 @@ This skill helps agents analyze logs end-to-end, correlate runtime signals with
 - `agents/openai.yaml`: Agent interface metadata and default prompt.
 - `references/investigation-checklist.md`: Investigation validation checklist.
 - `references/log-signal-patterns.md`: Log signal pattern reference.
-- `scripts/filter_logs_by_time.py`: Time-window log filtering helper.
-- `scripts/search_logs.py`: Keyword / regex search helper with optional context.
+- `scripts/filter_logs_by_time.py`: Time-window log filtering helper, exposed as `apltk filter-logs`.
+- `scripts/search_logs.py`: Keyword / regex search helper with optional context, exposed as `apltk search-logs`.
 - `scripts/log_cli_utils.py`: Shared timestamp parsing utilities.
 - Dependency skill: `open-github-issue` for deterministic issue publishing.
 
@@ -72,9 +72,9 @@ When the time window is not explicitly provided, the skill should first derive a
 Useful bundled commands:
 
 ```bash
-python3 scripts/filter_logs_by_time.py app.log --start "2026-03-24T10:00:00Z" --end "2026-03-24T10:30:00Z"
-python3 scripts/search_logs.py app.log --keyword timeout --keyword payment --mode all --after-context 3
-python3 scripts/search_logs.py app.log --regex "request_id=ab12.*ERROR" --start "2026-03-24T10:00:00Z" --end "2026-03-24T10:15:00Z"
+apltk filter-logs app.log --start "2026-03-24T10:00:00Z" --end "2026-03-24T10:30:00Z"
+apltk search-logs app.log --keyword timeout --keyword payment --mode all --after-context 3
+apltk search-logs app.log --regex "request_id=ab12.*ERROR" --start "2026-03-24T10:00:00Z" --end "2026-03-24T10:15:00Z"
 ```
 
 ## Example

package/analyse-app-logs/SKILL.md

@@ -15,7 +15,7 @@ description: Comprehensive application log investigation workflow that reads log
 ## Standards
 
 - Evidence: Use a bounded investigation window and correlate log lines with code, runtime context, and concrete identifiers.
-- Execution: Scope the incident, use the bundled scripts to cut logs down by time window or search terms, build a timeline, validate candidate issues, then prioritize and optionally publish them.
+- Execution: Scope the incident, use the bundled CLI tools to cut logs down by time window or search terms, build a timeline, validate candidate issues, then prioritize and optionally publish them.
 - Quality: Separate confirmed issues from hypotheses and include time-window, log, code, impact, and confidence evidence for each report.
 - Output: Return incident summary, confirmed issues, hypotheses, monitoring improvements, and publication status.
 
@@ -38,11 +38,11 @@ Use this skill to analyze application logs systematically with the codebase and
    - If the user does not provide a trustworthy window, derive one from a concrete runtime boundary first, such as the last container restart, pod recreation, deploy start, worker boot, or first failure after a known healthy state.
    - Prefer analyzing logs only inside that bounded window first (for example, from the last restart until now) to avoid stale logs polluting the diagnosis; widen the window only when the bounded slice cannot explain the symptom.
    - Identify relevant identifiers (trace ID, request ID, user ID, job ID, tx hash).
-   - Use `scripts/filter_logs_by_time.py` first when the raw log set is large and the incident window can be bounded.
+   - Use `apltk filter-logs` first when the raw log set is large and the incident window can be bounded.
 2. Build a timeline from logs
    - Extract key events in chronological order within the chosen window: deploys, config changes, warnings, errors, retries, and recoveries.
    - Group repeated symptoms by signature (error type, message prefix, stack frame, endpoint).
-   - Use `scripts/search_logs.py` to narrow by error signature, IDs, endpoint names, or repeated keywords before summarizing the timeline.
+   - Use `apltk search-logs` to narrow by error signature, IDs, endpoint names, or repeated keywords before summarizing the timeline.
 3. Correlate across context
    - Link related log lines using identifiers and timestamps.
    - Map stack traces and log messages to exact code locations.
@@ -83,6 +83,8 @@ Pass these fields to the dependency skill:
 - `reproduction`: steps/conditions if known; otherwise leave empty
 - `repo`: target repository in `owner/repo` format when known
 
+If invoking the publisher CLI directly, pass these fields through `apltk open-github-issue --payload-file <json>` or `@file` inputs rather than inline shell arguments, because log evidence can contain backticks or shell metacharacters.
+
 Issue body sections must always include these three parts:
 
 - Chinese-language repositories: use localized equivalents of
@@ -120,7 +122,7 @@ Use this structure in responses:
 
 - `references/investigation-checklist.md`: Step-by-step checklist for evidence-driven log investigations.
 - `references/log-signal-patterns.md`: Common log signatures, likely causes, validation hints, and false-positive guards.
-- `scripts/filter_logs_by_time.py`: Filter raw logs to a bounded incident window from files or stdin.
-- `scripts/search_logs.py`: Search logs by keyword or regex with optional time-window filtering and context lines.
+- `scripts/filter_logs_by_time.py`: Filter raw logs to a bounded incident window from files or stdin; exposed as `apltk filter-logs`.
+- `scripts/search_logs.py`: Search logs by keyword or regex with optional time-window filtering and context lines; exposed as `apltk search-logs`.
 - `scripts/log_cli_utils.py`: Shared timestamp parsing and stdin/file iteration utilities for the bundled log scripts.
 - Dependency skill: `open-github-issue` for deterministic issue publishing with auth fallback and README language detection.

package/codex/codex-memory-manager/README.md

@@ -45,13 +45,13 @@ Persist durable user preferences from recent Codex conversations into reusable,
 Extract the recent conversations:
 
 ```bash
-python3 scripts/extract_recent_conversations.py --lookback-minutes 1440
+apltk extract-codex-conversations --lookback-minutes 1440
 ```
 
 Refresh the AGENTS memory index after updating the memory files:
 
 ```bash
-python3 scripts/sync_memory_index.py --agents-file ~/.codex/AGENTS.md --memory-dir ~/.codex/memory
+apltk sync-codex-memory-index --agents-file ~/.codex/AGENTS.md --memory-dir ~/.codex/memory
 ```
 
 Use the bundled memory template when creating or refactoring category files:

package/codex/codex-memory-manager/SKILL.md

@@ -25,8 +25,8 @@ Keep a durable, categorized memory of user preferences so future agents can quic
 
 ## Required Resources
 
-- `scripts/extract_recent_conversations.py` to read the last 24 hours of Codex sessions, including archived sessions.
-- `scripts/sync_memory_index.py` to maintain a normalized memory index section at the end of `~/.codex/AGENTS.md`.
+- `scripts/extract_recent_conversations.py` to read the last 24 hours of Codex sessions, including archived sessions, exposed as `apltk extract-codex-conversations`.
+- `scripts/sync_memory_index.py` to maintain a normalized memory index section at the end of `~/.codex/AGENTS.md`, exposed as `apltk sync-codex-memory-index`.
 
 ## Workflow
 
@@ -35,7 +35,7 @@ Keep a durable, categorized memory of user preferences so future agents can quic
 - Run:
 
 ```bash
-python3 ~/.codex/skills/codex-memory-manager/scripts/extract_recent_conversations.py --lookback-minutes 1440
+apltk extract-codex-conversations --lookback-minutes 1440
 ```
 
 - The extractor reads both `~/.codex/sessions` and `~/.codex/archived_sessions`.
@@ -97,14 +97,14 @@ User preferences about how engineering tasks should be investigated, planned, im
 ### 4) Refresh the AGENTS memory index at the end of `~/.codex/AGENTS.md`
 
 - First inspect `~/.codex/AGENTS.md` and mirror its existing language in the memory section instructions.
-- After updating memory files, run `scripts/sync_memory_index.py` to rewrite the managed section at the end of the file.
+- After updating memory files, run `apltk sync-codex-memory-index` to rewrite the managed section at the end of the file.
 - The section must do both of these things explicitly:
   - instruct future agents to review the index before starting work
   - instruct future agents to update the matching memory files and refresh the index when a new category appears
 - Example command in English AGENTS files:
 
 ```bash
-python3 ~/.codex/skills/codex-memory-manager/scripts/sync_memory_index.py \
+apltk sync-codex-memory-index \
   --agents-file ~/.codex/AGENTS.md \
   --memory-dir ~/.codex/memory \
   --section-title "## User Memory Index" \

package/codex/codex-memory-manager/tests/test_extract_recent_conversations.py

@@ -43,14 +43,15 @@ def run_extractor(
     archived_dir: Path | None = None,
     *extra_args: str,
 ) -> str:
+    effective_archived_dir = archived_dir or (sessions_dir.parent / "__isolated_archived_sessions__")
     cmd = [
         sys.executable,
         str(SCRIPT_PATH),
         "--sessions-dir",
         str(sessions_dir),
+        "--archived-sessions-dir",
+        str(effective_archived_dir),
     ]
-    if archived_dir is not None:
-        cmd.extend(["--archived-sessions-dir", str(archived_dir)])
     cmd.extend(extra_args)
     result = subprocess.run(cmd, capture_output=True, text=True, check=True)
     return result.stdout

package/codex/learn-skill-from-conversations/README.md

@@ -41,7 +41,7 @@ This skill extracts the latest conversations from `~/.codex/sessions` and `~/.co
 Run the extractor:
 
 ```bash
-python3 scripts/extract_recent_conversations.py --lookback-minutes 1440
+apltk extract-skill-conversations --lookback-minutes 1440
 ```
 
 - If output is `NO_RECENT_CONVERSATIONS`, no action is required.

package/codex/learn-skill-from-conversations/SKILL.md

@@ -25,7 +25,7 @@ Extract recent conversations, identify reusable lessons, and convert those lesso
 
 ## Required Resources
 
-- `scripts/extract_recent_conversations.py` for deterministic session extraction.
+- `scripts/extract_recent_conversations.py` for deterministic session extraction, exposed as `apltk extract-skill-conversations`.
 - `$skill-creator` for all skill creation/update work.
 
 ## Workflow
@@ -35,7 +35,7 @@ Extract recent conversations, identify reusable lessons, and convert those lesso
 - Run:
 
 ```bash
-python3 ~/.codex/skills/learn-skill-from-conversations/scripts/extract_recent_conversations.py --lookback-minutes 1440
+apltk extract-skill-conversations --lookback-minutes 1440
 ```
 
 - If output is exactly `NO_RECENT_CONVERSATIONS`, stop immediately and report that no action is required.

package/codex/learn-skill-from-conversations/tests/test_extract_recent_conversations.py

@@ -43,14 +43,15 @@ def run_extractor(
     archived_dir: Path | None = None,
     *extra_args: str,
 ) -> str:
+    effective_archived_dir = archived_dir or (sessions_dir.parent / "__isolated_archived_sessions__")
     cmd = [
         sys.executable,
         str(SCRIPT_PATH),
         "--sessions-dir",
         str(sessions_dir),
+        "--archived-sessions-dir",
+        str(effective_archived_dir),
     ]
-    if archived_dir is not None:
-        cmd.extend(["--archived-sessions-dir", str(archived_dir)])
     cmd.extend(extra_args)
     result = subprocess.run(cmd, capture_output=True, text=True, check=True)
     return result.stdout

package/docs-to-voice/README.md

@@ -39,7 +39,7 @@ Two modes are supported:
 ### 1) say mode
 
 ```bash
-python3 scripts/docs_to_voice.py \
+apltk docs-to-voice \
   --project-dir "/path/to/project" \
   --mode say \
   --text "Hello, this is a voice synthesis test."
@@ -48,13 +48,13 @@ python3 scripts/docs_to_voice.py \
 ### 2) api mode (Model Studio)
 
 ```bash
-python3 scripts/docs_to_voice.py \
+apltk docs-to-voice \
   --project-dir "/path/to/project" \
   --mode api \
   --text "Hello, this is a qwen3-tts test."
 ```
 
-> Compatibility note: `scripts/docs_to_voice.sh` still works and internally delegates to the Python script.
+> Compatibility note: `scripts/docs_to_voice.sh` still works, while `apltk docs-to-voice` is the preferred entrypoint.
 
 ## `.env` settings
 

package/docs-to-voice/SKILL.md

@@ -15,13 +15,13 @@ description: Convert text and document content into audio files and sentence-lev
 ## Standards
 
 - Evidence: Confirm `project_dir`, input source, mode, and environment-backed settings before generation.
-- Execution: Use `scripts/docs_to_voice.py` to write audio plus matching timeline and subtitle files under `project_dir/audio/{project_name}/`.
+- Execution: Use `apltk docs-to-voice` to write audio plus matching timeline and subtitle files under `project_dir/audio/{project_name}/`.
 - Quality: Respect mode-specific options, sentence splitting rules, and post-process requirements such as `ffmpeg` for speed changes.
 - Output: Return the absolute output audio path together with the generated `.timeline.json` and `.srt` companions.
 
 ## Overview
 
-Use `scripts/docs_to_voice.py` to convert raw text or text files into audio and always save under:
+Use `apltk docs-to-voice` to convert raw text or text files into audio and always save under:
 
 `project_dir/audio/{project_name}/`
 
@@ -69,7 +69,7 @@ Modes:
 
 ## Script Reference
 
-`scripts/docs_to_voice.py` flags:
+`apltk docs-to-voice` flags:
 
 - `--project-dir` (required)
 - `--project-name` (optional)
@@ -104,4 +104,4 @@ Environment variables:
 - `api` mode: confirm `command -v python3` and valid `DASHSCOPE_API_KEY`.
 - Long-text chunk merge (especially AIFF output): recommend `command -v ffmpeg`.
 - If output exists, use `--force` or a new `--output-name`.
-- `scripts/docs_to_voice.sh` is kept as a compatibility wrapper for existing workflows.
+- `scripts/docs_to_voice.sh` is kept as a compatibility wrapper for existing workflows, but prefer `apltk docs-to-voice`.

package/docs-to-voice/tests/test_docs_to_voice_shell_wrapper.py

@@ -0,0 +1,51 @@
+#!/usr/bin/env python3
+
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+
+
+SCRIPT_PATH = Path(__file__).resolve().parents[1] / "scripts" / "docs_to_voice.py"
+SHELL_SCRIPT_PATH = Path(__file__).resolve().parents[1] / "scripts" / "docs_to_voice.sh"
+
+
+class DocsToVoiceShellWrapperTests(unittest.TestCase):
+    def test_shell_wrapper_execs_python_script_with_same_arguments(self) -> None:
+        with tempfile.TemporaryDirectory() as temp_dir:
+            capture_path = Path(temp_dir) / "argv.json"
+            fake_python = Path(temp_dir) / "python3"
+            fake_python.write_text(
+                f"#!{sys.executable}\n"
+                "import json, os, sys\n"
+                "with open(os.environ['CAPTURE_PATH'], 'w', encoding='utf-8') as handle:\n"
+                "    json.dump(sys.argv[1:], handle)\n",
+                encoding="utf-8",
+            )
+            fake_python.chmod(0o755)
+
+            env = dict(os.environ)
+            env["PATH"] = f"{temp_dir}:{env['PATH']}"
+            env["CAPTURE_PATH"] = str(capture_path)
+
+            result = subprocess.run(
+                ["bash", str(SHELL_SCRIPT_PATH), "--input", "notes.md", "--project-dir", "/tmp/project"],
+                capture_output=True,
+                text=True,
+                env=env,
+                check=False,
+            )
+
+            self.assertEqual(result.returncode, 0, result.stderr)
+            argv = json.loads(capture_path.read_text(encoding="utf-8"))
+            self.assertEqual(argv[0], str(SCRIPT_PATH))
+            self.assertEqual(argv[1:], ["--input", "notes.md", "--project-dir", "/tmp/project"])
+
+
+if __name__ == "__main__":
+    unittest.main()

package/feature-propose/SKILL.md

@@ -92,6 +92,7 @@ Load these references as needed during classification:
   - `reason`: why this feature should exist now
   - `suggested-architecture`: minimal architecture and module plan
   - `repo`: target repository in `owner/repo` format when known
+- If invoking the publisher CLI directly, pass accepted proposal details through `apltk open-github-issue --payload-file <json>` or `@file` inputs rather than inline shell arguments so Markdown and code identifiers remain literal.
 - Reuse the returned `mode`, `issue_url`, and `publish_error` in the response.
 - After the related feature is implemented, remove that feature entry from `## Accepted Feature Proposals` in `AGENTS.md`.
 - Remove only implemented items; keep unimplemented accepted items untouched.

package/generate-spec/README.md

@@ -36,11 +36,9 @@ A shared planning skill for feature work. It centralizes creation and maintenanc
 ## Quick start
 
 ```bash
-SKILL_ROOT=/path/to/generate-spec
 WORKSPACE_ROOT=/path/to/target-project
-python3 "$SKILL_ROOT/scripts/create-specs" "Membership upgrade flow" \
+apltk create-specs "Membership upgrade flow" \
   --change-name membership-upgrade-flow \
-  --template-dir "$SKILL_ROOT/references/templates" \
   --output-dir "$WORKSPACE_ROOT/docs/plans"
 ```
 
@@ -58,11 +56,10 @@ docs/plans/<today>/membership-upgrade-flow/
 Parallel batch output:
 
 ```bash
-python3 "$SKILL_ROOT/scripts/create-specs" "Membership write path" \
+apltk create-specs "Membership write path" \
   --change-name membership-write-path \
   --batch-name membership-cutover \
   --with-coordination \
-  --template-dir "$SKILL_ROOT/references/templates" \
   --output-dir "$WORKSPACE_ROOT/docs/plans"
 ```
 
@@ -89,6 +86,6 @@ docs/plans/<today>/membership-cutover/
 
 ## Notes
 
-- `scripts/...` and `references/...` are skill-folder paths, not project-folder paths.
+- `scripts/...` and `references/...` remain skill-folder paths when you need the raw assets, but `apltk create-specs` is the preferred command surface.
 - The generator replaces `[YYYY-MM-DD]`, `[Feature Name]`, `[功能名稱]`, `[change_name]`, and `[batch_name]` placeholders.
 - If a batch split produces specs that must land in a functional sequence, or still leaves unresolved shared-file collisions, re-slice the work so each spec becomes independently implementable, testable, mergeable, and parallel-safe before coding starts.

package/generate-spec/SKILL.md

@@ -50,9 +50,8 @@ Own the shared planning-doc lifecycle for feature work so other skills can reuse
 - Treat any unresolved shared-file collision, overlapping ownership, or incompatible contract change across spec sets as a planning bug to resolve before approval, not an implementation-time surprise.
 - If two candidate spec sets would still need to edit the same non-additive surface, either merge them into one spec set or record a concrete ownership split plus additive-only rule that makes parallel work safe.
 - Use:
-  - `SKILL_ROOT=<path_to_generate-spec_skill>`
   - `WORKSPACE_ROOT=<target_project_root>`
-  - `python3 "$SKILL_ROOT/scripts/create-specs" "<feature_name>" --change-name <kebab-case> --template-dir "$SKILL_ROOT/references/templates" --output-dir "$WORKSPACE_ROOT/docs/plans"`
+  - `apltk create-specs "<feature_name>" --change-name <kebab-case> --output-dir "$WORKSPACE_ROOT/docs/plans"`
 - For parallel multi-spec generation, also use:
   - `--batch-name <kebab-case-batch-name>`
   - `--with-coordination`
@@ -170,7 +169,7 @@ Own the shared planning-doc lifecycle for feature work so other skills can reuse
 
 ## References
 
-- `scripts/create-specs`: shared planning file generator.
+- `scripts/create-specs`: shared planning file generator, exposed as `apltk create-specs`.
 - `references/templates/spec.md`: BDD requirement template.
 - `references/templates/tasks.md`: task breakdown template.
 - `references/templates/checklist.md`: behavior-to-test alignment template.

package/generate-spec/tests/test_create_specs.py

@@ -0,0 +1,166 @@
+#!/usr/bin/env python3
+
+from __future__ import annotations
+
+import importlib.machinery
+import importlib.util
+import io
+import random
+import re
+import string
+import sys
+import tempfile
+import unittest
+from datetime import date
+from pathlib import Path
+from unittest.mock import patch
+
+
+SCRIPT_PATH = Path(__file__).resolve().parents[1] / "scripts" / "create-specs"
+LOADER = importlib.machinery.SourceFileLoader("create_specs", str(SCRIPT_PATH))
+SPEC = importlib.util.spec_from_loader("create_specs", LOADER)
+MODULE = importlib.util.module_from_spec(SPEC)
+SPEC.loader.exec_module(MODULE)
+
+
+class FixedDate(date):
+    @classmethod
+    def today(cls) -> "FixedDate":
+        return cls(2026, 4, 18)
+
+
+class CreateSpecsTests(unittest.TestCase):
+    def test_slugify_property_keeps_safe_slug_shape(self) -> None:
+        alphabet = string.ascii_letters + string.digits + string.punctuation + " \t中文"
+        generator = random.Random(20260418)
+
+        for _ in range(250):
+            raw = "".join(generator.choice(alphabet) for _ in range(generator.randint(0, 40)))
+            slug = MODULE._slugify(raw)
+            with self.subTest(raw=raw, slug=slug):
+                self.assertEqual(slug, slug.lower())
+                self.assertNotIn("--", slug)
+                self.assertFalse(slug.startswith("-"))
+                self.assertFalse(slug.endswith("-"))
+                self.assertRegex(slug, r"^[a-z0-9-]*$")
+
+    def test_render_replaces_all_placeholders(self) -> None:
+        rendered = MODULE._render(
+            content=(
+                "[YYYY-MM-DD]\n"
+                "[Feature Name]\n"
+                "[功能名稱]\n"
+                "[change_name]\n"
+                "[batch_name]\n"
+            ),
+            today="2026-04-18",
+            feature_name="Batch-safe planner",
+            change_name="batch-safe-planner",
+            batch_name="parallel-batch",
+        )
+
+        self.assertIn("2026-04-18", rendered)
+        self.assertEqual(rendered.count("Batch-safe planner"), 2)
+        self.assertIn("batch-safe-planner", rendered)
+        self.assertIn("parallel-batch", rendered)
+
+    def test_main_creates_spec_files_and_coordination_file(self) -> None:
+        with tempfile.TemporaryDirectory() as temp_dir:
+            root = Path(temp_dir)
+            template_dir = root / "templates"
+            output_dir = root / "docs" / "plans"
+            template_dir.mkdir(parents=True)
+
+            for name in MODULE.TEMPLATE_FILENAMES:
+                (template_dir / name).write_text(
+                    f"{name} [YYYY-MM-DD] [Feature Name] [change_name] [batch_name]\n",
+                    encoding="utf-8",
+                )
+            (template_dir / MODULE.COORDINATION_TEMPLATE).write_text(
+                "coordination [YYYY-MM-DD] [Feature Name] [change_name] [batch_name]\n",
+                encoding="utf-8",
+            )
+
+            argv = [
+                "create-specs",
+                "My Feature",
+                "--batch-name",
+                "parallel-batch",
+                "--with-coordination",
+                "--output-dir",
+                str(output_dir),
+                "--template-dir",
+                str(template_dir),
+            ]
+
+            with patch.object(MODULE, "date", FixedDate), patch.object(sys, "argv", argv), patch(
+                "sys.stdout", new_callable=io.StringIO
+            ) as stdout:
+                exit_code = MODULE.main()
+
+            self.assertEqual(exit_code, 0)
+            change_root = output_dir / "2026-04-18" / "parallel-batch" / "my-feature"
+            for name in MODULE.TEMPLATE_FILENAMES:
+                content = (change_root / name).read_text(encoding="utf-8")
+                self.assertIn("2026-04-18", content)
+                self.assertIn("My Feature", content)
+                self.assertIn("my-feature", content)
+                self.assertIn("parallel-batch", content)
+
+            coordination = output_dir / "2026-04-18" / "parallel-batch" / "coordination.md"
+            self.assertTrue(coordination.is_file())
+            self.assertIn(str(coordination), stdout.getvalue())
+
+    def test_main_rejects_existing_files_without_force(self) -> None:
+        with tempfile.TemporaryDirectory() as temp_dir:
+            root = Path(temp_dir)
+            template_dir = root / "templates"
+            output_dir = root / "docs" / "plans"
+            template_dir.mkdir(parents=True)
+            for name in MODULE.TEMPLATE_FILENAMES:
+                (template_dir / name).write_text("template\n", encoding="utf-8")
+
+            existing_root = output_dir / "2026-04-18" / "existing-change"
+            existing_root.mkdir(parents=True)
+            (existing_root / "spec.md").write_text("existing\n", encoding="utf-8")
+
+            argv = [
+                "create-specs",
+                "Existing Change",
+                "--change-name",
+                "existing-change",
+                "--output-dir",
+                str(output_dir),
+                "--template-dir",
+                str(template_dir),
+            ]
+
+            with patch.object(MODULE, "date", FixedDate), patch.object(sys, "argv", argv):
+                with self.assertRaises(SystemExit) as context:
+                    MODULE.main()
+
+            self.assertIn("Files already exist", str(context.exception))
+
+    def test_main_requires_explicit_ascii_change_name_when_slug_is_empty(self) -> None:
+        with tempfile.TemporaryDirectory() as temp_dir:
+            template_dir = Path(temp_dir) / "templates"
+            template_dir.mkdir(parents=True)
+            for name in MODULE.TEMPLATE_FILENAMES:
+                (template_dir / name).write_text("template\n", encoding="utf-8")
+
+            argv = [
+                "create-specs",
+                "功能名稱",
+                "--template-dir",
+                str(template_dir),
+            ]
+
+            with patch.object(sys, "argv", argv):
+                with self.assertRaises(SystemExit) as context:
+                    MODULE.main()
+
+            self.assertIn("Unable to build change_name", str(context.exception))
+
+
+if __name__ == "__main__":
+    unittest.main()

package/jupiter-development/SKILL.md

@@ -66,6 +66,10 @@ Implement Jupiter-backed Solana features safely by following the current officia
 - Treat Jupiter token and price data as curated but evolving.
   - Tokens V2 responses can change as Jupiter improves the schema.
   - Price V3 intentionally withholds unreliable prices.
+- Treat Jupiter routing program metadata as discovery data, not signer policy.
+  - Official program-label mappings such as `program-id-to-label` may help build observability, drift detection, and review queues for newly observed router programs.
+  - Do not automatically convert a Jupiter-maintained program list into a signing allowlist for wallet, hot-wallet, or `/swap-to-sol` style flows.
+  - Keep local transaction grammar fail-closed around allowed program classes, signer/writable scope, fee/output policy, instruction discriminators, and receiver semantics; only promote newly discovered programs after the local safety contract is understood and tested.
 - For Jupiter Lend advanced recipes, expect versioned transactions, address lookup tables, and sometimes extra compute budget.
 - Never commit private keys. Use environment variables, wallet adapters, secure signers, or managed key systems.
 
@@ -74,6 +78,7 @@ Implement Jupiter-backed Solana features safely by following the current officia
 - Confirm the base URL, auth header, and required parameters match the official docs you used.
 - Verify that any routing, payer, referral, or fee assumptions still hold after optional parameters are added.
 - When building transactions manually, verify quote endpoint compatibility, instruction order, compute budget, address lookup tables, and signing flow.
+- When using Jupiter-maintained program registries, verify that registry drift handling is observability-first: record unknown program labels and route context, alert or fail closed on unsafe transaction shapes, and keep signing decisions owned by the local policy layer rather than by the remote registry response.
 - When the task involves on-chain actions, report any remaining environment needs clearly, such as API keys, RPC endpoints, or wallet secrets that were intentionally not embedded.
 
 ## Reference Files