nomadcode/agent-task/m-agent-origin-milestone-creation-sync/02+01_identity_backfill/PLAN-cloud-G08.md

Plan - API

이 파일을 읽는 구현 에이전트에게

구현 후 active CODE_REVIEW-*-G??.md의 구현 에이전트 소유 섹션을 반드시 실제 구현 내용과 검증 출력으로 채운다. 검증을 실행하고, active 파일은 그대로 둔 뒤 리뷰 준비를 보고한다. 최종 판정, log rename, complete.log, archive 이동은 code-review 스킬 전용이다.

선택된 Milestone의 구현 잠금 > 결정 필요 항목이 실구현을 막을 때만 review stub의 사용자 리뷰 요청 섹션을 채우고 멈춘다. 구현 중 사용자에게 직접 질문하거나 선택지를 제시하거나 request_user_input을 호출하지 않는다.

배경

Missing-create는 Plane work item과 DB identity row를 만들지만, 그 identity를 source-of-truth roadmap markdown에 되돌려 쓰는 commit/push 경로가 아직 없다. 이 plan은 S04에 해당하는 identity-only backfill을 durable step으로 추가해, created Plane identity가 active Milestone 파일에 portable anchor로 남도록 한다.

사용자 리뷰 요청 흐름

사용자 리뷰 요청은 선택된 Milestone lock decision만 active review stub의 사용자 리뷰 요청 섹션에 기록한다. 직접 사용자 prompt는 금지이며, code-review가 정당성을 검증하고 실제 USER_REVIEW.md 작성을 소유한다.

Roadmap Targets

• Milestone: agent-roadmap/phase/agent-ops-mcp-control-plane/milestones/agent-origin-milestone-creation-sync.md
• Task ids:
  • identity-backfill: Plane 생성 직후 Milestone markdown에 Provider identity block을 주입하고 Core-authored backfill commit을 develop에 push한다.
• Completion mode: check-on-pass

분석 결과

읽은 파일

• agent-roadmap/phase/agent-ops-mcp-control-plane/milestones/agent-origin-milestone-creation-sync.md
• agent-roadmap/sdd/agent-ops-mcp-control-plane/agent-origin-milestone-creation-sync/SDD.md
• agent-contract/outer/gito-branch-webhook-consumer-v1.md
• agent-test/local/rules.md
• agent-test/local/core-smoke.md
• services/core/internal/roadmapsyncpipeline/service.go
• services/core/internal/roadmapsyncpipeline/service_test.go
• services/core/internal/storage/roadmap_sync_steps.go
• services/core/internal/storage/roadmap_sync_steps_test.go
• services/core/internal/authoring/identity_write.go
• services/core/internal/authoring/identity_write_test.go
• services/core/internal/gitosync/scanner.go
• services/core/internal/gitosync/scanner_test.go
• services/core/internal/scheduler/roadmap_sync_jobs.go
• services/core/internal/scheduler/jobs.go
• services/core/queries/roadmap_sync_steps.sql
• services/core/migrations/00007_create_roadmap_sync_steps.sql

SDD 기준

• SDD: agent-roadmap/sdd/agent-ops-mcp-control-plane/agent-origin-milestone-creation-sync/SDD.md
• 상태: [승인됨], SDD 잠금 해제, 사용자 리뷰 없음.
• Targeted scenario: S04=identity-backfill.
• Evidence Map row: identity backfill writer test and git commit scope check; completion evidence must show identity-backfill Roadmap Completion and commit diff evidence.
• Checklist is derived from S04: inject provider identity block, commit only that block, push to develop, and record the durable step after the push succeeds.

테스트 환경 규칙

• test_env: local.
• agent-test/local/rules.md present/read.
• Matched profile read: agent-test/local/core-smoke.md.
• Current preflight: repo root /config/workspace/nomadcode, branch main, HEAD d80abe83579dd0d6fbc86b1a74c83db6d18c756d, go version go1.26.2 linux/arm64, git version 2.43.0.
• Verification commands use current checkout focused Go tests plus git diff --check. Remote runner evidence may be collected after source sync to $HOME/agent-work/nomadcode.

테스트 커버리지 공백

• Existing authoring.LocalIdentityWriter injects provider identity into changed milestone files, but it is tied to authoring task dirty workspace state and does not commit/push identity-only backfills.
• Existing roadmapsyncpipeline.SyncCreation missing-create branch returns after StepDevelopMatched and has no backfill step or git scope check.
• Existing storage step enum/check constraint lacks an identity-backfilled step.

심볼 참조

• New step symbol likely needed: identity_backfilled. Grep all StepPlaneTodoMoved, OrderedSteps, and roadmap_sync_steps_step_check references before editing.

분할 판단

