Auto Go

---
name: auto-go
description: SPEC 구현 — SPEC 문서를 기반으로 코드를 구현합니다
compatibility: omp
---

# auto-go — SPEC 구현 스킬

## OMP Invocation

- `/auto go ...`
- `/auto-go ...`
- Load detail skill `auto-go` for either entrypoint.


## OMP Team and Provider Axes

- `--team` selects owner `omp` native `task` batch with explicit Lead/Builder/Guardian responsibilities.
- `--multi` selects provider-diverse planning and review, not team execution topology.
- `--team --multi` composes team execution with provider-diverse planning and review.
- without `--team` or `--solo`, owner `omp` uses the default native `task` batch pipeline.
- `--team` conflicts with `--solo` and owner `orca`.
- Lead, Builder, and Guardian coordinate only through native `task`, `hub`, and `todo`; the main OMP session owns the checklist and DAG.


## Execution Owner Control Plane

- Invocation: `/auto go SPEC-ID [--execution-owner omp|orca]`. Omission selects `omp` with receipt source `default`; a supplied exact value has source `explicit`.
- Parse the flag exactly once before any `task`, DAG-owning `todo`, OMP subprocess, or Orca Run effect. Reject repeated, mixed, case-shifted, whitespace-padded, or aliased values without fallback.
- Persist the body-free receipt `.autopus/pipeline-state/<SPEC-ID>.execution-owner.json` with schema `pipeline_execution_owner_receipt.v1` and only owner, source, reason, SPEC/run identity, `checked_at`, and `verification_status` evidence.
- Owner `omp`: the current OMP session is the sole DAG owner, uses native `task`, `hub`, and `todo`, and must not create an Orca Run.
- Owner `orca`: do not initialize an OMP task/todo DAG or call `task`. Run and read `orca skills get orchestration --full`, then use its supervised durable cross-worktree Run contract.
- At `auto pipeline run SPEC-ID --platform omp --execution-owner orca`, the tier integrity gate runs and the receipt is persisted before any Run, worker, or provider session exists, and the pipeline then executes its phases on supervised Orca workers. Never retry a failure as owner `omp`.


**프로젝트**: autopus-adk | **모드**: full

## 설명

SPEC 문서를 기반으로 코드를 구현합니다. TDD 방법론을 따릅니다.
기본 파이프라인 상세 단계는 `.omp/skills/agent-pipeline/SKILL.md`를 따릅니다.

## Context Profile: go

- Supervisor Required: core,resolved_spec,plan,acceptance
- Worker Optional: signature,learning,task_declared_extra
- Excluded: test,canary
- Select architecture explicitly with `--conditional-profile architecture` or `--required-document`.

## 사용법

```
/auto go SPEC-ID
/auto go SPEC-ID --continue
/auto go SPEC-ID --solo --quality ultra
/auto go SPEC-ID --auto --loop
/auto go SPEC-ID --team --auto
```

### 플래그

| Flag | Description |
|------|-------------|
| `--continue` | 이전 중단 지점에서 재개합니다. |
| `--team` | Codex Multi-Agent V2 Lead/Builder/Guardian 팀 프로파일로 실행합니다. |
| `--solo` | 서브에이전트 없이 메인 세션에서 직접 구현합니다. |
| `--strategy <value>` | `--multi` 리뷰 전략을 지정합니다. |
| `--providers <list>` | SPEC 및 코드 리뷰에 전달할 provider 목록을 지정합니다. |
| `--skip-scaffold` | 초기 테스트 스캐폴딩 단계를 건너뜁니다. |

### 공통 플래그

- `--auto`: 승인/확인 단계 자동 진행. Codex에서는 기본 `task` batch subagent pipeline 진행에 대한 명시적 승인으로도 해석합니다.
- `--loop`: RALF 재시도 루프 활성화
- `--multi`: 멀티 프로바이더 리뷰 활성화
- `--quality <mode>`: 하위 에이전트 품질 모드 지정

## Context Load

- 구현 전에 `auto workflow context --project-dir <root> --command go --spec-dir <SPEC_DIR> --format json`을 실행해 필수 문서 매니페스트를 생성하고 검증합니다.
- `AGENTS.md`, `.autopus/project/workspace.md`, 현재 존재하는 architecture 문서, relevant `spec.md`, `plan.md`, `acceptance.md` 전문을 receipt 예산 밖의 비축약 frozen snapshot으로 전달합니다.
- task별 추가 문서는 context 생성 시 `--required-document <ref>`로 선언하고, binding 검증 시 같은 집합을 `--context-required-document <ref>`로 다시 전달합니다. 선택한 conditional profile도 두 명령에 같은 값으로 전달합니다.
- scenarios, canary, signatures, learnings는 선택한 command profile이나 현재 task가 명시적으로 요구할 때만 추가합니다.
- worker에게 모든 문서와 해시를 전달하고 `context_ack`를 진단 증거로 요청합니다. 전달 무결성은 `context_ack` 문구가 아니라 supervisor가 보유한 필수 reference 집합과 매니페스트 해시로 판정합니다.
- core/SPEC 문서가 없거나 비어 있거나 읽을 수 없거나, 현재 존재하는 architecture 문서가 안전하게 전달되지 않거나, 매니페스트가 stale·incomplete·wrong-SPEC·hash mismatch 상태이면 provider를 호출하지 않습니다. full Ultra binding을 유지한 채 문서를 복구하거나 task를 분할한 뒤 다시 검증합니다.
- 토큰 예산으로 줄일 수 있는 것은 memory/knowledge/index의 optional recall뿐입니다. 전체 입력이 128K 안전 한도를 넘으면 필수 문서를 자르지 말고 task를 분할하거나 차단합니다.

