Skip to content

runtime.md

Latest commit

 

History

History
81 lines (68 loc) · 5.17 KB

runtime.md

File metadata and controls

81 lines (68 loc) · 5.17 KB
Raw

Runtime

Canonical Order

  1. 요청 수신
  2. 소크라테스 질문으로 spec.md 정의
  3. 사용자가 현재 spec 초안에 명시적으로 동의하면 approve로 승인 고정
  4. approve가 spec.md를 task.json.intake로 잠금
  5. plan으로 phases.json 적재
  6. phase-1 실행
  7. run --complete로 phase closure
  8. verify로 completed phase의 acceptance command 실행
  9. 다음 pending phase가 있으면 kickoff로 bootstrap proof 기록
  10. 새 세션이 run --start로 다음 phase 실행
  11. 모든 phase 완료 후 review
  12. review --close로 user validation과 완료 고정
  13. 필요하면 reopen으로 repair loop 재개

Task States

  • draft
  • approved
  • in_progress
  • failed
  • blocked
  • review_ready
  • completed

Phase States

  • pending
  • in_progress
  • completed
  • failed
  • blocked

Runtime Rules

  • approve 전에는 plan, run, verify, review를 허용하지 않는다.
  • 새 clarification contract에서 열린 질문은 Status: open으로 남기고, 모든 질문이 닫힌 뒤에만 승인을 요청한다.
  • approve는 spec.md의 필수 section, placeholder 제거 여부, Socratic Clarification Log의 Q:/A:/Decision:/Status: 형식을 검증한다.
  • approve는 clarification이 최소 1개 이상인지, 열린 질문이 없는지, open 항목에 Decision:이 없는지, resolved 항목이 A:와 Decision:으로 완결되는지 검증한다.
  • approve는 승인된 spec을 task.json.intake로 잠그며, 이후 spec.md를 수정했으면 approve를 다시 실행해 intake를 재잠가야 한다.
  • plan은 명시적 phase 입력 없이는 실행되지 않는다.
  • plan은 task.json.intake와 현재 spec.md가 일치할 때만 허용하며, 각 phase를 새 세션이 시작할 수 있도록 bootstrap metadata를 함께 적재한다.
  • status는 spec.md를 읽어 ready_for_approval, clarification_count, open_clarification_count, resolved_clarification_count, open_clarifications, validation_errors를 JSON으로 노출한다.
  • status는 active phase의 required_reads, starting_points, deliverables, completion_signal도 함께 노출해 다음 세션 시작점을 복원한다.
  • run --complete는 allowed_write_paths와 workflows/tasks/<task-id>/ 밖 변경을 차단한다.
  • run --start는 task.json.kickoff_required_for_phase가 active phase와 일치하면, matching phase_kickoff evidence 없이는 시작되지 않는다.
  • verify는 completed active phase 또는 지정된 completed phase의 acceptance.commands를 실행해 run evidence를 남긴다.
  • phase completion 뒤 verification이 통과하기 전까지 last_verified_run_id는 비어 있어야 한다.
  • verification이 다음 pending phase를 활성화하면 task를 approved로 되돌리고, 다음 phase에 대한 kickoff_required_for_phase를 기록한다.
  • kickoff는 active pending phase의 bootstrap summary를 runs/*.json에 기록한다. 이 증거는 실제 외부 session ID가 아니라 control-plane proof 역할을 한다.
  • review는 last_verified_run_id가 active phase와 일치하는 passed verification일 때만 허용한다.
  • task-level review는 모든 phase가 completed일 때만 연다.
  • review --close --user-validation-note ...만 최종 완료를 닫을 수 있다.
  • incomplete task directory는 doctor와 status --check에서 명시적 consistency error로 보고된다.

Internal Runtime Structure

  • scripts/workflow.py: 안정적인 CLI entrypoint
  • scripts/workflow_runtime/cli.py: command parsing과 dispatch
  • scripts/workflow_runtime/engine.py: 상태 전이와 실행 엔진
  • scripts/workflow_runtime/models.py: artifact validation과 공통 model helper
  • scripts/workflow_runtime/guards.py: TDD, write scope, dangerous command, verification freshness guard
  • scripts/workflow_runtime/doctor.py: repository health와 stale reference 점검
  • scripts/workflow_runtime/git_ops.py: staged/unpushed path 조회

workflow.py를 유지하는 이유는 사람과 AI가 단일 고정 명령 surface를 기억하는 편이 가장 효율적이기 때문이다. init는 로컬 git 저장소의 core.hooksPath를 .githooks로 맞추고, .githooks/*와 workflows/system/hooks.json을 source 기준으로 다시 동기화한다. doctor는 이 설정이 어긋나거나 runtime surface가 source와 drift하면 실패한다.

Retry / Blocked Semantics

  • phase 실패 시 retry_count를 증가시킨다.
  • verification 실패도 retry에 포함한다.
  • 동일한 error_fingerprint가 짧은 시간 안에 반복되면 Circuit Breaker가 blocked로 전이한다.
  • blocked는 외부 입력, spec 재정의, phase 재계획이 필요한 상태다.
  • reopen은 failed, blocked, review_ready, completed task를 다시 approved로 되돌리고 target phase와 그 이후 downstream phase를 pending으로 복구한 뒤 repair loop를 재시작한다.
  • reopened target phase가 2번째 이상 phase면 kickoff proof를 다시 요구한다.
  • 추가 요구사항이면 reopen 뒤 spec.md에 새 clarification을 열고, 질문을 닫은 다음 approve를 재실행한 뒤 plan으로 phase를 다시 적재한다.