---
name: auto-sync
description: 문서 동기화 — 구현 이후 SPEC, CHANGELOG, 문서를 반영합니다
compatibility: omp
---

# auto-sync — 문서 동기화 스킬

## OMP Invocation

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


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

## 설명

구현 완료 후 코드와 문서를 동기화합니다.

## 사용법

```
/auto-sync SPEC-ID
/auto-sync
```

## Codex 기본 실행 모델

- Codex에서는 `sync`도 기본적으로 `task` batch 기반 subagent-first를 따릅니다.
- 메인 세션은 동기화 범위 결정, 최종 상태 갱신, 커밋 판단을 담당합니다.
- 변경점 검토, 문서 영향 분석, 검증 로그 정리는 필요 시 서브에이전트로 위임합니다.
- 사용자가 `--auto` 또는 `--solo`를 명시하지 않았고 현재 Codex 런타임 정책이 암묵적 `task` batch 호출을 제한하면, 진행을 멈추고 하네스 기본값과 제약을 명시한 뒤 서브에이전트 opt-in 또는 `--solo` 확인을 먼저 받아야 합니다.
- 변경 범위가 작으면 메인 세션에서 직접 마무리할 수 있습니다.

## 동기화 항목

1. SPEC 상태 → completed
2. API 문서 갱신
3. 아키텍처 다이어그램 업데이트
4. Lore 의사결정 기록
5. CHANGELOG 갱신
6. Lore 형식 자동 커밋

## 구조 문서 동기화

구조 변경이 감지되면 다음 문서를 함께 갱신합니다.
- `ARCHITECTURE.md`
- `.autopus/project/structure.md`
- `.autopus/project/tech.md`
- `.autopus/project/product.md`
- `.autopus/project/workspace.md`

특히 repo 경계, 빌드/릴리스 스크립트, desktop/browser/API surface가 바뀌면 `workspace.md`의 QA/Journey Pack 대상 리포와 `auto qa init --project-dir <repo>` 명령도 함께 갱신합니다. meta workspace의 root `.autopus/qa/**`는 runtime/generated evidence로 취급하고 제품 리포 Journey Pack 위치와 섞지 않습니다.

## @AX Lifecycle Management

동기화 시 코드베이스의 @AX 태그 수명주기를 관리합니다.

### TODO Cycle Tracking

1. `@AX:TODO` 태그를 찾습니다.
2. `@AX:CYCLE:N` 카운터를 증가시키거나 없으면 `@AX:CYCLE:1`을 추가합니다.
3. CYCLE이 3 이상이면 `@AX:WARN` 으로 승격하고 이유를 기록합니다.

### ANCHOR Fan-In Verification

1. `@AX:ANCHOR` 태그를 찾습니다.
2. 함수 참조 수를 grep 기반으로 점검합니다.
3. caller count가 3 미만이면 `@AX:NOTE` 로 내리고 이유를 갱신합니다.

### NOTE Cleanup

1. 특정 함수/심볼을 참조하는 `@AX:NOTE` 를 찾습니다.
2. 해당 함수/심볼이 아직 존재하는지 확인합니다.
3. orphan NOTE는 제거합니다.

## 품질 게이트

- 에러: 0 / 경고: 최대 10

## Lore 커밋

동기화 완료 후 변경 파일을 Lore 형식으로 자동 커밋합니다.
- SPEC-ID가 있으면: `docs(<scope>): sync SPEC-{ID} 문서 및 상태 갱신`
- SPEC-ID가 없으면: `docs(sync): 프로젝트 문서 동기화`
- 구현 코드 포함 시 SPEC 주요 타입(feat, fix 등) 사용
- 변경 사항 없으면 커밋 생략

### 2-Phase Commit

1. Module repo 커밋: `{TARGET_MODULE}` 내부 SPEC 및 모듈 변경
2. Meta repo 커밋: 루트 문서(`ARCHITECTURE.md`, `.autopus/project/`, `CHANGELOG.md`)

판단 기준:
- `{TARGET_MODULE}/` 내부 파일 → module commit
- 루트 문서 → meta commit
- 구현 코드가 포함되면 SPEC의 주요 타입(feat/fix/refactor 등) 사용
- 문서만 바뀌면 `docs` 사용


## Completion Gates

sync 완료를 선언하거나 workflow lifecycle bar를 표시하기 전에 아래 gate를 모두 기록해야 합니다.

1. `Context Load` 결과
   - 읽은 프로젝트 컨텍스트 파일 목록 또는 missing/no-op 사유를 남깁니다.
2. `SPEC Path Resolution` 결과
   - `SPEC_PATH`, `TARGET_MODULE`, `WORKING_DIR`를 명시합니다.
3. `Completion Verdict` 결과
   - `Outcome Lock` 만족 여부, mandatory requirements 충족 수, Must acceptance 충족 수를 기록합니다.
   - `Completion Debt`가 하나라도 있으면 SPEC 상태를 `completed`로 바꾸지 말고 blocked reason을 남깁니다.
   - `Evolution Ideas`는 사용자에게 optional improvement로만 표시하고, 자동 follow-up SPEC이나 sibling SPEC으로 추천하지 않습니다.
4. `@AX Lifecycle Management` 결과
   - TODO/ANCHOR/NOTE 처리 결과를 남기고, 대상 태그가 없으면 `@AX: no tags found`, annotation을 요청하지 않은 실행이면 `@AX: not requested`로 기록합니다.
5. Lore 커밋 결과
   - 변경 사항이 있으면 Lore 커밋을 시도하고 commit hash를 남깁니다.
   - 커밋이 실패했거나 보류되면 blocked reason을 남기고 sync를 completed로 선언하지 않습니다.
6. 2-Phase Commit 판단 결과
   - module commit / meta commit / skip 중 무엇을 했는지와 이유를 남깁니다.
7. 완료 출력 순서
   - 완료 배너, workflow lifecycle bar, 다음 단계 추천은 위 gate가 모두 기록된 뒤에만 표시합니다.

## Completion Verdict Format

```markdown
## Completion Verdict
- Outcome Lock: satisfied / blocked
- Mandatory requirements: N/N
- Must acceptance: N/N
- Completion Debt: none / {items}
- Evolution Ideas: surfaced as optional, not scheduled
```

## Branding Formats

### Workflow Lifecycle (show after sync completes)

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

### Milestone Celebration (show when full pipeline completes)

```
╭────────────────────────────────────╮
│ 🐙 파이프라인 완료!                 │
│ {SPEC-ID}: {title}                 │
│ 태스크: N/N | 커버리지: N%          │
│ 리뷰: {verdict}                    │
╰────────────────────────────────────╯
```

Field mappings: `{title}` from spec.md, `N/N` = completed/total tasks, `{verdict}` = `APPROVE` or `N/A`.

### Next Step Auto-Detection (show after sync completes)

```
다음 단계: {recommendation}
```

Detection order:
1. SPEC status `completed` → `🐙 {SPEC-ID} 완료. 다음 기능: /auto plan "기능 설명"`
2. Existing pending SPECs created by an approved Sibling SPEC Decision exist → recommend next SPEC to implement
3. Do not recommend or create pending SPECs from Evolution Ideas
4. Always append: `배포 후 검증: /auto canary`