serhii-nochevnyi/shipyard

전달 컨베이어 규칙

이 프로젝트는 GSD(참조: docs/gsd_multilevel_delivery_pipeline.md) 위에서 티켓별 전달 컨베이어를 실행합니다. 계획은 티켓 역할을 겸하며, 이 규칙들은 컨베이어의 결정적 계층이 기계가 읽을 수 있도록 유지합니다.

언어. 모든 산출물(계획, 프론트매터, 커밋, 코드, PR 본문)은 영어로 작성합니다. 사용자와 직접 대화할 때는 사용자의 언어로 응답하세요. 산출물은 영어, 대화는 사용자 언어입니다.

계획자용(PLAN.md 작성)

1. 항상 전체 프론트매터: phase, plan, title, type, wave, depends_on: [], files_modified: [], requirements: []. 빈 requirements는 차단자(BLOCKER)입니다. GSD의 계획 검사기와 게이트 2(validate-graph) 모두 이를 거부합니다. ROADMAP 요구사항 ID 또는 계획을 가져올 때 외부 트래커 ID를 참조하세요. wave는 인간 독자를 위한 문서입니다. 그래프가 권위적이며 검증기가 실제 의존성 깊이를 다시 계산하여 값이 일치하지 않으면 경고합니다. 장식이 아닌 사실적으로 유지하세요.

2. 전달 블록(추가적이며 GSD 필드를 절대 대체하지 않음):

   delivery:
     ticket: T-<phase>-<plan>
     risk: low|medium|high        # high인 경우 human_checkpoint: true가 필수
     human_checkpoint: false
     repo: owner/name             # 작업이 다른 저장소에 있을 때만 사용
   

   repo는 이 저장소를 건드리지 않는 모든 티켓에 필수입니다. 생략하면 컨베이어가 잘못된 저장소에 대해 티켓을 추적합니다. PR이 그린이고 옆에서 병합되었지만 보드에는 pending으로 남아 있으며, 모든 종속 티켓은 절대 움직이지 않는 티켓 뒤에 차단됩니다. files_modified의 경로는 해당 저장소에 상대적입니다. ../other-repo/x.ts는 어떤 워크트리도 도달할 수 없습니다(게이트 2 경고, 상태 동기화가 티켓을 일시 중지). 교차-저장소 의존성은 캐스케이드되지 않습니다. 상위 항목이 먼저 병합되어야 하므로, 전체 기능을 기다리게 하지 말고 계약 측면(타입/도구 이름)을 자체 티켓으로 분할하세요.

3. 브랜치 이름을 임의로 만들지 마세요. 표준 브랜치는 ticket/<ID>-<slug>이며, slug는 정리된 티켓 제목(소문자, 음역, 비알파벳 문자를 단일 하이픈으로 축소, 40자 이하)입니다. delivery.branch를 생략하세요. 그래프 검증기가 생성합니다. 명시적 값은 동일한 규칙에 대해 검증됩니다.

4. files_modified는 추측이 아닌 계약입니다 — 계획이 건드리는 모든 경로를 나열하세요. 빈 files_modified는 게이트 2를 통과하지 못합니다(이것이 "의존성 순서가 없는 티켓이 절대 충돌하지 않음"을 확인 가능하게 하며 실행자의 범위입니다). 의존성 순서가 없는 계획이 경로를 겹치게 하는 경우 게이트 2를 통과하지 못합니다. 의존성 추가 또는 재분할로 해결하고, 글로브를 넓히지 마세요(모든 것을 일치시키는 베어 글로브는 플래그 지정됩니다).

