llm-wiki/raw/errors/developer-experience-contract-agents-bridge-2026-07-15.md

title, source_type, status, confidence, related_branches, related_projects, tags, created, status_label, evidence_grade

title	source_type	status	confidence	related_branches	related_projects	tags	created	status_label	evidence_grade
error / DeveloperExperienceContractTest replay worktree bridge (2026-07-15)	error-note	raw	medium	experiment-nplus1-feed-api-replay	ca-skeleton	error ca-skeleton testing gradle multi-module	2026-07-15	resolved	locally-verified

error: replay worktree의 ignored AGENTS.md 부재

lab/nplus1-api-replay를 별도 Git worktree에서 검증할 때 발생한 repository-root contract 문제다. 애플리케이션의 L12 동작 회귀가 아니라, 원래 worktree에만 있던 ignored/untracked AGENTS.md가 새 worktree에 존재하지 않은 환경 차이다.

Parent / 부모

• raw/branch-notes/experiment-nplus1-feed-api-replay — 11단계 replay의 검증 환경과 이 오류의 해결 결과를 기록한 branch note.

맥락

DeveloperExperienceContractTest는 repository root에서 AGENTS.md와 src/settings.gradle를 함께 찾는 contract를 갖는다. replay worktree에는 src/settings.gradle가 있었지만, Git이 추적하지 않는 root AGENTS.md는 원래 worktree에서 자동으로 복제되지 않았다.

증상 / Symptom

• 관찰된 실패 조건: DeveloperExperienceContractTest의 repository-root contract가 AGENTS.md 부재로 충족되지 않았다.
• 원문 exception text: 당시 Gradle 출력의 원문은 별도로 보존하지 않았다. 따라서 이 노트에서는 추정한 예외 문구를 인용하지 않는다.
• 발생 컨텍스트: replay worktree에서 focused Gradle 검증을 실행할 때.
• 발생 시점: 2026-07-15
• 발생 환경: local Git worktree
• 재현 가능 여부: always — root AGENTS.md가 없는 새 replay worktree에서 같은 contract를 실행하면 재현된다.

재현 절차 / Reproduction

1. lab/nplus1-api-replay의 별도 Git worktree를 준비한다.

2. 원래 worktree의 ignored/untracked root AGENTS.md를 새 worktree에 복사하지 않는다.

3. root에 src/settings.gradle는 존재하지만 AGENTS.md는 없는 상태를 확인한다.

4. src에서 다음 targeted test를 실행한다.

   ./gradlew :app-bootstrap:test --tests dev.caskeleton.bootstrap.contract.DeveloperExperienceContractTest
   

5. 기대 결과는 repository-root contract 통과이고, 실제 결과는 AGENTS.md marker 부재로 contract가 실패하는 것이다.

조사 단계 / Investigation log

• 2026-07-15 — replay worktree의 root marker를 비교했다. src/settings.gradle는 존재했고 AGENTS.md만 없었다.
• 2026-07-15 — root AGENTS.md가 Git 추적 대상이 아닌 local artifact임을 확인했다. 별도 worktree checkout은 그 파일을 전달하지 않는다.
• 2026-07-15 — 검증 동안에만 ignored local bridge AGENTS.md를 두고 targeted contract를 다시 실행했다. 검증이 진행됐다.
• 2026-07-15 — bridge를 삭제한 뒤 application repository의 commit history에 bridge가 포함되지 않았음을 확인했다.

근본 원인 / Root cause

• 직접 원인: DeveloperExperienceContractTest가 요구하는 repository-root marker 중 AGENTS.md가 replay worktree에 없었다.
• 근본 원인: Git worktree는 추적 파일을 checkout하지만, 원래 worktree에만 있던 ignored/untracked 파일을 복제하지 않는다. 반면 contract는 AGENTS.md와 src/settings.gradle 두 marker의 존재를 전제로 한다.
• 트리거 조건: 별도 replay worktree에서 root contract를 실행하면서 local bridge를 준비하지 않은 경우.

Sources / 근거

• raw/branch-notes/experiment-nplus1-feed-api-replay — ## 검증 기록의 focused DeveloperExperienceContractTest 실행과 ## 엣지·실패·의존의 temporary bridge 처리 기록이 해결 근거다.
• Local test contract: DeveloperExperienceContractTest의 repository-root marker 조건 — 이 오류의 직접 검증 대상이다.

해결 / Resolution

• 적용한 조치: replay worktree에서 contract 검증을 실행할 때에만 ignored local bridge AGENTS.md를 일시적으로 제공했다.
• 검증 방법: bridge가 있는 상태에서 targeted DeveloperExperienceContractTest를 실행한 뒤, bridge를 제거했다. replay branch의 application commit에는 bridge를 넣지 않았다.
• 잔여 위험 / 후속 작업: 새 worktree에서도 같은 root contract를 실행하려면 bridge 절차가 다시 필요하다. 이 조치는 repository contract의 근본 설계를 바꾸지 않으며, L12 또는 feed query의 회귀를 가리는 용도로 사용하면 안 된다.

회고 / Lessons

• 빨리 감지하는 신호: 새 worktree에서 DeveloperExperienceContractTest만 실패하고 repository root의 AGENTS.md가 없을 때, 애플리케이션 코드보다 ignored local artifact 차이를 먼저 확인한다.
• 예방 체크리스트 항목 후보: worktree 기반 verification 전에 AGENTS.md와 src/settings.gradle의 존재를 각각 확인하고, 필요한 bridge는 local-only로 만든 뒤 검증 직후 제거한다.
• wiki로 끌어올릴 가치가 있는 일반화된 교훈: Git worktree와 repository-root contract가 만날 때 ignored seed/guide 파일을 어떻게 다룰지에 대한 운영 규약.

Related / 관련

• raw/branch-notes/experiment-nplus1-feed-api-replay — parent branch의 replay checkpoint 및 검증 기록.