toki dd16b32cd5 sync: agent-ops from agentic-framework v1.1.177

2026-07-29 09:57:14 +09:00

31 KiB

Raw Permalink Blame History

name	description
sync-agent-ui	정합화된 agent-ui 변경분을 코드에 직접 반영하거나 plan/roadmap으로 라우팅하고 plan·Milestone 작업 매핑과 완료 후 상태 정합화를 소유한다. agent-ui와 코드 동기화, 화면정의서대로 코드 반영, agent-ui 코드 작업 준비·완료 정합화 요청에 사용한다.

sync-agent-ui

목적

정합화된 agent-ui/ 변경분을 실제 UI 코드에 반영한다. 기본 동작은 .sync-state.json의 last_synced_head 이후 agent-ui 변경분만 반영하며, 사용자가 전체 동기화를 명시한 경우에만 현재 agent-ui 전체를 코드와 대조한다. 코드 반영 전에 코드 작업 규모를 판정해 작은 작업은 직접 반영하고, 중간 작업은 plan 루프로, Milestone이 필요한 큰 코드 작업은 update-roadmap의 Milestone/Epic/Task 갱신으로 넘긴다. plan-required 작업은 일반 plan/code-review 문서에 agent-ui 전용 section을 넣지 않는다. 대신 plan pair 생성 직후 prepare-code-work로 task와 agent-ui 문서를 매핑하고, 일반 code-review PASS와 complete.log 생성 뒤 reconcile-completion으로 status/code evidence를 정합화한다. milestone-required 작업도 일반 Milestone 문서에 agent-ui 전용 완료 필드를 넣지 않는다. update-roadmap이 확정한 활성 Milestone을 prepare-milestone-work로 매핑하고, 종료 직전 complete-milestone check-only 근거를 받은 reconcile-milestone-completion이 status/code evidence를 정합화한다.

언제 호출할지

사용자가 "agent-ui와 코드 동기화", "화면정의서대로 코드 반영", "wireframe 변경사항 구현"을 요청할 때
update-agent-ui 또는 validate-agent-ui가 code sync 필요성을 판단했고 현재 범위에 미해결 USER_REVIEW가 없을 때
사용자가 "agent-ui와 코드 전체 동기화"처럼 full sync를 명시할 때
plan-required로 생성된 task와 agent-ui 문서의 연결을 기록할 때
일반 code-review PASS 뒤 생성된 complete.log를 agent-ui status/code evidence에 반영할 때
milestone-required로 확정된 활성 Milestone과 agent-ui 문서를 연결할 때
Milestone 종료 감사 통과 후보의 agent-ui 상태를 실제 종료 전에 정합화할 때

입력