## 구현 절차


1. RED: 실패 테스트 작성
2. GREEN: 최소 구현으로 통과
3. REFACTOR: 코드 개선


## Minimality Discipline

Before implementation assignment, apply the minimality ladder: `actual need` → `existing code/helper/pattern` → `stdlib/native` → `existing dependency` → `new dependency or abstraction` → `minimum sufficient verification`.

- Executors must search existing code paths, helpers, and patterns before adding new helpers, dependencies, or abstractions.
- Minimum sufficient implementation means the smallest change that closes the Outcome Lock with evidence, not the shortest code.
- Do not reduce non-reducible gates: `security`, `validation`, `accessibility`, `data-loss`, `deterministic-oracle`, `generated-surface-hygiene`.
- `minimum sufficient verification` must include the focused checks needed for the changed surface while preserving those gates.
- Final handoff must include a concise receipt of important choices: reused existing code/helper/pattern, skipped dependency or abstraction, accepted new dependency or abstraction with evidence, and selected verification.
- `qualityloop`/`skillevolve` signals are candidate-only and remain isolated/quarantined; do not apply them during this workflow.

## Phase 1.9: Risk-First Probe Gate

Phase 1.8 이후, Phase 2 fan-out 전에 메인 세션에서 실행합니다. 이 게이트는 기본 prompt-driven pipeline에 적용되며 deterministic Route A / Route Team 계약은 변경하지 않습니다.

- `plan.md`의 `## Risk-First Integration Probe` 표(1-3개 행)를 읽습니다.
- 지금 실행 가능한 `not-run` 행(실제 boundary, 격리된 fixture, 승인되지 않은 외부 효과 없음)은 실제로 실행하고 `PASS` 또는 `FAIL`을 실행 evidence ref와 함께 기록합니다.
- 계속 `not-run`인 행은 reason을 유지한 채 handoff의 명시적 limitation으로 넘깁니다. 절대 `PASS`로 보고하지 않습니다.
- high/critical 가정이 `FAIL`이면 planning으로 돌아가 `plan.md`를 수정합니다. re-plan은 최대 1회이며, 두 번째 `FAIL`은 세 번째 시도 대신 사용자에게 surface합니다.
- 구현자가 요구사항보다 넓은 제약(신규 ACL, 호환성 제한, 보안 제한)을 도입하면 scope expansion이므로 fan-out 전에 기존 런타임에서 probe합니다.

Gate applicability는 에이전트 판단이 아니라 receipt에서 옵니다. Phase 2 fan-out 전에 `auto spec gates {SPEC_ID} --base <ref>`(또는 `--changed p1,p2,...`)를 실행하면 `{SPEC_DIR}/gate-applicability.json`이 `spec_authoring, risk_first_probe, build, unit_tests, integration, security, validation, data_loss, deterministic_oracle, accessibility, ux_verification, annotation, provider_review, doc_sync` 전체에 대해 작성되고, 모든 worker 프롬프트가 그 결정을 `gate: applicability — reason`으로 전달합니다.

