marcioaltoe/write-tasks

Write Tasks

docs/specs/<slug>/_prd.md(와 _techspec.md가 존재하는 경우 함께)를 실행 가능한 작업 그래프로 변환합니다: 작업당 하나의 task_NN.md와 implement-task와 Roundfix Daemon이 스케줄링하는 매니페스트인 _tasks.md를 생성합니다. 이 아티팩트들은 계약의 일부입니다 — 새로운 에이전트 세션은 명세 폴더 외의 다른 컨텍스트 없이 하나의 작업 파일을 가져와 빌드할 수 있어야 합니다.

경량 계획(Light tier planning)

complexity: low이고 QA가 아니며 Governed Path를 선언하지 않은 작업은 경량 계층에서 실행됩니다. 작성자는 계획 풀 리퀘스트가 병합되기 전에 roundfix spec judge <slug> --stage tasks를 실행하여 계층 제안을 받을 수 있습니다. 제안은 디스패치를 제어하지 않습니다.

사전 조건

$ARGUMENTS는 명세를 가리킵니다. _prd.md는 반드시 존재해야 합니다. 실제 아키텍처 표면을 가진 기능에 _techspec.md가 누락된 경우, 먼저 write-techspec을 실행한 다음 분해하십시오 — 누락된 아티팩트를 작성하는 것이 해결 방법이며, 허가를 위해 중단할 이유가 아닙니다. 자율 작업 중에는 확인이 필요 없습니다: 자율 작업을 지시하면 이미 승인된 큐에 있는 모든 명세에 대해 전체 작성 체인이 승인된 것입니다(docs/agents/autonomous-work.md 참조). 기술 명세 없이 분해하라는 명시적인 지시가 있을 때만 수락을 요청하고, 분해 전에 더 깊은 코드베이스 탐색으로 보상하십시오.

프로젝트 제약 사전 점검

브레이크다운을 유도하거나 승인하기 전에 다음 사전 점검을 실행하십시오:

1. 명세를 분류하십시오. 해결된 아카이브 디렉토리(docs/history/specs/ (내장 docs/specs 루트의 경우) 또는 외부/기본이 아닌 루트의 경우 <spec-root>/_archived/) 아래에 있거나, 이 계약이 적용되기 전에 완료된 것으로 입증된 명세는 완료되었거나 보관된 레거시 명세입니다. 모든 레거시 아티팩트를 바이트 동일하게 유지하십시오: 백필, 재포맷, 재생성 또는 재작성하지 마십시오.
2. 활성, 비보관, 아직 완료되지 않은 모든 명세에 대해 PRD와 존재하는 모든 TechSpec에 완전한 Project Constraints 섹션이 포함되어 있어야 합니다. 각 섹션에는 Identifier strategy, Authentication and HTTP, Active ADR obligations, Tooling authority가 적용 가능 또는 적용 불가(이유 포함)로 기록되어야 하며, 각 행은 운영 docs/agents/ 소스 경로를 인용해야 합니다.
3. 활성 아티팩트 중 하나라도 누락되었거나 불완전한 경우, _tasks.md 또는 모든 작업 파일의 생성이나 업데이트를 거부하십시오. 누락된 모든 행, 이유 또는 소스 경로를 명명하고 명세를 소유 작성 스킬을 통해 다시 보내십시오.
4. 제안된 슬라이스가 저장소 도구 구성, 스크립트, 무시 파일, 플러그인 선언 또는 버전 핀의 생성, 편집, 이름 변경, 이동 또는 삭제를 포함하는지 검사하십시오. 이러한 작업은 PRD와 존재하는 TechSpec 기록이 유지 관리자 승인과 정확히 범위가 지정된 저장소-상대 파일을 명시하는 경우에만 승인됩니다. 일반적인 구현 요청, 설정 승인 또는 작업 할당은 승인이 아닙니다. 승인과 범위가 지정된 파일이 모두 없으면 분해를 거부하십시오.
5. 모든 도구 슬라이스에 대해 <spec-root>/<slug>/_authorization.md의 운영 기록을 확인하십시오. 기록이 없거나, proposed 기록이거나, 부여 날짜가 없는 기록은 아무것도 승인하지 않습니다. 운영 부여가 존재할 때까지 분해를 거부하십시오. 새 부여 또는 확장된 부여는 소비하는 스쿼시 전달 전에 대상 계보에 도착해야 하므로, 부여 또는 수정은 그것이 승인하는 변경 사항에 접힐 수 없습니다.
6. 범위가 지정된 파일 목록을 각 승인된 도구 작업의 범위 및 승인 기준에 복사하십시오. 작업은 해당 경로와 자체 작업 파일만 변경할 수 있습니다. 다른 경계가 필요한 작업은 분할하십시오.
7. 기록의 operations 목록은 명세가 사용할 모든 전달 작업을 부여해야 합니다. roundfix deliver start는 implement, commit, push, pull_request 또는 merge가 없는 기록을 거부합니다. Governed Path가 없는 명세는 paths: []를 기록합니다.
8. 작업 커밋은 해당 정확한 경로가 명세의 승인 기록에 executables 아래에 나열된 경우에만 추적되지 않은 실행 파일을 유지합니다. 다른 모든 추적되지 않은 실행 파일은 거부됩니다. 목록은 Run이 읽기 전에 전달 대상에 있어야 합니다. QA Report 및 Batch 커밋은 추적되지 않은 실행 파일을 절대 유지하지 않습니다. core.fileMode가 false인 저장소는 파일을 100644로 기록합니다.

