feat(#3703): 계획 실행기 rhwp run — 선언적 편집 계획의 정적 선검증·원자 실행·저널 (#3608 실행 3층) — #3705 적층

[kevin9327]

요약 (#3703 · #3608 실행 3층 · #3705 적층)

에이전트 실패의 뿌리는 다단 체이닝입니다 — 호출 사이에서 상태를 잃고, 중간 실패가
반편집 문서를 남깁니다. 이 PR은 절차(도구 호출 나열) 대신 의도(계획서) 를 받는
3층, 계획 실행기 rhwp run 을 신설합니다.

이 PR은 #3705(edit --verify) 위에 적층되어 있습니다 — verify 단언이 그 헬퍼를
재사용합니다. 마지막 커밋 1개가 본 변경입니다.

동작

{ "planVersion": "1.0", "input": "서식.hwp", "output": "제출본.hwp",
  "steps": [
    { "action": "fill_fields", "data": {"성명":"홍길동"} },
    { "action": "replace_text", "find": "2025년", "replace": "2026년" },
    { "action": "set_cell", "table": 1, "row": 0, "col": 0, "text": "값" },
    { "action": "set_checkbox", "occurrence": 1 }
  ],
  "assertions": { "notFoundEmpty": true, "verify": true } }

rhwp run plan.json --json (파일 대신 --plan-json '<인라인>' 가능):

1. 정적 선검증(실행 0) — 필드 존재·순번(collect_all_fields 계수)·치환 일치 건수
   (grep 읽기 전용)·셀 좌표(resolve_table_cell)·□ 계수를 전부 미리 검사. 위반을
   한 번에 모아 invalid[{step,action,reason}] + exit 2. 출력 파일을 아예 만들지
   않습니다(두더지잡기 방지 + 실행 0 증명).
2. 원자 실행 — 전 step 을 인메모리 IR 에만 적용. 중간 실패 = 디스크 무변경.
   set_cell 좌표는 앞 step 편집으로 밀릴 수 있어 실행 시점에 재해석합니다.
3. 사후 단언 → 단 한 번 저장 — assertions.verify 는 [내성 P2] 편집 --verify 내장 — 저장 직후 자기검증 봉투(verify:{identical,diffCount})와 exit 3 (#3630 3호) #3702 edit_verify_report
   재사용(저장 바이트 재파싱↔IR 대조). 실패 시 저장 없이 exit 3 — 자연 트랜잭션.
4. 저널 봉투 — step 별 결과(filledCount/ambiguous·replacedCount·oldText) + verify
   • assertions 에코. 무엇이 어떻게 됐는지 기계 판정 가능.

새 편집 로직 0 — 판정자와 적용자가 기존 edit 3종과 동일 함수입니다.
MCP hwp_run_plan{plan} 은 capabilities 단일 출처에 cmdTemplate 로 등록해
mcp-serve 본체 무변경입니다. help·capabilities 명령 목록 동기화 포함.

실측 (mydocs/report/task_m100_3703/evidence.txt)

1. 정상 계획(fill+replace, verify:true): 저널 steps 2건 + verify identical:true + exit 0.
2. 위반 2종 계획: invalid[] 에 두 위반 동시 보고, exit 2, 출력 파일 부재 = 실행 0 증명.
3. MCP hwp_run_plan 인라인: isError:false + structuredContent 동일 저널.

검증

• 신규 run_plan_contract 6건 green: 선검증 exit 2·출력 부재 / 중간 불가 원자성 /
  저널-단언 정합 / 왕복 재독(fields 재독으로 새 값 확인) / capabilities 선언 / MCP 저널
• 무회귀: cli_json_contract 22 · edit_verify 4 · fill 7 · replace 4 · set-cell 5 · mcp_server 4
• clippy -D warnings 0 · fmt clean

처리결과문서

• mydocs/report/task_m100_3703/README.md

🤖 Generated with Claude Code