@laitszkin/apollo-toolkit 2.14.23 → 3.0.1

package/maintain-project-constraints/SKILL.md

@@ -70,9 +70,9 @@ Example:
 ## Common Commands
 
 - `npm test` — run the repository's automated test suite.
-- `python3 scripts/validate_skill_frontmatter.py` — validate every top-level `SKILL.md` frontmatter block.
-- `python3 scripts/validate_openai_agent_config.py` — validate every `agents/openai.yaml` interface config.
-- `./scripts/install_skills.sh codex` — install the current toolkit into the local Codex skills directory.
+- `apltk validate-skill-frontmatter` — validate every top-level `SKILL.md` frontmatter block.
+- `apltk validate-openai-agent-config` — validate every `agents/openai.yaml` interface config.
+- `apltk codex` — install the current toolkit into the local Codex skills directory.
 
 ## Core Business Flow
 

package/maintain-skill-catalog/SKILL.md

@@ -56,8 +56,8 @@ Keep a skill repository coherent when many top-level skills evolve together.
 ### 4) Validate the catalog after changes
 
 - Run:
-  - `python3 scripts/validate_skill_frontmatter.py`
-  - `python3 scripts/validate_openai_agent_config.py`
+  - `apltk validate-skill-frontmatter`
+  - `apltk validate-openai-agent-config`
 - If the change touched installer or repo-discovery behavior, verify the relevant install scripts or discovery logic as well.
 - Resolve validation failures before finishing; missing `agents/openai.yaml`, stale prompt references, and mismatched skill names are catalog bugs, not follow-up work.
 

package/novel-to-short-video/SKILL.md

@@ -120,7 +120,7 @@ If producing multiple short videos in one request, enforce the same 50-60 second
 - Generate images with:
 
 ```bash
-python ~/.codex/skills/openai-text-to-image-storyboard/scripts/generate_storyboard_images.py \
+apltk generate-storyboard-images \
   --project-dir "<project_dir>" \
   --env-file ~/.codex/skills/openai-text-to-image-storyboard/.env \
   --content-name "<content_name>" \
@@ -133,7 +133,7 @@ python ~/.codex/skills/openai-text-to-image-storyboard/scripts/generate_storyboa
 - Generate audio + timeline + SRT:
 
 ```bash
-python ~/.codex/skills/docs-to-voice/scripts/docs_to_voice.py \
+apltk docs-to-voice \
   --project-dir "<project_dir>" \
   --project-name "<content_name>" \
   --text "<loop_narration_script>"

package/open-github-issue/README.md

@@ -16,7 +16,7 @@ This skill helps agents publish confirmed findings, accepted proposals, document
 
 - `SKILL.md`: Main skill definition and workflow.
 - `agents/openai.yaml`: Agent interface metadata and default prompt.
-- `scripts/open_github_issue.py`: Deterministic issue publisher.
+- `scripts/open_github_issue.py`: Deterministic issue publisher, exposed as `apltk open-github-issue`.
 
 ## Installation
 
@@ -36,41 +36,50 @@ Invoke the skill in your prompt:
 Use $open-github-issue to publish this confirmed finding or accepted proposal to GitHub.
 ```
 
-The bundled script can also be called directly:
+The bundled CLI can also be called directly:
 
 ```bash