의존성은 _tasks.md만이 소유합니다. 작업 상태는 각 작업 파일만이 소유합니다. 사전 점검은 이러한 책임을 절대 이동하지 않습니다.

다른 운영 체제용 코드는 해당 시스템에 대한 비테스트 코드를 빌드하여 확인합니다(예: GOOS=windows go build -buildvcs=false ./<package>). go vet는 호스트용으로 작성된 테스트도 컴파일하므로 사용하지 마십시오.

소유권 규칙 (무엇이 어디에 있으며, 그 이유)

• 의존성은 _tasks.md 그래프에만 존재합니다. 작업 파일에는 절대 존재하지 않습니다. 모서리(copy)의 두 복사본은 그래프가 표류(drift)하는 방법입니다.
• 상태는 각 작업 파일의 프론트매터(frontmatter)에만 존재합니다. _tasks.md는 토폴로지를 소유하고 진행 상황은 소유하지 않습니다 — 스케줄러는 상태를 위해 작업 파일을 다시 읽습니다.
• 작업 유형(Task Type)은 모든 작업 파일에 필수입니다. backend, frontend, data, infra, docs, test, chore 또는 qa 중 정확히 하나를 사용하십시오. qa는 매니페스트의 qa: 필드가 명명한 고유한 작성된 터미널 게이트를 위해 예약하십시오. Implement Command는 이 값을 라우팅에 사용하며 누락되거나 알 수 없는 값은 거부합니다. 자리 표시자를 남기거나 나중에 유형을 유추하지 마십시오.
• 내용 참조, 중복 금지. 작업 파일은 이름으로 PRD/TechSpec 섹션을 가리킵니다. 명세를 다시 기술하는 작업은 명세가 수정되는 즉시 오래됩니다. 채택된 소스를 해당 작업 파일에 상대적인 대상 경로로 소유 명세의 채택 후 경로에 링크하고, 채택 전 출처 경로에는 절대 링크하지 마십시오. 보조 명세는 기본 소유자의 복사본을 링크하고 아무것도 채택하지 않습니다. 소유자의 아카이브는 Archive Relink를 수행합니다: 해당 복사본을 docs/references/로 승격시키고 보조 명세의 링크를 다시 작성하므로, 소스는 하나의 소유자를 유지하고 보조 명세는 복사본이 필요하지 않습니다(ADR-0260, ADR-0083).
• 컨텍스트 항목은 레이블이 지정된 경로입니다. 작업에 표준 명세 번들 이상의 특정 지침이나 인터페이스 경로가 필요한 경우에만 ## Context를 추가하십시오. - instruction: <path>, - interface: <path>, - creates: <path> 또는 - deletes: <path> 모양의 글머리 기호를 사용하십시오. 경로는 깔끔하고 저장소-상대적이며 고유해야 합니다. 작업은 최대 50개의 고유 항목을 선언할 수 있습니다. Daemon은 이전에 변경된 파일로 200개 경로 Spec Context Bundle을 채우기 전에 해당 경로를 예약합니다.
• 선언된 편집과 Governed Path는 명시적입니다. 작업이 편집하는 모든 경로는 interface: 또는 creates: 아래에 선언됩니다. 제거하는 모든 경로는 deletes: 아래에만 선언되며, interface: 또는 instruction: 아래에는 절대 선언되지 않습니다. 제거하기 전에 파일을 읽는 작업도 deletes: 아래에 한 번만 나열합니다. 삭제는 확인되지 않은 참조 검사에 의해 건너뛰며, 범위, Governed Path 및 Wave 충돌 감사에서 계산됩니다. Daemon은 선언된 삭제가 여전히 존재할 경우 정산 전에 deletes: <path> still exists로 정착을 거부합니다. instruction: 경로는 읽기 전용이며 두 작업이 충돌하지 않습니다. 명령을 변경하는 각 작업은 변경하는 하나의 명령 파일을 선언합니다: .agents/skills/roundfix/references/<command>.md와 미러, 그리고 docs/user-guide/commands/<command>.md입니다. 스킬의 SKILL.md나 commands.md는 엔트리 파일 자체를 변경하지 않는 한 포함되지 않습니다. 동일한 파일을 선언하는 두 작업은 Wave를 공유할 수 없으므로, 다른 명령을 변경하는 작업은 함께 실행될 수 있고 동일한 명령을 변경하는 작업은 그들 사이에 엣지가 필요합니다. 선언되거나 Verification이 읽은 Governed Path는 명세의 _authorization.md paths:와 두 bounded files: 행에 모두 나타나야 합니다. 그렇지 않으면 SC-TOOLING-UNDECLARED로 작성이 거부됩니다. CLI surface를 명명하는 작업은 자신이나 의존하는 작업을 통해 스킬 또는 가이드를 명명합니다. 그렇지 않으면 SC-CLI-UNDOCUMENTED로 보고됩니다.