mode: incremental, full, prepare-code-work, reconcile-completion, prepare-milestone-work, reconcile-milestone-completion 중 하나. 기본값은 incremental (선택)
scope: all, view:<view-id>, component:<component-id> 중 하나. 기본값은 all (선택)
validated: true 또는 false. 기본값은 false (선택)
sync-intent-source: manual, update-agent-ui, validate-agent-ui 중 하나 (선택)
execution-route: auto, direct-sync, plan-required, milestone-required 중 하나. 기본값은 auto (선택)
task-path: agent-task/ 기준 원래 active task 경로. prepare-code-work와 reconcile-completion에서 필수
previous-task-path: plan refinement/reindex 전에 pending entry가 가리키던 active task 경로. prepare-code-work rebind에서만 선택
milestone-path: agent-roadmap/phase/*/milestones/*.md의 정확한 활성 Milestone 경로. Milestone prepare/reconcile에서 필수
agent-ui-docs: 완료 시 구현됨으로 전환할 활성 view/component 문서 목록. prepare-code-work에서 필수
frame-docs: 함께 검증할 활성 frame-view 문서 목록. prepare-code-work에서 선택
code-paths: 구현 후보 또는 완료 evidence 코드 경로 목록. prepare-code-work에서 필수
verification-requirements: 완료 정합화 전에 확인할 명령/기대 결과 목록. prepare-code-work에서 선택
completion-log: 일반 code-review가 만든 정확한 complete.log 경로. reconcile-completion에서 필수
closure-evidence: 같은 Milestone에 대해 complete-milestone mode=check-only가 반환한 종료 가능 근거와 검증 요약. reconcile-milestone-completion에서 필수
validation-evidence: update-agent-ui 후 실행한 validate-agent-ui PASS 근거. reconcile-completion에서 필수
sync-result-head: agent-ui와 코드 결과를 모두 포함한다고 검증된 commit hash. reconcile-completion에서 선택
push: true 또는 false. incremental|full에서만 사용하며 기본값은 true (선택)

먼저 확인할 것

agent-ops/rules/common/rules-agent-ui.md를 읽는다.
agent-ui/와 agent-ui/definition/index.md 존재 여부를 확인한다.
mode=incremental|full|prepare-code-work|prepare-milestone-work이고 validated=true가 아니면 먼저 validate-agent-ui를 실행한다.
agent-ui/USER_REVIEW.md가 있으면 현재 sync 범위와 관련된 미해결 항목이 없는지 확인한다.
agent-ui/.sync-state.json을 읽는다. 없고 mode=incremental|prepare-code-work|reconcile-completion|prepare-milestone-work|reconcile-milestone-completion이면 legacy baseline migration 필요로 보고 중단한다.
schema_version: 1|2|3이면 bundled state helper가 기존 필드와 pending 매핑을 보존·정규화하고 schema_version: 4로 올리게 한다.
.sync-state.json을 갱신하는 모든 모드에서 agent-ops/skills/common/sync-agent-ui/scripts/sync_state.py를 사용한다. shared state를 수동 read-modify-write하지 않는다.
mode=incremental|full이면 현재 sync 대상 agent-ui 경로 또는 그 상·하위 경로가 code/Milestone pending entry의 status_paths 또는 frame_paths와 겹치지 않는지 확인한다. 겹치면 direct sync를 시작하지 않고 기존 pending owner 흐름으로 돌린다.
mode=incremental|full이면 수정할 UI 코드 경로에 해당하는 project/domain rule을 먼저 읽는다.
mode=incremental|full이고 코드 변경 검증이 필요하면 작업 환경의 agent-test/<env>/rules.md를 읽는다. 환경 미지정은 local로 본다.
mode=prepare-code-work이면 exact active PLAN-*-G??.md와 matching CODE_REVIEW-*-G??.md가 task-path에 존재하는지 확인한다.
mode=reconcile-completion이면 원래 task-path, exact completion-log가 존재하고 matching pending entry가 정확히 하나인지 확인한다.
mode=prepare-milestone-work이면 update-roadmap이 확정한 exact active milestone-path가 존재하는지 확인한다.
mode=reconcile-milestone-completion이면 같은 milestone-path의 pending entry와 complete-milestone check-only closure evidence가 있는지 확인한다.
git status --short와 현재 HEAD를 확인한다.
unrelated dirty worktree가 있으면 sync commit 전에 범위를 보고하고, agent-ui와 관련 코드 파일만 stage한다.
이전 sync 실패로 남은 관련 작업트리 변경이 있으면 보존할지, 사용자 결정과 충돌하는지 확인한다.

실행 절차

prepare-code-work 절차

task 매핑 검증
- task-path의 active PLAN/review pair가 같은 task header를 갖고 아직 verdict가 없는지 확인한다.
- agent-ui-docs는 현재 활성 view/component 문서이고 status가 계획인지 확인한다. 가정, 불명확, 이미 archive 된 문서는 매핑하지 않는다.
- frame-docs는 visual source가 있는 활성 frame-view 문서인지 확인하고 대응 view가 agent-ui-docs에 포함됐는지 확인한다. frame-view 자체에는 status를 요구하거나 구현됨 전환을 적용하지 않는다.
- code-paths는 실제 구현 후보로 좁혀진 경로만 기록한다. 존재하지 않는 새 파일 후보는 경로와 생성 의도가 plan에 명시된 경우에만 허용한다.
- 기존 pending task가 refine-local-plans로 분할되거나 sibling reindex로 경로가 바뀌었으면 원래 매핑을 그대로 둘 수 없다. status 대상 전체를 닫는 child를 하나만 고르고 기존 경로를 previous-task-path, 그 child 경로를 task-path로 전달한다.
pending entry 기록
- agent-ui/.sync-state.json의 SHA-256을 계산한 뒤 bundled helper의 prepare 명령에 --expected-sha256으로 넘긴다. helper는 agent-ui 디렉터리 잠금을 잡은 다음 digest를 다시 확인한다.
- 같은 task_path와 같은 내용은 idempotent already_prepared로 허용한다.
- 같은 task_path의 내용이 다르면 helper가 중단한다. follow-up plan으로 범위가 실제 바뀐 것을 확인한 경우에만 --replace를 사용한다.
- previous-task-path를 전달하면 helper가 기존 pending entry를 새 task-path로 원자적으로 rebind한다. scope/status/frame/code/verification 매핑이 달라지면 전체 결과를 닫는 child인지 검증한 뒤에만 --replace를 함께 사용한다.
- 하나의 status_path 또는 frame_path를 둘 이상의 pending task가 소유하려 하면 helper가 중단한다.

{
  "task_path": "agent-task/<task-name>",
  "scope": "<scope>",
  "status_paths": ["agent-ui/definition/views/.../index.md"],
  "frame_paths": ["agent-ui/frame/views/.../index.md"],
  "code_paths": ["<code path>"],
  "verification_requirements": ["<command>: <expected result>"],
  "prepared_at": "<ISO-8601>",
  "state": "pending"
}

python3 agent-ops/skills/common/sync-agent-ui/scripts/sync_state.py prepare \
  --state agent-ui/.sync-state.json \
  --expected-sha256 <sha256> \
  --task-path agent-task/<task-name> \
  --scope <scope> \
  --status-path agent-ui/definition/views/<view-id>/index.md \
  --frame-path agent-ui/frame/views/<view-id>/index.md \
  --code-path <code-path> \
  --verification-requirement '<command>: <expected result>' \
  --prepared-at <ISO-8601>

--status-path와 --code-path는 필요한 만큼 반복하고, frame이 없으면 --frame-path를 생략한다.
refinement/reindex rebind에서는 --previous-task-path agent-task/<old-task-name>을 추가한다.

state 경계 유지
- helper가 schema_version을 4로 올리고 code/Milestone pending·reconciled 기록과 baseline 필드를 보존하게 한다.
- 이 모드는 last_synced_head, agent-ui status, code evidence를 바꾸지 않고 commit/push하지 않는다.
- 일반 plan/review 문서에는 agent-ui 전용 completion section이나 review 전용 status 전환 지시를 추가하지 않는다.

reconcile-completion 절차

완료 이벤트 매칭
- exact completion-log가 agent-task/archive/**/complete.log에 있고 header task가 원래 task-path와 일치하며 loop history에 terminal PASS/RESOLVED가 있는지 확인한다.
- 입력된 원래 task-path를 pending_code_work[].task_path와 exact match한다. archive destination suffix나 completion-log 경로에서 원래 task path를 역추정하지 않는다.
- zero/multiple match이면 agent-ui 문서를 추측해 갱신하지 않는다.
완료 evidence 검증
- pending entry의 모든 code_paths가 실제 존재하고 agent-ui 정의를 구현한 근거인지 확인한다.
- completion-log의 최종 검증과 verification_requirements가 충족됐는지 확인한다.
- generic complete.log에 agent-ui 전용 section이 없어도 정상으로 본다. 필요한 매핑은 pending entry에서만 읽는다.
- evidence가 부족하면 entry를 pending으로 유지하고 일반 plan/review artifact를 수정하지 않는다.
agent-ui 상태 반영
- pending entry의 status_paths에 있는 view/component 문서마다 update-agent-ui를 status=구현됨, 실제 code evidence, post-validate=false, post-sync=false로 실행한다.
- frame_paths에는 status를 쓰지 않는다. 대응 definition과 visual source 연결을 검증 대상으로만 사용한다.
- 모든 문서 갱신 뒤 validate-agent-ui를 matching scope, sync-intent=skip으로 실행하고 PASS 근거를 validation-evidence로 고정한다.
- 갱신이나 검증이 실패하면 pending entry를 제거하지 않고 agent-ui/USER_REVIEW.md에 Source Skill: sync-agent-ui, Stage: completion-reconcile로 차단 근거를 남긴다.
pending entry 종료
- 갱신과 검증이 모두 통과한 뒤 .sync-state.json의 최신 SHA-256을 다시 계산하고 bundled helper의 reconcile 명령을 실행한다.
- helper가 matching pending entry를 제거하고 reconciled_code_work에 task_path, exact completion_log, scope, status/frame/code paths, validation evidence를 기록하게 한다.
- helper가 last_sync_mode을 plan-reconcile, last_synced_at, agent_ui_paths, code_paths, notes를 완료 근거로 갱신하게 한다.
- sync-result-head가 실제 commit이고 matching agent-ui/code 결과를 모두 포함하는지 검증된 경우에만 last_synced_head를 그 값으로 갱신한다. 그렇지 않으면 기존 last_synced_head를 보존하고 notes에 기준점 미갱신 사유를 남긴다.
- 이미 같은 task_path와 completion-log가 reconciled_code_work에 있으면 helper의 idempotent already_reconciled 결과를 사용한다.
- 이 모드는 일반 plan/review/complete.log를 수정하거나 commit/push하지 않는다.