- `spec_authoring`: 저위험 선언 클래스(`test_only`, `docs_only`, `small_ui`, `bugfix_existing_contract`)는 compact `change.md`가 4문서 SPEC 세트를 대체하므로 `not_applicable`, `feature`/`multi_domain`/`security_or_data`는 `required`.
- `risk_first_probe`: 고위험 변경이 통합 경계를 건드리면 `required`, doc-only change set이나 저위험 선언 클래스면 `not_applicable`(단, `not-run` 한 행과 `no integration boundary` 이유 유지), fixture/환경이 없으면 `blocked`.
- `reusable`은 receipt가 부여할 때만 유효합니다. 직전 `{SPEC_DIR}/gates/evidence-<gate>.json`의 `input_closure_sha256`이 현재 트리와 일치하고 `status: pass`, `complete: true`, `observed_at`이 `--max-age`(기본 168h) 안일 때만입니다. `input_globs`를 재확장하므로 파일 추가도 수정과 동일하게 evidence를 무효화하며, 의존성 변경·`fail`·`partial`·누락 입력·만료 receipt는 실패 조건을 명시한 `required`가 됩니다. 에이전트가 `reusable`을 자체 부여하지 않습니다.
- 실제 build/test/UX 실행 직후 `auto spec gates record {SPEC_ID} --gate <id> --status pass|fail|partial --inputs <glob,...> [--dynamic-deps <path,...>] [--command "<text>"]`로 evidence를 기록합니다.
- `security`, `validation`, `data_loss`, `deterministic_oracle`은 `not_applicable`이 될 수 없습니다. `accessibility`와 `ux_verification`은 변경 집합에 UI 경로가 있으면 `required`, 없으면 `no UI surface in change set` 이유의 `not_applicable`이며 classifier만 판단합니다.
- `autopus.yaml`에 `verify.capture: no-capture`가 설정되면 스크린샷 없이 검증하고 `dom_geometry`, `accessibility_tree`, `keyboard_navigation`, `state_transition` 네 oracle이 모두 필수가 됩니다. 하나라도 없으면 UX PASS는 금지이며 kind를 명시한 `blocked`로 보고합니다.
- 각 결정은 `auto telemetry record --spec-id {SPEC_ID} --action gate --gate <id> --applicability <value> [--resolved]`로 기록하고, 첫 probe `PASS`(모든 행이 `not-run`이면 첫 실제 통합 실행) 시점에 `auto telemetry record --spec-id {SPEC_ID} --action milestone --name first_vertical_slice`를 기록합니다.

## Frontend Design Preflight

- UI 관련 변경(`.tsx`, `.jsx`, CSS-family, theme/token/design-system 경로, configured UI globs)이 있으면 구현 전에 `auto design pack --format markdown`을 실행하거나 동등한 local evidence를 수집합니다.
- `DESIGN.md`, declared `source_of_truth`, token/theme refs, shared UI primitives, screenshot/golden refs, Figma refs, Code Connect readiness를 Design Source Pack으로 기록합니다.
- 구현 전 Design Discovery Matrix를 작성합니다: surface type, core job, density, risk, required primitives, required states, accessibility checks, responsive checks, anti-patterns.
- source가 없거나 Figma/Code Connect가 없으면 setup gap으로 기록합니다. 기존 프로젝트 디자인 시스템을 임의로 대체하거나 새 palette/radius/shadow 체계를 만들지 않습니다.
- raw color, generated token edit, primitive token consumption, unlabeled icon-only control, missing focus state, proofless production action, responsive overlap, color-only status meaning은 SPEC 예외가 없는 한 blocking issue로 취급합니다.

## QAMESH Scope Budget

- `go` 안에서는 변경 범위와 직접 관련된 affected/fast/smoke QAMESH lane만 실행합니다. 먼저 `auto qa plan --lane fast --format json`으로 Journey Pack, adapter, setup gap을 확인합니다.
- full GUI/native/release matrix는 `go`에서 기본 실행하지 않습니다. 전체 데스크톱 GUI 탐색은 명시적 `auto qa ...` 실행으로 넘기고, `auto canary`는 post-deploy smoke/status gate로만 사용합니다.
- QA 신호가 있지만 Journey Pack이 없으면 기본값은 `auto qa init --format json`입니다. 이 명령은 project-local starter와 release gate scaffold를 함께 만듭니다. Journey Pack만 필요하면 `auto qa init --local-only --format json`을 사용합니다. 생성된 pack/workflow는 command, origin, forbidden action, oracle, env 검토 전에는 실행하거나 required gate로 승격하지 않습니다.

## 실행 계약

### Step 0: 플래그 파싱

구현 시작 전에 다음 항목을 먼저 확정합니다.
- `--team` → Codex team profile
- `--solo` → 단일 세션 구현
- `--strategy <value>`
- `--providers <list>` → `PROVIDERS`; 입력이 없으면 provider 플래그를 생략
- `--continue`
- `--skip-scaffold`
- 글로벌 `--auto` / `--loop` / `--multi` / `--quality`

실행 모드:
- `--team` → Codex Multi-Agent V2 팀 프로파일
- `--solo` → single session
- 그 외 → 기본 `task` batch subagent pipeline

### Step 1: SPEC Path Resolution

- SPEC-ID를 받으면 먼저 실제 `SPEC_PATH`, `SPEC_DIR`, `TARGET_MODULE`, `WORKING_DIR`를 해석합니다.
- 해석 순서:
  1. `.autopus/specs/{SPEC-ID}/spec.md`
  2. `**/.autopus/specs/{SPEC-ID}/spec.md` 재귀 탐색 (`.git`, `node_modules`, `vendor`, `.cache`, `dist` 제외)
- 0개면 사용 가능한 SPEC 목록과 함께 중단하고, 2개 이상이면 duplicate 경로를 보고하고 중단합니다.
- 이후 파일 열기, 테스트/빌드 실행, worker 프롬프트에는 해석된 값을 사용합니다.

### Step 2: SPEC 로드