-python scripts/open_github_issue.py \
-  --issue-type problem \
-  --title "[Log] Payment timeout spike" \
-  --problem-description $'Expected Behavior (BDD)\nGiven the payment service sees transient upstream latency\nWhen the retry path runs\nThen requests should recover without user-visible failures\n\nCurrent Behavior (BDD)\nGiven the payment service sees transient upstream latency\nWhen the retry path runs\nThen repeated timeout warnings still escalate into request failures\n\nBehavior Gap\n- Expected: retries absorb transient upstream slowness.\n- Actual: retries still end in request failures.\n- Difference/Impact: customers receive failed payment attempts during the incident window.\n\nEvidence\n- symptom: repeated timeout warnings escalated into request failures.\n- impact: payment attempts failed for end users.\n- key evidence: logs from the incident window show retries without successful recovery.' \
-  --suspected-cause "payment-api/handler.py:84 retries immediately against a slow upstream with no jitter; confidence high." \
-  --reproduction "Not yet reliably reproducible; more runtime evidence is required." \
-  --repo owner/repo
+cat > /tmp/open-github-issue-payload.json <<'JSON'
+{
+  "issue_type": "problem",
+  "title": "[Log] Payment timeout spike",
+  "problem_description": "Expected Behavior (BDD)\nGiven the payment service sees transient upstream latency\nWhen the retry path runs\nThen requests should recover without user-visible failures and keep `request_id` evidence intact\n\nCurrent Behavior (BDD)\nGiven the payment service sees transient upstream latency\nWhen the retry path runs\nThen repeated timeout warnings still escalate into request failures\n\nBehavior Gap\n- Expected: retries absorb transient upstream slowness.\n- Actual: retries still end in request failures.\n- Difference/Impact: customers receive failed payment attempts during the incident window.\n\nEvidence\n- symptom: repeated timeout warnings escalated into request failures.\n- impact: payment attempts failed for end users.\n- key evidence: logs from the incident window show retries without successful recovery.",
+  "suspected_cause": "payment-api/handler.py:84 retries immediately against a slow upstream with no jitter; confidence high.",
+  "reproduction": "Not yet reliably reproducible; more runtime evidence is required."
+}
+JSON
+
+apltk open-github-issue --payload-file /tmp/open-github-issue-payload.json --repo owner/repo
 ```
 
 ```bash
-python scripts/open_github_issue.py \
-  --issue-type feature \
-  --title "[Feature] Add incident timeline export" \
-  --proposal "Allow users to export incident timelines as Markdown and CSV from the incident detail page." \
-  --reason "Support handoff to on-call engineers and postmortem writing without copy-paste." \
-  --suggested-architecture "Add an export action in the incident UI, reuse timeline query service, and centralize renderers in a shared export module." \
-  --repo owner/repo
+cat > /tmp/open-github-issue-payload.json <<'JSON'
+{
+  "issue_type": "feature",
+  "title": "[Feature] Add incident timeline export",
+  "proposal": "Allow users to export incident timelines as Markdown and CSV from the incident detail page.",
+  "reason": "Support handoff to on-call engineers and postmortem writing without copy-paste.",
+  "suggested_architecture": "Add an export action in the incident UI, reuse timeline query service, and centralize renderers in a shared export module."
+}
+JSON
+
+apltk open-github-issue --payload-file /tmp/open-github-issue-payload.json --repo owner/repo
 ```
 
 ```bash
-python scripts/open_github_issue.py \
+apltk open-github-issue --repo owner/repo \
   --issue-type security \
   --title "[Security] Missing authorization check on admin export" \
-  --problem-description "The admin export endpoint can be reached without verifying the caller's admin role." \
+  --problem-description @/tmp/security-risk.md \
   --severity high \
   --affected-scope "/admin/export endpoint and exported customer data" \