python3 agent-ops/skills/common/sync-agent-ui/scripts/sync_state.py reconcile \
  --state agent-ui/.sync-state.json \
  --expected-sha256 <sha256> \
  --task-path agent-task/<task-name> \
  --completion-log agent-task/archive/<YYYY>/<MM>/<task-path>/complete.log \
  --validation-evidence '<validate-agent-ui PASS evidence>' \
  --reconciled-at <ISO-8601>

검증된 결과 commit이 있을 때만 --sync-result-head <commit>을 추가한다.

Milestone 매핑과 완료 정합화 절차

Milestone 작업 준비
- execution-route=milestone-required이면 코드 구현을 시작하지 않고 먼저 update-roadmap으로 활성 Milestone을 생성하거나 정확히 하나를 선택한다.
- 일반 Milestone 문서에는 agent-ui 전용 완료 필드나 status 전환 지시를 쓰지 않는다.
- agent-ui-docs, frame-docs, code-paths, verification-requirements를 prepare-code-work와 같은 기준으로 검증한다.
- .sync-state.json의 최신 SHA-256과 exact active milestone-path를 bundled helper의 prepare-milestone에 전달한다.
- 같은 Milestone과 같은 매핑은 already_prepared로 허용하고, 실제 scope/evidence 변경을 확인한 경우에만 --replace를 사용한다.