- 해석된 `SPEC_PATH`와 `SPEC_DIR`를 기준으로 `spec.md`, `plan.md`, `acceptance.md`를 읽습니다.
- review gate 활성화 여부는 `spec.md` 본문에서 추론하지 말고 `autopus.yaml`에서 명시적으로 판정합니다.
  - 조회 우선순위: `WORKING_DIR/autopus.yaml` → workspace root `autopus.yaml`
  - 판정 키: `spec.review_gate.enabled`
  - `review-findings.json` 부재만으로 review gate 비활성으로 간주하지 않습니다.
- SPEC 상태가 `draft`이고 `review_gate`가 활성화돼 있으면 `LOOP_MODE`/`AUTO_MODE` 조합으로 분기합니다.

| LOOP_MODE | AUTO_MODE | 동작 |
|-----------|-----------|------|
| false | false | 구현 진행 금지. `/auto spec review {SPEC-ID}` 안내 후 중단. |
| false | true | `auto spec review {SPEC-ID} --strategy {STRATEGY} [--providers {PROVIDERS}]` 1회 트리거 → 현재 invocation의 promotion receipt 검증 → 승격 증거가 있으면 Step 3 진입, 아니면 verdict/findings 보고 후 중단. 재귀 auto-chain 금지. |
| true | * | **SPEC Quality Loop** 진입. 구현 Phase 1은 loop이 PASS 또는 circuit break로 종료된 후에만 허용. |

- review gate 내부의 단일 review iteration은 `auto spec review`의 `max_revisions` 루프에 맡기되, SPEC Quality Loop는 그 위에서 verdict 단위 (PASS/REVISE/REJECT) 의 외부 사이클을 형성합니다.

#### SPEC Quality Loop (`LOOP_MODE = true`)

리뷰 finding을 닫아 SPEC을 `approved` 로 수렴시키는 외부 루프. RALF Loop과 평행한 1급 사이클이며 수렴 타깃은 `review.md` PASS 입니다.

```
SPEC Quality Loop:
  ┌─→ TARGET   : review-findings.json 의 Status="open" 항목 추출
  │   REVISE   : spec-writer 서브에이전트에 finding-scoped 프롬프트 위임
  │   VERIFY   : `auto spec review {SPEC-ID} --strategy {STRATEGY} [--providers {PROVIDERS}]` 재실행
  └── LOOP     : verdict == PASS, max iter, 또는 circuit break까지
```

**Bootstrap**: `review.md` 가 아직 없으면 첫 revise 전에 `auto spec review {SPEC-ID} --strategy {STRATEGY} [--providers {PROVIDERS}]` 1회 트리거 (iter 0, 예산 차감 안 함).

각 review 호출 뒤 `{SPEC_DIR}/review-receipt.json`을 읽고
`schema=spec_review_promotion_receipt.v1`인지 확인합니다. draft gate를 통과하려면
현재 invocation의 `run_id`와 일치하고 `finished_at`이 invocation 시작 이후여야
합니다. 또한 `analysis_verdict=PASS`, `gate_status=passed`,
`critical_veto=false`, `current_status=approved`가 필수이며,
`degraded_reasons`가 비어 있지 않으면 `override_applied=true`도 필수입니다.
review 직전 상태가 draft였을 때는 `status_changed=true`여야 합니다. 이미
approved였던 SPEC의 clean re-review는 `status_changed=false`여도 위 current-run
조건이 모두 맞으면 허용합니다. receipt가 없거나 stale/invalid이면 fail-close
합니다. `go`는 SPEC 상태를 직접 수정하지 않습니다.

**Iteration limit**: 최대 **3** quality iterations.

**spec-writer 프롬프트 계약**:
- `open_findings_json` 전체 제공 (요약 금지)
- 가능한 모든 open finding을 한 번의 수정 배치에서 닫습니다. 한 iteration에 하나씩 처리하는 drip-feed 방식 금지
- 명시 finding만 닫고 SPEC redesign 금지
- 4개 SPEC 파일 (`spec.md`, `plan.md`, `acceptance.md`, `research.md`) 중 필요한 곳만 수정
- `Status: draft → approved` 수동 전환 금지 (review verdict만 승격 가능)
- `research.md` 에 `## Revision {N} closure` 표 추가 (`F-ID | category | one-line closure | file:line`)

**Progress detection** (이전 iter 대비):
- open finding count 감소 → 진행, 계속.
- 같은 finding ID 가 2회 연속 그대로 → circuit break (stuck).
- open count 증가 + 새 finding ID 가 다른 scope → circuit break (regression).
- verdict PASS → exit loop. 현재 review receipt에서 `analysis_verdict=PASS`,
  `gate_status=passed`, `critical_veto=false`, `current_status=approved`, 유효한
  current-run/degraded override 증거를 확인한 뒤 Step 3 진입. review 직전 상태가
  draft일 때만 `status_changed=true`를 요구합니다.

**Circuit break 출력**:

```
🐙 SPEC Quality [CIRCUIT BREAK] ──────
  SPEC: {SPEC-ID} | Iteration: {N}/3
  Stuck: {stuck | regression | iteration_exhausted}
  Open findings:
  - {F-ID} | {category}/{severity} | {desc 발췌}
  복구:
  1. {SPEC_DIR}/review.md 검토 후 SPEC 직접 수정 → /auto spec review {SPEC-ID}
  2. /auto plan --from-idea {SPEC-ID} 로 SPEC 재설계
  3. /auto go {SPEC-ID} --continue (수정 후 재개)
```

**Anti-recursion**: SPEC Quality Loop 는 단일 `go` invocation 안에서만 돕니다. PASS 후에도 자기 자신을 재귀 호출하지 않고 같은 invocation에서 Step 3 으로 순차 진행.

### Step 2.5: Change Class and Gate Applicability

- Phase 1 전에 `auto spec gates <SPEC-ID> --base <ref> [--change-class <class>] [--new-contract] --json`을 실행하고 모든 gate 결정을 각 worker 프롬프트에 전달합니다. `--change-class`를 생략하면 change set에서 클래스를 유도하므로 과소 선언이 불가능합니다.
- `{SPEC_DIR}/change.md` 또는 이 SPEC을 참조하는 `.autopus/specs/CHG-<id>/change.md`가 있으면 compact change contract입니다. `## Intended Surface`가 구현 범위를, `## Verification Plan`이 검증 범위를 한정하며 이 경로에서는 SPEC 세트를 새로 작성하지 않습니다.
- `change_risk.risk_tier: low`이면 `spec_authoring`과 `risk_first_probe`가 `not_applicable`입니다. `high`이면 둘 다 `required`이며 Phase 2 fan-out 전에 Phase 1.9 probe를 실행합니다.
- `change_risk.decision: escalate_to_full_spec`이면 실행을 중단하고 승격 이유를 보고한 뒤 `/auto plan`으로 넘깁니다.
- 기록된 risk 필드만으로 단계를 생략하지 않습니다. CLI가 단일 계약과 실제 변경 경로를 재평가한 route를 따릅니다. 계약이 손상·중복·불일치하면 full이며, `--continue`는 저장된 route와 현재 승인된 route가 일치해야 합니다.
- 소유 경로가 분리된 독립 태스크는 병렬 실행합니다. 전체 build/race/coverage/security/Phase 4 review는 통합 후 union change set에 대해 한 번만 실행하며 acceptance ID별 verdict와 evidence를 남깁니다. per-criterion 행이 없는 batch PASS는 불완전한 receipt입니다.
- review loop는 `loop_status`로 종료합니다: `converged`, `awaiting_changes`(검토 입력이 그대로이므로 같은 입력으로 재검토하지 말고 명시된 blocking finding을 해결하거나 이유와 함께 defer), `revisions_exhausted`, `provider_unavailable`.

### Step 3: 파이프라인 라우팅

- 기본 경로: `the pipeline reference above`에 정의된 subagent pipeline
- `--solo`: 메인 세션 직접 구현
- `--team`: `the pipeline reference above`의 Codex team profile 적용

### Workflow Authenticity Evidence

- 기본 subagent pipeline을 선택하면 Phase 1 전에 `task` batch surface 사용 가능 여부를 preflight합니다.
- 완료 전까지 `subagent_dispatch_count`, `subagent_roles_dispatched`, `degraded-mode`를 기록합니다.
- JSON/report consumers를 위해 `degraded_mode`도 같은 값으로 기록하고 `delegation_depth`, `delegation_depth_cap`, `safety_rail_decisions`를 초기화합니다.
- subagent pipeline 모드에서 dispatch를 만들거나 관측할 수 없으면 Phase 1 전에 workflow authenticity blocker로 중단합니다.
- workflow authenticity blocker는 working subagent surface로 재실행하거나 명시적으로 `--solo`를 선택하라고 안내해야 합니다.
- `--solo`는 `subagent_dispatch_count: 0`으로 보고하되 degraded-mode pipeline처럼 표현하지 않습니다.

### Harness-Only Tasks

모든 변경 대상이 `.md` 파일뿐이면:
- 빌드/테스트 검증을 생략할 수 있습니다.
- validator는 포맷, frontmatter, Markdown 섹션 구조 같은 문서 중심 체크만 수행합니다.

### Pre-Completion Verification