5. 새로 작성하기 전에 이미 이 작업을 수행하는 것이 무엇인지 명명하세요. 모든 계획의 컨텍스트 읽음은 티켓이 확장하는 기존 구현(path:line — 변환기, 정렬기, 미들웨어, 헬퍼, 엔드포인트)을 가리키거나, 찾지 못했다는 확인(검색한 동작과 찾아본 두세 개의 그럴듯한 위치)을 기록해야 합니다. 의도한 새 코드의 이름이 아닌 동작으로 검색하세요. 중복된 코드는 거의 항상 다른 이름으로 불리며, 이것이 바로 검토를 통과하는 이유입니다. "보지 못했다"는 "찾아봤다"와 다른 진술입니다. 오직 두 번째만이 독자가 신뢰할 수 있는 계획입니다. 이는 컨베이어에서 가장 저렴한 게이트입니다. 눈에 띄지 않는 중복은 통합자가 한 단계 후에 발견하며, 다른 티켓이 이미 그 위에 구축된 후이며, 그때 제거하는 것은 자체 티켓입니다. §4와 달리 이는 프론트매터에서 기계적으로 확인할 수 없습니다. 게이트 2는 이를 볼 수 없으며, 드리프트-체크는 재판단하는 티켓에 대해서만 백스톱 역할을 하므로, 이를 기록하는 것이 통제 수단입니다.

6. 검증 명령어는 티켓에 범위가 지정되며, 프로젝트 전체가 아닙니다. files_modified를 실제로 커버하는 가장 좁은 명령어를 작성하세요. 특정 테스트 파일이나 필터, 건드린 경로에 대한 타입체크 및 린트. 베어 npm test / make test / 전체 e2e 스위트는 여기서 검증 명령어가 아닙니다. 이는 CI에 속하며, CI는 이를 위해 구축된 하드웨어에서 푸시당 한 번 실행합니다. 실행자는 모든 시도에서 이를 실행하고 수정 역할은 모든 라운드에서 다시 실행하므로, 범위가 지정되지 않은 명령어는 한 번 느린 것이 아니라, 컨베이어 전체의 틱 속도에 각 티켓이 자체 워크트리에서 병렬로 실행되는 횟수를 곱한 것입니다. 명령어가 사용 가능하려면 두 가지 속성이 필요합니다. 외부 서비스 없이 베어 워크트리에서 실행 가능해야 하며, 이 티켓의 실수에 대해서만 실패해야 합니다. 범위를 지정할 수 없는 명령어(라이브 데이터베이스, 브라우저, 배포된 환경이 필요한 스위트)는 CI 전용 검사입니다. 테스트 전략 아래에 명시하고 검증 명령어에서 제외하여 실행자에게 실행할 수 없는 것을 전달하지 마세요.

7. depends_on은 순서뿐만 아니라 캐스케이드를 구동합니다. 에픽 스택 전달(기본값)에서 루트 티켓(빈 depends_on)은 단계 에픽 브랜치로 PR을 보냅니다. 종속 티켓은 캐스케이드됩니다. 즉, 병합을 기다리지 않고 기본 부모의 브랜치로 PR을 보내므로 흐름이 절대 차단되지 않습니다. 의존성을 정확하게 선언하세요. 가짜 의존성은 흐름을 직렬화하고, 누락된 의존성은 실행자에게 불완전한 베이스를 제공합니다. 검증기는 에픽(epic/<phase-dir>), 기본 부모, pr_base를 파생합니다. 동일 단계의 여러 부모(다이아몬드)는 경고를 받습니다. 실용적일 때 선형화하세요. 의존성을 한 단계 내로 유지하세요. 교차-단계 의존성은 캐스케이드될 수 없습니다. 공유 브랜치가 없어 스택할 수 없으므로 종속 티켓은 부모의 전체 단계가 기본 브랜치에 도착할 때까지 차단된 상태로 유지됩니다. 검증기는 각각에 대해 경고합니다. 대신 재분할하세요.

8. ID는 표준입니다: T-<2자리 단계>-<2자리 계획>. T-01-02로 작성하고 T-1-2는 사용하지 마세요. 검증기는 둘 다 정규화하지만, 브랜치, PR 제목 및 Jira 레이블은 다른 모든 곳에서 문자열 비교됩니다.

9. 값에 후행 # 주석을 달지 마세요. 주석은 별도 줄에 두세요. files_modified: [a.ts] # note는 주석을 마지막 경로에 접곳습니다. 파서는 이제 이를 올바르게 제거하지만, 게이트 2는 #을 포함하는 모든 값을 거부합니다. 거의 항상 누출이기 때문입니다.

