The approved Issue #96 branch already shipped the ePost English-address helper
and executable shebang/mode fix. This follow-up only locks the last user-facing
surface: docs and docs regression now mention the direct `./scripts/zipcode_search.py`
entrypoint alongside the `python3` form, so the published guidance matches the
actual executable helper behavior.
Constraint: Keep the branch diff narrow and aligned with the already-approved Issue #96 scope
Rejected: Add more helper code changes | executable behavior was already correct and verified
Confidence: high
Scope-risk: narrow
Reversibility: clean
Directive: Keep docs/tests aligned whenever helper entrypoint contracts change
Tested: node --test scripts/skill-docs.test.js; python3 -m unittest scripts.test_zipcode_search; python3 scripts/zipcode_search.py "서울특별시 강남구 테헤란로 123"; ./scripts/zipcode_search.py "서울특별시 강남구 테헤란로 123"; npm run build; PYTHONPATH=.:scripts python3 -m unittest scripts.test_patent_search; npm run ci
Not-tested: No additional live address samples beyond the documented Gangnam example
The feature branch already routed zipcode lookup through the integrated ePost English-address surface, but the helper scripts themselves still lacked a shebang and executable mode. This follow-up locks the packaging/CLI contract with a regression test and marks both entrypoints executable so the documented helper can be invoked directly as a script.
Constraint: Issue #96 requires an executable zipcode_search.py helper in both the repo script wrapper and bundled skill helper
Rejected: Document python3-only invocation and leave file modes unchanged | would not satisfy the executable-helper requirement or catch future regressions
Confidence: high
Scope-risk: narrow
Reversibility: clean
Directive: Keep the wrapper and bundled helper executable together because tests assert the pair as the public entrypoints
Tested: python3 -m unittest scripts.test_zipcode_search; node --test scripts/skill-docs.test.js; python3 scripts/zipcode_search.py "서울특별시 강남구 테헤란로 123"; ./scripts/zipcode_search.py "서울특별시 강남구 테헤란로 123"; npm run build; PYTHONPATH=.:scripts python3 -m unittest scripts.test_patent_search; npm run ci
Not-tested: Direct execution of the bundled zipcode-search/scripts/zipcode_search.py helper against the live endpoint
The zipcode-search feature now uses the official ePost integrated search surface
for postcode plus English-address lookups, ships a runnable helper, and
locks the behavior with regression coverage plus aligned docs.
A narrow compatibility fallback was also added to the KIPRIS XML parser so
repository CI stays green on the current Python 3.14 environment where
pyexpat is unavailable.
Constraint: Must use official public ePost output instead of custom romanization rules
Constraint: Repository verification must pass under the current local Python 3.14 toolchain
Rejected: Implement our own Hangul-to-English address formatter | would diverge from the official postal rendering
Rejected: Leave the KIPRIS parser untouched | npm run ci currently fails in this environment without the XML fallback
Confidence: medium
Scope-risk: moderate
Reversibility: clean
Directive: Keep zipcode-search tied to the official ePost integrated surface unless a new approved source is added
Tested: python3 -m unittest scripts.test_zipcode_search
Tested: node --test scripts/skill-docs.test.js
Tested: python3 scripts/zipcode_search.py '서울특별시 강남구 테헤란로 123'
Tested: npm run build
Tested: PYTHONPATH=.:scripts python3 -m unittest scripts.test_patent_search
Tested: npm run ci
Not-tested: Live no-result and multi-result zipcode queries beyond the verified Teheran-ro example
The zipcode-search docs were directionally correct, but they left a few practical failure modes underexplained for real operator use. This update makes the retry order explicit, adds guidance for temp-file based parsing in wrapped shells, and documents the benign curl (23) case when downstream readers close early.
Constraint: Keep the change docs-first without adding runtime code or dependencies
Constraint: The official ePost endpoint remains intermittently flaky, so guidance must focus on stable operator behavior rather than pretending transport is deterministic
Rejected: Replace the docs example with a larger shell wrapper script | too heavy for a small skill-doc improvement
Rejected: Ignore curl (23) and here-doc issues as user error | repeated operator confusion is worth documenting
Confidence: high
Scope-risk: narrow
Reversibility: clean
Directive: If the zipcode-search example changes again, keep the retry order and shell-wrapper caveats aligned between the skill doc, feature doc, and regression test
Tested: node --check scripts/skill-docs.test.js
Tested: node --test scripts/skill-docs.test.js
Tested: npm run ci
Tested: npx --yes skills add . --list
Not-tested: Live ePost requests for this doc-only follow-up
The zipcode-search docs and regression suite now stop constraining the curl retry path with an outer Python timeout. The docs instead state that curl owns the transport budget, which matches the blocking review feedback and keeps the regression test aligned with that invariant.
Constraint: Follow-up had to stay on the existing feature/#3 PR branch and keep the documented curl-based flow intact
Constraint: ePost endpoint was timing out from this environment during live verification, so the fix had to be grounded in the reviewed failure mode and local regression evidence
Rejected: Raise timeout=30 to a slightly larger Python cap | still duplicates curl transport budgeting and risks another too-short wrapper limit
Confidence: medium
Scope-risk: narrow
Reversibility: clean
Directive: If the zipcode-search transport example changes again, keep the regression test aligned with whichever layer owns retry/timeout control
Tested: node --test scripts/skill-docs.test.js; npm run ci; npx --yes skills add . --list; repeated python3/curl probes to parcel.epost.go.kr and www.epost.go.kr
Not-tested: Successful live ePost query from this environment on 2026-03-26; current probes timed out with curl exit 28
The follow-up narrows the regression test to retry-related transport invariants and updates the zipcode-search examples to document intermittent ePost resets/timeouts while using retry-aware curl flags. The Python example now captures curl output cleanly so successful retries do not leak transient transport noise into the user-facing walkthrough.
Constraint: Review feedback required a docs-first fix on the existing feature/#3 PR branch
Constraint: The ePost endpoint intermittently resets/times out even when the retry path eventually succeeds
Rejected: Revert to urllib example | modern local runs were less reliable than curl with HTTP/1.1 + TLS 1.2
Rejected: Leave curl stderr streaming during retries | transient reset logs made successful examples look flaky
Confidence: high
Scope-risk: narrow
Directive: Keep the retry flags and official ePost extraction fields aligned between the skill doc, feature doc, and root regression test
Tested: node --test scripts/skill-docs.test.js; npm run ci; npx --yes skills add . --list; live docs example query for 세종대로 209 (3 runs)
Not-tested: Alternate address keywords beyond 세종대로 209
Broaden the root regression suite to cover the roadmap/source/feature-doc surface and replace the fragile urllib example with a curl-backed, timeout-bounded snippet that matches the verified live query path.
Constraint: The ePost endpoint resets the shipped urllib transport on current local python3 toolchains
Constraint: Must keep the fix doc-only with no new dependencies
Rejected: Keep urllib and add a warning only | the published example would still fail as written
Confidence: high
Scope-risk: narrow
Directive: If the ePost markup or transport requirements change, update both docs and scripts/skill-docs.test.js together
Tested: node --test scripts/skill-docs.test.js
Tested: npx --yes skills add . --list
Tested: python3 /tmp/zipcode_live_check.py
Tested: npm run ci
Not-tested: Alternative HTTP clients beyond the curl-backed path
Issue #3 asks for a low-friction way to turn a known Korean address into a postal code. This change adds a dedicated zipcode-search skill, wires it into repo docs, and protects the new discovery/documentation surface with a root-level regression test that now runs under npm test/ci.
Constraint: Must use the official ePost postal search page and avoid new dependencies
Rejected: Data.go.kr key-based postal API | unnecessary setup for a simple lookup skill
Confidence: high
Scope-risk: narrow
Directive: Keep the zipcode-search extraction logic aligned with the official ePost HTML fields unless a more stable public API replaces it
Tested: node --test scripts/skill-docs.test.js
Tested: npm run ci
Tested: npx --yes skills add . --list
Tested: python3 live query against the ePost endpoint for 세종대로 209
Not-tested: Broader address variants beyond the verified ePost query example
