← Docs hub

A2A Planner Cleanup Backlog

이 문서는 A2A Planner Deep Dive의 18. 남은 정리 과제를 실행 가능한 backlog로 풀어쓴 것이다. 목적은 단순 문서 보강이 아니라, planner prompt, response schema, registry, agent catalog, second pass, schedule slot, ODL task contract 사이의 drift를 줄이는 것이다.

1. 전체 우선순위

2. 실행 순서

1. P0-1 Schema/Prompt Drift를 먼저 한다.
2. P0-2 ODL Token Safety를 같이 본다. step schema와 device task contract가 같은 경계에 있기 때문이다.
3. P1-1 Capability Registry Contract를 만든다.
4. P1-2 Skill Registry Auto Table을 만든다.
5. P1-3 Schedule Slot Contract를 만든다.
6. P1-4 Dynamic Replanning Contract를 만든다.
7. P2-1 Second Pass Benchmark Report로 성능 영향을 분리한다.
8. P2-2 Reader Path/Dedup으로 wiki 흐름을 정리한다.

3. P0-1 Schema/Prompt Drift 점검

목적

main_router.system_prompt.txt가 요구하는 steps[] 필드와 main_router.response_schema.json이 허용하는 필드가 같은지 확인한다. 현재 확인된 주요 관심점은 prompt가 token_text와 device step 규칙을 강하게 지시하지만, schema의 steps.items.properties에는 token_text와 device_task가 명시되어 있지 않다는 점이다.

확인 대상

점검 항목

산출물

• planner-schema-prompt-drift.md
• 필요한 경우 main_router.response_schema.json patch
• 필요한 경우 main_router.system_prompt.txt patch
• Cloud-only, mixed cloud/device, device-only step fixture

4. P0-2 ODL Token/Task Contract 안전 경계

목적

Planner, ODL agent, runtime task manager, on-device bridge 사이에서 token_text와 device_task_request를 누가 만들 수 있는지 고정한다.

현재 기준

확인 대상

완료 기준

• token_text는 catalog/contract 또는 ODL/device-token contract에서 제공된 경우에만 planner output에 존재한다.
• token이 없으면 planner는 execution_target=device만 표시하고, ODL agent 또는 bridge가 executable task를 구성한다.
• device step이 전부 token을 갖는 경우에만 task_manager.py가 plan-level device_intent_step으로 변환한다는 정책이 문서화된다.
• 실패/차단/사용자 결정 필요 이벤트만 Cloud replan 대상으로 올라간다는 경계가 유지된다.

5. P1-1 Capability Registry Contract 문서화

목적

capability_registry.v2.json의 필드를 router 판단 계약으로 문서화한다. 특히 kind, scheduling, visibility는 ODL/SCH/DQR/UNS 경계에 직접 영향을 준다.

확인 대상

contract로 분리할 필드

산출물

• capability-registry-contract.md
• capability kind별 예시 표
• schedulable capability 목록
• planner exposed false 항목이 있을 경우 별도 표

6. P1-2 Skill Registry / Flow Catalog 자동 표 추출

목적

skill_registry.json에서 agent/skill/flow 목록을 사람이 볼 수 있는 wiki 표로 자동 생성한다. 수동 문서와 registry가 어긋나는 문제를 줄인다.

확인 대상

추출할 표

산출물

• agent-skill-flow-catalog.md
• 가능하면 tools/export_skill_registry_wiki.py 또는 동등한 생성 스크립트
• wiki build 시 stale 여부를 확인할 수 있는 검증 명령

7. P1-3 Schedule Workflow Slot Schema 연결

목적

Planner의 missing_slots, schedule agent의 resolved_slots, on-device schedule relay payload가 같은 slot 의미를 쓰도록 연결한다.

확인 대상

정리할 slot 이름

완료 기준

• Planner와 schedule agent가 같은 slot 이름을 사용한다.
• 고정청정 예약해줘 -> 언제/어디/반복 multi-turn 예시가 문서화된다.
• 등록/삭제/수정/조회가 같은 slot schema에서 action만 달라지는 구조로 정리된다.

8. P1-4 Plan Expansion / Dynamic Replanning Contract

목적

처음 planner가 만든 plan이 최종 목적까지 충분하지 않거나, 실행 중 결과를 보고 추가 plan이 필요해지는 경우를 명확한 계약으로 고정한다. 이 과제의 핵심은 Cloud LLM을 매 task event마다 다시 돌리는 것이 아니라, “판단이 필요한 순간”만 workflow context와 event reason을 근거로 replan하게 만드는 것이다.

현재 구현 기준

구분해야 할 planning 종류

Plan expansion에서 필요한 계약