- [ ] Phase 1: Planning 완료 (또는 compact route에서 dispatch되지 않음)
- [ ] Phase 1.5: Test Scaffold 완료, `--skip-scaffold`, 또는 compact route에서 미dispatch
- [ ] Gate 1: Approval 완료 또는 `--auto`
- [ ] Phase 1.8: Doc Fetch 완료 또는 skip
- [ ] Phase 1.9: Risk-First Probe Gate 완료 (executed 또는 이유가 있는 `not-run`)이며 `auto spec gates`가 `{SPEC_DIR}/gate-applicability.json`을 작성
- [ ] Phase 2: Implementation 완료
- [ ] Gate 2: Validation PASS
- [ ] @AX Annotation: 명시적 opt-in일 때만 완료, 그 외에는 `@AX: not requested`
- [ ] Phase 3: Testing 완료 또는 harness-only skip
- [ ] Gate 3: Coverage 측정값 보고 완료, 선언된 threshold가 있으면 충족 (선언이 없으면 수치 게이트 없음)
- [ ] Phase 4: Review APPROVE
- [ ] Sync Readiness Gate PASS (`completion_verdict_preview`, `sync_ready`, `sync_blockers`, `spec_status_after_go`, `sync_evidence_refs` 기록)
- [ ] subagent_dispatch_count 기록, role 목록, degraded-mode 상태 확인
- [ ] `auto telemetry leadtime [--run {SPEC_ID}] [--baseline <SPEC-ID|dir>]`로 first-slice/completion lead time과 `critical_path`를 보고하고 `escaped_defects`·`unresolved_safety_gates` 증가 없음 확인

하나라도 비어 있으면 sync 단계 안내로 넘어가지 않습니다.

### Sync Readiness Gate

`go`가 성공처럼 종료되기 전에 sync 단계가 뒤늦게 구현 누락을 발견하지 않도록 다음 항목을 확정합니다.

- `completion_verdict_preview`: sync의 Completion Verdict와 같은 형식으로 Outcome Lock, mandatory requirements, Must acceptance, Completion Debt, Evolution Ideas를 요약합니다.
- `sync_ready`: Outcome Lock 만족, mandatory requirements 전부 충족, Must acceptance 전부 충족, Completion Debt `none`일 때만 `yes`.
- `sync_blockers`: `none` 또는 `implemented` 상태 전환을 막는 구체 blocker.
- `spec_status_after_go`: 성공 시 `implemented`. `done`/`completed`를 사용하지 않습니다. `completed`는 `/auto sync` 전용 상태입니다.
- `sync_evidence_refs`: 변경 파일, 검증 명령, Phase 4 verdict, @AX annotation 결과 또는 `@AX: not requested`.
- `decision_receipt`: reused existing code/helper/pattern, skipped dependency or abstraction, accepted expansion with evidence, and minimum sufficient verification summary.

`sync_ready != yes`이면 workflow lifecycle bar와 `/auto sync` handoff를 출력하지 말고 blocker를 먼저 해결합니다.

### Completion Handoff Gates

성공 응답으로 종료하기 전에 아래 handoff 필드를 모두 확정합니다.

- `current_gate`: 현재 완료 상태 또는 아직 남아 있는 gate 이름
- `phase_4_review_verdict`: `APPROVE` 또는 completion을 막는 blocker 요약
- `completion_verdict_preview`: sync가 사용할 완료 판정 미리보기
- `sync_ready`: `yes` 또는 blocker
- `sync_blockers`: `none` 또는 blocker 목록
- `spec_status_after_go`: `implemented`
- `sync_evidence_refs`: 변경/검증/리뷰/@AX 증거
- `decision_receipt`: 중요한 구현 선택과 minimum sufficient verification 요약
- `next_required_step`: supervisor가 다음에 반드시 진행해야 하는 단계
- `next_command`: surface-native 다음 명령 (`/auto sync {SPEC-ID}` 또는 동등 alias)
- `auto_progression_state`: `--loop` 여부와 무관하게 handoff를 생략하지 않는다는 상태 설명

하나라도 비어 있으면 완료처럼 닫지 않습니다. 구현/검증 요약만으로 종료하지 말고, 미충족 gate와 blocker를 먼저 명시합니다.

### Final Output Contract

`go` 성공 경로의 최종 응답은 아래 순서를 유지합니다.

1. workflow lifecycle bar
2. `current_gate`
3. `phase_4_review_verdict`
4. `next_required_step`
5. `next_command`
6. 필요한 경우 `auto_progression_state`

`--loop`여도 handoff를 생략하지 않습니다. handoff gate를 채우지 못하면 success-style completion summary로 종료하지 않습니다.

### Autonomous Review Loop Contract

- `--auto --loop`에서 review가 actionable finding을 반환하면, 같은 invocation 안에서 즉시 `fix -> validate -> test -> review verify` 루프로 이어갑니다.
- review retry budget이 남아 있는 동안에는 사용자에게 수동 수정, 재실행, 확인을 요청하지 않습니다.
- 수동 개입은 요구사항 충돌, 외부 credential/승인 필요, retry budget 소진, circuit break 같은 실제 blocker일 때만 허용합니다.
- `Completion Handoff Gates`와 `Final Output Contract`는 terminal state에서만 사용합니다. review finding이 아직 fixable한데 `/auto go --continue` 또는 수동 review를 next step으로 제시하면 안 됩니다.
- `go` 성공의 terminal handoff는 `/auto sync {SPEC-ID}` 까지입니다. `go`가 `sync`를 자동 호출하지는 않지만, review 수렴 전에는 sync handoff도 출력하지 않습니다.
- 재리뷰는 frozen open-finding checklist에 대한 verify mode입니다. `{SPEC_DIR}/review-receipt.json`의 `discovery_repeat_detected`, `repeat_discovery_count`, `same_input_rereview`를 읽고, 이전 checklist에 없지만 정규화된 title 또는 같은 file+line으로 이전 finding과 매칭되면 신규가 아니라 repeat으로 분류합니다. repeat이 감지되면 같은 입력으로 discovery를 다시 돌리지 않고 open finding을 해결하거나 이유를 명시해 defer합니다.
- 이미 검증된 입력을 다시 읽거나 통과한 검사를 다시 실행하면 `auto telemetry record --spec-id {SPEC_ID} --action action --kind reread|rerun --target <path|cmd> --reason <text>`를 기록합니다.

