Agent environments (OpenClaw, Claude Code, Codex) assume users delegate
credentials to the agent. sops+age added setup friction without real
security benefit since the agent decrypts on every call anyway.
New model: skills declare required env var names; how they are supplied
is up to the agent (own vault, shell env, or ~/.config/k-skill/secrets.env
as the default fallback with 0600 permissions).
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
The validate job was failing because the KTX helper regression suite imported optional runtime dependencies directly from the module top level. GitHub Actions does not inherit the local user site-packages that made those imports succeed on the workstation, so the test suite died before it could exercise the helper logic.
This change makes the helper import-safe in minimal environments by deferring requests usage, providing lightweight fallbacks for optional Korail/Crypto imports during unit tests, and surfacing an explicit install command when the real runtime dependencies are actually needed. The docs now list pycryptodome alongside korail2, and the regression suite forces PYTHONNOUSERSITE=1 so CI keeps exercising the dependency-light path instead of accidentally relying on a developer machine.
Constraint: PR #19 must keep npm run ci green on GitHub Actions without assuming user-level Python packages
Constraint: The KTX helper still needs the real korail2 and pycryptodome packages for live reservation flows
Rejected: Installing ad-hoc Python packages in the CI workflow | hides the import-safety regression instead of fixing the helper/test contract
Rejected: Removing the Python regression suite from skill-docs coverage | would lose the guard on the train_id reservation flow
Confidence: high
Scope-risk: narrow
Reversibility: clean
Directive: Keep the KTX helper importable under PYTHONNOUSERSITE=1 and document every required runtime package in both the skill and install docs
Tested: PYTHONNOUSERSITE=1 python3 -m unittest discover -s scripts -p test_ktx_booking.py
Tested: node --test scripts/skill-docs.test.js
Tested: npm run ci
Not-tested: GitHub Actions validate rerun after push
The reserve replay search now auto-includes waiting-list candidates when users opt into --try-waiting, so the stable train_id chosen from search remains resolvable for docs-following flows. A regression test reproduces the prior stale-train failure and locks the corrected behavior.\n\nConstraint: Reserve must keep using the existing train_id replay flow without broad CLI redesign\nRejected: Require users to repeat --include-waiting-list on reserve | contradicts the documented flow and review feedback\nConfidence: high\nScope-risk: narrow\nReversibility: clean\nDirective: Keep --try-waiting and reserve replay search semantics aligned so waiting-list-only trains remain selectable\nTested: python3 -m py_compile scripts/ktx_booking.py; python3 -m unittest discover -s scripts -p test_ktx_booking.py; node --test scripts/skill-docs.test.js; npm run ci; python3 scripts/ktx_booking.py --help; python3 scripts/ktx_booking.py reserve --help; live search/reservations/reserve/cancel/reservations via sops-managed Korail credentials\nNot-tested: Live waiting-list reservation creation (no waiting-list-eligible train appeared in the smoke search output)
Reserve used to replay search results and trust a fresh ordinal index, which could silently target a different train when sold-out entries disappeared or ordering changed. This change emits a stable train_id from search output, requires reserve to match the exact train identity on replay, and updates docs/tests to lock the safer CLI contract.
Constraint: Korail search results can reorder between search and reserve while the helper still needs to replay the live lookup
Rejected: Keep --train-index as the reserve selector | still allows silent wrong-train bookings when the result set shifts
Confidence: high
Scope-risk: narrow
Reversibility: clean
Directive: If upstream train identity fields change, update the train_id payload and the docs/tests together before changing reserve selection again
Tested: python3 -m py_compile scripts/ktx_booking.py; python3 -m unittest discover -s scripts -p test_ktx_booking.py; node --test scripts/skill-docs.test.js; npm run ci; live search/reservations/reserve/cancel/reservations with sops-managed Korail credentials
Not-tested: Forced live stale-train_id failure against a disappearing train between search and reserve
Korail's current mobile endpoints reject the published raw korail2
examples with MACRO ERROR, so this change adds a repo-local
helper that patches Dynapath token/Sid/version behavior and reroutes
KTX docs/tests to the helper-based flow.
Constraint: Must keep credentials in sops-managed secrets and prove the flow with a real reservation
Rejected: Fork and publish a patched korail2 package | broader release surface than this repo needs
Confidence: high
Scope-risk: moderate
Directive: Re-check the helper constants and private korail2 hooks whenever Korail changes its mobile anti-bot flow
Tested: python3 -m py_compile scripts/ktx_booking.py
Tested: npm run ci
Tested: Live search via scripts/ktx_booking.py search 서울 부산 20260328 000000 --include-no-seats --include-waiting-list
Tested: Live reserve/cancel via scripts/ktx_booking.py reserve/cancel/reservations on March 28, 2026 KTX #001
Not-tested: Final payment completion after reservation
Jeffrey (Dongkyu) Kim