Daemon은 커밋 시 ## Recorded paths 아래에 작업이 선언하지 않고 변경한 경로를 기록합니다. QA 범위 감사는 해당 기록된 경로를 선언된 것으로 계산하며, 기록은 변경을 공개할 뿐 아무것도 예약하지 않습니다. 모든 예측 가능한 경로를 선언하는 것이 규칙입니다.

두 작업이 각각 변경할 수 있는 테스트 헬퍼, 페이크, 픽스처 또는 골든 파일은 예측 가능한 경로입니다. 이를 변경할 수 있는 모든 작업의 interface: 아래에 선언하면, roundfix spec check --strict가 명세가 아직 작성 중인 동안 SC-WAVE-COLLISION을 보고하고, 그것이 명명한 needs 엣지가 해당 작업을 직렬로 실행합니다. 기록은 아무것도 예약하지 않으며, 완료된 작업은 절대 충돌하지 않습니다: 작업의 정산 커밋은 두 작업 중 하나가 완료되지 않은 경우에만 충돌 증거입니다(예: pending으로 다시 열린 작업). 따라서 동일한 Wave의 두 작업이 선언되지 않은 동일한 파일을 변경한 후 모두 완료되더라도 거부되지 않습니다. 파일을 선언하는 것이 유일한 보호 장치입니다.

변경된 동작 표면(Behavior Surfaces)에 대한 스킬 작업

docs/references/skill-coverage.json에 있는 저장소의 Skill Coverage Map을 읽으십시오(존재하는 경우). 비QA 작업이 interface:, creates: 또는 deletes: 아래에 선언한 소스에 대해 다루는 모든 동작 표면(Behavior Surface)에 대해, interface: 또는 creates: 아래에 해당 스킬 파일 중 하나를 선언하는 비QA 스킬 작업을 포함하십시오. 해당 작업이 없는 표면은 SC-SKILLS-UNTASKED로 보고됩니다.

변경에 스킬 텍스트가 필요하지 않은 경우, PRD의 선택적 ## Skills 섹션에 - unchanged: <surface id> — <reason>을 기록하고 Coverage Review를 기록하기 위해 interface: 또는 creates: 아래에 맵을 선언하는 비QA 작업을 포함하십시오. 항목만으로는 표면을 면제하지 않습니다. 다른 모양의 항목, 알 수 없는 표면 또는 빈 이유는 SC-SKILLS-MALFORMED로 보고됩니다. 두 규칙 모두 맵이 추가된 커밋부터 시작됩니다. 맵이 없는 저장소는 이를 건너뜁니다.

docs/user-guide/ 아래의 Markdown 페이지를 interface:, creates: 또는 deletes: 아래에 선언하는 비QA 작업은 또한 docs/references/behavior-surfaces.json을 interface: 또는 creates: 아래에 선언하고 요구 사항에 -record-skill-coverage 단계를 명명해야 합니다. 다른 작업이 이를 대체할 수 없습니다: 가이드 작업의 자체 정산이 핑거프린트를 확인합니다. 명세의 _authorization.md Limits는 해당 기록을 금지해서는 안 됩니다. 기록이 있는 저장소에서 Tasks 단계의 어떤 격차도 SC-SURFACE-RECORD-UNTASKED로 보고됩니다.

분해 규칙

다른 운영 체제용 코드는 해당 시스템에 대한 비테스트 코드를 빌드하여 확인합니다(예: GOOS=windows go build -buildvcs=false ./<package>). go vet는 호스트용으로 작성된 테스트도 컴파일하므로 사용하지 마십시오.