-  --impact "Unauthorized users may access privileged exports containing sensitive business data." \
-  --evidence "Code path review and reproduced requests show the handler validates session presence but not the admin permission gate." \
-  --suggested-action "Add explicit authorization enforcement, regression tests, and audit logging for denied access attempts." \
-  --repo owner/repo
+  --impact @/tmp/security-impact.md \
+  --evidence @/tmp/security-evidence.md \
+  --suggested-action @/tmp/security-action.md
 ```
 
+Use `--payload-file` or `@file` for Markdown-rich fields. Inline shell arguments can corrupt backticks, `$()`, quotes, and other shell metacharacters before the Python script receives them.
+
 ## Publication behavior
 
 For each issue:

package/open-github-issue/SKILL.md

@@ -38,7 +38,8 @@ It is designed to be reusable by other skills that already know the issue title
 - Preserve upstream evidence content; only localize section headers and default fallback text.
 - Make the issue type explicit: `problem`, `feature`, `performance`, `security`, `docs`, or `observability`.
 - For `problem` issues, describe the expected behavior and current behavior with BDD-style `Given / When / Then`, then state the behavioral difference explicitly.
-- Prefer `python3` plus an absolute helper path when invoking bundled scripts; do not assume `python`, relative paths, or the caller's cwd are wired correctly.
+- Prefer the bundled `apltk open-github-issue` command when available; if it is unavailable, fall back to the packaged script with an absolute path instead of assuming `python`, relative paths, or the caller's cwd are wired correctly.
+- Never pass Markdown-rich issue content inline when it may contain backticks, `$()`, quotes, or shell metacharacters. Write a JSON payload file or content files first, then pass `--payload-file` or `@file` references so the shell cannot perform command substitution before Python receives the text.
 
 ## Workflow
 
@@ -94,88 +95,100 @@ It is designed to be reusable by other skills that already know the issue title
 
 ## Deterministic command
 
-Use the bundled script.
+Use the bundled command. Prefer `--payload-file` for all rich issue content because inline shell arguments can corrupt Markdown code spans such as `` `symbol` `` before the script starts.
 
-First resolve:
+Safe problem issue payload:
 
 ```bash
-SKILL_ROOT=~/.codex/skills/open-github-issue
+cat > /tmp/open-github-issue-payload.json <<'JSON'
+{
+  "issue_type": "problem",
+  "title": "[Log] <short symptom>",
+  "problem_description": "Expected Behavior (BDD)\nGiven ...\nWhen ...\nThen `literal_code_span` should remain unchanged\n\nCurrent Behavior (BDD)\nGiven ...\nWhen ...\nThen ...\n\nBehavior Gap\n- Expected: ...\n- Actual: ...\n- Difference/Impact: ...\n\nEvidence\n- symptom: ...\n- impact: ...\n- key evidence: ...",
+  "suspected_cause": "<path:line + causal chain + confidence>",
+  "reproduction": "<steps/conditions or leave empty>"
+}
+JSON
+
+apltk open-github-issue --payload-file /tmp/open-github-issue-payload.json --repo <owner/repo>
 ```
 
-Problem issue:
+Safe feature proposal payload:
 
 ```bash
-python3 "$SKILL_ROOT/scripts/open_github_issue.py" \
-  --issue-type problem \
-  --title "[Log] <short symptom>" \
-  --problem-description $'Expected Behavior (BDD)\nGiven ...\nWhen ...\nThen ...\n\nCurrent Behavior (BDD)\nGiven ...\nWhen ...\nThen ...\n\nBehavior Gap\n- Expected: ...\n- Actual: ...\n- Difference/Impact: ...\n\nEvidence\n- symptom: ...\n- impact: ...\n- key evidence: ...' \
-  --suspected-cause "<path:line + causal chain + confidence>" \
-  --reproduction "<steps/conditions or leave empty>" \
-  --repo <owner/repo>
+cat > /tmp/open-github-issue-payload.json <<'JSON'
+{
+  "issue_type": "feature",
+  "title": "[Feature] <short proposal>",
+  "proposal": "<what should be added or changed>",
+  "reason": "<why this matters now, user value, constraints>",
+  "suggested_architecture": "<modules, boundaries, implementation direction>"
+}
+JSON
+
+apltk open-github-issue --payload-file /tmp/open-github-issue-payload.json --repo <owner/repo>
 ```
 
-Feature proposal issue:
+Safe individual field files are also supported:
 
 ```bash
