The public-restroom lookup now keeps the official CSV as the authoritative first layer while enriching sparse areas with Kakao Local keyword and gas-station searches when a REST API key is configured. All returned POIs are normalized onto local haversine distance calculations so Kakao's unreliable distance field cannot affect ordering, and map links encode names before coordinates.\n\nThe CSV path can optionally use Kakao coord2address to correct display names and addresses for known source-data coordinate mismatches without changing the default no-key behavior.\n\nConstraint: Kakao REST API requires caller-provided REST API key via option or KAKAO_REST_API_KEY\nConstraint: Existing no-key CSV-only behavior must continue to work\nRejected: Replace CSV with Kakao-only search | loses official open-time metadata and source priority\nRejected: Trust Kakao distance field | issue evidence shows user-origin mismatch\nConfidence: high\nScope-risk: moderate\nDirective: Keep CSV sourceLayer priority ahead of Kakao dedupe unless official data is explicitly deprecated\nTested: npm test --workspace public-restroom-nearby\nTested: npm run lint --workspace public-restroom-nearby\nTested: npm run ci\nNot-tested: Live Kakao REST API call with a production key
The cleanup helper now streams local logs, reports which evidence sources were merged, and keeps README table coverage tied to the central skill-name fixture so the documented cleanup signal stays trustworthy for large local histories and mixed imported counts.
Constraint: Follow-up addresses PR #178 review comments without changing the non-destructive recommendation model.
Rejected: Filtering imported usage JSON by --days inside the helper | imported counts are already aggregated and lack per-record timestamps.
Confidence: high
Scope-risk: narrow
Directive: Keep --usage-json documented as pre-windowed unless the input schema gains timestamped per-record events.
Tested: PYTHONPATH=scripts python3 -m unittest scripts.test_k_skill_cleaner
Tested: node --test scripts/skill-docs.test.js
Tested: npm run lint
Tested: npm run typecheck && npm test
Tested: npm run ci
The standalone helper is advertised from inside the k-skill-cleaner directory, so --skills-root . now resolves that self-skill directory to its parent skills root before scanning siblings. A subprocess regression locks the installed-skill layout that previously returned skill_count 0.\n\nConstraint: Preserve the documented standalone command without requiring users to switch to --skills-root ..\nRejected: Documentation-only fix | would make the advertised command more brittle and leave existing users with empty reports\nConfidence: high\nScope-risk: narrow\nDirective: Keep standalone helper invocation from inside k-skill-cleaner covered when changing root detection\nTested: PYTHONPATH=scripts python3 -m unittest scripts.test_k_skill_cleaner\nTested: Standalone temp-layout smoke from inside k-skill-cleaner with --skills-root .\nTested: npm run lint && npm run typecheck && npm test && npm run ci
The cleanup helper is now shipped inside the k-skill-cleaner skill payload while the repo-root script remains as a compatibility wrapper. The CLI also enforces the interview-selected usage window with --days/--since and reports the effective cutoff so recommendations match the documented contract.\n\nConstraint: Selective skill installs only receive files under the skill directory.\nRejected: Remove k-skill-cleaner from selective install docs | the feature is intended to be installable standalone.\nConfidence: high\nScope-risk: narrow\nDirective: Keep the skill-local helper as the canonical implementation; the root script should stay a thin wrapper.\nTested: PYTHONPATH=scripts python3 -m unittest scripts.test_k_skill_cleaner\nTested: node --test scripts/skill-docs.test.js\nTested: CLI smoke via k-skill-cleaner/scripts/k_skill_cleaner.py with --days 90\nTested: npm run lint\nTested: npm run typecheck && npm test\nTested: npm run ci\nTested: Architect verification APPROVED\nNot-tested: Live agent transcript schemas beyond fixture-style local log samples
Add a conservative k-skill-cleaner workflow that interviews users, scans best-effort agent trigger logs, and reports deletion or review candidates without mutating skill directories automatically.
Constraint: Trigger-count storage differs by coding agent and may be absent or rotated locally
Rejected: Auto-delete low-usage skills | cleanup recommendations need explicit user approval because log signals are incomplete
Confidence: high
Scope-risk: narrow
Directive: Keep deletion behavior recommendation-only unless a future issue explicitly approves mutation with stronger safeguards
Tested: PYTHONPATH=scripts python3 -m unittest scripts.test_k_skill_cleaner; helper CLI smoke; npm run lint; npm run typecheck && npm test; npm run ci; architect verification
Not-tested: Live exports from OpenClaw/ClawHub or Hermes Agent because no stable public local trigger-count schema is assumed
The IROS docs now make the corp-number happy path produce the company-name list that pinned upstream iros_download.py opens after payment, and route the customer workbook excel_path into the same private workdir boundary as other sensitive inputs and outputs.
Constraint: Live IROS login/payment smoke requires user credentials, certificate/authentication, and card payment authority
Rejected: Rely on upstream data/ defaults | leaves real customer workbook and company list paths inside the cloned repository
Confidence: high
Scope-risk: narrow
Tested: node --test --test-name-pattern='iros-registry-automation' scripts/skill-docs.test.js
Tested: ./scripts/validate-skills.sh
Tested: npm run lint && npm run typecheck && npm test
Tested: npm run ci
Tested: cloned pinned upstream SHA and verified companies_list, excel_path, and configured paths resolve under private temp workdir
Not-tested: Live IROS login/payment smoke; requires user credentials/authentication/payment authority
The IROS skill delegates sensitive browser automation to an upstream Playwright implementation, so the execution guide now checks out a reviewed SHA and keeps real inputs and generated files in a private workdir instead of the clone. Regression coverage locks the pin and privacy-path contract to prevent future docs drift.\n\nConstraint: PR #177 review required an enforceable upstream execution boundary before merge\nConstraint: Live IROS login and payment smoke requires user credentials and card authority\nRejected: Continue documenting mutable upstream HEAD | unsafe for authenticated legal-document/payment-adjacent flows\nConfidence: high\nScope-risk: narrow\nDirective: Do not update iros-registry-automation/scripts/upstream.pin without reviewing the new upstream diff and updating the documented checkout SHA\nTested: node --test --test-name-pattern='iros-registry-automation' scripts/skill-docs.test.js\nTested: ./scripts/validate-skills.sh\nTested: npm run lint && npm run typecheck && npm test\nTested: npm run ci\nTested: cloned upstream, checked out pinned SHA, rewired config.json to a private temp workdir, and verified selected paths stay under that workdir\nNot-tested: Live IROS login/payment smoke; requires user credentials, certificate/authentication, and payment authority
Issue #175 needs a 등기부등본 skill grounded in the challengekim reference implementation while preserving user control over IROS login, authentication, and payment. Add a docs-first skill with regression coverage that locks the upstream credit, safety boundaries, and repository documentation wiring.
Constraint: Original author link must be mentioned in documentation.\nConstraint: IROS login, certificate authentication, and card payment must remain user-controlled.\nRejected: Add a packaged automation wrapper | no dependency or executable implementation was required and credential/payment flows are high-risk.\nConfidence: high\nScope-risk: narrow\nDirective: Do not remove the challengekim upstream credit or weaken the manual login/payment boundary without a new review.\nTested: node --test --test-name-pattern='iros-registry-automation' scripts/skill-docs.test.js; ./scripts/validate-skills.sh; npm run ci\nNot-tested: Live IROS smoke with real login/payment, intentionally not run without user credentials and payment authority
Merged origin/dev into feature/#168 and resolved the README table conflict by preserving dev's skill-name column while keeping the corporate-registration-consulting row. The README docs regression mapping now includes the new skill so future table checks cover it.
Constraint: PR #169 must remain reviewable after updating from dev without merging the PR itself
Rejected: Keep the old four-column README row | it would drop dev's issue #165 skill-name column contract
Confidence: high
Scope-risk: narrow
Tested: node --test --test-name-pattern='corporate-registration-consulting' scripts/skill-docs.test.js
Tested: node --test --test-name-pattern='README skill table' scripts/skill-docs.test.js
Tested: npx --yes k-skill-rhwp create-blank <tmp>/blank.hwp and info <tmp>/blank.hwp
Tested: npm run ci
Tighten the Korean corporate registration skill after round-3 review by keeping filled HWP examples outside the repository, turning the investigation-report conclusion into a user/expert-confirmed placeholder, and locking human-only final action prohibitions with regression coverage.
Constraint: Legal-document workflow must avoid collecting or committing filled PII artifacts
Constraint: Agent may prepare drafts and checklists only, not final legal/tax conclusions or filings
Rejected: Add out/ to .gitignore | safer to teach non-repo private output for sensitive generated forms
Confidence: high
Scope-risk: narrow
Tested: node --test --test-name-pattern='corporate-registration-consulting' scripts/skill-docs.test.js
Tested: npx --yes k-skill-rhwp create-blank <tmp>/blank.hwp && npx --yes k-skill-rhwp info <tmp>/blank.hwp
Tested: npm run ci
Round-two review showed that the new consulting skill still needed explicit stop gates for non-standard incorporation paths and tighter documentation regression locks. The follow-up keeps the user-facing flow beginner-friendly while routing materially different legal/tax structures to official or professional review before draft generation.
Constraint: Legal-document skill must remain reference-only and avoid implying filing, tax, or governance determinations for non-standard cases
Rejected: Keep broad regex alternations for human-only boundaries | they allowed prior safety requirements to regress while tests still passed
Confidence: high
Scope-risk: narrow
Directive: Do not collapse the separate safety-boundary assertions back into alternations without a stronger replacement
Tested: node --test --test-name-pattern='corporate-registration-consulting' scripts/skill-docs.test.js
Tested: npx --yes k-skill-rhwp create-blank <tmp>/blank.hwp && npx --yes k-skill-rhwp info <tmp>/blank.hwp
Tested: npm run ci
The review follow-up closes legal-document safety gaps before merge by locking the expected guidance in the docs regression test and updating the skill surfaces that users and agents rely on. The representative-director clause now avoids board-resolution wording for the common two-director/no-board case, registration-license tax points to the direct 지방세법 제28조 anchor, and PII plus human-only filing boundaries are repeated where filled document workflows can expose sensitive data.
Constraint: PR review requested TDD coverage for legal/tax safety wording and privacy guidance
Rejected: Keep a single generic disclaimer only | document templates also need local warnings where filled artifacts are produced
Confidence: high
Scope-risk: narrow
Directive: Do not remove the repeated privacy and human-only boundaries unless every user-facing generation surface keeps equivalent guidance
Tested: node --test --test-name-pattern='corporate-registration-consulting' scripts/skill-docs.test.js
Tested: npx --yes k-skill-rhwp create-blank <tmp>/blank.hwp && npx --yes k-skill-rhwp info <tmp>/blank.hwp
Tested: npm run ci
Add a reference-only corporate registration consulting skill for first-time Korean incorporation workflows. The skill keeps user decisions explicit, provides conservative articles/document templates, and routes HWP automation through existing rhwp/kordoc surfaces instead of introducing new machinery.
Constraint: Issue #168 requires legal-disclaimer wording, tax pitfall guidance, rhwp-based form support, TDD, and PR delivery to dev.
Rejected: Add a new package or external automation dependency | existing skill docs and rhwp tooling are enough for this documentation/template workflow.
Confidence: high
Scope-risk: narrow
Directive: Do not present generated registration documents as legal or tax advice; keep official-source verification and professional review caveats visible.
Tested: node --test --test-name-pattern='corporate-registration-consulting' scripts/skill-docs.test.js; npx --yes k-skill-rhwp create-blank/info smoke; npm run ci
Not-tested: Live court registry submission or live tax payment, intentionally outside reference-skill scope
Surface every skill's directory identifier (e.g. `kbl-results`,
`real-estate-search`) directly in the "어떤 걸 할 수 있나" table so users
can search README and copy-paste the exact name into install commands or
agent frontmatter without leaving the page.
- README.md: insert `스킬 이름` column after `할 수 있는 일` for all 54
rows (5-column header, separator, and per-row inline-code identifier);
apply matching strikethrough to the deprecated blue-ribbon-nearby cell.
- scripts/skill-docs.test.js: add 4 regression tests pinning the header
shape, the 53 active label↔skill-name mappings, the strikethrough on
the deprecated row, and a cross-check that every advertised skill
identifier matches a real on-disk SKILL.md whose frontmatter `name`
agrees (validate-skills.sh invariant).
* feat: add catchtable-sniper skill
* Make the Catchtable skill loadable and discoverable
The submitted skill landed under skills/ without YAML frontmatter, which broke the repo's auto-discovery contract and Codex skill loading. Move it to the root-level skill layout, add the required metadata block, and document the feature in the main README plus a dedicated guide so the PR ships in a usable state.
Constraint: This repository auto-discovers skills from root-level directories only
Constraint: Skill manifests must start with YAML frontmatter for Codex to load them
Rejected: Keep the nested skills/catchtable-sniper layout | validate-skills and the repo's documented convention reject it
Rejected: Add only README links without a feature guide | would create a broken documentation target
Confidence: high
Scope-risk: narrow
Reversibility: clean
Directive: Future skill PRs should follow docs/adding-a-skill.md and place each skill in its own root directory
Tested: node --test scripts/skill-docs.test.js
Tested: ./scripts/validate-skills.sh
Tested: git diff --check
Not-tested: End-to-end Catchtable reservation completion on a logged-in account
---------
Co-authored-by: Jeffrey (Dongkyu) Kim <vkehfdl1@gmail.com>
Round-3 review flagged two non-blocking doc-completeness nits in docs/features/naver-news-search.md:
- 실패 모드의 `400 bad_request` 항목이 preflight 케이스(`start + display - 1 > 1000`)를 누락하고 있었음. SKILL.md line 94 와 본문 line 128 의 '운영 팁' 과 대칭이 되도록 업데이트.
- 운영 팁의 canonical dedup 설명이 쿼리 파라미터 순서와 trailing slash 만 언급해서, 실제 구현(`canonicalizeLinkForDedup`)이 같이 정규화하는 host 대소문자와 URL fragment 를 빠뜨리고 있었음. test/naver-news.test.js line 273 이 네 가지 모두 검증하고 있으므로 공개 문서를 구현과 테스트에 맞춰 정정.
Round 2 review flagged a latent Unicode safety bug: when replaceAll's
caseSensitive=false branch encounters characters whose toLowerCase()
changes UTF-16 length (e.g. Turkish İ U+0130 → i + U+0307 combining dot
above), offsets taken in the lowercased haystack drift by the expansion
delta for every subsequent match and silently corrupt the document.
Reviewer repro: 'ABCİABCİXYZ' + case-insensitive İ→Z reported
{ok:true,count:2} but rendered 'ABCZABCİZYZ' instead of 'ABCZABCZXYZ'
(the X at index 8 was corrupted while the second İ survived).
Surface a descriptive error rather than silently drift:
- findAllMatchOffsets: in the case-insensitive branch, verify that the
paragraph text and the query each preserve UTF-16 length under
toLowerCase; otherwise throw with an actionable message pointing the
user to --case-sensitive or input normalization.
- This is strictly a safety guard: the 2025→2026 headline workflow,
ASCII, Hangul, and every existing test are unaffected.
Tests (TDD red → green, net +4 in packages/k-skill-rhwp):
- 'replaceAll refuses case-insensitive matching when source text
contains case-folding length-changing chars (e.g. Turkish İ U+0130)'
reproduces the exact reviewer input and asserts rejection + no output
file
- 'replaceAll refuses case-insensitive matching when the query itself
contains case-folding length-changing chars' covers the query-side path
- 'replaceAll with --case-sensitive succeeds on inputs containing İ'
confirms the guard only fires in the case-insensitive path and that
case-sensitive produces ABCZABCZXYZ with no X corruption
- 'replaceAll case-insensitive still works for normal ASCII/Hangul'
regression-guards against the fix over-rejecting the common case
Doc disclosure in all 4 surfaces called out by the reviewer:
- rhwp-edit/SKILL.md: new failure-mode bullet naming U+0130 specifically
- docs/features/rhwp-edit.md: Unicode 대소문자 무시 주의 paragraph
under scenario 3 (replace-all)
- packages/k-skill-rhwp/README.md: extended Scope section
- packages/k-skill-rhwp/src/cli.js: USAGE 'Scope note' appended
- scripts/skill-docs.test.js: 2 new assertions locking the SKILL.md and
feature-doc disclosure so they can't be silently removed
- .changeset: note the guard in the pending v0.1.0 release notes
Manual QA (end-to-end via the published CLI):
$ k-skill-rhwp replace-all … --query İ --replacement Z
→ exit 1 + 'case-insensitive matching is unsafe because case folding
changes the UTF-16 length …'
→ no output file written
$ k-skill-rhwp replace-all … --query İ --replacement Z --case-sensitive
→ {ok:true,count:2}, render shows 'ABCZABCZXYZ', search İ ⇒ found:false
$ replace-all '2025'→'2026' on '2025 2025 2025' ⇒ {ok:true,count:3}
$ replace-all 'hello'→'hi' (case-insens.) on 'hello WORLD 안녕 HELLO'
⇒ {ok:true,count:2}
Verification:
- npm test --workspace k-skill-rhwp: 35 pass / 0 fail (+4 vs Round 2)
- node --test scripts/skill-docs.test.js: 114 pass / 0 fail
- npm run ci: exit 0 (lint + typecheck + all workspace tests +
pack:dry-run + validate-skills.sh all green)
Refs PR #162 Round 2 review 'Non-blocking residual risk — Unicode
case-insensitive offset drift'.
Upstream @rhwp/core HwpDocument.replaceAll returns {ok:true, count:N} but
does not persist the mutation into exportHwp() serialization, so the output
bytes are byte-identical to the input. This is confirmed against
@rhwp/core@0.7.3 with SHA diffing and round-trip searchText.
Rewrite the Node wrapper replaceAll to compose engine primitives that do
persist: for each body paragraph, read the full text via getTextRange,
compute all non-overlapping match offsets in JS, then apply replaceText
right-to-left so earlier offsets are unaffected by length changes. This
restores the documented '2025 → 2026 일괄 치환' headline workflow.
Guard rails in the new replaceAll:
- Reject replacements containing newline or paragraph-break characters
(\n, \r, U+2028, U+2029) with a descriptive error. Splitting a paragraph
via replaceText would invalidate subsequent offsets.
- Non-overlapping semantics against the original text, so
--query a --replacement aa against 'aaa' yields 'aaaaaa' (3 replacements)
instead of looping on the freshly inserted 'a' characters.
Tighten the regression tests to assert content, not just length:
- Same-length replacement: output SHA must differ from input, searchText
must find the replacement and must NOT find the original query.
- Longer-length replacement: paragraph length must grow by the correct
amount and output SHA must differ.
- Shorter-length replacement: paragraph length must shrink by the correct
amount and output SHA must differ.
- Empty replacement: deletes every match and output no longer contains
the query.
- Replacement contains query (a→aa on aaa): expects count 3 and length 6.
- Zero matches: count 0, output still written.
- Case-sensitive flag skips mismatched case.
- Newline replacement is rejected synchronously.
Document the body-only scope of search and replace-all in the SKILL.md
routing policy, failure-modes, CLI USAGE text, feature doc, and package
README so users know to use set-cell-text for cell content. This matches
the upstream searchText contract, which does not descend into table cells,
headers, footers, or footnotes.
Add a matching regression assertion to scripts/skill-docs.test.js so the
body-only scope note cannot be silently removed from SKILL.md or the
feature doc.
Closes review round 1 for PR #162.
Implements the three non-blocking observations from PR #161 round-3 review:
1. Numbered-h2 gate (reviewer-flagged fragility):
Refactored _extract_first_section_between_h2 to extract h2 inner text
(stripping nested tags) and filter by '^\\s*\\d+(?:\\.\\d+)*\\.\\s+\\S'.
Sidebar widgets like <h2>관련 문서</h2> or <h2>외부 링크</h2> can no longer
anchor the extractor - only numbered section headers (1., 1.2., 2.3.4.) do.
Handles live Namu Wiki structure where the number sits inside an <a> tag
(<a>1.</a> <span>개요</span>), which the round-3 suggested regex-only gate
missed. All 29 seed pages continue to produce valid summaries on live
fetches.
2. Category-nav template strip (reviewer-flagged long-page noise):
a. CATEGORY_NAV_RE strips the inline '[펼치기 · 접기]' marker plus its
same-line aftermath (the category list items on the same line).
b. DETAILS_PELCHIGI_RE strips the entire <details> block whose <summary>
contains 펼치기. Namu Wiki today wraps category nav in exactly this
structure, so the strip removes the full noise block (not just the
marker line).
꿀잼 summary drops from 3482 chars of category dump to 562 chars
starting with the real definition '무언가가 매우 재미있다는 의미의 인터넷
유행어'. Non-category <details> blocks (spoilers, footnotes) are
preserved.
3. TDD + mutation coverage:
6 new tests total: 2 numbered-h2 gate tests, 2 inline category-nav tests,
1 <details>-block strip test, 1 <details>-keep test (negative case).
All 6 were written first and confirmed RED against the round-2 baseline,
then made GREEN after the implementation landed. Each fix path was also
mutation-tested (revert regex, remove .sub line) to confirm the tests
genuinely catch the target bug class.
Suite grows from 45 to 51 tests. All pass. npm run ci exits 0.
Namu Wiki's current HTML layout uses build-time-obfuscated CSS class
names (e.g. _36R8DWTn, OZVChh+l) and has no <article>/<main>/<section>
tags, so all six MAIN_CONTENT_CLASSES anchors fail to match and
extract_summary() returned empty with a 'Main content region not
detected' warning on every live page.
Replace the single class-based strategy with a three-tier fallback
chain that pins to progressively weaker but more structurally stable
anchors:
1. First h2 section boundary. Namu Wiki articles consistently open
with '<h2>1. 개요[편집]</h2>' and mark subsequent sections with
numbered h2 headings. Extracting text between the first and
second h2 reliably captures the overview section on every page
sampled (중꺾마, 갓생, 럭키비키, 어쩔티비).
2. MAIN_CONTENT_CLASSES / <article> - kept as a legacy fallback
for older Namu Wiki layouts and for third-party fixtures.
3. og:description meta tag - final safety net before returning
empty, gives the agent at least a ~64-char preview when the
article has unusual structure.
Strip '[편집]' edit-affordance markers and numbered section prefixes
(e.g. '1.2.') from the extracted text so headings don't leak through
as noise.
Live verification (text format):
slang_lookup.py 중꺾마 -> Title + 286-char summary
slang_lookup.py 갓생 -> Title + 96-char summary
slang_lookup.py 럭키비키 -> Title + 59-char summary
slang_lookup.py 어쩔티비 -> Title + 20-char summary
All previously-empty. Not-found / blocked / upstream-error paths and
exit codes are unchanged.
Reviewer flagged 4/30 seed namuwiki_url values returning HTTP 404 on live
Namu Wiki. These URLs are part of the documented response contract and get
surfaced directly to agents, so broken links are a functional bug, not a
cosmetic one.
Root causes per entry:
- 중꺾마: wrong 꺾 codepoint (U+AFFA 꿺 instead of U+AEBE 꺾).
- 아아: typo in aliased title (아이스 아메리칸노 instead of 아메리카노).
- 어쩔티비: missing 받침 (어쩌티비 instead of 어쩔티비).
- 당모치: encoding correct but no live Namu Wiki article exists; dropped.
Also fixes two separately-broken 중꺾마 example URLs in SKILL.md
(U+AFBE 꾾 instead of U+AEBE 꺾) — these were discovered while auditing
the seed and would have surfaced as 404 to agents following the example
snippets.
Adds two regression tests:
- test_each_seed_url_decodes_to_term_or_alias: decodes every seed URL's
path segment and asserts it equals the term or one of its aliases.
Catches Hangul-codepoint typos offline (no network dependency) and
would have caught all 3 encoding bugs in this PR.
- test_no_seed_entry_points_at_known_missing_namuwiki_page: locks the
당모치 drop so nobody re-adds an entry pointing at a page that does
not exist on Namu Wiki.
Fixes the existing LookupNetworkTest assertion that was hard-coding the
broken URL — it now derives the expected URL via build_namuwiki_url()
so the test cannot drift out of sync with the helper again.
Verification:
- PYTHONPATH=.:scripts python3 -m unittest scripts.test_korean_slang_writing -> 40/40 pass
- Live GET with browser headers against all 29 remaining seed URLs -> 29/29 return 200
- npm run ci -> exit 0
- Manual QA: slang_search on 중꺾마, 어쩔티비, 아이스 아메리카노 returns
correct URLs; slang_lookup live-fetches 중꺾마 and extracts the
canonical title '중요한 것은 꺾이지 않는 마음'.
Address the three non-blocking items flagged in the round 1/2 reviews. All
were explicitly deferred by the reviewer as "follow-up if the maintainer
wants" — picking them up now so the feature lands with a tighter surface.
1) Preflight 400 for start + display - 1 > 1000
Naver's official news endpoint only exposes the first 1000 items
(start 1..1000, display 1..100). Asking for start=1000 & display=100
would send a request that silently returns no usable items, wasting
an upstream quota call. Reject the combination before calling upstream
with a 400 bad_request and a message that tells the caller which item
the request would have needed and what the cap is. Boundary values
(start + display - 1 === 1000) are still accepted.
2) Canonical link dedup
The previous dedup key was link.toLowerCase(), which failed to merge
the same article when Naver's redirect URLs differed only by query-param
order, trailing slash, host-name casing, or fragment. Added
canonicalizeLinkForDedup() which parses the URL, sorts search params by
key, strips a single trailing pathname slash, drops the fragment, and
lowercases the result — conservative on purpose so different paths or
different query values stay as distinct articles. The visible
items[].link value is still the original URL returned by Naver; only
the dedup key is canonicalized.
3) Clarify the naverSearchApiConfigured vs naverNewsApiConfigured split
The two flags currently evaluate the same boolean, but their semantic
contracts differ: naverSearchApiConfigured reports "are the Naver
Open API keys configured" (which is advisory for the shopping route
since shopping has a BFF fallback), while naverNewsApiConfigured
reports "is the news route operational end-to-end" (no fallback — 503
when false). Hoist the shared expression into a local, and add a
`/health 업스트림 플래그 의미` section to packages/k-skill-proxy/README.md
documenting the split. Also update naver-news-search SKILL.md and
docs/features/naver-news-search.md to mention the new preflight and
the canonical-link dedup behavior.
TDD verification: added 4 new node:test cases exercising the boundary,
overflow, and URL-dedup paths; ran the full k-skill-proxy workspace
suite (202/202 pass) plus the root `npm run ci` (exit 0). Manual QA on
a proxy started from this commit reproduces every round-1 case plus the
new preflight: start=1000 & display=100 → 400 bad_request before
upstream; start=1000 & display=1 and start=901 & display=100 → 503 (or
200/401 depending on keys), confirming the boundary passes preflight.
Pins the HWP table row rename to 'HWP 문서 조회/변환', asserts the new
'HWP 문서 편집' and 'HWP 레이아웃·IR 디버깅' README rows and their linked
feature docs, pins the new SKILL.md routing policy for rhwp-edit and
rhwp-advanced (k-skill-rhwp CLI + @rhwp/core for editing vs upstream
Rust CLI for layout/IR debugging), and asserts the k-skill-rhwp
package.json wiring (bin mapping, @rhwp/core dependency, Node 18+
engines, wasm-init shim + CLI bin files).
Per AGENTS.md rule, no assertion is added on the presence of any
.changeset/*.md file so the changeset release flow can consume the
rhwp-edit-skill.md entry without breaking CI at version-bump time.
Also captures the package-lock.json delta introduced by adding the
k-skill-rhwp workspace (pulls @rhwp/core@0.7.3 and its WASM binary).
Refs #155.
The prior commit 4c7877a on this branch renamed the HWP feature row to
'HWP 문서 조회/변환' and added two new rows ('HWP 문서 편집',
'HWP 레이아웃·IR 디버깅') pointing at docs/features/rhwp-edit.md and
docs/features/rhwp-advanced.md. Those docs do not exist on any branch
in this repo, and the rename violates scripts/skill-docs.test.js
assertions at lines 210, 223, 224, which caused the CI 'validate' job
to fail.
Those changes belong to a separate rhwp-edit/rhwp-advanced feature
effort (tracked elsewhere), not to issue #143 'naver-news-search'.
Revert README.md in both the feature table and the list section so the
only additions in this PR relative to origin/dev are the two
in-scope naver-news-search entries.
Verified by running 'npm run ci' locally (EXIT=0). skill-docs.test.js
now passes 110/110 (previously failed 2/110) and the full
k-skill-proxy suite remains 198/198 including the 14 naver-news tests.
* ✨ feat: add k-dart skill for DART OpenAPI financial disclosures
금감원 전자공시시스템(DART) 14개 endpoint 조회 스킬 추가.
공시검색, 기업개황, 재무제표, 배당, 증자/감자, 전환사채, 소송 등.
API_K_DART 환경변수로 직접 호출하며 프록시 불필요.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* 📝 docs(k-dart): remove redundant korean-stock-search dependency
corpCode.xml 자체에 회사명·종목코드·고유번호가 모두 포함되어 있으므로
korean-stock-search 스킬 연계 절차 제거
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* 📝 docs: add k-dart to README feature table
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* 📝 docs: add k-dart feature guide and fix README link format
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* 🐛 fix(k-dart): correct status code 013, remove invalid corp_name filter, update daily limit
3개 critical 정확성 오류 수정:
1. 상태코드 013은 "조회된 데이터 없음"이며 "접근 권한 없음"이 아님 (012=접근 불가 IP).
상태코드 표를 공식 명세 기준으로 재정리하고 누락된 014/021 코드 추가.
2. list.json은 corp_name 파라미터를 검색 필터로 지원하지 않음. SKILL.md의
잘못된 진술과 corp_name을 사용한 misleading example을 제거하고, corp_code
확보 절차를 거치도록 명시.
3. DART 일일 한도는 키당 10,000건이 아닌 20,000건이며 분당 약 1,000회
throttle도 별도로 존재함. SKILL.md 및 docs/features/k-dart.md 모두 정정.
추가로 status: "013" 발생 시 사용자 안내 정책을 Response policy에 추가하고,
오픈API 이용현황 페이지 링크를 Notes에 추가함.
* 🐛 fix(k-dart): correct pifricDecsn endpoint, list.json corp_code optional, add empSttus, soften throttle claim
Codex adversarial review에서 식별된 4건의 추가 정확성 이슈 수정:
1. endpoint #8 유무상증자 결정이 잘못된 API에 연결됨. piicDecsn.json은
유상증자 결정 (apiId=2020023)이며, 유무상증자 결정은 pifricDecsn.json
(apiId=2020025)이 맞음. endpoint를 정정하고 piicDecsn (유상증자) 및
fricDecsn (무상증자)와의 차이를 주의문으로 추가.
2. list.json의 corp_code 는 사실 선택사항이며, 미지정 시 검색 기간이
3개월 이내로 제한될 뿐임. 이전 commit의 "corp_code 필수" 표현을
정정하고, 두 가지 호출 패턴(corp_code 지정/미지정)을 Example
requests에 모두 추가.
3. "분당 약 1,000회 throttle"은 공식 공개 가이드에 근거 없음
(apiUsageStatusView.do 는 로그인 게이트). 공식 가이드가 명시한
"일반적으로 20,000건 이상 요청 시 020 발생"만 유지하고 분당
throttle 주장을 제거. 상태코드 표·Response policy도 일관되게 정리.
4. docs/features/k-dart.md가 "직원 현황" 기능을 광고하지만 SKILL.md
에는 endpoint가 누락됨. empSttus.json (apiGrpCd=DS002,
apiId=2019011)을 endpoint #8로 추가하고 example도 함께 등록.
기존 endpoint 9~14는 10~15로 재번호.
* 🐛 fix(k-dart): align list.json signature and 020 caveat with official spec
Codex 2nd-round review에서 식별된 정확성 이슈 2건 수정:
1) list.json 요청 인자 signature가 공식 가이드(DS001/2019001)와 정확히
일치하도록 재작성. crtfc_key 외 모든 파라미터가 선택사항임을 분명히
하고, 각 파라미터의 default 동작과 pblntf_ty 값(A/B/C/D/E)도 명시.
"corp_code 지정 시 기간 제한 없음" 표현은 공식 가이드가 보장하지
않으므로 제거. corp_name이 공식 파라미터에 "존재하지 않는다"는
사실로 수정 (이전: "지원하지 않는다").
"corp_code 미지정 시 3개월 제한"은 외부 사용 사례에서 관찰된
동작으로 약화 (공식 가이드에 별도 명시 없음).
2) 020 (요청 제한 초과) 안내가 일일 20,000건 cap 으로 너무 단정적
해석되던 표현을 공식 메시지 그대로 보존: "일반적으로 20,000건
이상 요청 시 발생하며, 키별로 별도 한도가 설정된 경우 다른
임계치에서도 동일 코드가 반환될 수 있음". 상태코드 표·Response
policy·Notes·docs/features/k-dart.md 모두 일관되게 정정.
* 🐛 fix(k-dart): mirror official Korean DS001/2019001 list.json spec exactly
Codex 3rd-round review에서 식별된 잔존 정확성 이슈 수정.
영어 가이드(DE001/AE00001)와 한국어 가이드(DS001/2019001)가 list.json
필수여부에서 다르게 표기되어 있어 이전 commit이 영어 가이드를 따랐으나,
한국어 공식 가이드를 직접 확인한 결과(opendart.fss.or.kr/guide/detail.do
?apiGrpCd=DS001&apiId=2019001) 다음이 한국어 공식 spec임을 확인:
- bgn_de, end_de는 Y(필수) (기본값은 명시되어 있으나 표기상 필수)
- corp_code 미지정 시 검색기간 3개월 제한은 공식 spec에 명시된 룰
(외부 사용 사례 관찰이 아님)
- pblntf_ty는 A~J 전체 enum (정기공시/주요사항보고/발행공시/지분공시/
기타공시/외부감사관련/펀드공시/자산유동화/거래소공시/공정위공시)
- page_count 기본값 10, 최대값 100
- corp_cls 복수 조건 불가
- last_reprt_at, sort, sort_mth 각 default 동작 명시
list.json 섹션을 공식 가이드 표와 1:1 일치하는 마크다운 표로 재작성.
3개월 제한 표현을 "외부 사례"에서 "공식 spec"으로 정정. Response policy
에 잔존하던 corp_name "지원하지 않는다" 표현도 "공식 파라미터에 존재하지
않는다"로 통일하여 #1 endpoint 섹션과 일관성 확보. docs/features/k-dart.md
도 동일하게 정정.
* 🐛 fix(k-dart): make list.json table 1:1 mirror of DS001/2019001 + unify corp_name wording
Codex 4th-round review가 식별한 잔존 이슈 2건 마무리.
1) list.json 파라미터 표를 공식 가이드 행 순서 그대로(crtfc_key,
corp_code, bgn_de, end_de, last_reprt_at, pblntf_ty,
pblntf_detail_ty, corp_cls, sort, sort_mth, page_no, page_count)
재정리하고 공식 표의 모든 컬럼(요청키/명칭/타입/필수여부/값설명)을
포함. page_no(1~n) / page_count(1~100, 기본10, 최대100) 범위
값을 공식 표 그대로 표기. pblntf_detail_ty 값설명도 공식 표
그대로 "(※ 상세 유형 참조: pblntf_detail_ty)"로 두고, 자주 쓰는
코드 예시(A001/B001/F001/D001)는 표 아래 별도 단락으로 분리해
표의 1:1 mirror 성격을 유지.
2) corp_name 관련 canonical 문장 "공식 요청 파라미터 표에
corp_name 은 존재하지 않는다" 를 다음 3곳 모두 verbatim 일치
시킴 (이전 commit에서 SKILL.md는 '않는다', docs/features는
'않음' 으로 어미 차이가 잔존했음):
- k-dart/SKILL.md #1 endpoint 섹션 주의문
- k-dart/SKILL.md Response policy
- docs/features/k-dart.md 에러/제약 섹션
* 🐛 fix(k-dart): unify corp_name canonical sentence verbatim + soften list.json table claim
Codex 5th-round review가 식별한 fine-grained 이슈 마무리.
1) corp_name canonical 문장을 self-contained 형태로 재작성하여
3곳 모두 byte-for-byte 동일하게 통일:
"DART OpenAPI list.json 의 공식 요청 파라미터 표에 corp_name 은
존재하지 않는다."
- SKILL.md #1 endpoint 섹션 주의문
- SKILL.md Response policy
- docs/features/k-dart.md 에러/제약 섹션
이전에는 SKILL.md는 "위 공식 요청 파라미터 표에"로 docs/features는
"list.json 공식 요청 파라미터 표에" 로 prefix가 달라 verbatim
일치하지 않았음.
2) list.json 표 헤더 문구를 "공식 가이드 표를 그대로 옮긴 것"에서
"공식 가이드 요청 인자 정리 (필수여부·기본값·허용값은 공식 표
기준, 식별자는 코드 폰트로 표기)"로 약화. 마크다운 backtick 등
포매팅 차이가 "1:1 mirror" 약속과 모순되지 않게 정확히 표현.
---------
Co-authored-by: hon2be <hon2be>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Co-authored-by: Jeffrey (Dongkyu) Kim <vkehfdl1@gmail.com>
Splits HWP handling into three focused skills per issue #155:
- hwp (kept): kordoc-based read/convert (Markdown, JSON, diffing, form
fields, Markdown->HWPX). Description narrowed to 'read-only' to make
the routing policy explicit.
- rhwp-edit (new): HWP binary editing via new k-skill-rhwp npm package
that wraps the @rhwp/core WASM bindings as CLI subcommands: info,
list-paragraphs, search, insert-text, delete-text, replace-all,
create-table, set-cell-text, create-blank, and render.
- rhwp-advanced (new): guidance for the upstream Rust rhwp CLI
(export-svg --debug-overlay, dump, dump-pages, ir-diff, thumbnail,
convert) for layout debugging, IR inspection, version comparison,
and read-only-document unlocking.
The new k-skill-rhwp package under packages/ ships a Node.js 18+ CLI
and library that round-trips HWP 5.x documents entirely in-process; no
Rust toolchain is required. It auto-installs the WASM-required
globalThis.measureTextWidth shim for headless Node, and all editing
subcommands always write to a distinct output path so the source file
is never mutated. HWPX save remains disabled per the upstream rhwp
#196 data-safety gate; HWPX input is accepted but output is written as
HWP 5.x.
Includes 24 node:test cases covering init, round-trip insertText,
replaceAll, createTable + setCellText, deleteText, searchText,
listParagraphs, renderPage (SVG/HTML), and full CLI arg-parse +
end-to-end round-trip through the CLI layer.
Wires README feature table (3 rows for hwp / rhwp-edit / rhwp-advanced),
docs/install.md optional-install list, docs/roadmap.md (marks HWP
advanced editing as shipped while keeping Windows/security-module
automation out of scope), docs/sources.md (adds rhwp upstream, CLI
source, @rhwp/core, @rhwp/editor, and rhwp #196 references), and the
root pack:dry-run script. Adds a Changesets entry for k-skill-rhwp
minor.
Closes#155.
Closes#143. Proxies the official Naver Search Open API news endpoint
(openapi.naver.com/v1/search/news.json) through k-skill-proxy so users do
not need to issue their own Naver Client ID/Secret. Reuses the existing
NAVER_SEARCH_CLIENT_ID/NAVER_SEARCH_CLIENT_SECRET that naver-shopping already
consumes, since the Naver Developer application enables the 'Search' scope
covering both news and shopping.
Implementation details:
- src/naver-news.js normalizes q/display/start/sort, builds the official URL,
calls upstream with X-Naver-Client-Id/Secret headers, and parses the JSON
response into rank/title/description/link/original_link/pub_date items.
- Strips <b> highlight tags and decodes HTML entities in title/description
using zero-width replacement so compound Korean words like '주식형' are
preserved (not split into '주식 형').
- Parses RFC822 pubDate into pub_date_iso (ISO-8601 UTC) for clients.
- Deduplicates items by normalized link; drops entries missing title/link.
- Returns 503 upstream_not_configured when proxy keys are absent (no public
BFF fallback exists for news like it does for shopping, so keys are
required).
- Failure responses are not cached (failure-aware cache layer).
- Exposes naverNewsApiConfigured on /health.
14 new tests in test/naver-news.test.js cover query validation, URL
building, payload normalization (HTML stripping, entity decoding,
deduplication, missing-field tolerance), plus Fastify integration tests
for 200/400/401/429/500/503 paths, cache hit/miss, header wiring, and
the health flag.
Adds a 12-line header comment to the 'lh-notice detail does not cache
upstream XML auth errors so retries self-heal' test in server.test.js
naming the two cache-protection layers it pins:
(a) the early-return catch block in the route handler (no cache.set
on upstream failure), and
(b) the isFailureResponse() guard inside cache.set (refuses any
payload with .error set).
Points future maintainers to the independent sabotage audit in PR #158
Round 3 review that proved bypassing either layer alone makes the
State 2 self-heal assertion fail, and cross-links the sibling /search
failure-not-cached test for symmetric coverage.
Addresses the Round 3 non-blocking observation #2 nice-to-have.
Test-only, comment-only: +12 lines, 0 source changes, 0 behavior
changes, 0 doc changes, 0 changeset changes. server.test.js remains
96/96, lh-notice.test.js remains 38/38, full proxy workspace 184/184.
Round 2 review noted that /v1/lh-notice/detail failure-not-cached
behavior was only verified via manual QA, while /search had an
explicit automated regression test.
This adds an equivalent automated test for /detail that:
- fails upstream once (XML SERVICE_KEY error, upstream_code=30)
- confirms first call returns 502 with cache.hit=false
- switches upstream to success and retries the same URL
- confirms second call returns 200 with cache.hit=false (failure was
NOT cached, retry hit upstream again)
- sabotages upstream back to failing and verifies the third call
serves the previously-cached success (cache.hit=true, no new fetch)
Verified the test genuinely catches regressions by temporarily
monkey-patching the detail route to cache error payloads — the test
correctly fails in that sabotaged state and passes when the route is
correct. Full server.test.js suite goes from 95 to 96 tests, all pass.
Per review note #4 on PR #158, extractNoticeEnvelope accepts four upstream
CMN.CODE values ("SUCCESS", "0", "00", "000") and three header.resultCode
values ("0", "00", "000") as success. This is deliberate: the data.go.kr
platform has surfaced different forms across catalog eras, and a future
normalization that flips SUCCESS to a numeric form must not regress into
502'ing otherwise-valid responses.
- Add an inline comment above the array-envelope success-code check in
src/lh-notice.js explaining why the accept-list is NOT redundant.
- Add regression tests in test/lh-notice.test.js that explicitly exercise
each accepted success code (SUCCESS/0/00/000 for array envelope; 0/00/000
for object envelope) so a future refactor cannot silently collapse the
accept-list.
- Add a paired rejection test that numeric-looking non-success codes like
"22" and "10" still raise as upstream_error, disambiguating the
accept-list from a blanket 'any numeric string passes' rule.
Test count: lh-notice.test.js 30 -> 38 (all pass); npm run ci exits 0.
Wraps the official data.go.kr LH (Korea Land & Housing Corporation) 청약
공고 Open API (B552555/lhLeaseNoticeInfo1/*) so agents can look up LH
임대/분양/주거복지/토지/상가 공고 by region, status, category, keyword,
and notice ID without asking users for a ServiceKey. Reuses the shared
DATA_GO_KR_API_KEY the proxy already manages; users see '불필요'.
Adapter handles both the LH-specific [CMN, dsList] JSON envelope and the
standard data.go.kr <OpenAPI_ServiceResponse> XML error envelope; refuses
to cache failure responses so transient upstream errors self-heal.
Closes#145.