10. 게이트 2는 기계적입니다. 그래프 검증기가 0으로 종료될 때만 통과합니다. Jira/GitHub 이슈, ROLLOUT.md, 또는 산문 요약은 구체화된 PLAN 파일을 대체하지 않습니다.

11. Jira는 투영이며 진실의 원천이 아닙니다. 기본적으로(pipeline.jira.enabled: false이거나 Jira MCP가 연결되지 않은 경우가 아니면) 분해는 게이트 2 이후에 검증된 그래프를 Jira로 내보냅니다(단계당 하나의 에픽, 티켓당 하나의 이슈). 영어로, 게이트 2 이후에, 절대 이전이나 대신으로 내보내지 않습니다. 프로젝트는 자동으로 해결되고 캐시됩니다. Jira 실패는 분해를 차단하지 않아야 합니다. PLAN 파일은 표준 상태를 유지합니다.

실행자용(티켓 구현)

1. files_modified 내에 머무르세요. 범위를 벗어난 변경은 다른 티켓에 속합니다. 조용히 범위를 확장하지 말고 에스컬레이션하세요.
2. 새 코드를 작성하기 전에 기존 구현을 읽으세요. 계획이 §5 아래에 명명한 모든 것, 그리고 드리프트-체크에서 컨베이어가 제공한 reuse_candidates를 먼저 각각 읽고, 그 위에 병렬 레이어를 추가하기보다 확장하세요. 후보가 진정으로 맞지 않으면 증거에 이유를 명시하세요. 이는 합법적인 결과이며, 조용히 무시하는 것은 그렇지 않습니다. 재사용은 결코 files_modified를 벗어나는 것을 허용하지 않습니다. 그 위에 구축하면 범위를 벗어난다면, 이는 더 넓은 diff가 아닌 범위 외 에스컬레이션(§1)입니다.
3. 원자적 커밋은 티켓 ID를 접두사로 사용합니다: feat(T-01-02): ….
4. 계획의 검증 명령어를 로컬에서 그린으로 실행한 후 완료를 선언하세요. 명령어 출력 없이 검증을 주장하지 마세요. 해당 명령어를 실행하고, 전체 스위트를 넓혀서 "철저하게" 하지 마세요(§6). CI가 전체 실행을 소유하며, 여기서 시작한 스위트는 자신의 워크트리와 머신을 공유하는 다른 모든 실행자를 차단합니다. 계획의 명령어가 깨졌거나 변경 사항을 분명히 커버하지 않는 경우, 계획에서 수정하거나 좁히고 증거에 명시하세요. 조용히 npm test로 대체하는 것은 수정이 아닙니다.
5. 워크트리와 브랜치는 컨베이어(tickets.json)에서 제공됩니다. 임시로 브랜치나 워크트리를 만들지 마세요. PR 베이스도 컨베이어에 의해 결정됩니다(delivery-state.json → base: 루트 티켓의 경우 에픽 브랜치, 종속 티켓의 경우 부모 브랜치). 에픽 스택 아래에서는 절대 main/master로 직접 PR을 열지 마세요.
6. 커밋에서 멈추세요. push하지 말고, 풀 리퀘스트를 열지 말고, 리뷰어를 지정하지 마세요. 오케스트레이터는 아무것도 게시하기 전에 워크트리를 기계적으로 확인합니다(git log <base>..HEAD). 이 확인은 "에이전트가 성공을 보고했지만 아무것도 변경하지 않음"을 잡아내며, 게시가 확인 중인 에이전트의 손에 있지 않을 때만 작동합니다. 검증 증거와 PR 본문을 대신 전달하세요.

유지보수자용

이 지식은 에이전트별로 분할되고 캐시되며 각 실행 시작 시 재구성됩니다. 프롬프트 증발을 방지하려면 항상 skills/shipyard/ 아래에 이 파일을 다시 로드하세요.