• Split decision policy evaluated before file selection.
• This dependent subtask is 02+01_identity_backfill; predecessor index 01 is required.
• Active predecessor lookup: no agent-task/m-agent-origin-milestone-creation-sync/01_*/complete.log or 01+*/complete.log exists at plan creation.
• Archive predecessor lookup: not performed because this is a new active task group and no prior completion can satisfy the new first subtask.
• Implementer must wait for 01_scan_create_ledger PASS/complete.log before starting this plan.

범위 결정 근거

• Include only identity backfill writer/commit/push and durable ledger step.
• Exclude self-loop redelivery interpretation, provider body/title update projection, broad conflict taxonomy, and live field smoke; those are later dependent plans.

빌드 등급

• cloud-G08: git write/push, DB step schema, pipeline side effects, and provider identity contracts are all in scope; verification must prove no unrelated roadmap diff is pushed.

의존 관계 및 구현 순서

02+01_identity_backfill depends on sibling predecessor 01_scan_create_ledger. Start implementation only after agent-task/m-agent-origin-milestone-creation-sync/01_scan_create_ledger/complete.log exists or the matching archived complete.log is explicitly provided by runtime.

구현 체크리스트

• identity-backfill step을 storage/domain ordered step set에 추가하고 DB check constraint migration/query tests를 갱신한다.
• missing-create Plane create + identity upsert 직후 Milestone markdown에 Provider identity block을 주입하는 pipeline seam을 추가한다.
• backfill writer가 identity block 외 unrelated roadmap 변경을 commit하지 않는 git scope check를 구현/테스트한다. 검증: backfill commit에는 identity block 외의 unrelated roadmap 변경이 포함되지 않는다.
• push 성공 뒤에만 identity_backfilled ledger step을 mark하고, 실패 시 retry가 create를 반복하지 않고 backfill부터 재개하게 한다.
• git diff --check, focused go test -count=1, focused go vet를 실행한다.
• CODE_REVIEW-*-G??.md의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다. 이 항목이 완료되기 전에는 구현이 완료된 것이 아니다.

[API-1] Durable Backfill Step

문제

services/core/internal/roadmapsync/retry.go:10 has only develop, comment, body, todo steps. services/core/internal/storage/roadmap_sync_steps.go:15 mirrors the same closed set. S04 needs a durable identity backfill step between Plane create and later self-loop checks.

해결 방법

Add identity_backfilled to domain/storage ordered steps and migrate the DB check constraint. Keep ordering explicit so retries can resume after create/upsert without re-creating Plane work items.

Before:

// services/core/internal/roadmapsync/retry.go:10
const (
    StepDevelopMatched           Step = "develop_matched"
    StepOriginalCommentPreserved Step = "original_comment_preserved"
    StepPlaneBodyUpdated         Step = "plane_body_updated"
    StepPlaneTodoMoved           Step = "plane_todo_moved"
)

After:

const (
    StepDevelopMatched           Step = "develop_matched"
    StepIdentityBackfilled       Step = "identity_backfilled"
    StepOriginalCommentPreserved Step = "original_comment_preserved"
    StepPlaneBodyUpdated         Step = "plane_body_updated"
    StepPlaneTodoMoved           Step = "plane_todo_moved"
)

수정 파일 및 체크리스트

• services/core/internal/roadmapsync/retry.go: add step and order.
• services/core/internal/roadmapsync/retry_test.go: first incomplete and all-complete cases include new step.
• services/core/internal/storage/roadmap_sync_steps.go: add storage step and validation.
• services/core/internal/storage/roadmap_sync_steps_test.go: validation and completed-set tests include new step.
• services/core/migrations/00010_add_roadmap_identity_backfilled_step.sql: update check constraint without dropping data.

테스트 작성

Regression tests required because this changes retry persistence semantics.

중간 검증

cd services/core && go test -count=1 ./internal/roadmapsync ./internal/storage

Expected: PASS; ordered step tests prove identity_backfilled sits after develop_matched.

[API-2] Identity Backfill Writer And Commit Scope

문제

services/core/internal/authoring/identity_write.go:37 injects identity into dirty authoring workspace files, but missing-create backfill needs a Core-authored identity-only commit in the develop checkout. services/core/internal/roadmapsyncpipeline/service.go:179 creates the Plane item and line 223 marks only develop_matched, then returns.

해결 방법

Introduce a pipeline-owned backfill seam that writes the identity block to Expected.RoadmapMilestonePath in the configured develop checkout, stages only that path, verifies the diff contains only the provider identity block, commits with a Core-authored marker, and pushes to develop.

Before:

// services/core/internal/roadmapsyncpipeline/service.go:223
if _, err := s.store.MarkStepCompleted(ctx, identityRow.ID, toStorageStep(roadmapsync.StepDevelopMatched)); err != nil {
    return SyncCreationResult{}, err
}

return SyncCreationResult{
    Action:   SyncActionProjected,
    Reason:   "plane work item created for missing active milestone",
    NextStep: roadmapsync.StepDevelopMatched,
}, nil

After:

// after develop_matched ledger mark:
if err := s.backfiller.BackfillIdentity(ctx, BackfillInput{Identity: identity, MarkdownPath: identity.RoadmapMilestonePath}); err != nil {
    return SyncCreationResult{}, err
}
if _, err := s.store.MarkStepCompleted(ctx, identityRow.ID, toStorageStep(roadmapsync.StepIdentityBackfilled)); err != nil {
    return SyncCreationResult{}, err
}

수정 파일 및 체크리스트

• services/core/internal/roadmapsyncpipeline/service.go: add optional backfiller dependency and missing-create resume path.
• services/core/internal/roadmapsyncpipeline/service_test.go: fake backfiller proves call order create -> identity upsert -> develop_matched mark -> backfill -> identity_backfilled mark.
• services/core/internal/authoring/identity_write.go or new nearby helper: reuse identity block rendering without dirty-worktree assumptions.
• services/core/internal/authoring/identity_write_test.go: identity block rendering remains parser-compatible.
• New git-scope test with temp repo: unrelated roadmap edit stays unstaged/uncommitted and commit diff contains only provider identity block.

테스트 작성

Regression tests required for S04, including temp git repo commit-scope test.

중간 검증

cd services/core && go test -count=1 ./internal/roadmapsyncpipeline ./internal/authoring

Expected: PASS; fake backfiller and temp git tests prove retry and commit scope.

[API-3] Scheduler Wiring And Review Evidence

문제

services/core/internal/scheduler/roadmap_sync_jobs.go:81 passes pipeline input but has no way to configure a backfill checkout/pusher. Without worker wiring, production jobs cannot perform S04.

해결 방법

Wire the backfiller at server/scheduler construction where Gito develop checkout path and remote/branch config are already available. If config is missing, missing-create backfill must fail explicitly rather than silently completing with only DB identity.

수정 파일 및 체크리스트

• services/core/internal/scheduler/roadmap_sync_jobs.go: pass any new pipeline input fields only if needed; avoid putting secrets in job args.
• services/core/cmd/server/main.go: wire backfiller from GITO_DEVELOP_REPO_PATH, GITO_REMOTE_NAME, GITO_BRANCH.
• services/core/internal/scheduler/jobs_test.go or server wiring tests: configured roadmap sync worker has backfiller when Gito checkout is configured.
• agent-task/m-agent-origin-milestone-creation-sync/02+01_identity_backfill/CODE_REVIEW-cloud-G08.md: fill implementation-owned sections.

테스트 작성

Add wiring tests if constructor seams allow it; otherwise record code inspection evidence plus focused pipeline tests.

중간 검증

cd services/core && go test -count=1 ./internal/scheduler ./cmd/server ./internal/roadmapsyncpipeline

Expected: PASS.

수정 파일 요약

파일	항목
services/core/internal/roadmapsync/retry.go	API-1
services/core/internal/roadmapsync/retry_test.go	API-1
services/core/internal/storage/roadmap_sync_steps.go	API-1
services/core/internal/storage/roadmap_sync_steps_test.go	API-1
services/core/migrations/00010_add_roadmap_identity_backfilled_step.sql	API-1
services/core/internal/roadmapsyncpipeline/service.go	API-2
services/core/internal/roadmapsyncpipeline/service_test.go	API-2
services/core/internal/authoring/identity_write.go	API-2
services/core/internal/authoring/identity_write_test.go	API-2
services/core/internal/scheduler/roadmap_sync_jobs.go	API-3
services/core/cmd/server/main.go	API-3
services/core/internal/scheduler/jobs_test.go	API-3
agent-task/m-agent-origin-milestone-creation-sync/02+01_identity_backfill/CODE_REVIEW-cloud-G08.md	API-3

최종 검증

git diff --check
cd services/core && go test -count=1 ./internal/roadmapsync ./internal/storage ./internal/authoring ./internal/roadmapsyncpipeline ./internal/scheduler ./cmd/server
cd services/core && go vet ./internal/roadmapsync ./internal/storage ./internal/authoring ./internal/roadmapsyncpipeline ./internal/scheduler ./cmd/server

Expected: all commands exit 0. Fresh -count=1 is required for Go tests.

모든 코드 변경 완료 후 반드시 CODE_REVIEW-*-G??.md의 구현 에이전트 소유 섹션을 채운다. 이 파일 작성이 구현의 마지막 단계다.