-python3 "$SKILL_ROOT/scripts/open_github_issue.py" \
-  --issue-type feature \
-  --title "[Feature] <short proposal>" \
-  --proposal "<what should be added or changed>" \
-  --reason "<why this matters now, user value, constraints>" \
-  --suggested-architecture "<modules, boundaries, implementation direction>" \
-  --repo <owner/repo>
+apltk open-github-issue --repo <owner/repo> \
+  --issue-type problem \
+  --title "[Log] <short symptom>" \
+  --problem-description @/tmp/problem-description.md \
+  --suspected-cause @/tmp/suspected-cause.md
 ```
 
 Performance issue:
 
 ```bash
-python3 "$SKILL_ROOT/scripts/open_github_issue.py" \
+apltk open-github-issue \
   --issue-type performance \
   --title "[Performance] Slow dashboard query under large tenants" \
-  --problem-description "Dashboard loading time degrades sharply once tenant data exceeds current pagination assumptions." \
-  --impact "Users wait 8-12 seconds before the page becomes interactive; this blocks support workflows." \
-  --evidence "Profiler output, slow-query logs, and production timings all point to repeated full-table scans in the summary query path." \
-  --suggested-action "Add bounded pagination, pre-aggregated summaries, and an index review for the offending query path." \
+  --problem-description @/tmp/performance-problem.md \
+  --impact @/tmp/performance-impact.md \
+  --evidence @/tmp/performance-evidence.md \
+  --suggested-action @/tmp/performance-action.md \
   --repo <owner/repo>
 ```
 
 Security issue:
 
 ```bash
-python3 "$SKILL_ROOT/scripts/open_github_issue.py" \
+apltk open-github-issue \
   --issue-type security \
   --title "[Security] Missing authorization check on admin export" \
-  --problem-description "The admin export endpoint can be reached without verifying the caller's admin role." \
+  --problem-description @/tmp/security-risk.md \
   --severity high \
   --affected-scope "/admin/export endpoint and exported customer data" \
-  --impact "Unauthorized users may access privileged exports containing sensitive business data." \
-  --evidence "Code path review and reproduced requests show the handler validates session presence but not the admin permission gate." \
-  --suggested-action "Add explicit authorization enforcement, regression tests, and audit logging for denied access attempts." \
+  --impact @/tmp/security-impact.md \
+  --evidence @/tmp/security-evidence.md \
+  --suggested-action @/tmp/security-action.md \
   --repo <owner/repo>
 ```
 
 Docs issue:
 
 ```bash
-python3 "$SKILL_ROOT/scripts/open_github_issue.py" \
+apltk open-github-issue \
   --issue-type docs \
   --title "[Docs] Deployment guide omits required Redis configuration" \
-  --problem-description "The deployment guide does not mention the required Redis URL and worker startup order." \
-  --evidence "README deploy steps differ from the actual compose file and runtime startup checks." \
-  --suggested-action "Update deployment docs with required env vars, startup order, and a minimal validation checklist." \
+  --problem-description @/tmp/docs-gap.md \
+  --evidence @/tmp/docs-evidence.md \
+  --suggested-action @/tmp/docs-action.md \
   --repo <owner/repo>
 ```
 
 Observability issue:
 
 ```bash
-python3 "$SKILL_ROOT/scripts/open_github_issue.py" \
+apltk open-github-issue \
   --issue-type observability \
   --title "[Observability] Missing request identifiers in payment retry logs" \