현재 구조에는 requires_semantic_next_step, pending_cloud_steps, resume_workflow가 있어 다음 step resume의 기반은 있다. 다만 “새 step을 추가 생성해야 하는 경우”는 더 명확한 planner/runtime contract가 필요하다.

정리해야 할 필드 후보:

{
  "requires_cloud_decision": true,
  "requires_semantic_next_step": true,
  "plan_expansion_reason": "prior_step_result_requires_new_action",
  "available_outputs": {
    "step_1": {"output_key": "candidate_places", "result_ref": "candidate_places.result"}
  },
  "allowed_next_routes": ["FRG", "DEF", "ODL"],
  "blocked_routes": ["STT_NULL"],
  "user_input_required": false
}

확인 대상

완료 기준

• task event 중 Cloud LLM replan이 필요한 이벤트와 불필요한 이벤트가 표로 고정된다.
• FAILED/BLOCKED/NEEDS_USER_INPUT과 requires_semantic_next_step의 차이가 문서화된다.
• 기존 plan의 다음 step을 resume하는 경우와 새 step을 생성해야 하는 plan expansion 경우가 분리된다.
• workflow_context.last_replan_decision을 planner가 어떻게 읽는지 예시가 있다.
• Cloud-only, mixed cloud/device, device recovery, semantic next-step expansion fixture가 생긴다.

예시 1: 정상 resume

사용자: 거실로 가서 청정하고 안방으로 가
plan: step_1 move(living_room) -> step_2 clean(living_room) -> step_3 move(bedroom)
이벤트: step_1 COMPLETED
처리: 기존 plan의 step_2를 resume. Cloud LLM replan 불필요.

예시 2: 실패 recovery replan

이벤트: step_1 BLOCKED, reason_code=path_blocked, requires_cloud_decision=true
처리: workflow_state가 replan_action=ask_user 생성
사용자: 그럼 안방으로 가
planner: workflow_context.last_replan_decision을 보고 ODL recovery step 생성

예시 3: semantic next-step expansion

사용자: 오늘 혼잡한 곳을 찾고, 그중 가까운 곳으로 이동해
step_1 FRG: 혼잡한 곳 후보와 위치 정보 반환
이벤트: WORKFLOW_STEP_COMPLETED, requires_semantic_next_step=true
처리: Cloud가 step_1 결과와 device_context를 보고 다음 ODL 이동 step을 생성할 수 있어야 함

이 예시는 단순 resume이 아니다. 최초 plan에 정확한 목적지가 없었고, 앞 step 결과를 보고 새 device action step을 구체화해야 하므로 plan expansion contract가 필요하다.

9. P2-1 Second Pass Benchmark 영향 문서화

목적

second_pass_family_judge가 실제 성능에 준 영향을 정량적으로 분리한다. 특히 DEF/STT_NULL/FRG 회색지대에서 얻은 이득과 specialist family 손실이 있는지 확인한다.

확인 대상

비교할 지표

산출물

• second-pass-benchmark-impact.md
• benchmark summary table
• 대표 flip 사례 10개
• harmful flip 사례 10개
• 최종 채택/롤백 판단 기준

10. P2-2 Planner Routing / Deep Dive 중복 정리

목적

planner-routing.md는 개요, planner-deep-dive.md는 소스 기준 상세라는 역할을 분리한다. 같은 설명이 두 문서에 반복되면 최신화가 어렵다.

정리 원칙

완료 기준

• Planner and Routing을 읽으면 개념이 잡힌다.
• A2A Planner Deep Dive를 읽으면 실제 코드와 field가 잡힌다.
• 두 문서가 서로 링크하지만 같은 표를 중복 유지하지 않는다.
• book-roadmap.md의 Part 4/4-1 설명과 일치한다.

11. 추적 보드

12. 지금 바로 착수할 때의 권장 순서

가장 먼저 PL-CLEAN-01을 한다. 이유는 schema가 prompt를 따라가지 못하면 planner가 올바른 multi-step field를 내도 runtime까지 전달되지 않을 수 있기 때문이다. 그 다음 PL-CLEAN-02를 이어서 처리하면 device execution 안전 경계까지 같이 닫을 수 있다.

그 이후 PL-CLEAN-03, PL-CLEAN-04, PL-CLEAN-05는 registry/catalog/schedule 계약 정리다. PL-CLEAN-06은 runtime replan과 plan expansion 경계를 닫는 작업이므로 schedule/device task 계약과 함께 진행하는 것이 좋다. PL-CLEAN-07은 benchmark artifact가 필요하므로 테스트 결과가 쌓인 뒤 진행하는 것이 낫다. PL-CLEAN-08은 앞 문서들이 만들어진 뒤 마지막에 정리한다.