# Hangeul-mcp — progress log

## 2026-07-08 — Planning phase (plan-first run)
- Created PLAN.md (architecture, MCP tool API, FieldSchema data model, roadmap M0-M4, test strategy, risks, open questions).
- Created prd.json with 13 concrete user stories (US-000 approval gate .. US-012 release).
- Assets carried from prototype (workspace): working XML fill engine — analyze (rowAddr/colAddr+span), line-break->paragraph, bullet dedup, spacing normalize, byte-preserving repack, inline-blank discovery.
- Proven learnings to encode in engine:
  * kordoc fill_form emits raw \n inside <hp:t> -> overlap; must convert to paragraphs.
  * BULLET paraPr cells auto-add marker -> don't add manual "-"/"∘".
  * ElementTree drops XML declaration standalone="yes" -> must byte-preserve, not re-serialize.
  * Complex forms: merged 2D layouts + inline blanks (mid-sentence) are the hard, differentiating cases.
- STATUS: awaiting user approval of PLAN.md + answers to 5 open questions (section 10). Build loop (M0->M4) starts after approval.

## Substrate decision (pending US-002 spike)
- Candidate: python-hwpx (byte-preserving patch, mature) as substrate + our understanding/inline/fill layer on top.

## Next
- US-000 approval gate: user reviews plan, confirms repo location + decisions.

## 2026-07-08 — Decisions locked, build approved (US-000 passes)
- D1 substrate: own byte-preserving engine + python-hwpx (XSD validation, security).
- D2 matching: field_id authoritative + label alias.
- D3 .hwp: v1 auto-convert to HWPX (COM-first, LibreOffice/H2Orestart fallback).
- D4 name: hangeul-mcp; PyPI deferred to v1.0.
- D5 git remote: pblsketch/Hangeul-mcp (private), push now.
- NEXT: ralph build M0 (scaffold) -> M1 (core engine port) -> M2 (MCP server v1).

## 2026-07-08 — Build progress (ralph iters)
- US-001 scaffold: pyproject, packages, entrypoint, smoke tests. PASS.
- US-002 owpml: HwpxPackage byte-preserving container. 5 tests. PASS.
- US-003 analyze: tables/cells/spans/bullet/spacing. 7 tests. PASS.
- US-004 understand: 2D label-value mapping (merged-cell aware). 4 tests. PASS.
  * Proven on real form: 성명->r2.c3, 직위->r2.c2, 휴대전화->r2.c7 (value cells, not labels).
- Total: 18 tests green. NEXT: US-005 inline-blank, US-006 fill engine.

## 2026-07-08 — M1 core engine COMPLETE
- US-006 fill engine: raw-XML byte-preserving fill via cellAddr location (nesting-aware).
  * set (empty/self-closing runs), append (bullet dedup), inline (marker + multi-paragraph colon).
  * multi-line -> real <hp:p> (no raw \n); spacing normalize via cloned charPr; declaration/mimetype preserved.
  * verified: only target cells change, other entries byte-identical. 9 tests.
- Total: 32 tests green. M1 (owpml/analyze/understand/inline/fill) done.
- NEXT: M2 — US-007 MCP server (FastMCP stdio), US-008 client configs.

## 2026-07-08 — M2 COMPLETE (v1 headless done)
- US-007 MCP server (FastMCP stdio): detect_format/analyze_form/fill_form/extract_text. 5 tests.
- US-008 client docs (Claude Desktop/Codex/Antigravity) + real stdio client integration test.
  * a standard MCP client spawns `python -m hangeul_mcp.server`, lists 4 tools, calls one. PASS.
- Total: 38 tests green. v1 headless functionally complete (M0+M1+M2).
- NEXT: M3 — US-009 COM bridge (pyhwpx, env-guarded), US-010 apply_to_open_hwp.

## 2026-07-08 — M3 COM live-apply (code complete, live-verify pending desktop)
- US-009 hangeul_core/hwp/com.py: HwpBridge (available/connect/status/get_field_list/put_field_text).
  * env-guarded: available() import-only (no dispatch); off-Windows/no-pywin32 -> graceful.
  * security prompt via RegisterModule(FilePathCheckerModule).
- US-010 server tools: hwp_status (side-effect free), apply_to_open_hwp (normalize -> put_field_text).
  * returns needs_field_registration when no 누름틀; graceful when unavailable.
- Tests: 6 (5 run + 1 live-gated skip). Suite 44 passed, 1 skipped.
- NOTE: live COM (actual fill into open 한글) must be verified on the user's desktop
  with `HANGEUL_MCP_LIVE=1` — cannot run from headless CI/session.
- NEXT: US-011 skill, US-012 CI + .hwp convert policy + release.

## 2026-07-08 — M4 COMPLETE / v0.1.0
- US-012: hangeul_core/convert.py (.hwp->.hwpx via COM, guarded); wired into analyze_form/fill_form (graceful error without 한글).
- .github/workflows/ci.yml (ubuntu, py3.11-3.13). README Quickstart. Version bumped 0.1.0.
- Suite: 48 passed, 1 skipped (live COM). ALL 13 stories pass.
- Next external step: codex QA review.

## 2026-07-08 — Codex QA round + hardening (v0.1.0)
- codex exec (xhigh) reviewed against acceptance criteria; found & reproduced 5 issues, all fixed:
  * HIGH multi-section fill (Cell.section/table_in_section; fill per-section).
  * HIGH inline marker double-marker (anchor-specific dedup).
  * MED merged covered-coordinate mapping (understand._occupancy grid).
  * MED .hwp convert COM error -> RuntimeError (graceful).
  * LOW byte-preservation wording clarified.
- Round-1 fixes (also codex): _find_cell_span spillover, CRLF, unused imports.
- Regression tests added (test_qa_regress, test_fill_regress). Suite: 55 passed, 1 skipped. pyflakes clean.
- See docs/qa-codex-v0.1.0.md. STATUS: v1 headless done + v2 COM scaffolded (live-verify pending desktop).