-  --problem-description "Retry logs do not include stable request or trace identifiers, so multi-line failures cannot be correlated quickly." \
-  --impact "On-call engineers cannot isolate a single failing payment flow without manual log stitching." \
-  --evidence "Current retry log lines include endpoint and error text only; incident review required manual timestamp matching." \
-  --suggested-action "Add request_id, trace_id, upstream target, and retry attempt fields to retry logs and dashboard facets." \
+  --problem-description @/tmp/observability-gap.md \
+  --impact @/tmp/observability-impact.md \
+  --evidence @/tmp/observability-evidence.md \
+  --suggested-action @/tmp/observability-action.md \
   --repo <owner/repo>
 ```
 
@@ -198,6 +211,7 @@ When another skill depends on `open-github-issue`:
 
 - Pass exactly one confirmed issue or one accepted proposal per invocation.
 - Prepare evidence or proposal details before calling this skill; do not ask this skill to infer root cause or architecture.
+- When invoking the CLI directly, write rich Markdown fields into a JSON payload file or `@file` inputs first; do not inline text containing backticks or shell metacharacters.
 - For `problem` issues, pass a `problem-description` that contains `Expected Behavior (BDD)`, `Current Behavior (BDD)`, and `Behavior Gap`; the difference must be explicit, not implied.
 - Reuse the returned `mode`, `issue_url`, and `publish_error` in the parent skill response.
 - For accepted feature proposals, pass `--issue-type feature` plus `--proposal`, `--reason`, and `--suggested-architecture`.
@@ -205,5 +219,5 @@ When another skill depends on `open-github-issue`:
 
 ## Resources
 
-- `scripts/open_github_issue.py`: Deterministic issue publishing helper with auth fallback and README language detection.
+- `scripts/open_github_issue.py`: Deterministic issue publishing helper with auth fallback and README language detection, exposed as `apltk open-github-issue`.
 - If the helper path is unavailable or still fails for environment reasons, fall back to direct `gh issue create` or GitHub REST API publishing instead of retrying the same broken relative-path invocation.

package/open-github-issue/scripts/open_github_issue.py

@@ -43,6 +43,38 @@ PROBLEM_BDD_MARKER_GROUPS = (
         r"行為(?:落差|差異)",
     ),
 )
+TEXT_FIELDS = (
+    "title",
+    "problem_description",
+    "suspected_cause",
+    "reproduction",
+    "proposal",
+    "reason",
+    "suggested_architecture",
+    "impact",
+    "evidence",
+    "suggested_action",
+    "affected_scope",
+)
+PAYLOAD_FIELDS = frozenset(
+    (
+        "title",
+        "issue_type",
+        "problem_description",
+        "suspected_cause",
+        "reproduction",
+        "proposal",
+        "reason",
+        "suggested_architecture",
+        "impact",
+        "evidence",
+        "suggested_action",
+        "severity",
+        "affected_scope",
+        "repo",
+        "dry_run",
+    )
+)
 
 
 def parse_args() -> argparse.Namespace:
@@ -52,11 +84,18 @@ def parse_args() -> argparse.Namespace:
             "Auth order: gh CLI login -> GitHub token -> draft only."
         )
     )
-    parser.add_argument("--title", required=True, help="Issue title")
+    parser.add_argument(
+        "--payload-file",
+        help=(
+            "Path to a JSON payload file. Use '-' to read JSON from stdin. "
+            "CLI flags override values loaded from the payload."
+        ),
+    )
+    parser.add_argument("--title", help="Issue title")
     parser.add_argument(
         "--issue-type",
         choices=ISSUE_TYPES,
-        default=ISSUE_TYPE_PROBLEM,
+        default=None,
         help="Structured issue type to publish.",
     )
     parser.add_argument(
@@ -116,6 +155,94 @@ def parse_args() -> argparse.Namespace:
     return parser.parse_args()
 
 
+def normalize_payload_key(key: str) -> str:
+    return key.replace("-", "_")
+
+
+def read_payload_file(raw_path: str) -> dict[str, object]:
+    if raw_path == "-":
+        raw_content = sys.stdin.read()
+        context = "stdin"
+    else:
+        path = Path(raw_path).expanduser()
+        raw_content = path.read_text(encoding="utf-8")
+        context = str(path)
+
+    try:
+        payload = json.loads(raw_content)
+    except json.JSONDecodeError as exc:
+        raise SystemExit(f"Invalid JSON payload in {context}: {exc}") from exc
+
+    if not isinstance(payload, dict):
+        raise SystemExit(f"Invalid JSON payload in {context}: top-level value must be an object.")
+
+    normalized: dict[str, object] = {}
+    for raw_key, value in payload.items():
+        key = normalize_payload_key(str(raw_key))
+        if key not in PAYLOAD_FIELDS:
+            raise SystemExit(f"Unsupported payload key: {raw_key}")
+        normalized[key] = value
+    return normalized
+
+
+def payload_value_to_string(field_name: str, value: object) -> str | None:
+    if value is None:
+        return None
+    if isinstance(value, str):
+        return value
+    raise SystemExit(f"Payload field '{field_name}' must be a string or null.")
+
+
+def read_at_file_value(field_name: str, value: str | None) -> str | None:
+    if value is None:
+        return None
+    if value.startswith("@@"):
+        return value[1:]
+    if value == "@-":
+        return sys.stdin.read()
+    if value.startswith("@") and len(value) > 1:
+        path = Path(value[1:]).expanduser()
+        try:
+            return path.read_text(encoding="utf-8")
+        except OSError as exc:
+            raise SystemExit(f"Unable to read @{field_name} file {path}: {exc}") from exc
+    return value
+
+
+def hydrate_args(args: argparse.Namespace) -> argparse.Namespace:
+    payload_file = getattr(args, "payload_file", None)
+    if payload_file:
+        payload = read_payload_file(payload_file)
+        for field_name, value in payload.items():
+            current_value = getattr(args, field_name, None)
+            if field_name == "dry_run":
+                if not isinstance(value, bool):
+                    raise SystemExit("Payload field 'dry_run' must be a boolean.")
+                if not current_value:
+                    setattr(args, field_name, value)
+                continue
+
+            if field_name in TEXT_FIELDS:
+                value = payload_value_to_string(field_name, value)
+            elif not isinstance(value, str):
+                raise SystemExit(f"Payload field '{field_name}' must be a string.")
+
+            if current_value is None or current_value == "":
+                setattr(args, field_name, value)
+
+    if args.issue_type is None:
+        args.issue_type = ISSUE_TYPE_PROBLEM
+    if args.issue_type not in ISSUE_TYPES:
+        raise SystemExit(f"Invalid issue_type: {args.issue_type}")
+
+    for field_name in TEXT_FIELDS:
+        setattr(args, field_name, read_at_file_value(field_name, getattr(args, field_name, None)))
+
+    if not (args.title or "").strip():
+        raise SystemExit("Issue title is required. Pass --title or include title in --payload-file.")
+    return args
+
+
 def validate_issue_content_args(args: argparse.Namespace) -> None:
     if args.issue_type == ISSUE_TYPE_FEATURE:
         if not (args.reason or "").strip():
@@ -497,7 +624,7 @@ def create_issue_with_token(repo: str, title: str, body: str, token: str) -> str
 
 
 def main() -> int:
-    args = parse_args()
+    args = hydrate_args(parse_args())
     validate_issue_content_args(args)
 
     gh_authenticated = has_gh_auth()

package/open-github-issue/tests/test_open_github_issue.py

@@ -5,6 +5,7 @@ from __future__ import annotations
 import importlib.util
 import io
 import json
+import tempfile
 import unittest
 from argparse import Namespace
 from pathlib import Path
@@ -22,6 +23,100 @@ class OpenGitHubIssueTests(unittest.TestCase):
         with self.assertRaises(SystemExit):
             MODULE.validate_repo("owner-only")
 
+    def test_hydrate_args_loads_payload_file_with_literal_backticks(self) -> None:
+        with tempfile.TemporaryDirectory() as temp_dir:
+            payload_path = Path(temp_dir) / "issue.json"
+            payload_path.write_text(
+                json.dumps(
+                    {
+                        "title": "[Log] backticks",
+                        "issue_type": MODULE.ISSUE_TYPE_PROBLEM,
+                        "problem_description": (
+                            "Expected Behavior (BDD)\n"
+                            "Given markdown content contains code spans\n"
+                            "When the issue is published\n"
+                            "Then `printf should_not_run` remains literal\n\n"
+                            "Current Behavior (BDD)\n"
+                            "Given markdown content contains code spans\n"
+                            "When the issue is published\n"
+                            "Then `printf should_not_run` can be eaten by shell quoting\n\n"
+                            "Behavior Gap\n"
+                            "- Expected: `printf should_not_run` survives.\n"
+                            "- Actual: inline shell args are fragile.\n"
+                            "- Difference/Impact: issue evidence can be corrupted.\n"
+                        ),
+                        "suspected_cause": "Shell command substitution happens before Python receives argv.",
+                    }
+                ),
+                encoding="utf-8",
+            )
+
+            args = Namespace(
+                payload_file=str(payload_path),
+                title=None,
+                issue_type=None,
+                problem_description=None,
+                suspected_cause=None,
+                reproduction=None,
+                proposal=None,
+                reason=None,
+                suggested_architecture=None,
+                impact=None,
+                evidence=None,
+                suggested_action=None,
+                severity=None,
+                affected_scope=None,
+                repo=None,
+                dry_run=False,
+            )
+
+            hydrated = MODULE.hydrate_args(args)
+
+        self.assertEqual(hydrated.title, "[Log] backticks")
+        self.assertIn("`printf should_not_run` remains literal", hydrated.problem_description)
+        self.assertEqual(hydrated.issue_type, MODULE.ISSUE_TYPE_PROBLEM)
+
+    def test_hydrate_args_reads_at_file_text_values(self) -> None:
+        with tempfile.TemporaryDirectory() as temp_dir:
+            description_path = Path(temp_dir) / "description.md"
+            description_path.write_text(
+                "Expected Behavior (BDD)\n"
+                "Given a markdown file contains backticks\n"
+                "When it is loaded with @file syntax\n"
+                "Then `literal` content survives\n\n"
+                "Current Behavior (BDD)\n"
+                "Given a markdown file contains backticks\n"
+                "When inline shell args are avoided\n"
+                "Then `literal` content reaches argparse unchanged\n\n"
+                "Behavior Gap\n"
+                "- Expected: file content is safe.\n"
+                "- Actual: inline shell content is fragile.\n"
+                "- Difference/Impact: safer invocation is needed.\n",
+                encoding="utf-8",
+            )
+            args = Namespace(
+                payload_file=None,
+                title="[Log] @file",
+                issue_type=MODULE.ISSUE_TYPE_PROBLEM,
+                problem_description=f"@{description_path}",
+                suspected_cause="Use @file for rich text fields.",
+                reproduction=None,
+                proposal=None,
+                reason=None,
+                suggested_architecture=None,
+                impact=None,
+                evidence=None,
+                suggested_action=None,
+                severity=None,
+                affected_scope=None,
+                repo="owner/repo",
+                dry_run=True,
+            )
+
+            hydrated = MODULE.hydrate_args(args)
+
+        self.assertIn("Then `literal` content survives", hydrated.problem_description)
+
     def test_detect_issue_language_prefers_chinese_when_threshold_met(self) -> None:
         readme = "這是一個中文專案說明。" * 10
 

package/openai-text-to-image-storyboard/README.md

@@ -55,7 +55,7 @@ OPENAI_IMAGE_MODEL=gpt-image-1
 3. Run with JSON prompt file
 
 ```bash
-python scripts/generate_storyboard_images.py \
+apltk generate-storyboard-images \
   --project-dir /path/to/project \
   --env-file ~/.codex/skills/openai-text-to-image-storyboard/.env \
   --content-name "1_chapter_title" \

package/openai-text-to-image-storyboard/SKILL.md

@@ -66,7 +66,7 @@ A template is provided at:
 Use JSON prompt file:
 
 ```bash
-python ~/.codex/skills/openai-text-to-image-storyboard/scripts/generate_storyboard_images.py \
+apltk generate-storyboard-images \
   --project-dir /path/to/project \
   --env-file ~/.codex/skills/openai-text-to-image-storyboard/.env \
   --content-name "1_chapter_title" \