python3 agent-ops/skills/common/sync-agent-ui/scripts/sync_state.py prepare-milestone \
  --state agent-ui/.sync-state.json \
  --expected-sha256 <sha256> \
  --milestone-path agent-roadmap/phase/<phase>/milestones/<milestone>.md \
  --scope <scope> \
  --status-path agent-ui/definition/views/<view-id>/index.md \
  --frame-path agent-ui/frame/views/<view-id>/index.md \
  --code-path <code-path> \
  --verification-requirement '<command>: <expected result>' \
  --prepared-at <ISO-8601>

종료 직전 정합화
- caller/router는 Milestone 종료 요청에서 먼저 complete-milestone mode=check-only를 실행한다. 종료 가능 판정과 실제 검증 근거가 없으면 이 모드를 실행하지 않는다.
- closure-evidence에는 exact milestone-path, check-only 판정, 코드레벨 감사, 실행한 검증 결과, spec check-only 결과를 식별 가능하게 요약한다. 재시도 idempotency를 위해 실행 시각처럼 의미 없는 가변 값은 넣지 않는다.
- pending entry의 모든 code_paths와 verification_requirements가 check-only 근거와 현재 checkout에서 충족되는지 다시 확인한다.
- status_paths의 view/component만 update-agent-ui status=구현됨과 실제 code evidence로 갱신하고, frame_paths는 연결 정합성만 검증한다.
- 모든 문서 갱신 뒤 validate-agent-ui sync-intent=skip을 실행한다. 실패하면 pending entry를 유지하고 Milestone close를 호출하지 않는다.
Milestone pending 종료
- 갱신과 검증이 통과한 뒤 최신 state SHA-256과 closure/validation evidence를 helper의 reconcile-milestone에 전달한다.
- helper가 matching entry를 pending_milestone_work에서 reconciled_milestone_work로 이동하고 완료 근거를 기록한다.
- 성공 또는 같은 evidence의 already_reconciled 뒤에만 caller/router가 complete-milestone mode=close를 실행한다. close가 다시 감사를 통과하지 못하면 roadmap 상태를 추측해 바꾸지 않는다.
- 이 모드는 일반 Milestone 문서와 complete-milestone 결과를 수정하지 않고 commit/push하지 않는다.