## 품질 기준

- 테스트 커버리지: 측정값을 증거로 보고합니다. 수치 게이트는 프로젝트가 선언했을 때만 적용합니다. `workflow.coverage_threshold` 기본값은 `0`(수치 게이트 없음)이며, 프로젝트/라우트가 명시한 threshold는 선언된 그대로 강제하고 route가 global보다 우선합니다. 선언되지 않은 수치를 만들어 내지 않습니다.
- LSP 에러: 0
- 린트 에러: 0

## Subagent Delegation

기본값은 메인 세션 인라인 실행입니다. 위임은 리스크 기준이며 크기 기준이 아닙니다. 소유 경로가 분리되고 미완료 작업에 의존하지 않으며 단독으로 끝낼 수 있는 독립 슬라이스이거나, 격리된 컨텍스트 또는 현재 세션이 수행하지 않는 전문 역할이 필요할 때만 `task batch`로 위임합니다. 파일 수, 줄 수, 패키지 수는 위임 근거가 아닙니다. 저위험 compact contract 작업(`test_only`, `docs_only`, `small_ui`, `bugfix_existing_contract`)은 planner나 전용 scaffold/validator 에이전트 없이 인라인으로 진행하되 실제 검증은 동일하게 수행합니다.

### Executor Agent

```json
{
  "i": "Dispatching bounded OMP work",
  "context": "Shared goal, constraints, owned-path boundaries, and cross-task contracts.",
  "tasks": [
    {
      "name": "executor",
      "task": "Implement {task description}",
      "outputSchema": {
        "type": "object",
        "additionalProperties": false,
        "required": ["owned_paths", "changed_files", "verification", "blockers", "next_required_step"],
        "properties": {
          "owned_paths": {"type": "array", "items": {"type": "string"}},
          "changed_files": {"type": "array", "items": {"type": "string"}},
          "verification": {"type": "array", "items": {"type": "string"}},
          "blockers": {"type": "array", "items": {"type": "string"}},
          "next_required_step": {"type": "string"}
        }
      },
      "schemaMode": "strict"
    }
  ]
}
```

### Tester Agent

```json
{
  "i": "Dispatching bounded OMP work",
  "context": "Shared goal, constraints, owned-path boundaries, and cross-task contracts.",
  "tasks": [
    {
      "name": "tester",
      "task": "Write tests for {scope}",
      "outputSchema": {
        "type": "object",
        "additionalProperties": false,
        "required": ["owned_paths", "changed_files", "verification", "blockers", "next_required_step"],
        "properties": {
          "owned_paths": {"type": "array", "items": {"type": "string"}},
          "changed_files": {"type": "array", "items": {"type": "string"}},
          "verification": {"type": "array", "items": {"type": "string"}},
          "blockers": {"type": "array", "items": {"type": "string"}},
          "next_required_step": {"type": "string"}
        }
      },
      "schemaMode": "strict"
    }
  ]
}
```

### Reviewer Agent

```json
{
  "i": "Dispatching bounded OMP work",
  "context": "Shared goal, constraints, owned-path boundaries, and cross-task contracts.",
  "tasks": [
    {
      "name": "reviewer",
      "agent": "reviewer",
      "task": "Review implementation for {SPEC-ID}",
      "outputSchema": {
        "type": "object",
        "additionalProperties": false,
        "required": ["owned_paths", "changed_files", "verification", "blockers", "next_required_step"],
        "properties": {
          "owned_paths": {"type": "array", "items": {"type": "string"}},
          "changed_files": {"type": "array", "items": {"type": "string"}},
          "verification": {"type": "array", "items": {"type": "string"}},
          "blockers": {"type": "array", "items": {"type": "string"}},
          "next_required_step": {"type": "string"}
        }
      },
      "schemaMode": "strict"
    }
  ]
}
```

### Delegation Rules

- Define clear scope with expected output for each agent
- Include resolved SPEC context files in the agent prompt
- Review agent output before integrating
- Use parallel delegation for independent subtasks
- Maximum 3 sequential agent chains
- Run build, lint, and test commands from `WORKING_DIR`

## Multi-Provider 모드

`--multi` 플래그로 멀티 프로바이더 오케스트레이션을 활성화합니다:

```bash
auto orchestra review {review paths} --risk-tier {risk_tier} --strategy {strategy} --providers {providers} --no-detach --format json
```

