KTX 상세 좌석 조회에서 가운데 호차를 먼저 탐색하고,
같은 호차 안에서는 콘센트 좌석과 순방향 좌석을 우선 노출합니다.
#294 요구사항을 우선순위 함수와 command_seats 회귀 테스트로 고정합니다.
Constraint: #294는 기존 seats 공개 인터페이스 유지를 요구함
Rejected: 예약 API에 객차/좌석 번호를 직접 주입 | 현재 helper 예약 경로가 해당 선택 인자를 노출하지 않음
Confidence: high
Scope-risk: narrow
Directive: 좌석 우선순위 변경 시 command_seats 출력 순서 테스트를 함께 갱신할 것
Tested: PYTHONPATH=.:scripts python3 -m unittest scripts.test_ktx_booking
Tested: node --test scripts/skill-docs.test.js
Tested: npm run typecheck
Tested: npm run ci
Add a seats command to inspect residual seats by car, normalize seat metadata, and surface power-outlet hints while preserving the existing search and reserve selector flow. Update skill docs so seat-number and good-seat requests route through the detailed lookup before reservation.
Constraint: Korail reservation remains separate from seat inspection; the new flow must not select, hold, or pay for seats.
Rejected: Reusing train-level has_general_seat flags for good-seat requests | those flags cannot answer car number, seat label, or outlet availability.
Confidence: high
Scope-risk: moderate
Directive: Keep search, seats, and reserve on the same train_type and stable train_id path so stale results fail explicitly.
Tested: PYTHONPATH=.:scripts python3 -m unittest scripts.test_ktx_booking; python3 -m py_compile scripts/ktx_booking.py scripts/test_ktx_booking.py; node --check scripts/skill-docs.test.js
Not-tested: npm run ci is blocked locally because gitignored .agents/ and .venv directories are treated as missing SKILL.md by scripts/validate-skills.sh.
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
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
The feature branch already restored the patched Korail helper, so this follow-up stays narrow: lock the documented helper flags in regression tests and teach both KTX docs surfaces about the search and waiting-list toggles the live CLI already supports.
Constraint: Follow-up had to stay compatible with the shipped scripts/ktx_booking.py parser and existing PR scope
Rejected: Expand README into a full command matrix | duplicates the dedicated KTX docs and skill guide
Confidence: high
Scope-risk: narrow
Directive: When the helper CLI changes, update both KTX docs surfaces and the regression assertions in the same change
Tested: node --test scripts/skill-docs.test.js
Tested: python3 -m py_compile scripts/ktx_booking.py
Tested: npm run ci
Tested: live python3 scripts/ktx_booking.py search/reservations/reserve/cancel via sops-managed Korail credentials
Not-tested: 예약대기 success path on a sold-out train
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
This snapshots the current repository updates as a coherent release-prep
baseline: workspace/package scaffolding, release automation docs and
workflows, refreshed skill/setup documentation, roadmap expansion, and
the README thumbnail polish.
Constraint: Node packages in this repo must use npm workspaces and Changesets for releases
Constraint: Python release automation stays scaffold-only until a real package exists
Rejected: Split the current work into multiple commits | user asked to commit the current changes together
Confidence: medium
Scope-risk: moderate
Reversibility: clean
Directive: Keep release docs, workflows, and package metadata aligned when adding future packages
Tested: npm run ci
Not-tested: GitHub Actions execution on remote after push
The README previously listed skill package names without making the
actual user-facing capabilities obvious, and several linked docs used
local absolute paths instead of repository-relative links. This change
reframes the entry point around tasks users can accomplish, adds real
feature pages for each supported workflow, and connects the install and
security docs to those pages with working relative links.
Constraint: Keep the change documentation-only and avoid introducing new dependencies
Rejected: Link directly to each SKILL.md | too implementation-centric for a README first impression
Rejected: Keep one short README and defer detail to package names | does not make capabilities obvious enough
Confidence: high
Scope-risk: narrow
Reversibility: clean
Directive: Keep README organized by user-facing jobs rather than internal skill identifiers unless the product positioning changes
Tested: Local markdown link validation across all .md files
Not-tested: GitHub web rendering preview after push
