aiwf 0.3.23 → 0.4.0

package/docs/modernization/CLI-PRODUCTIVITY-REVIEWED-2026-10-03.ko.md

@@ -0,0 +1,177 @@
+# CLI 생산성 개선 분석과 권고안
+
+작성: 2026-10-03. 분석 기준: 로컬 checkout `fcf5ebc24bcd5e49148290a65ac6e1a5c4b22ba6`.
+
+상태: **분석과 구현 제안, 휴먼 리뷰 대기**. 아래 `verify`, 검사 runner, 실행 receipt, packet v2, 문서 검토 보고서와 CI 작업은 아직 구현되지 않았다. 현재 CLI 명령은 `init`, `pin`, `check`, `packet`이다. npm 배포판의 기능·상태를 새로 확인한 기록은 아니다.
+
+## 권고하는 방향
+
+AIWF CLI는 **유스케이스 명세를 구현·실제 검증 결과·휴먼 리뷰로 연결하는 도구**에 집중한다. 최신 문서와 실행 기록은 이 연결을 사람이 확인하도록 돕는다. 문서 관리가 우선이라는 사용자 지침은 모든 작업의 품질 조건으로 적용한다. 원문·한글본 갱신을 먼저 확인하되, 저장소 문서 관리 기능의 확장이 소비 프로젝트의 실제 UC 검증을 대신하지 않도록 한다.
+
+방향 적합성을 재검토한 제품 확장 순서는 다음과 같다.
+
+1. 현재 스킬·CLI로 소비 프로젝트의 실제 UC 하나를 명세→계획→구현→검증→packet까지 수행한다. UC/BR/TC와 실제 검사·미검증 사항의 연결을 사람이 확인하고 수작업·누락을 기록한다.
+2. 파일럿에서 반복한 구조 검사·필수 검사기 확인·명세 drift 확인을 읽기 전용 `verify`로 통합한다.
+3. 결과 전사·수집이 병목이면 UC/BR/TC에 연결된 선택 runner, 버전이 있는 실행 기록, 이를 검증하는 packet v2를 함께 구현한다. 이 연결과 최신성 계약은 runner의 초기 범위에 포함한다.
+4. 같은 UC의 명세 변경·재검증 파일럿으로 효과를 비교한 뒤 Sprintable·병렬 실행의 필요성을 판단한다.
+
+원문·한글본·README·검토 기록의 동시 갱신은 위 모든 단계에 적용한다. AIWF 저장소의 문서 검토 보고서와 기존 검사 명령의 CI 연결은 이를 지원하는 유지보수 개선이다. 이 개선을 새 제품 기능의 선행 조건으로 만들어 실제 UC 파일럿을 미루지 않는다.
+
+새 스킬 수, 명령 수, 에이전트 수는 성공 지표로 삼지 않는다. 문서 갱신 누락, 오래된 결과의 재사용, 검토 준비에 드는 수작업이 줄어드는지가 기준이다.
+
+## 근거와 확신 수준
+
+| 순위 | 분석 결과 | 구분·확신 | 근거 |
+| --- | --- | --- | --- |
+| 1 | 문서 정합성 검사는 있지만 휴먼 리뷰 대상은 여전히 많다. 변경된 원문과 한글본을 함께 제시하면 검토 준비를 줄일 가능성이 크다. | 현황은 사실·높음, 시간 절감은 추론·중간 | 한글 문서 70개, 검토 대기 70개, 휴먼 리뷰 기록 0개. checker는 파일·해시·참조·검토 기록을 검사한다. |
+| 2 | 명세 구조 검사와 pin 확인을 통합하는 것은 기존 기능을 재사용하는 작은 확장이다. 종료 코드만 합산하면 검사 누락을 놓친다. | 사실·높음 | CLI `check`는 lint를 실행하지 않는다. Python lint는 JSON을 제공하지만 sibling validator 누락을 INFO로 기록한다. |
+| 3 | 검사 자동 실행의 전제는 실행 당시 명세·코드·설정과 결과의 연결이다. 현재 packet만으로 최신 실행을 확인할 수 없다. | 계약은 사실·높음, 재사용 위험은 추론·높음 | packet 생성 시 명세를 확인하고 로그를 읽는다. evidence 입력에는 실행 시각·run ID·실행 당시 digest·exit code 필드가 없다. |
+| 4 | 먼저 순차 실행과 로컬 검토를 검증하면 병렬·원격 상태 관리 부담을 늦출 수 있다. | 추론·중간 | 선택 위임은 이미 분리되어 있고 Sprintable은 제안 단계다. 반복 업무의 시간·빈도 측정은 없다. |
+
+직접 확인한 파일:
+
+- [CLI](../../src/cli/spec-cli.js): 명령 목록, `check`와 `packet`의 실행·종료 계약.
+- [명세·packet 라이브러리](../../src/lib/spec-workflow.js): 명세 snapshot, Git 메타데이터, evidence 허용 필드, 로그 수집, `reported_untrusted`.
+- [구조 검사기](../../plugins/aiwf-core/skills/spec-review/scripts/spec_lint.py): `load_sibling`, `check_structure`, `check_bpmn`, `--format json`, `--trace`, INFO와 종료 코드.
+- [workflow](../../plugins/aiwf-spec/skills/workflow/SKILL.md)와 [한글 검토본](../ko-skills/aiwf-spec/skills/workflow/SKILL.ko.md): lint, pin, 테스트, evidence 작성, packet 확인의 현재 절차.
+- [한글 문서 검사기](../../scripts/check-korean-docs.mjs)와 [관리 목록](../ko-skills/manifest.json): 파일별 원문·번역 버전과 실제 검토 기록.
+- [스킬 설치 회귀 검증](../../tests/spec-workflow/install-skills.test.mjs): 기본 core 전체 설치에서 sibling 검사기가 유지된다.
+- [이전 실제 CLI 파일럿](FULL-TEST-2026-10-03.md): Codex 구현과 12개 서비스 테스트, Claude 의미 검토를 기록했다. 운영 앱 전체나 생산성 개선율을 입증한 자료는 아니다.
+
+## 이번에 재확인한 동작
+
+2026-10-03 로컬 Node `v22.23.1`, Python `3.14.8`에서 확인했다. 최소 선언 버전 Node 20/Python 3.9 실행 검증과는 별개다.
+
+| 확인 | 결과 | 설계에 주는 의미 |
+| --- | --- | --- |
+| `aiwf-spec --help`에 해당하는 저장소 CLI 실행 | 현재 명령 4개 확인 | 제안한 새 명령을 설치 안내에 구현된 기능처럼 적지 않는다. |
+| 예제를 전체 core의 lint로 검사, `--strict --no-baseline --format json` | exit 0, errors/warnings/infos 모두 0 | 기존 검사기를 호출하고 JSON을 읽는 방식을 재사용할 수 있다. |
+| 같은 검사 파일만 임시 sibling 없는 폴더에 복사해 같은 예제 검사 | exit 0, INFO `VALIDATOR_MISSING` | exit 0만으로 구조 검사가 전부 실행됐다고 보고하면 안 된다. 임시 폴더는 확인 후 제거했다. |
+| 전체 core의 `--trace --format json` 실행 | exit 0, 요구사항 행 1개 | `--trace`는 문서 연결표다. 별도 lint 성공 또는 테스트 실행 증거가 아니다. |
+| `npm run docs:check:local` | 통과, 문서 70개 모두 검토 대기 | 파일 정합성과 이 컴퓨터의 로컬 스킬 snapshot 일치는 확인했다. 의미 검토와 승인은 남아 있다. |
+
+`BPMN_PARSER_MISSING`도 코드상 INFO이며 필요한 BPMN 검사가 생략된다. 이번 sibling 격리 예제에는 BPMN 파일이 없으므로 그 분기는 실험으로 실행하지 않았다. 전체 core 설치가 항상 불완전하다는 뜻도 아니다. 작은 휴대용 스킬 하나만 설치한 상황과 전체 bundle 설치를 구분해야 한다.
+
+## 생산성이 생기는 지점
+
+| 반복 업무 | 현재의 수작업·오류 가능성 | 권고하는 자동화 | 제약 |
+| --- | --- | --- | --- |
+| 원문과 한글본 검토 준비 | 관리 목록과 diff를 따로 찾고 변경·미검토 범위를 판단 | 같은 변경의 원문·번역 diff와 검토 상태를 짝지은 보고서 | 자동 번역·해시 갱신으로 의미 검토를 대체하지 않는다. |
+| 검사 경로와 선행 조건 확인 | 호스트 설치 구조마다 Python 경로·sibling·pin을 확인 | `verify`에서 번들 검사기와 실제 로드 상태, 명세 drift를 함께 진단 | 누락된 필수 검사를 통과로 표시하지 않는다. |
+| 결과 수집 | 검사마다 로그 저장, 상태 전사, evidence JSON 작성 | 선택한 named-check의 결과·로그·실행 기록 자동 생성 | 실행 범위와 입력 버전을 기록해야 한다. |
+| 다시 검토할 때 최신성 확인 | Git HEAD, 명세 pin, 로그 생성 시점을 수동 대조 | receipt와 현재 입력을 비교해 `fresh/stale/unknown` 표시 | Git HEAD 하나나 `dirty` boolean만으로 충분하지 않다. |
+| PR의 기본 검증 | 로컬 실행 여부를 사람이 확인 | 기존 docs·회귀·출처·예제 검사를 CI에 연결 | CI 성공을 번역 승인이나 업무 수용으로 취급하지 않는다. |
+
+자동 실행이 줄이는 것은 명령 선택 후 기록·전사·묶기다. 요구사항 판단, 테스트 설계, 한국어 의미 검토에 필요한 시간은 별도로 측정한다. 지금은 절감률을 계산할 자료가 없다.
+
+## 첫 단계: 문서 검토 준비와 검사 통합
+
+### AIWF 저장소를 유지하는 사람
+
+기존 `npm run docs:check`를 유지하고, `manifest.json`을 재사용해 변경 보고서를 만든다. 비교 기준은 사용자가 지정한 Git revision 또는 CI의 PR 기준 commit으로 고정한다. 원문 경로, 한글본 경로, 두 diff, 현재 해시·기록된 해시, 검토 상태, 관련 README·참조 링크를 한 항목으로 제시한다.
+
+보고서는 이번 변경에서 수정된 자료와 기존 미검토 자료를 구분하고, workflow/core와 선택한 stack처럼 실제 작업에 필요한 문서부터 찾을 수 있게 한다. 문서가 변했는데 한글본이 누락되었으면 기존 검사처럼 실패한다. 실제 휴먼 리뷰 기록은 검토자·시각·검토한 두 해시에 연결한다. 에이전트는 승인을 만들어 넣지 않는다.
+
+현재 checkout에는 `.github/` workflow가 없다. 새 CLI를 기다리지 않고 기존 npm/Python 검사를 CI 작업에 연결하는 것이 가능하다. `docs:check:local`은 개인 컴퓨터의 설치 경로 비교이므로 일반 CI 필수 검사로 삼지 않는다. CI에서는 보관된 snapshot과 repository 원문을 검사한다. 이 문서는 CI YAML을 추가하지 않았다.
+
+### AIWF를 사용하는 프로젝트
+
+첫 CLI 확장의 가칭은 `aiwf-spec verify --root <project> --json`이다. **미구현 제안**이며 목표는 애플리케이션 검사를 실행하기 전 명세 상태를 읽는 것이다.
+
+1. 대상 root, 명세 파일과 pin을 기존 라이브러리 계약으로 확인한다.
+2. Python과 CLI에 동봉된 core 검사기를 확인한다. 검사기 경로는 CLI 설치 리소스 기준으로 결정하고, 소비 프로젝트의 임의 스크립트를 같은 이름으로 자동 탐색·실행하지 않는다.
+3. 기존 lint를 `--strict --no-baseline --format json`으로 실행한다. UC 구조와 BPMN 검사는 lint에 통합되어 있으므로 같은 검사를 중복 실행하지 않는다.
+4. 필수 validator 누락과 사용 중인 BPMN parser 누락은 별도 `incomplete`로 처리한다. 파일 존재만으로 로드 성공을 보장하지 않으므로 JSON의 누락 코드도 확인한다.
+5. 명세 drift·lint findings·선행 조건·미검증 의미 검토를 각각 보존해 단일 보고서를 출력한다. drift가 있어도 가능한 읽기 검사를 수행해 수정할 사항을 함께 보여준다.
+
+전체 필수 기계 검사가 실행·통과했을 때만 verify exit 0을 반환한다. 실패·누락은 비정상 종료하고, 사용법 오류와 구분한다. pin 없음, draft marker, drift, 구조 오류를 한 가지 “승인 실패”로 합치지 않는다. 검사 통과는 의미 검토나 제품 승인 상태를 변경하지 않는다. 소비 프로젝트 문서와 pin도 쓰지 않는다.
+
+AIWF의 한글 스킬 검토 archive는 npm 설치 payload가 아니므로, 소비 프로젝트에 `docs/ko-skills/`나 `npm run docs:check`가 있다고 요구하지 않는다. maintainer 문서 검사는 AIWF 저장소에서, 제품 명세 검사는 소비 프로젝트에서 수행한다.
+
+## 두 번째 단계: 선택 실행과 실행 기록을 함께 구현
+
+검사 runner만 먼저 만들면 수작업으로 작성하던 `passed`를 자동으로 작성하는 데 그친다. 다음 범위를 하나의 기능 단위로 묶는 것이 필요하다.
+
+| 기록할 정보 | 목적 |
+| --- | --- |
+| 목표 UC, 소속 BR, TC와 필수 실행 check의 명시적 매핑 | 실행 결과가 어떤 명세·흐름·규칙을 검증하려는지 확인 |
+| receipt 자체 schema/version, run ID, 안정적인 check ID | 이름이 같은 재실행을 구분 |
+| 실행 시작·종료 시각, 실제 executable·argv·cwd, runner·도구 버전 | 어떤 검사를 어떻게 실행했는지 확인 |
+| 실행 당시 명세 digest와 pin digest | 이후 pin 갱신으로 옛 결과가 최신이 되지 않도록 확인 |
+| 코드·테스트·설정·lockfile의 명시적 입력 manifest와 digest | 같은 Git HEAD의 미커밋 변경도 구분 |
+| 검사 정의/config hash, 관련 환경의 허용된 항목 | 명령·환경 변경의 영향을 확인; 비밀값·전체 환경은 기록하지 않음 |
+| exit code, signal, 시작 오류, timeout·취소, 시작하지 않은 이유 | 실패와 미실행을 보존 |
+| run별 stdout/stderr 로그, bytes·hash·완전성 표시 | 기존 로그 덮어쓰기와 불완전한 수집을 확인 |
+| 실행 전후 입력 비교, 현재와의 `fresh/stale/unknown` | 실행 결과와 지금 사용할 수 있는 결과를 구분 |
+
+입력 manifest는 tracked 파일 외에 선언한 범위의 새 파일도 포함한다. `.git`, 실행 결과 `.aiwf/runs`, 의존성 설치 폴더와 build 산출물의 제외 정책을 명시한다. 누락된 입력·외부 서비스·동적 환경 의존성은 `unknown` 또는 미검증 항목으로 남긴다. 이 계약은 완전한 재현 빌드나 원격 신뢰 증명을 뜻하지 않는다. 실행 전후 hash가 같아도 실행 중 변경 후 복구까지 검출한다고 주장하지 않는다.
+
+`fresh`는 기록에 명시한 입력·환경 범위에 한정한다. 선언한 필수 입력이나 환경 식별 정보를 수집·비교할 수 없으면 `unknown`이며 최신 필수 검증을 충족시키지 못한다. 확인된 차이는 `stale`로 표시한다. 범위 밖의 의존성은 제외·미검증 목록으로 제시하고, 선언 범위의 일치를 프로젝트 전체의 최신성으로 확대하지 않는다.
+
+runner는 프로젝트가 명시적으로 정의하고 선택한 검사 ID만 순차 실행한다. 각 검사에는 목표 UC와 관련 BR/TC를 연결하고, 정상·대안·실패 흐름마다 검증 방법이나 미검증 이유를 기록한다. 명세 ID의 존재와 필수 매핑 누락은 기계적으로 검사하되, 테스트가 규칙을 충분히 검증하는지는 별도 의미 검토 대상이다. 전체 테스트 suite를 여러 TC에 연결할 수 있어도 suite 통과나 이름만으로 규칙별 검증 완료를 선언하지 않는다.
+
+dry-run으로 command·범위·출력 위치를 보여주고, 기본 verify나 packet 호출로 애플리케이션 검사를 시작하지 않는다. test script는 파일·DB·네트워크에 영향을 줄 수 있으므로 실행을 읽기 전용 검사라고 표시하지 않는다. 모델 호출·교차 CLI 위임은 기존 선택 위임 스킬의 별도 계약을 유지한다.
+
+프로세스 실행은 argv 배열, 명시적 cwd, 환경 전달 정책을 사용한다. shell 없는 실행도 OS 샌드박스가 아니다. stdout/stderr를 모두 읽고 제한·부분 수집을 기록하며, timeout·취소 신호만으로 모든 하위 프로세스 종료를 단정하지 않는다. Node의 `close` 후 수집을 마감하는 계약과 Windows `.cmd` 실행 차이는 [공식 child_process 문서](https://nodejs.org/download/release/v20.20.2/docs/api/child_process.html)에 근거한다. 최초 runner의 지원 OS와 취소 보장 범위를 검증해 문서에 적는다.
+
+현재 packet은 UTF-8 로그 파일당 1 MiB까지 받는다. 첫 runner는 이 제한 안에서 완전한 로그를 수집하는 정책을 갖춰야 한다. 초과·잘못된 인코딩·저장 실패를 조용히 자르고 성공으로 남기지 않는다. 실패 후 시작하지 않은 필수 검사는 `not_run`과 이유로 보존한다. run별 고유 경로에 결과를 남기고 중단된 receipt를 완료 기록과 구분한다.
+
+### 현재 evidence와의 호환성
+
+현재 입력 evidence에는 version 필드가 없고 `checks/unverified`, 각 검사에는 `name/command/status/log`만 허용된다. packet의 `schema_version: 1`과 입력 JSON 계약은 별개다. 여기에 실행 metadata를 임의 추가하면 기존 parser가 거부한다.
+
+기존 `packet --evidence`는 수동 보고용으로 유지하고 `reported_untrusted`를 보존한다. 새 receipt는 독립 version을 갖고, 향후 packet v2의 별도 실행 기록 입력에서 schema·run ID·hash·입력 버전·필수 검사 집합을 확인한다. 새 packet은 실행 결과와 최신성을 따로 표시한다. 오래된 실행은 과거 결과로 볼 수 있어도 최신 필수 검증을 충족했다고 표시하지 않는다.
+
+호환 출력이 필요하면 receipt에서 v1 evidence를 명시적으로 생성할 수 있다. 시작한 검사의 timeout·취소는 v1 `failed`와 진단 로그로 투영하되 원래 outcome을 receipt에 남긴다. 시작 전 취소는 `not_run`과 이유로 남긴다. **sidecar 파일을 만드는 것만으로 현재 packet이 실행 출처를 검증하는 것은 아니다.** v2 연결 구현 전에는 그런 보장을 안내하지 않는다. 로컬 receipt도 변조 불가능한 인증 자료가 아니다.
+
+runner의 exit 0은 선택한 필수 검사 전체 실행·통과·기록 완료를 뜻하도록 정한다. packet의 exit 0은 파일 생성 성공이라는 현재 계약을 유지한다. 둘을 CI에서 같은 의미로 사용하지 않는다. pin refresh, lint baseline 수용, 휴먼 승인, merge·배포는 자동 실행의 부수 효과로 넣지 않는다.
+
+## 구현 전에 확정할 성공 조건
+
+| 범위 | 통과해야 할 검증 |
+| --- | --- |
+| 문서 보고서 | 변경 원문·한글본·검토 상태를 짝지음; 추가·삭제·이동 반영; 기준 revision 표시; 승인 hash 불일치 거부 |
+| verify | 전체 core에서 통과; validator 누락·로드 실패 시 incomplete; BPMN 사용 시 parser 누락 거부; trace 출력을 lint로 오인하지 않음; 실패 JSON과 exit code 일치; 대상 파일 변경 없음 |
+| receipt와 packet v2 | UC/BR/TC→check의 필수 매핑과 미검증 이유 확인; 새 pin에 옛 로그 재사용, 코드·테스트·설정·lockfile 변경, 필수 검사 누락을 식별; Git 사용 불가 시 확인 한계 표시 |
+| runner | 정상·실패·미시작·시작 오류·timeout·취소·출력 초과·저장 실패 보존; 실행 전후 확인에서 관찰된 입력 변경 식별; 기존 run 파일 덮어쓰기 거부 |
+| 호환성과 설치 | 기존 4개 명령과 evidence 계약 유지; npm payload 및 checkout에서 리소스 확인; 기존 스킬·소비 프로젝트 문서 보존; Node/Python 지원 버전과 OS 검증 |
+| 리뷰 상태 | 자동 통과 후에도 번역은 실제 리뷰 전 `awaiting_review`, packet은 acceptance 미기록 |
+
+지원 runtime 정책도 확정한다. `package.json`은 Node 20+를 선언하지만 [공식 릴리스 표](https://nodejs.org/en/about/previous-releases)는 Node 20을 EOL로 표시한다. 운영 권장 runtime은 지원 중인 LTS로 정하고, Node 20 하한을 유지할지는 별도의 호환성 결정과 실제 검증으로 처리한다. 이번 분석은 선언 버전을 변경하지 않았다.
+
+## 효과를 판단할 파일럿
+
+기존 12개 테스트가 있는 지출 제출 예제는 CLI 연결 smoke 검증에 재사용할 수 있다. 실제 개발·리뷰 생산성은 별도의 소비 프로젝트에서 측정한다. 단순 UC, 실패·대안 흐름이 있는 UC, 명세 변경으로 재검증하는 UC를 각각 고른다. 비교 가능한 작업 규모·검증 범위·검토 기준과 runtime을 먼저 기록한다. 같은 과제를 두 번 수행해서 생기는 학습 효과는 CLI 개선 효과로 계산하지 않는다.
+
+| 측정값 | 측정 방법 |
+| --- | --- |
+| 검토 자료 준비 시간 | 검증이 끝난 뒤 원문·한글본·로그·미검증 사항을 묶는 데 쓴 실제 작업 시간 |
+| 전체 완료 시간 | 문서 작성부터 리뷰 수정과 관련 검사까지 포함; 대기 시간도 별도 기록 |
+| 기록 오류·누락 | 잘못된 상태 전사, 필수 검사 누락, source/translation 누락, 오래된 로그 재사용 건수 |
+| 검토 반복 | 자료 부족 때문에 재요청한 횟수와 의미·기능 문제로 수정한 횟수를 구분 |
+| 유지 비용 | 검사 정의·manifest·예외 처리·실패 진단을 유지하는 데 쓴 시간 |
+
+운영에 필수인 기준은 누락·오래된 증거를 최신 통과로 표시하지 않는 것이다. 자동화 비용까지 포함한 절감은 파일럿에서 확인한다. 손익은 `반복 횟수 × 회당 줄어든 수작업 시간 > 구현 시간 + 같은 기간의 유지 시간`으로 비교할 수 있다. 지금은 어느 항의 수치도 추정 성공률이나 개선율로 채우지 않는다. 작은 파일럿 결과를 통계적 우위나 모든 stack의 성능으로 일반화하지 않는다.
+
+## 뒤로 미루는 범위와 재검토 조건
+
+- **독립 doctor:** 첫 verify의 prerequisite 진단을 재사용한다. 설치·인증·리소스 문제로 반복 실패한 기록이 생기면 별도 명령을 검토한다. 자동 설치·로그인은 넣지 않는다.
+- **변경 영향에 따른 테스트 자동 축소:** UC/BR/TC→check의 명시적 매핑과 누락 검사는 첫 runner부터 포함한다. 현재 문서 추적표만으로 변경 영향 전체를 알 수 없으므로, 영향을 받은 검사만 자동 선택하는 최적화는 별도로 검증한 뒤 도입한다. 테스트 이름이나 파일명만으로 검증 범위를 줄이지 않는다.
+- **병렬·멀티 에이전트 runner:** 긴 독립 검사가 실제 병목이라는 측정이 있고 파일·DB·port·run ID 격리가 가능할 때 추가한다. 변경 파일의 소유권과 통합 검증은 현재 에이전트가 맡는다.
+- **Sprintable:** 로컬 결과의 버전 계약과 리뷰 묶음이 유용하다는 확인 후 [기존 연결 제안](SPRINTABLE.ko.md)을 재검증한다. 과거에 읽은 MCP/backend 계약을 최신 서버 계약으로 가정하지 않는다.
+- **무인 반복 실행·자동 merge:** 로컬 파일럿, 실패·중단·재개, 동시 수정과 실제 승인 버전 계약을 검증하기 전 우선순위에 올리지 않는다.
+
+한글 검토 문서의 의미 검토, runtime 지원 하한 결정, 소비 프로젝트별 필수 검사·입력 범위, packet v2 계약, 실제 시간 측정은 아직 확정되지 않았다. 이 문서는 그 결정에 필요한 근거와 첫 구현 범위를 제공한다.
+
+## 이번 문서 변경의 검증
+
+분석 문서를 저장하고 관련 저장소 README, `aiwf-spec` README 원문·한글본, 문서 목록과 해당 두 해시를 함께 갱신했다. CLI·스킬 실행 지시·upstream 검사기는 수정하지 않았다.
+
+- `npm test`: 85개 통과, 실패 0. 선행 `docs:check`도 통과했다.
+- `npm run check:deps`, `npm run validate:spec-plugin`: 통과.
+- `npm run test:spec-upstream`: Python 검사기 3개의 self-test 통과.
+- `npm run validate:spec-example`: errors/warnings/infos 모두 0.
+- `npm run docs:check:local`: 통과, 관리 문서 70개 모두 검토 대기.
+- 새 분석 문서의 로컬 링크 10개 존재 확인, 추적된 변경의 `git diff --check` 통과.
+
+upstream 출처 검증은 보관된 hash 기준으로 통과했다. 회귀 테스트의 선택적 원본 checkout 비교는 `/private/tmp/aiwf-aiup-reference-20261002`가 없어 실제 비교를 수행하지 않았다. 새 기능의 실행·생산성·실제 휴먼 리뷰를 검증한 결과로 해석하지 않는다.

package/docs/modernization/CLI-PRODUCTIVITY.ko.md

@@ -0,0 +1,193 @@
+# CLI 생산성 개선 분석과 권고안
+
+작성: 2026-10-03. 분석 기준: 로컬 checkout `fcf5ebc24bcd5e49148290a65ac6e1a5c4b22ba6`.
+
+후속 수정: Claude 두 세션의 지적을 반영해 파일럿을 첫 실행 범위로 구체화하고, 상세 runner 계약은 미채택 후보로 낮췄다. [검토 당시 고정본](CLI-PRODUCTIVITY-REVIEWED-2026-10-03.ko.md)의 SHA256은 `426d38f8d52001678083979ca7418c64c6d0b780fa8ef504aec1d6aa5c6b7ab8`이다. [이전 리뷰](CLAUDE-PLAN-REVIEW-2026-10-03.ko.md)는 이 고정본에 대한 결과이며 수정본의 검토 완료로 재사용하지 않는다.
+
+상태: **분석과 구현 제안, 휴먼 리뷰 대기**. 아래 `verify`, 검사 runner, 실행 receipt, packet v2, 문서 검토 보고서와 CI 작업은 아직 구현되지 않았다. 현재 CLI 명령은 `init`, `pin`, `check`, `packet`이다. npm 배포판의 기능·상태를 새로 확인한 기록은 아니다.
+
+## 권고하는 방향
+
+AIWF CLI는 **유스케이스 명세를 구현·실제 검증 결과·휴먼 리뷰로 연결하는 도구**에 집중한다. 최신 문서와 실행 기록은 이 연결을 사람이 확인하도록 돕는다. 문서 관리가 우선이라는 사용자 지침은 모든 작업의 품질 조건으로 적용한다. 원문·한글본 갱신을 먼저 확인하되, 저장소 문서 관리 기능의 확장이 소비 프로젝트의 실제 UC 검증을 대신하지 않도록 한다.
+
+방향 적합성을 재검토한 제품 확장 순서는 다음과 같다.
+
+1. 현재 스킬·CLI로 소비 프로젝트의 실제 UC 하나를 명세→계획→구현→검증→packet까지 수행한다. UC/BR/TC와 실제 검사·미검증 사항의 연결을 사람이 확인하고 수작업·누락을 기록한다.
+2. 파일럿에서 반복한 구조 검사·필수 검사기 확인·명세 drift 확인을 읽기 전용 `verify`로 통합한다.
+3. 결과 전사·수집이 병목이면 UC/BR/TC에 연결된 선택 runner, 버전이 있는 실행 기록, 이를 검증하는 packet v2를 함께 구현한다. 이 연결과 최신성 계약은 runner의 초기 범위에 포함한다.
+4. 같은 UC의 명세 변경·재검증 파일럿으로 효과를 비교한 뒤 Sprintable·병렬 실행의 필요성을 판단한다.
+
+원문·한글본·README·검토 기록의 동시 갱신은 위 모든 단계에 적용한다. AIWF 저장소의 문서 검토 보고서와 기존 검사 명령의 CI 연결은 이를 지원하는 유지보수 개선이다. 이 개선을 새 제품 기능의 선행 조건으로 만들어 실제 UC 파일럿을 미루지 않는다.
+
+새 스킬 수, 명령 수, 에이전트 수는 성공 지표로 삼지 않는다. 문서 갱신 누락, 오래된 결과의 재사용, 검토 준비에 드는 수작업이 줄어드는지가 기준이다.
+
+## 근거와 확신 수준
+
+| 순위 | 분석 결과 | 구분·확신 | 근거 |
+| --- | --- | --- | --- |
+| 1 | 현재 도구로 UC의 명세·구현·실행 결과·실제 검토를 연결하는 파일럿이 먼저다. 예제 재실행과 실제 제품 적용은 구분해야 한다. | 기존 방향은 사실·높음, 자동화 효과는 미확인 | workflow가 UC·테스트·구현·packet을 연결한다. 기존 12개 테스트는 서비스 예제이며 실제 소비 프로젝트의 생산성 측정이 아니다. |
+| 2 | 명세 구조 검사와 pin 확인을 통합하는 것은 기존 기능을 재사용하는 작은 확장이다. 종료 코드만 합산하면 검사 누락을 놓친다. | 사실·높음 | CLI `check`는 lint를 실행하지 않는다. Python lint는 JSON을 제공하지만 sibling validator 누락을 INFO로 기록한다. |
+| 3 | 검사 자동 실행의 전제는 실행 당시 명세·코드·설정과 결과의 연결이다. 현재 packet만으로 최신 실행을 확인할 수 없다. | 계약은 사실·높음, 재사용 위험은 추론·높음 | packet 생성 시 명세를 확인하고 로그를 읽는다. evidence 입력에는 실행 시각·run ID·실행 당시 digest·exit code 필드가 없다. |
+| 4 | 70개 문서의 실제 휴먼 리뷰 기록은 미기록이다. 별도 보고서가 필요한지는 사람이 검토할 때의 준비 시간을 먼저 확인한다. | 기록은 사실·높음, 시간 절감은 추론·중간 | checker는 파일·해시·참조·검토 기록을 검사한다. 기록이 없다는 사실로 사람이 문서를 읽은 적이 없다고 추정하지 않는다. |
+
+직접 확인한 파일:
+
+- [CLI](../../src/cli/spec-cli.js): 명령 목록, `check`와 `packet`의 실행·종료 계약.
+- [명세·packet 라이브러리](../../src/lib/spec-workflow.js): 명세 snapshot, Git 메타데이터, evidence 허용 필드, 로그 수집, `reported_untrusted`.
+- [구조 검사기](../../plugins/aiwf-core/skills/spec-review/scripts/spec_lint.py): `load_sibling`, `check_structure`, `check_bpmn`, `--format json`, `--trace`, INFO와 종료 코드.
+- [workflow](../../plugins/aiwf-spec/skills/workflow/SKILL.md)와 [한글 검토본](../ko-skills/aiwf-spec/skills/workflow/SKILL.ko.md): lint, pin, 테스트, evidence 작성, packet 확인의 현재 절차.
+- [한글 문서 검사기](../../scripts/check-korean-docs.mjs)와 [관리 목록](../ko-skills/manifest.json): 파일별 원문·번역 버전과 실제 검토 기록.
+- [스킬 설치 회귀 검증](../../tests/spec-workflow/install-skills.test.mjs): 기본 core 전체 설치에서 sibling 검사기가 유지된다.
+- [이전 실제 CLI 파일럿](FULL-TEST-2026-10-03.md): Codex 구현과 12개 서비스 테스트, Claude 의미 검토를 기록했다. 운영 앱 전체나 생산성 개선율을 입증한 자료는 아니다.
+
+## 이번에 재확인한 동작
+
+2026-10-03 로컬 Node `v22.23.1`, Python `3.14.8`에서 확인했다. 최소 선언 버전 Node 20/Python 3.9 실행 검증과는 별개다.
+
+| 확인 | 결과 | 설계에 주는 의미 |
+| --- | --- | --- |
+| `aiwf-spec --help`에 해당하는 저장소 CLI 실행 | 현재 명령 4개 확인 | 제안한 새 명령을 설치 안내에 구현된 기능처럼 적지 않는다. |
+| 예제를 전체 core의 lint로 검사, `--strict --no-baseline --format json` | exit 0, errors/warnings/infos 모두 0 | 기존 검사기를 호출하고 JSON을 읽는 방식을 재사용할 수 있다. |
+| 같은 검사 파일만 임시 sibling 없는 폴더에 복사해 같은 예제 검사 | exit 0, INFO `VALIDATOR_MISSING` | exit 0만으로 구조 검사가 전부 실행됐다고 보고하면 안 된다. 임시 폴더는 확인 후 제거했다. |
+| 전체 core의 `--trace --format json` 실행 | exit 0, 요구사항 행 1개 | `--trace`는 문서 연결표다. 별도 lint 성공 또는 테스트 실행 증거가 아니다. |
+| `npm run docs:check:local` | 통과, 문서 70개 모두 검토 대기 | 파일 정합성과 이 컴퓨터의 로컬 스킬 snapshot 일치는 확인했다. 의미 검토와 승인은 남아 있다. |
+
+`BPMN_PARSER_MISSING`도 코드상 INFO이며 필요한 BPMN 검사가 생략된다. 이번 sibling 격리 예제에는 BPMN 파일이 없으므로 그 분기는 실험으로 실행하지 않았다. 전체 core 설치가 항상 불완전하다는 뜻도 아니다. 작은 휴대용 스킬 하나만 설치한 상황과 전체 bundle 설치를 구분해야 한다.
+
+## 생산성이 생기는 지점
+
+| 반복 업무 | 현재의 수작업·오류 가능성 | 권고하는 자동화 | 제약 |
+| --- | --- | --- | --- |
+| 원문과 한글본 검토 준비 | 관리 목록과 diff를 따로 찾고 변경·미검토 범위를 판단 | 같은 변경의 원문·번역 diff와 검토 상태를 짝지은 보고서 | 자동 번역·해시 갱신으로 의미 검토를 대체하지 않는다. |
+| 검사 경로와 선행 조건 확인 | 호스트 설치 구조마다 Python 경로·sibling·pin을 확인 | `verify`에서 번들 검사기와 실제 로드 상태, 명세 drift를 함께 진단 | 누락된 필수 검사를 통과로 표시하지 않는다. |
+| 결과 수집 | 검사마다 로그 저장, 상태 전사, evidence JSON 작성 | 선택한 named-check의 결과·로그·실행 기록 자동 생성 | 실행 범위와 입력 버전을 기록해야 한다. |
+| 다시 검토할 때 최신성 확인 | Git HEAD, 명세 pin, 로그 생성 시점을 수동 대조 | receipt와 현재 입력을 비교해 `fresh/stale/unknown` 표시 | Git HEAD 하나나 `dirty` boolean만으로 충분하지 않다. |
+| PR의 기본 검증 | 로컬 실행 여부를 사람이 확인 | 기존 docs·회귀·출처·예제 검사를 CI에 연결 | CI 성공을 번역 승인이나 업무 수용으로 취급하지 않는다. |
+
+자동 실행이 줄이는 것은 명령 선택 후 기록·전사·묶기다. 요구사항 판단, 테스트 설계, 한국어 의미 검토에 필요한 시간은 별도로 측정한다. 지금은 절감률을 계산할 자료가 없다.
+
+## 첫 실행 범위: UC 파일럿과 실제 리뷰 기록
+
+[UC-001 파일럿 계획](PILOT-UC-001.ko.md)에 선정 범위, 단계별 기록, 실패·재검증, 실제 검토 양식과 종료 조건을 정의했다. 사용자 지정 소비 프로젝트가 없으므로 기존 지출 예제로 로컬 실행·명세 변경 흐름을 먼저 확인하고 실제 제품 파일럿 완료로 기록하지 않는다.
+
+[로컬 실행 결과](PILOT-RESULT-2026-10-03.ko.md)는 기존 12개 테스트 통과, 명세 drift에 대한 packet 거부, 새 요구사항의 7개 실패 검출과 수정 후 23개 통과를 기록한다. packet readback과 보관본 재실행까지 확인했으며 사람의 활성 시간·업무 수용은 미기록이다. 이번 한 UC의 결과로 후속 기능을 채택하지 않는다.
+
+실제 제품 확장의 탐색 기준은 독립 UC 2개 이상에서 같은 준비 작업이 반복되고 측정한 사람의 활성 시간이 합계 10분 이상인 경우다. 제안 기준이며 입증된 손익 수치가 아니다. 자동화 없이 충분하면 새 기능 없이 종료한다. 결정적인 검사 누락·오래된 증거 오인은 시간과 별개로 정확성 문제로 처리한다.
+
+## 별도 유지보수 후보: 문서 검토 준비와 CI
+
+### AIWF 저장소를 유지하는 사람
+
+기존 `npm run docs:check`는 계속 유지한다. 별도 변경 보고서는 사람이 문서를 검토하면서 자료 준비의 병목이 확인된 경우에 도입한다. 후보는 `manifest.json`을 재사용해 원문·번역 diff, 현재·기록된 해시, 검토 상태와 관련 링크를 함께 제시하는 것이다. 비교 기준은 사용자가 지정한 Git revision 또는 CI의 PR 기준 commit으로 고정한다.
+
+보고서는 이번 변경에서 수정된 자료와 기존 미검토 자료를 구분하고, workflow/core와 선택한 stack처럼 실제 작업에 필요한 문서부터 찾을 수 있게 한다. 문서가 변했는데 한글본이 누락되었으면 기존 검사처럼 실패한다. 실제 휴먼 리뷰 기록은 검토자·시각·검토한 두 해시에 연결한다. 에이전트는 승인을 만들어 넣지 않는다.
+
+현재 checkout에는 `.github/` workflow가 없다. 새 CLI를 기다리지 않고 기존 npm/Python 검사를 CI 작업에 연결하는 것이 가능하다. `docs:check:local`은 개인 컴퓨터의 설치 경로 비교이므로 일반 CI 필수 검사로 삼지 않는다. CI에서는 보관된 snapshot과 repository 원문을 검사한다. 이 문서는 CI YAML을 추가하지 않았다.
+
+## 후보 A: 파일럿에서 확인한 검사 절차 통합
+
+첫 CLI 확장의 가칭은 `aiwf-spec verify --root <project> --json`이다. **미구현 제안**이며 목표는 애플리케이션 검사를 실행하기 전 명세 상태를 읽는 것이다.
+
+1. 대상 root, 명세 파일과 pin을 기존 라이브러리 계약으로 확인한다.
+2. Python과 CLI에 동봉된 core 검사기를 확인한다. 검사기 경로는 CLI 설치 리소스 기준으로 결정하고, 소비 프로젝트의 임의 스크립트를 같은 이름으로 자동 탐색·실행하지 않는다.
+3. 기존 lint를 `--strict --no-baseline --format json`으로 실행한다. UC 구조와 BPMN 검사는 lint에 통합되어 있으므로 같은 검사를 중복 실행하지 않는다.
+4. 필수 validator 누락과 사용 중인 BPMN parser 누락은 별도 `incomplete`로 처리한다. 파일 존재만으로 로드 성공을 보장하지 않으므로 JSON의 누락 코드도 확인한다.
+5. 명세 drift·lint findings·선행 조건·미검증 의미 검토를 각각 보존해 단일 보고서를 출력한다. drift가 있어도 가능한 읽기 검사를 수행해 수정할 사항을 함께 보여준다.
+
+Python 시작 실패·비정상 종료·stdout JSON 파싱 실패·필수 필드 불일치는 `tool_error`로 분류한다. JSON의 findings·summary를 검증하고 exit code와 대조한다. `lint_failed`, `tool_error`, `incomplete`, `drift`를 보고서에서 구분하고, 읽기 전후 관찰된 명세 변경은 유효한 단일 시점 검사로 표시하지 않는다. 종료 코드 관계는 구현 시 `--help`와 회귀 검증으로 확정한다. `--no-baseline`은 기존 수용 항목도 다시 findings로 보고하는 현재 workflow 정책이며 자동으로 baseline을 수용하지 않는다.
+
+전체 필수 기계 검사가 실행·통과했을 때만 verify exit 0을 반환한다. 실패·누락은 비정상 종료하고, 사용법 오류와 구분한다. pin 없음, draft marker, drift, 구조 오류를 한 가지 “승인 실패”로 합치지 않는다. 검사 통과는 의미 검토나 제품 승인 상태를 변경하지 않는다. 소비 프로젝트 문서와 pin도 쓰지 않는다.
+
+AIWF의 한글 스킬 검토 archive는 npm 설치 payload가 아니므로, 소비 프로젝트에 `docs/ko-skills/`나 `npm run docs:check`가 있다고 요구하지 않는다. maintainer 문서 검사는 AIWF 저장소에서, 제품 명세 검사는 소비 프로젝트에서 수행한다.
+
+## 후보 B: 미채택 runner·실행 기록 계약
+
+아래는 구현 착수 범위가 아니라 후속 검토할 계약 후보 목록이다. 파일럿에서 전사·수집이 병목으로 측정되면 필요한 최소 항목만 별도 설계로 채택한다. 범용 설정·입력 탐색·환경 식별·새 packet을 한 번에 구현하는 계획으로 사용하지 않는다.
+
+계약 소유는 AIWF의 `aiwf-spec`/CLI다. 초기 매핑·검사 명령의 문서 위치는 pin에 포함되는 소비 프로젝트 `docs/plans/UC-XXX.md`로 정한다. 현재는 사람이 읽는 계획이며 실행 파서는 없다. 향후 파서는 명시적 검사 ID·argv·입력 파일 목록부터 검토하고, 같은 계획의 pin 일치와 선택된 ID·명령 bytes를 실행 기록에 연결한다. plan·매핑·명령이 바뀌면 기존 결과를 최신 검증으로 재사용하지 않는다. 추가 `--yes`를 반복 요구하는 별도 승인 흐름은 기본으로 넣지 않는다.
+
+| 기록할 정보 | 목적 |
+| --- | --- |
+| 목표 UC, 소속 BR, TC와 필수 실행 check의 명시적 매핑 | 실행 결과가 어떤 명세·흐름·규칙을 검증하려는지 확인 |
+| receipt 자체 schema/version, run ID, 안정적인 check ID | 이름이 같은 재실행을 구분 |
+| 실행 시작·종료 시각, 실제 executable·argv·cwd, runner·도구 버전 | 어떤 검사를 어떻게 실행했는지 확인 |
+| 실행 당시 명세 digest와 pin digest | 이후 pin 갱신으로 옛 결과가 최신이 되지 않도록 확인 |
+| 코드·테스트·설정·lockfile의 명시적 입력 manifest와 digest | 같은 Git HEAD의 미커밋 변경도 구분 |
+| 검사 정의/config hash, 관련 환경의 허용된 항목 | 명령·환경 변경의 영향을 확인; 비밀값·전체 환경은 기록하지 않음 |
+| exit code, signal, 시작 오류, timeout·취소, 시작하지 않은 이유 | 실패와 미실행을 보존 |
+| run별 stdout/stderr 로그, bytes·hash·완전성 표시 | 기존 로그 덮어쓰기와 불완전한 수집을 확인 |
+| 실행 전후 입력 비교, 현재와의 `fresh/stale/unknown` | 실행 결과와 지금 사용할 수 있는 결과를 구분 |
+
+입력 manifest는 tracked 파일 외에 선언한 범위의 새 파일도 포함한다. `.git`, 실행 결과 `.aiwf/runs`, 의존성 설치 폴더와 build 산출물의 제외 정책을 명시한다. 누락된 입력·외부 서비스·동적 환경 의존성은 `unknown` 또는 미검증 항목으로 남긴다. 이 계약은 완전한 재현 빌드나 원격 신뢰 증명을 뜻하지 않는다. 실행 전후 hash가 같아도 실행 중 변경 후 복구까지 검출한다고 주장하지 않는다.
+
+`fresh`는 기록에 명시한 입력·환경 범위에 한정한다. 선언한 필수 입력이나 환경 식별 정보를 수집·비교할 수 없으면 `unknown`이며 최신 필수 검증을 충족시키지 못한다. 확인된 차이는 `stale`로 표시한다. 범위 밖의 의존성은 제외·미검증 목록으로 제시하고, 선언 범위의 일치를 프로젝트 전체의 최신성으로 확대하지 않는다.
+
+runner는 프로젝트가 명시적으로 정의하고 선택한 검사 ID만 순차 실행한다. 각 검사에는 목표 UC와 관련 BR/TC를 연결하고, 정상·대안·실패 흐름마다 검증 방법이나 미검증 이유를 기록한다. 명세 ID의 존재와 필수 매핑 누락은 기계적으로 검사하되, 테스트가 규칙을 충분히 검증하는지는 별도 의미 검토 대상이다. 전체 테스트 suite를 여러 TC에 연결할 수 있어도 suite 통과나 이름만으로 규칙별 검증 완료를 선언하지 않는다.
+
+dry-run으로 command·범위·출력 위치를 보여주고, 기본 verify나 packet 호출로 애플리케이션 검사를 시작하지 않는다. test script는 파일·DB·네트워크에 영향을 줄 수 있으므로 실행을 읽기 전용 검사라고 표시하지 않는다. 모델 호출·교차 CLI 위임은 기존 선택 위임 스킬의 별도 계약을 유지한다.
+
+프로세스 실행은 argv 배열, 명시적 cwd, 환경 전달 정책을 사용한다. shell 없는 실행도 OS 샌드박스가 아니다. stdout/stderr를 모두 읽고 제한·부분 수집을 기록하며, timeout·취소 신호만으로 모든 하위 프로세스 종료를 단정하지 않는다. Node의 `close` 후 수집을 마감하는 계약과 Windows `.cmd` 실행 차이는 [공식 child_process 문서](https://nodejs.org/download/release/v20.20.2/docs/api/child_process.html)에 근거한다. 최초 runner의 지원 OS와 취소 보장 범위를 검증해 문서에 적는다.
+
+현재 packet은 UTF-8 로그 파일당 1 MiB까지 받는다. 후속 runner는 실행 outcome과 로그·packet 저장 상태를 구분한다. 로그 전체를 run별 파일로 보관하되 현재 v1 한도를 넘으면 packet 생성 실패·이유를 기록한다. 테스트가 실제 통과했다면 그 outcome을 로그 용량 때문에 실패로 바꾸지 않고, 자료 묶음이 완전하다고도 표시하지 않는다. 발췌·외부 참조는 별도 packet 계약을 채택하기 전에는 사용하지 않는다. 잘못된 인코딩·저장 실패·중단과 미시작 이유도 보존한다.
+
+### 현재 evidence와의 호환성
+
+현재 입력 evidence에는 version 필드가 없고 `checks/unverified`, 각 검사에는 `name/command/status/log`만 허용된다. packet의 `schema_version: 1`과 입력 JSON 계약은 별개다. 여기에 실행 metadata를 임의 추가하면 기존 parser가 거부한다.
+
+기존 `packet --evidence`는 수동 보고용으로 유지하고 `reported_untrusted`를 보존한다. 새 receipt는 독립 version을 갖고, 향후 packet v2의 별도 실행 기록 입력에서 schema·run ID·hash·입력 버전·필수 검사 집합을 확인한다. 새 packet은 실행 결과와 최신성을 따로 표시한다. 오래된 실행은 과거 결과로 볼 수 있어도 최신 필수 검증을 충족했다고 표시하지 않는다.
+
+호환 출력이 필요하면 receipt에서 v1 evidence를 명시적으로 생성할 수 있다. 시작한 검사의 timeout·취소는 v1 `failed`와 진단 로그로 투영하되 원래 outcome을 receipt에 남긴다. 시작 전 취소는 `not_run`과 이유로 남긴다. **sidecar 파일을 만드는 것만으로 현재 packet이 실행 출처를 검증하는 것은 아니다.** v2 연결 구현 전에는 그런 보장을 안내하지 않는다. 로컬 receipt도 변조 불가능한 인증 자료가 아니다.
+
+runner의 exit 0은 선택한 필수 검사 전체 실행·통과·기록 완료를 뜻하도록 정한다. packet의 exit 0은 파일 생성 성공이라는 현재 계약을 유지한다. 둘을 CI에서 같은 의미로 사용하지 않는다. pin refresh, lint baseline 수용, 휴먼 승인, merge·배포는 자동 실행의 부수 효과로 넣지 않는다.
+
+## 후속 기능을 채택할 때의 검증 후보
+
+| 범위 | 통과해야 할 검증 |
+| --- | --- |
+| 문서 보고서 | 변경 원문·한글본·검토 상태를 짝지음; 추가·삭제·이동 반영; 기준 revision 표시; 승인 hash 불일치 거부 |
+| verify | 전체 core에서 통과; validator 누락·로드 실패 시 incomplete; BPMN 사용 시 parser 누락 거부; trace 출력을 lint로 오인하지 않음; 실패 JSON과 exit code 일치; 대상 파일 변경 없음 |
+| receipt와 packet v2 | UC/BR/TC→check의 필수 매핑과 미검증 이유 확인; 새 pin에 옛 로그 재사용, 코드·테스트·설정·lockfile 변경, 필수 검사 누락을 식별; Git 사용 불가 시 확인 한계 표시 |
+| runner | 정상·실패·미시작·시작 오류·timeout·취소·출력 초과·저장 실패 보존; 실행 전후 확인에서 관찰된 입력 변경 식별; 기존 run 파일 덮어쓰기 거부 |
+| 호환성과 설치 | 기존 4개 명령과 evidence 계약 유지; npm payload 및 checkout에서 리소스 확인; 기존 스킬·소비 프로젝트 문서 보존; Node/Python 지원 버전과 OS 검증 |
+| 리뷰 상태 | 자동 통과 후에도 번역은 실제 리뷰 전 `awaiting_review`, packet은 acceptance 미기록 |
+
+runtime 지원 하한은 파일럿과 별도 호환성 결정으로 남긴다. `package.json`의 Node 20+ 선언과 [공식 릴리스 표](https://nodejs.org/en/about/previous-releases)를 확인하고 실제 지원 버전을 검증한 뒤 변경한다.
+
+## 효과를 판단할 파일럿
+
+기존 12개 테스트가 있는 지출 제출 예제는 CLI 연결 smoke 검증에 재사용할 수 있다. 실제 개발·리뷰 생산성은 별도의 소비 프로젝트에서 측정한다. 단순 UC, 실패·대안 흐름이 있는 UC, 명세 변경으로 재검증하는 UC를 각각 고른다. 비교 가능한 작업 규모·검증 범위·검토 기준과 runtime을 먼저 기록한다. 같은 과제를 두 번 수행해서 생기는 학습 효과는 CLI 개선 효과로 계산하지 않는다.
+
+| 측정값 | 측정 방법 |
+| --- | --- |
+| 검토 자료 준비 시간 | 검증이 끝난 뒤 원문·한글본·로그·미검증 사항을 묶는 데 쓴 실제 작업 시간 |
+| 전체 완료 시간 | 문서 작성부터 리뷰 수정과 관련 검사까지 포함; 대기 시간도 별도 기록 |
+| 기록 오류·누락 | 잘못된 상태 전사, 필수 검사 누락, source/translation 누락, 오래된 로그 재사용 건수 |
+| 검토 반복 | 자료 부족 때문에 재요청한 횟수와 의미·기능 문제로 수정한 횟수를 구분 |
+| 유지 비용 | 검사 정의·manifest·예외 처리·실패 진단을 유지하는 데 쓴 시간 |
+
+운영에 필수인 기준은 누락·오래된 증거를 최신 통과로 표시하지 않는 것이다. 자동화 비용까지 포함한 절감은 파일럿에서 확인한다. 손익은 `반복 횟수 × 회당 줄어든 수작업 시간 > 구현 시간 + 같은 기간의 유지 시간`으로 비교할 수 있다. 지금은 어느 항의 수치도 추정 성공률이나 개선율로 채우지 않는다. 작은 파일럿 결과를 통계적 우위나 모든 stack의 성능으로 일반화하지 않는다.
+
+## 뒤로 미루는 범위와 재검토 조건
+
+- **독립 doctor:** 첫 verify의 prerequisite 진단을 재사용한다. 설치·인증·리소스 문제로 반복 실패한 기록이 생기면 별도 명령을 검토한다. 자동 설치·로그인은 넣지 않는다.
+- **변경 영향에 따른 테스트 자동 축소:** UC/BR/TC→check의 명시적 매핑과 누락 검사는 첫 runner부터 포함한다. 현재 문서 추적표만으로 변경 영향 전체를 알 수 없으므로, 영향을 받은 검사만 자동 선택하는 최적화는 별도로 검증한 뒤 도입한다. 테스트 이름이나 파일명만으로 검증 범위를 줄이지 않는다.
+- **병렬·멀티 에이전트 runner:** 긴 독립 검사가 실제 병목이라는 측정이 있고 파일·DB·port·run ID 격리가 가능할 때 추가한다. 변경 파일의 소유권과 통합 검증은 현재 에이전트가 맡는다.
+- **Sprintable:** 로컬 결과의 버전 계약과 리뷰 묶음이 유용하다는 확인 후 [기존 연결 제안](SPRINTABLE.ko.md)을 재검증한다. 과거에 읽은 MCP/backend 계약을 최신 서버 계약으로 가정하지 않는다.
+- **무인 반복 실행·자동 merge:** 로컬 파일럿, 실패·중단·재개, 동시 수정과 실제 승인 버전 계약을 검증하기 전 우선순위에 올리지 않는다.
+
+한글 검토 문서의 의미 검토, runtime 지원 하한 결정, 소비 프로젝트별 필수 검사·입력 범위, packet v2 계약, 실제 시간 측정은 아직 확정되지 않았다. 이 문서는 그 결정에 필요한 근거와 첫 구현 범위를 제공한다.
+
+## 이번 문서 변경의 검증
+
+아래는 최초 분석 문서 작성 시점의 기록이다. 후속 수정본의 검증·로컬 파일럿은 별도 실행 기록에 남기고 이전 결과를 새 변경의 결과로 승격하지 않는다.
+
+분석 문서를 저장하고 관련 저장소 README, `aiwf-spec` README 원문·한글본, 문서 목록과 해당 두 해시를 함께 갱신했다. CLI·스킬 실행 지시·upstream 검사기는 수정하지 않았다.
+
+- `npm test`: 85개 통과, 실패 0. 선행 `docs:check`도 통과했다.
+- `npm run check:deps`, `npm run validate:spec-plugin`: 통과.
+- `npm run test:spec-upstream`: Python 검사기 3개의 self-test 통과.
+- `npm run validate:spec-example`: errors/warnings/infos 모두 0.
+- `npm run docs:check:local`: 통과, 관리 문서 70개 모두 검토 대기.
+- 새 분석 문서의 로컬 링크 10개 존재 확인, 추적된 변경의 `git diff --check` 통과.
+
+upstream 출처 검증은 보관된 hash 기준으로 통과했다. 회귀 테스트의 선택적 원본 checkout 비교는 `/private/tmp/aiwf-aiup-reference-20261002`가 없어 실제 비교를 수행하지 않았다. 새 기능의 실행·생산성·실제 휴먼 리뷰를 검증한 결과로 해석하지 않는다.

package/docs/modernization/CORE-PACKAGE-PLAN.md

@@ -0,0 +1,7 @@
+# Core package correction — 2026-10-03
+
+Historical plan. Legacy-retention decisions are superseded by [LEGACY-REMOVAL-PLAN.md](LEGACY-REMOVAL-PLAN.md) on 2026-10-03.
+
+The upstream core skills were imported under aiwf-spec, while aiwf-core still advertised legacy session and task commands. Make the methodology foundation explicit: aiwf-core owns the seven original core skills and their provenance; aiwf-spec owns only the AIWF workflow extension. Preserve legacy core files under aiwf-core-legacy with a separate marketplace entry. Keep the aiwf-spec CLI and installed Codex skill names stable.
+
+Before moving files, add a regression proving that the marketplace/default installer points to the methodology core, the original hashes remain exact, the wrapper has no duplicate core skills, and legacy resources are preserved. Then update paths, manifests, installation, validation and guides. Verify targeted tests, original Python self-tests, example lint, dependencies and packaged contents. No model execution, automatic MCP installation or Sprintable publication is part of this correction.

package/docs/modernization/DEEP-REVERSE-ENGINEERING.ko.md

@@ -0,0 +1,88 @@
+# 깊은 역설계 고도화 검토안
+
+작성: 2026-10-04. 상태: 제안, 휴먼 검토 대기.
+
+이 문서는 현재 스킬의 번역이 아니라 AIWF 고도화 검토안이다. 아직 새로운 실행 모드나 CLI 명령으로 구현하지 않았다. 대상 제품을 실제로 분석하거나 테스트한 결과도 아니다.
+
+## 목적과 현재 기반
+
+역설계의 목표는 기존 시스템을 변경할 때 필요한 현행 동작, 업무 규칙, 데이터 변화, 실패 시 보장과 그 근거를 복원하는 것이다. 현재 구현의 오류를 원하는 요구사항으로 채택하는 일은 별도 판단이다.
+
+현재 [core 역설계 원문](../../plugins/aiwf-core/skills/reverse-engineer/SKILL.md)과 [한글 검토본](../ko-skills/aiwf-core/skills/reverse-engineer/SKILL.ko.md)은 코드·설정·테스트·스키마에서 액터, 유스케이스, 대안 흐름, 업무 규칙과 엔티티를 추출한다. 삭제 전파와 관계의 다중성도 추적하며, 결과는 `docs/use_cases.puml`, `docs/use_cases/UC-XXX-name.md`, `docs/entity_model.md`에 작성한다. 큰 프로젝트는 기능별로 나누어 조사한다.
+
+현재 절차에 더할 핵심은 주장별 근거 연결, 실행을 통한 관찰, 근거 충돌 기록과 조사 범위의 명시다. 보존된 upstream core는 수정하지 않고, 파일럿 이후 AIWF 소유 workflow에서 확장할 범위를 결정한다.
+
+## 분석 깊이 선택
+
+| 깊이 | 조사 내용 | 사용할 상황 |
+| --- | --- | --- |
+| 구조 파악 | 실행 진입점, 기능 경계, 의존성, 액터, 데이터 지도 | 온보딩과 후속 조사 범위 결정 |
+| 동작 복원 | 사용자 목표별 호출 경로, 규칙, 상태 변화, 부작용, 예외 흐름 | 기능 변경과 현행 명세 작성 |
+| 실행 검증 | 격리 환경에서 경계값·실패·중복·권한·동시성 시나리오 관찰 | 중요한 변경 전 근거 확보 |
+
+전체 시스템의 구조를 먼저 파악하되, 우선순위가 높은 유스케이스 하나를 동작 복원과 실행 검증까지 완결한다. 문서 수나 에이전트 수로 분석 깊이를 평가하지 않는다.
+
+## 진행 절차
+
+1. **분석 기준을 기록한다.** 대상 커밋, 미커밋 변경, 실행 환경, 관련 설정 이름·비밀이 아닌 설정값, 조사 포함·제외 범위를 남긴다. 사용 가능한 DB 스키마가 어느 환경·버전인지 확인한다. 마이그레이션 파일만으로 실제 배포 DB 상태를 단정하지 않는다.
+2. **시스템 지도를 만든다.** 사용자 진입점뿐 아니라 스케줄러, 메시지 소비자, 웹훅을 포함한다. 기능 경계와 공유 인증·데이터·외부 연동을 표시한다. 모든 발견 진입점을 유스케이스, 기술 인프라 또는 미분류 중 하나에 연결한다. 호출되지 않는 코드와 실제 경로를 구분한다.
+3. **유스케이스 하나를 끝까지 추적한다.** 입력 → 권한·검증 → 도메인 판단 → 저장 → 외부 호출·이벤트 → 응답을 연결한다. 업무 흐름은 core 형식으로 작성하고, 함수·SQL·트랜잭션 같은 구현 근거는 별도 분석 문서에서 연결한다. 정상 흐름 외에 상태 전이, 실패 시 남는 데이터, 재시도와 중복 처리도 조사한다.
+4. **의미 있는 시나리오로 재현한다.** 기존 테스트를 먼저 활용한다. 근거가 부족한 중요한 동작에는 최소 재현 테스트를 작성한다. 경계값, 권한·소유권, 중간 저장 실패, 외부 연동 실패, 중복 요청과 동시 실행 중 해당 UC에 필요한 항목을 선택한다. 격리된 로컬 환경과 대체 외부 서비스를 사용한다. 실행하지 못한 항목은 이유와 관찰 한계를 기록한다.
+5. **근거를 대조한다.** 코드, 테스트, 실행 결과, 스키마, 기존 문서의 일치·충돌을 기록한다. 테스트 존재와 실행 통과를 구분한다. 현행 동작은 관찰 환경의 사실로, 원하는 정책은 검토할 요구사항으로 작성한다. 설계 이유는 ADR·변경 이력의 명시적 설명이 있을 때만 역사적 사실로 기록하고 나머지는 추론으로 둔다.
+6. **반박 검토 후 문서를 확정한다.** 작성과 검토를 별도 단계로 수행한다. 검토자는 근거 링크를 직접 확인하고 잘못된 일반화, 빠진 예외, 의도와 구현의 혼동을 찾는다. 형식 검사와 의미 검토를 구분한다. 미확인·충돌 항목과 사람에게 필요한 판단을 함께 제출한다.
+
+분석 중 확인한 버그의 수정은 별도 구현 범위다. 재현용 테스트를 통해 현행 동작을 기록해도 그 동작을 제품 정책으로 승인하지 않는다.
+
+## 반드시 추적할 내용
+
+| 관점 | 확인할 질문 |
+| --- | --- |
+| 업무 규칙 | 제한값과 조건은 어디서 적용되며, 다른 진입점에서 우회할 수 있는가? |
+| 상태·데이터 | 생성·수정·삭제 시 어떤 값과 관계가 바뀌며, 삭제 전파와 소유권 영향은 무엇인가? |
+| 실패 보장 | 중간 단계가 실패하면 어떤 데이터와 외부 부작용이 남는가? |
+| 비동기 동작 | 이벤트 순서 변경, 중복 전달, 재시도, 부분 완료 시 어떻게 되는가? |
+| 권한 경계 | 역할뿐 아니라 객체 소유권·테넌트 경계가 모든 경로에서 적용되는가? |
+| 설정·운영 | 기능 플래그, 시간대, 제한값과 배포 환경에 따라 동작이 달라지는가? |
+| 설계 배경 | 현재 설계를 설명하는 ADR·변경 이력이 있는가? 당시 이유가 현재에도 해당하는가? |
+
+해당하지 않는 관점은 사유를 기록한다. 로그·설정·샘플 데이터의 비밀값과 개인정보는 문서에 복사하지 않는다.
+
+## 근거 기록 계약
+
+각 중요한 주장에는 소속 UC/BR/대안 흐름, 코드 파일·심볼·분석 커밋, 테스트 위치, 실제 실행 로그와 종료 코드, 관찰 환경, 남은 질문을 연결한다. 미커밋 파일은 해시도 기록하여 커밋만으로 특정되지 않는 내용을 구분한다.
+
+확인 상태는 아래처럼 설명하고, 임의의 신뢰도 백분율을 만들지 않는다. 이는 제안된 분석 표의 표현이며 core 파서의 명세 상태를 대체하지 않는다.
+
+- **실행 확인:** 기록된 조건에서 재현했다. 그 밖의 환경까지 보장하지 않는다.
+- **코드 확인:** 코드 경로로 확인했으나 실행으로 검증하지 않았다.
+- **추론:** 해석은 가능하지만 근거 또는 실행 조건이 부족하다.
+- **미확인:** 필요한 자료나 실행 환경이 없다.
+- **충돌:** 근거들이 서로 다른 동작이나 정책을 말한다.
+
+예를 들어 지출 제출을 조사한다면 “저장 실패 시 아무 데이터도 남지 않는다”는 문장에 검증·저장 순서, 트랜잭션 경계와 실패 주입 테스트를 연결한다. 트랜잭션 표시가 있다는 사실만으로 외부 알림까지 취소된다고 주장하지 않는다. 이 예시는 실제 제품에서 확인한 사실이 아니다.
+
+## 문서 배치와 CLI 책임
+
+소비 프로젝트에서는 기존 core 산출물을 유지하고, 필요할 때 다음 한글 본문 문서를 추가하는 방식을 제안한다.
+
+- `docs/architecture/reverse-engineering-scope.md`: 분석 기준, 기능 지도, 조사 포함·제외 범위.
+- `docs/architecture/UC-XXX-evidence.md`: 호출 경로, 상태·실패 분석, 주장별 근거, 충돌·미확인 항목.
+- `docs/test_cases/TC-XXX-name.md`: 중요한 현행 동작을 검증할 시나리오.
+
+먼저 범위와 근거표 두 문서로 시작하고, 내용이 커질 때만 나눈다. 사람은 한글로 읽고, UC 명세의 파서용 영어 헤딩·ID·상태는 보존한다. 역설계 요청만으로 비전이나 승인된 요구사항을 만들어내지 않는다.
+
+현재 `aiwf-spec`은 위 `docs/architecture/`와 `docs/test_cases/`의 Markdown을 pin에 포함한다. 그러나 코드 분석, 재현 실행, 코드 해시 수집이나 증거의 최신성 검증을 자동 수행하지 않는다. `pin`은 필수 문서와 UC/TC 조건을 요구하므로 core 역설계 산출물 세 종류만으로 바로 실행할 수 있다고 가정하지 않는다. 일반 로그와 별도 분석 폴더 전체가 pin에 들어가는 것도 아니다.
+
+## 선택적 다중 에이전트
+
+독립적인 분석이 유용한 규모라면 코드 흐름, 데이터·상태, 실행 검증을 제한된 범위로 나눈다. 각 담당자는 공동 기준 버전과 UC를 사용하고 근거·한계·충돌을 반환한다. 메인 담당자는 공용 인증·엔티티·이벤트 경계를 통합하고 최종 문서를 작성한다. 검토 담당자는 결론을 받아쓰지 않고 근거에서 결론이 성립하는지 확인한다.
+
+Claude/Codex 선택은 분석 역할과 별개다. 네이티브 위임을 활용할 수 있고 교차 CLI 호출은 기존 선택 위임 플러그인의 명시적 옵션을 따른다. 이 검토안은 새 세션 실행이나 교차 CLI 호출의 자동 활성화를 의미하지 않는다.
+
+## 첫 파일럿과 완료 기준
+
+실제 소비 프로젝트에서 변경 예정이거나 실패 영향이 큰 UC 하나를 선택한다. 시스템 전체의 진입점 지도는 만들되 상세 분석은 해당 UC와 공유 경계에 집중한다.
+
+완료 기준은 중요한 규칙과 대안 흐름에 근거가 연결되고, 위험이 큰 실패·권한·상태 동작이 재현되거나 미검증 이유가 기록되고, 근거 충돌과 분석 제외 범위를 사람이 읽을 수 있는 것이다. 재현 결과는 실행 당시 버전과 환경을 특정해야 한다. 사람은 충돌하는 정책, 유지해야 할 현행 동작, 변경할 결함과 미검증 위험을 판단한다.
+
+고도화 효과는 근거 없는 주장 수, 놓친 실패 흐름, 검토 시 되찾아야 했던 코드 위치, 후속 변경에서 발견한 누락과 조사·검토 시간으로 확인한다. 첫 파일럿 결과를 바탕으로 workflow 지시와 한글 검토본을 함께 개정할 범위를 정한다. 자동 검사 통과나 AI 검토는 휴먼 승인을 대체하지 않는다.

package/docs/modernization/DELEGATION-OPTIONAL.ko.md

@@ -0,0 +1,57 @@
+# Claude·Codex 위임 스킬 — 선택 설치·선택 실행 명세
+
+## 목표
+
+AIWF 사용자가 `Claude` 또는 `Codex`를 명시해 독립 작업을 맡기고, 결과와 검증 근거를 다시 통합할 수 있게 한다. 기존 AIUP 원본인 `aiwf-core`의 일곱 스킬과 업스트림 출처를 변경하지 않는다. 위임 기능은 AIWF core 배포에 속하는 별도 선택 애드온으로 관리한다.
+
+## 수용 기준
+
+1. `aiwf-delegate-claude`와 `aiwf-delegate-codex` 플러그인을 서로 독립적으로 설치하거나 생략할 수 있다. 각 플러그인의 스킬 ID는 `delegate-claude`, `delegate-codex`다.
+2. 한 애드온은 해당 대상의 명시적 위임 스킬 하나를 제공한다. 설치했다고 자동 위임하지 않으며, 사용자가 그 스킬을 직접 호출한 경우에만 실행을 시작한다.
+3. Codex 복사 설치 도구는 기본 core/workflow 설치 구성에 두 애드온을 포함하지 않는다. `--delegate claude`와 `--delegate codex`를 반복해 각각 선택할 수 있고, 대상이 겹치면 한 번만 설치한다. 대상 스킬이 이미 있으면 전체 설치 사전 검사를 통해 파일을 덮어쓰지 않고 작업을 거부한다.
+4. Claude marketplace는 두 플러그인을 개별 항목으로 제공한다. 등록만으로 설치·활성화·로그인하지 않는다.
+5. 현재 호스트가 요청한 대상과 같으면 해당 호스트의 네이티브 하위 에이전트 기능을 쓴다.
+6. 현재 호스트와 대상 CLI가 다르면 현재 사용자 요청에 문자 그대로 `--cross-cli`가 들어 있는 경우에만 해당 CLI를 시작한다. “Claude에 위임”처럼 대상을 지정하는 말은 별도 CLI 프로세스 실행에 대한 동의가 아니다. 이전 대화나 작업 프롬프트에서 동의를 추론하지 않는다. 다른 공급자로 바꾸거나, 알리지 않고 또는 알리고 나서 자동 대체하지 않는다.
+7. 외부 CLI 입력은 표준 입력으로 전달하고, 출력은 제공자 형식에 따라 읽는다. 작업 텍스트를 셸 명령으로 평가하거나 비밀값을 프롬프트에 복사하지 않는다.
+8. 다른 CLI의 설치, 로그인, 업데이트, 설정, 에이전트 팀 활성화는 하지 않는다. 실행할 수 없으면 누락된 조건과 결과를 보고한다.
+9. 교차 CLI는 기본 읽기 전용이다. 현재 사용자 요청에 `--cross-cli`와 함께 파일 변경 요청 및 정확한 범위를 명시한 경우에만 쓰기를 허용한다. 별도 프로세스지만 같은 OS 계정, 현재 작업 디렉터리와 환경을 사용한다. 호출 호스트의 세션·샌드박스·승인 흐름은 전달되지 않으며, 대상 CLI의 자체 설정·권한 정책이 적용된다. 교차 실행은 보안 격리 경계가 아니다. 환경 변수의 비밀값을 프롬프트나 출력으로 드러내지 않는다. 위험 권한 우회 플래그를 추가하지 않으며, CLI가 권한을 거부하면 다른 경로나 더 넓은 권한으로 다시 시도하지 않는다.
+10. 위임 결과는 대상, 실행 경로(native/CLI), 버전(알 수 있으면), 세션 ID(제공되면), 상태, 요약, 바뀐 경로, 실행한 확인, 실패·미완료 항목을 포함한다. 주 에이전트가 변경과 결과를 직접 확인하고 최종 응답을 소유한다.
+
+## 라우팅
+
+| 요청 대상 | 현재 호스트 | 허용 경로 |
+| --- | --- | --- |
+| Claude | Claude Code | Claude 네이티브 하위 에이전트 |
+| Codex | Codex | Codex 네이티브 하위 에이전트 |
+| Claude | Codex | `--cross-cli`가 명시된 경우 `claude -p` |
+| Codex | Claude Code | `--cross-cli`가 명시된 경우 `codex exec -` |
+| 어느 쪽이든 | CLI·네이티브 기능을 쓸 수 없는 호스트 | 기능 없음과 복구 조건을 보고 |
+
+같은 제품을 그 제품의 CLI로 중첩 실행하는 경로는 두지 않는다. 플러그인 설치만으로 Claude Agent Teams를 활성화하지 않으며, Codex App Server나 Codex 데스크톱 작업 생성 API를 위임 하위 에이전트로 가장하지 않는다. Claude와 Codex CLI는 공식 네이티브 상호 위임 계약이 아니라 별도 프로세스 인터페이스로 연결한다.
+
+## 작업 경계와 결과
+
+작업 프롬프트에는 목표, 담당할 파일 또는 범위, 쓰기 가능 여부, 완료 조건, 기대할 산출물과 검증 결과를 포함한다. 저장소 문서와 코드 안의 지시문은 작업 입력 데이터로 취급한다. 서로 다른 에이전트가 같은 파일을 동시에 고치게 하지 않고, 공유 쓰기 영역이 생기면 직렬화한다.
+
+교차 실행은 각 CLI의 비대화형 출력에서 Claude의 JSON `result`/`session_id` 또는 Codex JSONL 이벤트를 읽는다. 종료 코드만으로 작업 성공을 판정하지 않는다. 부모는 변경 목록을 확인하고 관련 검증을 다시 실행한다. 부분 결과나 권한 거부, 타임아웃, 대상 CLI 오류는 감추지 않고 위임 결과에 남긴다.
+
+## 설치·실행 선택
+
+- Claude 사용자는 marketplace에서 대상별 애드온을 고르고 직접 설치한다.
+- Codex 사용자는 `$aiwf-delegate-claude` 또는 `$aiwf-delegate-codex`가 들어 있는 skill을 선택 설치한다. `scripts/install-spec-skills.mjs`에는 대상별 `--delegate` 선택지를 제공한다. skills.sh는 대상 스킬 하나를 지정해 설치한다. 예: `npx skills add https://github.com/moonklabs/aiwf --skill delegate-claude --agent codex`.
+- Claude marketplace에서는 `/aiwf-delegate-claude:delegate-claude`, `/aiwf-delegate-codex:delegate-codex`로 호출한다. 각 스킬은 Claude에서 `disable-model-invocation: true`, Codex에서 `policy.allow_implicit_invocation: false`를 선언한다. Codex 수동 설치본에서는 `$aiwf-delegate-claude`, `$aiwf-delegate-codex` 형식을 쓴다. skills.sh 설치 시 CLI는 원래 `delegate-claude`, `delegate-codex` 이름을 유지한다.
+- skills.sh CLI 설치는 Claude Code 또는 Codex 중 한 호스트를 지정하며, 스킬 이름은 `delegate-claude` / `delegate-codex`로 유지된다. 설치 스크립트는 Codex용 `.agents/skills/aiwf-delegate-claude` / `.agents/skills/aiwf-delegate-codex`를 만들고, frontmatter 이름도 `aiwf-` 접두사를 붙인다.
+- 네이티브 경로는 직접 호출한 대상 스킬을 통해 사용한다. 다른 호스트에서 CLI를 시작하려면 현재 사용자 요청에 `--cross-cli` 토큰을 넣는다. 대상 CLI의 기존 권한 정책이 허용하지 않으면 권한을 넓히지 않고 중단한다.
+- 대상 CLI가 없거나 로그인 상태가 아니면 설치·로그인 절차를 대신 수행하거나 `npx`, 다른 바이너리, 다른 공급자로 대체하지 않는다. 사용자가 나중에 다시 실행할 수 있도록 원인을 기록한다.
+
+## 범위 밖
+
+런타임 CLI 설치와 인증, 자동 작업 분할 수·공급자 모델 선택기, 다중 CLI 동시 실행 관리 UI, 벤더 간 세션을 하나로 합치는 작업, 실험 기능인 Claude Agent Teams, App Server 통합, 풀 액세스·위험 권한 자동 승인, 설치 후 암묵적 호출은 이번 구현에 포함하지 않는다.
+
+## 공식 계약 확인 자료
+
+- [Claude Code skills](https://code.claude.com/docs/en/skills), [Claude Code plugins](https://code.claude.com/docs/en/plugins-reference), [Claude Code headless mode](https://code.claude.com/docs/en/headless)
+- [Codex skills](https://developers.openai.com/codex/skills), [Codex portable plugin packaging](https://developers.openai.com/plugins/build/plugins), [Codex non-interactive mode](https://developers.openai.com/codex/noninteractive)
+- [skills.sh CLI](https://www.skills.sh/docs/cli), [Codex skill installation via skills.sh](https://www.skills.sh/agent/codex)
+
+공식 문서는 CLI 입력·출력과 개별 호스트의 네이티브 기능을 설명한다. Claude와 Codex를 하나의 네이티브 하위 에이전트로 연결하는 계약은 이번 설계에서 가정하지 않는다.