python3 agent-ops/skills/common/sync-agent-ui/scripts/sync_state.py reconcile-milestone \
  --state agent-ui/.sync-state.json \
  --expected-sha256 <sha256> \
  --milestone-path agent-roadmap/phase/<phase>/milestones/<milestone>.md \
  --closure-evidence '<complete-milestone check-only closure evidence>' \
  --validation-evidence '<validate-agent-ui PASS evidence>' \
  --reconciled-at <ISO-8601>

검증된 결과 commit이 있을 때만 --sync-result-head <commit>을 추가한다.

incremental/full 절차

동기화 범위 확정
- .sync-state.json이 없고 mode=incremental이면 현재 agent-ui를 legacy baseline 후보로 본다.
- legacy baseline 후보는 validate-agent-ui 통과 후 agent-ui baseline commit과 .sync-state.json commit을 남기는 migration으로 처리하고, 같은 실행에서 코드 반영은 하지 않는다.
- mode=incremental이면 .sync-state.json.last_synced_head 이후 현재 HEAD/worktree까지의 agent-ui 변경분을 확인한다.
- 변경분 판정에서 agent-ui/.sync-state.json 자체는 제외한다.
- mode=full이면 현재 활성 agent-ui/definition/**과 agent-ui/frame/** 전체를 코드와 대조한다.
- mode=full에서 .sync-state.json이 없으면 code sync 성공 후 새 sync state를 만든다.
- 가정 또는 불명확 상태 항목은 코드 반영 대상에서 제외하고 USER_REVIEW로 남긴다.
- 현재 범위에 미해결 USER_REVIEW가 있으면 중단한다.
- 확정된 sync 대상 agent-ui 경로 트리가 pending_code_work 또는 pending_milestone_work의 status_paths/frame_paths와 하나라도 겹치면 direct sync 대상으로 가져오지 않는다. 해당 pending task/Milestone의 완료 정합화 흐름을 사용한다.
코드 반영 방식 판정
- 이 판정은 agent-ui 문서 작업의 크기가 아니라, 정합화된 agent-ui 변경분을 코드에 반영하는 구현 작업의 크기와 위험만 대상으로 한다.
- execution-route=auto이면 코드 반영 대상의 크기와 위험을 direct-sync, plan-required, milestone-required 중 하나로 판정한다.
- direct-sync는 다음 조건을 모두 만족할 때만 사용한다.
  - 단일 view/component/frame 또는 한 화면 안의 국소 변경이다.
  - 기존 route, shell, navigation, shared state, design token, package boundary를 그대로 사용한다.
  - 새 정보구조, 새 주요 workflow, 새 공통 component 체계, 제품 방향 결정이 필요 없다.
  - 변경 후보 코드가 소수 파일로 좁혀지고 검증 명령이 명확하다.
- plan-required는 목표와 범위는 명확하지만 독립 리뷰 가능한 구현 루프가 필요할 때 사용한다.
  - 여러 view/component에 걸친 반영, shared component 추출, route/shell 조정, 테스트/검증 보강, UI 상태와 코드 변경을 함께 다루는 작업이 여기에 속한다.
  - 이 경우 직접 코드 반영을 시작하지 않고 plan 스킬로 전환한다.
  - plan에는 일반 구현 범위, 코드 후보, 검증 기준만 넘긴다.
  - plan pair가 생성되면 이 스킬의 prepare-code-work를 실행해 반영 대상 agent-ui 문서, 코드 후보, verification requirement를 task에 매핑한다.
  - 일반 code-review PASS와 complete.log 생성 뒤 caller/router/runtime가 reconcile-completion을 실행해 mapped agent-ui 문서를 구현됨으로 전환한다.
- milestone-required는 코드 구현이 제품 UI 구조나 장기 작업 단위까지 바꾸는 경우 사용한다.
  - navigation/information architecture 재정렬, 외부 제품 UI 분석 기반 재설계, 여러 workflow/role/surface를 묶는 작업, 활성 Milestone 범위 밖 작업이 여기에 속한다.
  - 이 경우 직접 코드 반영과 plan 생성을 시작하지 않고 update-roadmap으로 Milestone/Epic/Task 배치를 먼저 남긴다.
  - exact active Milestone이 확정되면 prepare-milestone-work로 UI 매핑을 .sync-state.json에 남긴다. Milestone 문서에는 agent-ui 전용 완료 필드를 추가하지 않는다.
- plan-required 판정 시 prepare-code-work pending entry 외에는 agent-ui 문서 status, baseline sync state, commit/push를 갱신하지 않는다.
- milestone-required 판정 시 agent-ui 문서 status와 baseline sync state, commit/push를 갱신하지 않고 pending_milestone_work 매핑만 기록한다.
코드 반영
- 이 단계는 execution-route=direct-sync일 때만 수행한다. plan-required 또는 milestone-required 판정이면 Step 2의 라우팅 결과를 보고하고 해당 스킬 흐름으로 전환한다.
- 계획 상태의 view/component 요구사항과 연결된 frame의 layout 근거를 UI 코드에 반영한다.
- existing component, route, shell, widget 구조를 우선하고 새 구조를 임의로 만들지 않는다.
- definition이 요구하는 정보 우선순위, region, action, state, component 참조를 코드 반영 기준으로 삼는다.
- wireframe/frame은 layout, density, visual relationship 보조 근거로만 사용하고 definition을 대체하지 않는다.
검증
- 관련 domain rule과 agent-test rule에 맞는 최소 검증을 실행한다.
- 검증 실패가 명확하고 에이전트가 해결 가능하면 수정과 검증을 반복한다.
- 구현 방향 충돌, 환경/권한 차단, 반복 실패, 사용자 판단이 필요한 시각 결과는 agent-ui/USER_REVIEW.md에 남기고 중단한다.
- USER_REVIEW로 중단하면 commit/push하지 않고 .sync-state.json도 갱신하지 않는다.
- USER_REVIEW로 중단할 때 관련 작업트리 변경은 사용자 결정과 충돌하지 않으면 보존하고, 재개 진입점과 변경 파일을 USER_REVIEW에 남긴다.
- execution-route=direct-sync에서 코드 반영과 검증이 모두 통과한 항목은 이 스킬 실행 안에서 agent-ui 문서의 status를 구현됨으로 갱신하고 Source Evidence에 코드 경로를 남긴다.
sync state와 commit/push
- 이 단계는 execution-route=direct-sync에서 코드 반영, 검증, agent-ui status/code evidence 갱신이 모두 통과한 경우에만 수행한다.
- commit 전에 state를 다시 읽어 direct sync 대상이 새 pending entry의 소유 경로와 겹치지 않는지 재확인한다. 겹치면 commit하지 않고 충돌 경로와 pending owner를 보고한다.
- 검증이 통과하면 agent-ui/code 변경을 먼저 commit한다.
- .sync-state.json이 없으면 agent-ops/skills/common/_templates/agent-ui/sync-state-template.json 기준으로 새로 만든다.
- 방금 만든 sync 결과 commit hash와 .sync-state.json의 최신 SHA-256을 bundled helper record-sync에 넘긴다.
- helper가 lock 안에서 pending 소유 경로와의 겹침을 다시 거부한 뒤 last_sync_mode, last_synced_head, last_synced_at, agent_ui_paths, code_paths, notes를 갱신하고 기존 code/Milestone pending·reconciled 기록을 보존하게 한다.

python3 agent-ops/skills/common/sync-agent-ui/scripts/sync_state.py record-sync \
  --state agent-ui/.sync-state.json \
  --expected-sha256 <sha256> \
  --sync-mode <incremental|full> \
  --sync-result-head <sync-result-commit> \
  --synced-at <ISO-8601> \
  --agent-ui-path <agent-ui-path> \
  --code-path <code-path> \
  --note '<sync evidence>'

agent-ui/code 경로와 note는 필요한 만큼 옵션을 반복한다.
legacy baseline migration은 --sync-mode migration을 사용하고 code 반영이 없으면 --code-path를 생략한다.
.sync-state.json 변경을 별도 commit한다.
commit message는 예를 들어 sync: apply agent-ui to code와 sync: record agent-ui sync state처럼 목적이 분리되게 쓴다.
push=true이면 두 commit을 push한다.

결과 보고
- sync mode와 scope
- execution route와 판정 근거
- 반영한 agent-ui 파일과 코드 파일
- 변경한 status
- 실행한 검증
- sync 결과 commit hash와 sync-state commit/push 결과
- USER_REVIEW 생성/갱신 여부

실행 결과 검증

validate-agent-ui가 먼저 실행되었거나 validated=true 근거가 있는가
현재 sync 범위에 미해결 USER_REVIEW가 없는가
코드 반영 전에 direct-sync, plan-required, milestone-required 중 하나로 판정했는가
plan-required 판정에서 직접 코드 변경, status 구현됨 전환, baseline sync state 갱신, commit/push를 하지 않고 pending entry만 기록했는가
milestone-required 판정에서 직접 코드 변경, status 구현됨 전환, baseline sync state 갱신, commit/push를 하지 않고 exact Milestone pending mapping만 기록했는가
direct-sync 판정에서 코드 반영과 검증이 통과한 항목은 같은 실행 안에서 agent-ui 문서 status를 구현됨으로 바꾸고 code evidence를 남겼는가
direct-sync 대상이 code/Milestone pending owner의 status/frame path와 겹치지 않는지 코드 변경 전과 commit 전 확인했는가
prepare-code-work가 exact task path와 활성 agent-ui 문서를 unique pending entry로 기록했는가
refinement/reindex된 pending task는 전체 결과를 닫는 child 하나로 rebind되어 이전 task path가 남지 않았는가
view/component는 status_paths, frame-view는 validation-only frame_paths로 분리했는가
하나의 status/frame path가 둘 이상의 pending task에 배정되지 않았는가
state helper에 inspection 시점 SHA-256을 전달해 directory lock 안에서 concurrent/stale write를 차단했는가
prepare-code-work가 일반 plan/review 문서에 agent-ui 전용 completion section을 요구하지 않았는가
reconcile-completion이 exact completion log, code path, verification requirement를 확인했는가
reconcile-completion이 update-agent-ui 다음 validate-agent-ui sync-intent=skip 순서로 실행했는가
reconcile 실패 시 pending entry를 유지하고 성공 시에만 제거했는가
reconcile 성공과 idempotency를 reconciled_code_work로 판정했는가
Milestone mapping은 roadmap 문서가 아니라 pending_milestone_work에만 기록했는가
Milestone reconcile 전에 complete-milestone check-only의 closure-ready 근거를 확인했는가
Milestone reconcile 성공 뒤에만 caller/router가 complete-milestone close로 진행하는가
검증되지 않은 sync-result-head로 last_synced_head를 바꾸지 않았는가
가정 또는 불명확 항목을 코드로 반영하지 않았는가
direct-sync로 코드 반영된 항목의 status가 구현됨이고 code evidence가 있는가
direct-sync 관련 검증이 통과했는가
실패 또는 차단 시 commit/push와 .sync-state.json 갱신을 하지 않았는가
실패 또는 차단 시 재개 진입점과 남은 변경 파일이 USER_REVIEW에 기록되었는가
direct-sync 성공 시 sync 결과 commit과 .sync-state.json commit이 분리되었는가
direct-sync 성공 시 .sync-state.json.last_synced_head가 sync 결과 commit hash를 가리키는가
direct-sync/baseline state 갱신도 helper를 사용해 code/Milestone pending·reconciled 기록을 보존했는가
unrelated dirty file이 sync commit에 포함되지 않았는가
검증 실패 시: 에이전트가 해결할 수 없으면 agent-ui/USER_REVIEW.md에 남기고 중단한다.

출력 형식

## agent-ui 코드 동기화 결과: <PASS|PLAN_REQUIRED|MILESTONE_REQUIRED|PREPARED|RECONCILED|ALREADY_RECONCILED|USER_REVIEW|FAIL>

- Mode: <incremental|full|prepare-code-work|reconcile-completion|prepare-milestone-work|reconcile-milestone-completion>
- Scope: <scope>
- Execution Route: <direct-sync|plan-required|milestone-required|not-applicable>
- Task Mapping: <task-path와 pending 상태 또는 없음>
- Milestone Mapping: <milestone-path와 pending 상태 또는 없음>
- Completion Log: <path 또는 없음>
- Closure Evidence: <Milestone check-only 근거 또는 없음>
- Agent UI Changes: <파일 목록 또는 없음>
- Code Changes: <파일 목록 또는 없음>
- Status Updates: <구현됨 전환 목록 또는 없음>
- Verification: <명령과 결과>
- Sync Commit: <hash 또는 없음>
- Sync State Commit/Push: <완료/생략/실패>
- State Transition: <prepared|already_prepared|replaced|rebound|reconciled|already_reconciled|없음>
- USER_REVIEW: <생성/갱신/없음>
- Remaining Issues: <목록 또는 없음>

금지 사항

validate-agent-ui를 거치지 않고 코드 동기화를 시작하지 않는다.
미해결 USER_REVIEW가 있는 범위를 코드에 반영하지 않는다.
가정 또는 불명확 상태 항목을 코드로 구현하지 않는다.
plan-required 또는 milestone-required로 판정된 작업을 같은 sync-agent-ui 실행에서 직접 구현하지 않는다.
일반 plan/review/complete.log에 agent-ui 전용 completion schema나 status 전환 책임을 추가하지 않는다.
일반 Milestone 문서나 roadmap 스킬에 agent-ui 전용 완료 필드나 status 전환 책임을 추가하지 않는다.
code/Milestone pending entry가 소유한 status/frame path를 direct sync로 반영하거나 record-sync하지 않는다.
matching pending entry 없이 complete.log만 보고 agent-ui 문서를 추측해 갱신하지 않는다.
frame-view 문서에 status를 추가하거나 구현됨 전환을 적용하지 않는다.
.sync-state.json을 bundled helper 밖에서 수동 read-modify-write하지 않는다.
refinement/reindex 뒤 이전 task path의 pending entry를 남기거나 같은 status/frame path를 여러 pending task에 중복 배정하지 않는다.
reconcile 실패 시 pending entry를 제거하거나 last_synced_head를 추정하지 않는다.
complete-milestone check-only 종료 가능 근거 없이 Milestone pending entry를 reconcile하거나 close를 계속하지 않는다.
execution-route=milestone-required로 라우팅된 agent-ui 코드 작업의 일반 plan 완료만으로 agent-ui status를 일괄 구현됨으로 바꾸지 않는다. 종료 감사와 code evidence가 있는 항목만 반영한다.
검증 실패나 사용자 판단 차단 상태에서 commit/push하지 않는다.
.sync-state.json을 agent-ui 변경분 판정 대상으로 삼지 않는다.
정의서와 충돌하는 wireframe만을 근거로 코드 구현을 확정하지 않는다.
실패한 sync의 작업트리 변경을 사용자 결정 없이 되돌리지 않는다.

31 KiB Raw Permalink Blame History