배포 체크리스트

Apothem 에코시스템을 새 머신에 배포하거나, 다른 사람과 공유하거나, 프로덕션 준비 완료로 취급하기 전의 사전 검증 단계입니다.

1. YAML 유효성

• 모든 규칙 파일이 YAML 오류 없이 파싱됨 — frontmatter 블록이 ---로 열리고 ---로 닫히며 블록 외부에 고립된 콘텐츠가 없음
• 모든 위임 작업자 파일이 YAML 오류 없이 파싱됨
• 모든 명령 파일이 YAML 오류 없이 파싱됨
• 모든 스킬 SKILL.md 파일이 YAML 오류 없이 파싱됨

검증: python scripts/dev/validate_ecosystem.py는 각 아티팩트의 frontmatter를 파싱하고 YAML 오류 + 누락된 필수 필드를 표시합니다. 즉석으로 고립된 목록 항목을 감지하려면: rg -n "^- " src/apothem/rules/*.md.

2. frontmatter 완전성

각 아티팩트 유형에 대해 필수 필드가 존재하는지 확인하세요:

규칙 (src/apothem/rules/*.md)

• name — 파일 이름과 일치하는 kebab-case 식별자
• version — semver MAJOR.MINOR.PATCH (예: "X.Y.Z")
• updated — ISO 8601 날짜 (예: "2026-04-20")
• description — 한 문장 요약
• scope — "always-on" 또는 "path-filtered"
• portability — "universal", "universal-with-windows-caveats", "unix-only", 또는 "windows-only"
• pathFilter — 경로 필터링 규칙의 경우 존재하며 유효한 glob 문자열; 항상 켜진 규칙의 경우 부재

명령 (src/apothem/commands/*.md)

• name — kebab-case 명령 이름
• version, updated, description, argument-hint 존재
• disable-model-invocation 존재하며 의도적임 (지침 전용 명령의 경우 true)
• effort, portability 존재하는 경우 검토됨 (schema상 선택 사항)

위임 작업자

경로:

src/apothem/agents/*.md

• name, version, updated, description 존재
• tools — 허용된 도구의 쉼표로 구분된 목록
• disallowedTools — 허용되지 않은 도구를 명시적으로 나열
• maxTurns — 설정됨 (> 10인 경우 근거 주석 포함)
• permissionMode — "bypassPermissions"이면 안 됨 — "default" 사용
• memory: false, 단 영속 메모리가 의도적인 경우는 예외

스킬 (src/apothem/skills/*/SKILL.md)

• name, version, updated, description 존재
• user-invocable — 선언됨 (true/false)

3. 보안

• 어떤 위임 작업자도 permissionMode: "bypassPermissions"를 사용하지 않음 — 이것은 Write/Bash 작업에 대한 대화형 확인을 우회함
• 작업자의 tools 목록은 최소한임 — 작업자가 정말로 필요로 하는 도구만 포함
• Bash 액세스를 가진 작업자는 정당화되었으며 maxTurns 제한이 있음
• 어떤 아티팩트에도 하드코딩된 경로, 토큰 또는 시크릿이 없음
• settings.json의 훅은 합리적인 타임아웃(≤ 60초)을 가지며 사용자 입력으로부터 임의의 코드를 실행하지 않음

4. 상호 참조 무결성

• src/apothem/rules/ 테이블에 나열된 모든 규칙이 명시된 경로에 디스크에 존재함
• src/apothem/commands/ 테이블에 나열된 모든 명령이 디스크에 존재함
• src/apothem/agents/ 레지스트리 테이블에 나열된 모든 위임 작업자가 디스크에 존재함
• src/apothem/skills/ 테이블에 나열된 모든 스킬이 디스크에 존재함
• src/apothem/hooks/ 테이블의 모든 훅이 settings.json에 해당 항목을 가짐
• CLAUDE.md Implements 열에서 참조하는 모든 src/apothem/rules/*.md 파일이 존재함

5. 지령 커버리지

• CLAUDE.md에서 참조된 모든 CM-N이 시행 위치를 가짐 (규칙 파일 또는 명시적 인라인 정의)
• 어떤 규칙 파일도 다른 규칙 파일과 모순되지 않음 (특히 심각도 스케일링 주변에서)
• CM-21 3측면 구분이 존중됨 — 어떤 규칙도 다른 규칙의 CM-21 측면 소유권을 주장하지 않음

6. 기능 스모크 테스트

먼저 Python 검증 표면을 실행하세요 — 빠르고 오프라인이며 구조적 회귀를 잡아냅니다:

• pytest tests — 훅 런타임의 단위 테스트, 모두 그린
• python scripts/dev/validate_hooks.py — 훅 구조 + Python 전용 위생 검사 통과
• python scripts/dev/validate_ecosystem.py — 전체 트리 + frontmatter + 위임 훅 검사 통과
• python scripts/dev/chaos_pass.py — 구성된 각 훅 명령이 저하된 입력 하에서 유효한 JSON 봉투를 반환함

그다음 라이브 시나리오:

• /plan-spec --interactive (또는 /plan-spec <sample-file>) — 명령 수준 오류 없이 수집/명확화를 완료함
• /plan-generate --dry-run — 파일을 쓰지 않고 구조 미리보기를 생성함
• 완성된 플랜 스위트에 대한 /plan-status — 정확한 단계 수를 반환함
• 위임 작업자 디스패치: 작은 범위로 호출된 codebase-explorer 작업자가 maxTurns 내에 완료하고 구조화된 출력을 반환함

7. 문서 최신성

• CHANGELOG.md(에코시스템 루트)가 마지막 릴리스 이후의 모든 아티팩트 변경을 반영함; 다음 릴리스의 섹션이 태그가 안착하기 전에 채워졌거나, 모든 변경이 이미 릴리스된 섹션으로 분류됨
• site/content/docs/developer-guide.mdx가 현재 아티팩트 구조를 정확하게 기술함
• site/content/docs/reference/artifact-schema.mdx가 아티팩트에 실제로 존재하는 frontmatter 필드와 일치함
• site/content/docs/reference/settings-reference.mdx가 settings.json의 실제 훅 구성과 일치함
• README.md가 디스크상의 트리와 일관됨

8. 이식성 (다른 사람과 공유하는 경우)

• 훅 명령의 모든 경로가 환경에 구애받지 않거나 ~ 확장을 사용함
• 훅 명령이 exec 형식을 사용하고 셸별 명령 문자열을 피함
• 어떤 아티팩트에도 하드코딩된 C:\Users\username 또는 /home/username 경로가 없음
• settings.json이 단일 훅 이벤트 커버리지 테이블과 표준 디스패치 모듈 경로를 사용함

9. 버전 정렬

• CLAUDE.md version이 트리 내 어떤 아티팩트보다 가장 높음 (또는 관례상 가장 최근에 버전이 올라간 아티팩트의 버전과 같음)
• 각 아티팩트의 version이 명시된 semver(MAJOR.MINOR.PATCH)와 일치함
• CHANGELOG.md가 태깅 전에 정확히 대상 버전의 릴리스 항목을 포함함
• 각 아티팩트의 updated 필드가 마지막 동작 변경 편집 날짜이거나 그 이후임
• 어떤 아티팩트도 마지막으로 손댄 버전보다 낮은 version을 갖지 않음 (회귀 없음)
• src/apothem/skills/plan-suite/SKILL.md와 src/apothem/skills/plan-suite/master-template.md가 동일한 템플릿 버전 라인에 고정됨

승인

배포 승인자: ___________________ 날짜: ___________________ 배포된 에코시스템 버전: ___________________