pane-capable 터미널에서는 로그인된 interactive pane이 기본이며, plain/CI·mux 미가용·명시적 `--subprocess`에서만 subprocess를 사용해 여러 AI 프로바이더의 합의 기반 리뷰를 수행합니다.

The review result is an `orchestration_run_receipt.v1`. Preserve
`requested_providers`, `configured_providers`, `resolved_providers`,
`attempted_providers`, `usable_providers`, `failed_providers`,
`degraded_reasons`, `critical_veto`, `analysis_verdict`, and `gate_status`.
Provider discovery evidence never overrides deterministic validation, and a
degraded PASS requires an explicit audited override.
The synchronous review gate accepts only `schema=orchestration_cli_result.v1` with
an embedded `receipt.schema=orchestration_run_receipt.v1`; a detached job ID or
untyped prose cannot satisfy the gate.

## Codex Notes

- Codex의 기본 구현 모드는 `task` batch 기반 subagent pipeline입니다.
- Codex에서 `--auto`는 기본 subagent pipeline 진행에 대한 명시적 승인입니다.
- `--auto`가 없고 현재 Codex 런타임 정책이 암묵적 `task` batch 호출을 제한하면, 조용히 단일 세션으로 폴백하지 말고 하네스 기본값과 제약을 사용자에게 명시적으로 설명한 뒤 서브에이전트 opt-in 또는 `--solo` 선택을 받습니다.
- `--team`은 Codex Multi-Agent V2 팀 프로파일입니다. 모든 worker는 같은 shared cwd/filesystem을 사용하며 병렬 writer는 disjoint write ownership을 가져야 합니다. 메인 세션은 `task` batch, `hub send`, `hub send`, target-less `hub with {"i":"Waiting for blocked work","op":"wait","ids":["<job id>"]}`, `hub cancel`, `hub list`만 사용합니다.
- Use only a runtime-exposed OMP goal surface. If none is available, do not claim or create persisted goal state; `/auto goal` remains the explicit route.
- `--multi`는 구현 이후 reviewer / security-auditor / orchestra 리뷰를 추가로 붙이는 강화 모드입니다.
- 전체 파이프라인 단계, 재시도 한도, 게이트 규칙은 `/auto go ...` 라우터 본문을 우선합니다.

## Branding Formats

### Pipeline Progress (show at Phase transitions)

```
🐙 Pipeline ─────────────────────────
  ✓ Phase 1: Planning
  → Phase 2: Implementation [N/M tasks]
  ○ Phase 3: Testing
  ○ Phase 4: Review
```

Status symbols: `✓` completed, `→` active, `○` pending. Replace `[N/M tasks]` with actual counts.

### Workflow Lifecycle (show after go completes)

```
🐙 Workflow: {SPEC-ID}
  ✓ plan  →  ● go  →  ○ sync
```

current_gate: go completed, sync pending
phase_4_review_verdict: APPROVE
subagent_dispatch_count: {N}
subagent_roles_dispatched: {실제로 dispatch된 role 목록, 인라인 실행이면 none (inline)}
degraded-mode: none | solo | blocker
degraded_mode: none | solo | blocker
delegation_depth: {N}
completion_verdict_preview: Outcome Lock satisfied, mandatory N/N, Must acceptance N/N, Completion Debt none
sync_ready: yes
sync_blockers: none
spec_status_after_go: implemented
sync_evidence_refs: {changed_files, verification_commands, review_verdict, ax_result}
decision_receipt: reused existing code/helper/pattern; skipped unjustified dependency or abstraction; minimum sufficient verification selected
next_required_step: sync 단계로 이동
next_command: /auto sync {SPEC-ID}
auto_progression_state: --loop enabled; handoff still required before autonomous continuation

다음 단계: `/auto sync {SPEC-ID}`

### Agent Result Format (use for executor/tester subagent results)

executor:
```
🐙 executor ─────────────────────────
  파일: {N}개 수정 | 테스트: {N}개 추가 | 커버리지: {N}%
  다음: 검증 단계로 진행
```

tester:
```
🐙 tester ───────────────────────────
  테스트: {N}개 추가 | 커버리지: {before}% → {after}% | 통과: {N}/{N}
  다음: 리뷰 단계로 진행
```

### Error Recovery (terminal only; use after retry budget exhaustion or circuit break)

Validation failure:
```
✗ Validation 실패: {N}개 이슈 발견
  복구 옵션:
  1. /auto go {SPEC-ID} --continue  (retry budget 소진 또는 circuit break 후 재개)
  2. /auto fix "{specific issue}"   (개별 이슈를 별도 복구)
```

Subagent failure:
```
✗ {agent-name} 실패: {error description}
  복구 옵션:
  1. /auto go {SPEC-ID} --continue  (worker crash/timeout 이후 파이프라인 재개)
  2. {manual fallback instruction}  (자동 재시도 범위를 벗어난 경우만 수동 처리)
```