• 수직 슬라이스(Vertical slices). 각 작업은 작업이 건드리는 모든 계층을 통과하는 좁지만 완전한 경로를 제공하며, 자체적으로 데모 가능하거나 검증 가능해야 합니다 — 추적자 탄환(tracer bullet)이지 계층이 아닙니다("모든 스키마"는 잘못된 작업입니다. "만료된 가져오기가 재시도되고 상태를 표시함"이 올바른 작업입니다).

• 먼저 사전 리팩토링(Prefactoring first). 슬라이스가 기반을 마련해야 하는 경우, 이를 자체 선행 작업으로 만드십시오: 변경을 쉽게 만든 다음, 쉬운 변경을 수행하십시오.

• 작성 중 외부 표면 특성화(Characterize external surfaces during authoring). 명세가 어댑터, 계약 또는 데이터베이스와 같은 외부 표면을 교차하는 경우, 실제 경계가 무엇을 하는지(페이크가 하는 것이 아니라) 기록하는 특성화(Characterization) 작업을 작성하십시오. 이는 지원되지 않는 전제가 QA 게이트가 아닌 명세 작성 중에 실패하도록 합니다.

  needs에 나열하십시오. 단순히 파일에서 더 앞에 있는 것이 아닙니다. 전제가 특성화에 의존하는 모든 작업은 _tasks.md의 needs 항목에 해당 작업을 명명합니다. 실행 Wave는 needs만으로 구축되므로, 매니페스트에서 단순히 나중에 나타나는 작업이 의존하는 특성화와 동일한 Wave에서 실행되어 아직 특성화되지 않은 경계를 읽을 수 있습니다. 파일 순서는 의존성이 아닙니다.

  특성화 작업은 실제 경계를 건드리므로, 명시적으로 바인딩하십시오. 해당 파일은 도달할 대상을 이름으로 명시합니다. 읽기는 하지만 쓰지는 않거나, 작업 자체가 생성하고 제거하는 격리된 인스턴스에 대해 실행됩니다. 기본적으로 공유 또는 프로덕션 상태에 대해 특성화하지 않습니다. 해당 대상으로만 범위가 지정된 자격 증명을 사용하고, 취소를 존중하며, 실패하더라도 생성한 것을 정리합니다. 기록을 위해 쓰기가 필요한 특성화는 다른 돌이킬 수 없는 작업과 마찬가지로 작업에서 해당 쓰기가 승인되어야 합니다. 경계가 하는 것을 기록하는 것은 이를 변경할 권한이 아닙니다.

  Verification은 기록을 주장하고, 경계를 주장하지 않습니다. Daemon은 작업의 선언된 ## Verification 명령을 셸을 통해 그대로 실행합니다. 에이전트 차례가 존재하기 전에 변경되지 않은 트리에서 한 번, 정산 시 다시 한 번 실행합니다. 해당 경로의 어떤 것도 위의 바운드를 읽지 않습니다: 이는 에이전트를 제약하며, Daemon은 에이전트가 아닙니다. 그러므로 실제 표면에 도달하는 Verification은 바운드 없이 두 번 도달합니다(작업이 수행되기 전에도 포함). 작업이 기록한 특성화(해당 형태, 존재 여부, 다운스트림 작업이 읽을 내용)를 확인하고, 경계 호출은 작업의 선언된 대상, 격리, 자격 증명 및 쓰기 승인이 적용되는 에이전트 차례에 남겨 두십시오. 이것이 이미 이러한 명령이 지니는 밀폐 규칙(hermeticity rule)입니다. 이를 깨고 싶은 유혹이 가장 강한 곳에 명시되었습니다: 라이브 외부 표면은 주변 상태이며, 이에 의존하는 명령은 밀폐적이지 않습니다.

• 하나의 새로운 세션에 적합한 크기. 에이전트가 새로운 컨텍스트로 한 번의 작업으로 완료할 수 있는 작업입니다. 약 7개 이상의 하위 작업 또는 파일은 분할해야 합니다.

• 테스트 포함, 분리 금지. 모든 작업의 승인 기준에는 자체 테스트가 포함됩니다. 후행 "테스트 작성" 작업은 이전 작업이 완료되지 않았음을 의미합니다.

• 독립적으로 구현 가능. needs가 완료되면, 작업은 다른 미완료 작업을 요구하지 않아야 합니다. 이것이 나중에 여러 작업 트리에서 병렬 실행을 가능하게 하는 것입니다.

• Verification은 밀폐적이고, 이식 가능하며, 효과를 증명하고, Daemon이 소유해야 합니다. 모든 작업의 ## Verification 명령은 다음과 같은 특성을 만족해야 합니다.