aiwf 0.3.23 → 0.4.0

package/docs/modernization/DIRECTION.ko.md

@@ -0,0 +1,56 @@
+# AIWF 개선 방향
+
+작성: 2026-10-02. 참고 저장소: AIUP `065dadda0f696c29ff2bacbda31b38152082e6fa`.
+
+## 결정
+
+AIWF를 **유스케이스 명세를 실제 구현과 검증으로 연결하는 개발 워크플로우**로 전환한다. 개발자는 기존 Claude Code/Codex와 프로젝트의 기술 스택을 사용한다. 명세는 Git에 남고, Sprintable은 향후 팀의 작업·검토·승인을 연결한다.
+
+예를 들어 “직원이 지출 내역을 제출한다”는 목표를 먼저 명세한다. 정상 제출, 금액 오류, 저장 실패 시 보장, 업무 규칙을 정의하고 각각의 검증 방법을 작성한다. 에이전트는 그 범위만 구현하고 실제 테스트 로그를 남긴다. 검토자는 어떤 명세 버전으로 무엇을 구현했고 무엇을 아직 확인하지 못했는지 한 묶음으로 읽는다. 다음 변경도 같은 명세를 수정하는 데서 시작한다.
+
+## AIUP에서 가져오는 것
+
+[공식 marketplace](https://github.com/AI-Unified-Process/marketplace)는 방법론을 담당하는 `aiup-core`와 기술 스택별 구현 플러그인을 분리한다. 이번에는 core의 7개 스킬, 문서 형식, 참조 템플릿, Python 검사기를 `plugins/aiwf-core`로, 기술 스택 플러그인 4개(`aiup-vaadin-jooq` 2.20.0, `aiup-angular-jpa` 0.7.0, `aiup-blazor-dotnet` 0.7.0, `aiup-nestjs-nextjs` 0.4.0)의 스킬 24개를 각 `plugins/aiwf-<stack>`으로 가져왔다. core SKILL.md 7개는 upstream 바이트와 동일하고 참조·검사기도 수정하지 않았으며, 유일한 upstream 소스 수정은 core NOTICE에 AIWF 출처를 덧붙인 것이다. stack 플러그인은 `skills/`, `rules/`, `agents/`, `LICENSE`, `NOTICE`를 바이트 그대로 두고 플러그인별 `UPSTREAM.json`에 hash를 기록한다. Apache-2.0 LICENSE와 NOTICE, 원본 커밋 및 수정 표시를 함께 보관한다. AIWF의 기존 MIT 라이선스와 가져온 플러그인의 Apache-2.0 라이선스는 파일 범위가 다르다.
+
+- 비전 → 요구사항 → 용어집/엔티티 → 유스케이스 → 테스트 정의.
+- `FR-001`, `UC-001`, `TC-001`로 연결하고 `UC-001 BR-001`처럼 업무 규칙의 소속을 표시한다.
+- 기존 시스템은 reverse-engineer로 실제 동작부터 조사한다.
+- 명세를 일회성 프롬프트로 버리지 않고 제품과 함께 유지한다.
+- 문서의 구조·참조 검사와 사람이 판단하는 의미 검토를 구분한다.
+
+실제 코드에서 확인한 한계도 있다. 스킬은 에이전트 지침이며 실행 강제 장치가 아니다. 추적표는 문서 간 연결을 계산할 뿐 구현이나 테스트 실행을 증명하지 않는다. upstream 생성 CI에는 작업 종류와 파일 변경으로 상태를 올리는 분기가 있어, 그것만으로 테스트 성공을 증명할 수 없다. 그 CI는 이번에 가져오지 않았다. [원본 생성 워크플로우](https://github.com/AI-Unified-Process/marketplace/blob/065dadda0f696c29ff2bacbda31b38152082e6fa/.github/workflows/aiup-generate.yml).
+
+## 책임 경계
+
+| 구성 | 책임 | 이번 상태 |
+|---|---|---|
+| 명세 `docs/` | 원하는 동작과 검증 정의, 안정적인 ID | AIUP 형식 채택 |
+| `aiwf-core` 플러그인 | 요구사항·엔티티·유스케이스·명세 검토 지침 (필수 core) | upstream 7개 바이트 그대로 |
+| `aiwf-spec` 플러그인 | AIWF `workflow`, `sync-docs`, host 중립 작업 추적·증거 경계 | 자체 스킬 2개 |
+| stack 플러그인 `aiwf-<stack>` | 스택별 마이그레이션·구현·테스트 지침 | upstream 4종 바이트 그대로 이식 |
+| `aiwf-spec` CLI | 초기화, 명세 버전 고정, 변경 감지, 검증 로그 묶기 | 로컬 구현 |
+| 현재 코딩 에이전트 | 코드 수정, 프로젝트 테스트 실행, 결과 보고 | 기존 도구 사용; 별도 모델 런타임 없음 |
+| Sprintable 어댑터 | 작업과 명세 버전 연결, 문서/증거 업로드 | 다음 단계 설계 |
+| 검토자/승인자 | 검토·업무 수용·승인 | 자동 통과로 대체하지 않음 |
+
+완료, 테스트 통과, 업무 수용, 승인, 병합, 배포는 서로 다른 사실이다. SHA256은 파일이 같은지 알려주며 내용이 옳은지는 알려주지 않는다. 이번 CLI의 packet은 에이전트가 보고한 결과와 로그를 기록하고 `awaiting_review`로 남긴다.
+
+## 레거시 정리
+
+2026-10-03 사용자 결정에 따라 예전 설치기·페르소나·언어/스프린트/YOLO 런타임, 중복 스킬·명령·규칙, 레거시 플러그인과 문서를 제거했다. 당시 정리 범위는 core/workflow/stack 플러그인 6개와 의존성 없는 명세 CLI였다. 이후 선택 위임 애드온 2개를 더한 현재 구성은 총 8개이며 위임 설치·실행은 선택 사항이다. 과거 기록은 Git 이력과 changelog에 남긴다. 실제 제품 앱의 파일럿은 별도 검증이 필요하다.
+
+## 진행 순서
+
+2026-10-03 후속 [CLI 생산성 분석](CLI-PRODUCTIVITY.ko.md)은 현재 도구로 실제 UC 파일럿을 먼저 수행하고, 관찰된 반복 절차를 읽기 전용 검사 통합과 UC/BR/TC에 연결된 선택 실행·버전 기록으로 줄이도록 권고한다. 원문·한글본 갱신은 모든 작업의 품질 조건이며 문서 검토 보고서와 CI는 이를 지원하는 유지보수 개선이다. 이 제안들은 기존 CLI에 추가된 기능이 아니다. 파일럿의 시간·검토 누락 측정으로 후속 자동화 범위를 정한다.
+
+1. **로컬 기반:** `aiwf-core`/`aiwf-spec` 분리와 4개 stack 이식, 완전한 한국어 예제, 구조 검사, 명세 pin/change check, 검증 로그 packet, Claude/Codex 설치 경로. 이번 작업 범위다.
+2. **실제 기능 파일럿:** 작은 실제 저장소에서 UC 하나를 선택한다. 정상 흐름과 실패 흐름을 구현하고 실제 앱 동작을 확인한다. 문서 작성부터 실행 결과까지 걸린 시간, 검토 횟수, 명세 대비 누락을 기록한다. 이 결과로 명세 양과 workflow를 조정한다.
+3. **Sprintable 연결:** 프로젝트/작업을 명시적으로 연결하고, packet을 문서로 등록하고, report evidence와 필요 시 승인 게이트를 만든다. 수정된 명세를 기존 승인으로 통과시키지 않는 버전 계약을 검증한다.
+4. **반복 실행:** 파일럿 이후 CI/에이전트 작업 큐·중단/재개·재시도·동시 작업 격리를 추가한다. 저장소 변경, 실패한 테스트, 승인 대기가 있는 경우 자동으로 병합하지 않는다. 반복 실행은 아직 구현되지 않았다.
+
+
+방법론 core 7개는 `plugins/aiwf-core`에, AIWF `workflow`는 `plugins/aiwf-spec`에 분리했다. 이전에는 core 7개를 `aiwf-spec`에 넣어 방법론 core와 AIWF 래퍼가 한 플러그인에 섞였는데, 원본 소스는 그대로 두고 위치만 옮겨 바로잡았다. Codex 설치기는 기본으로 core 7개와 `workflow`, `sync-docs` 2개를 설치하고 `--stack`으로 stack 하나를 추가하며, 기존 설치는 덮어쓰지 않고 강제 갱신 플래그도 없다. 설치는 파일 복사일 뿐 네이티브 Codex 에이전트를 등록하지 않고 MCP 서버를 자동 구성하지 않는다. 다만 어느 stack을 실제 파일럿에 쓸지는 대상 저장소가 정해진 뒤 선정한다. AIUP의 stack을 무조건 쓰기보다 실제 프로젝트의 테스트·구현 규칙과 맞추는 것이 먼저다.
+
+## 이번 범위의 검증과 남은 것
+
+검증 내역은 [VALIDATION.md](VALIDATION.md)에 기록한다. 구조 검사 통과와 로컬 CLI 테스트는 실제 에이전트가 애플리케이션을 성공적으로 개발했다는 증거가 아니다. Claude/Codex의 실제 스킬 자동 선택, 실제 앱 파일럿, Sprintable 운영 연동, 자동 승인 무효화, 무인 반복 실행은 후속 검증 범위다.

package/docs/modernization/FULL-TEST-2026-10-03.md

@@ -0,0 +1,49 @@
+# AIWF 전체 동작 검증 — 2026-10-03
+
+로컬 명세 workflow, npm 배포 파일, 모든 스킬 설치 조합, 실제 Codex 구현 및 Claude Code 명세 검토가 동작했다. 검사 중 발견한 packet 저장 대상의 파일 종류 오류는 수정했다. 이 결과는 실제 운영 앱이나 모든 stack의 구현 성공을 뜻하지 않는다.
+
+기준 커밋은 `10e885ea6236e30d0797523c1cec4bf8d844487e`이며 이후 아래 오류 수정과 회귀 검사를 추가했다. Node 22.23.1, Python 3.14.4 및 별도 Python 3.11에서 실행했다.
+
+| 검사 | 실제 결과 |
+|---|---|
+| `npm test` | 61 통과, 0 실패, 0 건너뜀 |
+| 원본·플러그인 검사 | 31 원본 스킬, 71 원본 리소스 hash 일치; core NOTICE의 출처 추가만 유지 |
+| 원본 Python 검사기 | 3개 self-test 통과; Python 3.11에서도 통과 |
+| 예제 명세 | strict/no-baseline lint: 오류·경고·정보 0; 추적표는 별도 실행 |
+| 정적 검사 | Node 문법, 내부 import/의존성 선언, 변경 파일 공백 검사 통과 |
+| Claude Code 자체 검사 | marketplace와 6개 플러그인 manifest 모두 통과 |
+| npm 실제 설치 | 새 임시 프로젝트·빈 npm cache에서 offline 설치; 외부 Node 의존성 없음; npm bin 및 라이브러리 import 실행 성공 |
+| 설치 조합 | core+workflow 8개; Vaadin 16개; Angular 14개; Blazor 13개; NestJS 13개 |
+| 설치 보존 | 5개 조합 모두 dry-run 쓰기 없음, 재설치 거부 후 모든 파일 hash 동일; 각 설치본 Python self-test 3개 통과 |
+| 실제 명세 사용 | 초기화 보존, Draft pin 거부, lint, pin, check, packet 저장·재읽기 성공 |
+| 실패 처리 | passed/failed/not_run 보존; 기본 덮어쓰기 거부; 명세 변경 감지; 오래된 명세 packet 생성 거부; 명세 복원 후 정상 |
+
+Node 내장 coverage 측정은 CLI·workflow library·installer 세 파일에서 줄 91.94%, 분기 86.18%, 함수 96.34%였다. 별도 프로세스로 검사한 provenance validator는 이 수치에 포함되지 않는다. coverage는 올바른 의미나 모든 경계 조건의 증명이 아니다.
+
+## 실제 에이전트 실행
+
+Codex CLI 0.154.0에서 설치된 `aiwf-workflow`와 core review 스킬을 발견하고 읽었다. `gpt-6-astra`가 기존 UC-001의 지출 제출 **서비스 범위**를 구현했다. 정상 제출·금액 오류·비정상 숫자·저장 실패 시 기존 기록 보존을 다루는 실제 Node 테스트 12개가 통과했다. UI와 로그인 구현은 범위에서 제외했다.
+
+계획 작성 → 실제 구조 검사 → pin → 실제 서비스 테스트 → check → evidence → packet 저장·재읽기를 수행했다. Main이 서비스 테스트를 별도로 다시 실행했고, packet의 로그 본문·SHA256·크기와 명세 파일 hash를 대조했다. packet은 `awaiting_review`, acceptance는 `not_recorded`; 4개 실행 검사와 4개 `not_run`을 보존했다. Codex 자체 의미 검토는 별도 검토자의 승인으로 간주하지 않았다.
+
+Claude Code 2.1.287과 `claude-sonnet-5-5`로 실제 `/aiwf-core:spec-review`를 로드했다. bundled checker와 review checklist를 사용했다. 구조 검사와 추적표 출력은 서로 다른 실행 모드이므로 분리해서 확인했다. 의미 검토에서는 예제 명세의 확인 불가능한 사전조건, 저장 실패 후 재시도/입력 상태, 사용 내용의 필수 여부에 대해 경고 3개와 정보 3개를 보고했다. 구조 검사 통과를 의미 검토 통과나 승인으로 바꾸지 않았다.
+
+## 발견하고 수정한 오류
+
+기존 폴더를 packet 저장 대상으로 지정하고 `--force`를 쓰면 원시 `EISDIR` 오류가 노출됐다. 저장 대상이 일반 파일인지 확인해 `output_not_file`로 거부하도록 수정했다. 강제 여부 두 경우 모두 폴더와 내부 사용자 파일 보존을 검증하는 회귀 테스트를 추가했다. 수정한 실제 npm 설치본의 `--json` 오류 코드와 파일 보존도 확인했다.
+
+## 실행 중 확인한 환경 문제와 한계
+
+- 현재 Codex CLI 설정의 `gpt-6.1-sol`은 이 ChatGPT 계정으로 거부됐다. 계정 모델 목록의 `gpt-6-astra`를 명시한 뒤 실제 실행이 완료됐다. 사용자 전역 설정은 변경하지 않았다.
+- 첫 Claude 검사에서는 모델이 허용된 Python 명령에 추가 명령을 붙여 실행 권한이 거부됐다. 허용 범위를 넓히지 않고 단일 Python 명령으로 다시 실행했으며 최종 실행은 권한 거부 없이 완료됐다.
+- 4개 stack은 설치·리소스·명령 매핑을 검증했다. 각 framework의 실제 프로젝트 생성·빌드·브라우저/E2E 동작은 이번 결과에 포함되지 않는다.
+- 최소 지원 버전 Node 20/Python 3.9는 설치되어 있지 않아 해당 버전 실행은 검증하지 않았다.
+- 운영 앱 UI·인증·업무 수용, Sprintable 동기화·승인, 무인 반복 실행은 미검증 또는 미구현이다.
+
+[실행 요약](evidence/full-test-20261003/summary.json), [coverage](evidence/full-test-20261003/coverage.log), [실제 Codex packet](evidence/full-test-20261003/codex-review-packet.json), [Claude 의미 검토](evidence/full-test-20261003/claude-review-retry.md), [Claude 구조 검사](evidence/full-test-20261003/claude-lint.md)를 보관했다. 기록의 명령·임시 경로는 당시 실행값 그대로 남겼다.
+
+보관된 서비스 예제도 재실행할 수 있다:
+
+```bash
+node --test docs/modernization/evidence/full-test-20261003/tests/expense.test.mjs
+```

package/docs/modernization/LEGACY-REMOVAL-PLAN.md

@@ -0,0 +1,9 @@
+# Legacy removal — 2026-10-03
+
+The user no longer needs the old AIWF framework. Keep the six AIUP methodology/stack/workflow plugins, the dependency-free spec CLI and installer, their tests, the worked example, modernization decisions/evidence, licenses and changelog.
+
+1. Add a regression for the supported plugin/bin inventory and absence of legacy package entry points; observe failure before deletion.
+2. Remove tracked legacy source, multilingual command collections, duplicate skills/rules, old plugins, installer/sprint/persona tests, obsolete docs and Jest configuration. Remove the old root plugin manifest; the root remains a marketplace. Delete only reviewed tracked repository files; leave local runtime/user data and Git history untouched.
+3. Reduce npm metadata to the spec CLI/library and six plugins, remove unused dependencies, regenerate the lockfile and make npm test run the surviving regression suite. Update current project guidance; retain historical changelog and validation evidence as history.
+4. Run Node regressions, provenance validation, original Python self-tests, strict example lint and static checks. Inspect the real npm tarball, install it in a clean temporary project, and run its CLI and skill installer without old dependencies.
+5. Review the diff and current links; commit and push after verification.

package/docs/modernization/PILOT-RESULT-2026-10-03.ko.md

@@ -0,0 +1,85 @@
+# UC-001 로컬 파일럿 실행 결과
+
+실행: 2026-10-03. 상태: **로컬 검증 완료, 실제 제품 적용·휴먼 리뷰 대기**. [실행 전 계획](PILOT-UC-001.ko.md), [검토 당시 계획](CLI-PRODUCTIVITY-REVIEWED-2026-10-03.ko.md), [Claude 두 세션의 리뷰](CLAUDE-PLAN-REVIEW-2026-10-03.ko.md)를 구분해 읽는다. 이번 수정본에 대한 Claude 재검토는 실행하지 않았다.
+
+## 결과와 이번 변경
+
+기존 지출 제출 예제를 별도 임시 프로젝트에서 실행했다. 엔터티의 사용 내용 길이 200을 `UC-001 BR-002/A3`, `TC-002`, [구현 계획의 검사 연결표](evidence/local-pilot-20261003/project/docs/plans/UC-001.md)에 명시하고 서비스 구현·테스트를 연결했다. Unicode code point 수와 생략·null·타입 정책은 이 예제의 결정이며 실제 업무 정책 승인이 아니다.
+
+기준 서비스 테스트 12개는 모두 통과했다. 새 요구사항을 검증하는 11개 테스트를 추가하자 **23개 중 7개가 실제로 실패**했다. 길이 초과·숫자/배열/객체 입력·null 처리·길이 수정 흐름의 누락을 검출했다. 저장 전에 타입·길이·선택 입력을 검증하도록 구현을 고친 후 **23개 모두 통과**했다. 보관한 최종 파일에서도 새 프로세스로 같은 23개를 다시 실행해 통과했다.
+
+명세 변경 시 `check`는 TC 추가 1개와 기존 문서 변경 3개를 drift로 보고했고 exit 1을 반환했다. 갱신 전 `packet`도 `packet_requires_sync`로 거부했으며 출력 파일이 만들어지지 않았다. 명세를 명시적으로 다시 pin한 뒤 실패·최종 packet을 따로 생성했다.
+
+AIWF의 실행 CLI·upstream 원문·스킬은 수정하지 않았다. 서비스 변경은 [보관 예제](evidence/local-pilot-20261003/README.ko.md)의 재현 자료다. `verify`, runner, packet v2, 문서 보고서와 CI는 미구현 후보로 유지한다.
+
+## 실행 근거
+
+| 단계 | 실제 결과 | 기록 |
+| --- | --- | --- |
+| 기준 구조·서비스 | lint findings 0, tests 12/12, exit 0 | [구조](evidence/local-pilot-20261003/project/artifacts/baseline-structure.stdout.txt), [테스트](evidence/local-pilot-20261003/project/artifacts/baseline-service.stdout.txt) |
+| 기준 pin·packet | pin과 digest 일치, passed 2 / not_run 2 | [기준 packet](evidence/local-pilot-20261003/project/artifacts/baseline-packet.json) |
+| 명세 변경 | TC 1개 추가, 문서 3개 변경, check exit 1 | [drift JSON](evidence/local-pilot-20261003/project/artifacts/changed-check.stdout.txt) |
+| drift 상태 packet | exit 1, packet_requires_sync, 출력 없음 | [거부 JSON](evidence/local-pilot-20261003/project/artifacts/changed-packet-refused.stdout.txt) |
+| 명세 재고정 후 구현 수정 전 | lint findings 0, tests 16 passed / 7 failed, test exit 1 | [실패 테스트](evidence/local-pilot-20261003/project/artifacts/red-service.stdout.txt) |
+| 실패 packet | 생성 exit 0, passed 1 / failed 1 / not_run 2 | [실패 packet](evidence/local-pilot-20261003/project/artifacts/red-packet.json), [readback](evidence/local-pilot-20261003/project/artifacts/red-readback.json) |
+| 구현 수정 후 | lint findings 0, tests 23/23, check in_sync, exit 0 | [최종 테스트](evidence/local-pilot-20261003/project/artifacts/final-service.stdout.txt), [check](evidence/local-pilot-20261003/project/artifacts/final-check.stdout.txt) |
+| 최종 packet | passed 2 / not_run 2, digest·로그 bytes 일치 | [최종 packet](evidence/local-pilot-20261003/project/artifacts/final-packet.json), [readback](evidence/local-pilot-20261003/project/artifacts/final-readback.json) |
+| 보관본 재실행 | lint findings 0, tests 23/23, exit 0 | [구조](evidence/local-pilot-20261003/project/artifacts/archive-structure.stdout.txt), [테스트](evidence/local-pilot-20261003/project/artifacts/archive-service.stdout.txt) |
+
+구조 검사는 모두 저장소 core의 `spec_lint.py --docs docs --strict --no-baseline --format json`으로 실행했다. UC 검사기는 core의 sibling에서 로드했고 누락 INFO도 없었다. 이번 명세에는 BPMN이 없어 BPMN 파싱 실행을 검증한 결과는 아니다. 구조 검사 통과는 한국어 의미·업무 수용과 별개다.
+
+서비스 검사 명령은 `node --test tests/expense.test.mjs`다. [실행 기록](evidence/local-pilot-20261003/execution.json)에 각 argv·cwd·UTC 시각·exit code·stdout/stderr bytes와 SHA256, 실행 전후 docs/src/tests hash를 보관했다. 각 명령 전후 관찰한 입력 hash는 동일했다. 그 사이의 일시적 변경까지 배제하는 격리 증명은 아니다.
+
+## 버전과 근거의 한계
+
+| 항목 | 확인 값 |
+| --- | --- |
+| checkout 기준 HEAD | `fcf5ebc24bcd5e49148290a65ac6e1a5c4b22ba6`; 문서 변경은 미커밋 상태 |
+| 실행 환경 | Node `v22.23.1`, Python `3.14.8` |
+| 기준 명세 digest | `53e0bd97d338aa9ca96472e09ff9f2ee54b33e0e6a39a9e23bf63c1bb4272bef` |
+| 변경·최종 명세 digest | `a2616b3224768a0a7972bd75ba19632d2e9b84afc5c175ae21c71281dc5017a2` |
+| 최종 서비스 SHA256 | `8f434f4614809a9ec3c478235232bc0a14b586fab6e7a6c4467e91d7040c0669` |
+| 최종 테스트 SHA256 | `90b7203d0933c09b63d3d2ba1e302bb45eef8932f2d54837d27194e82a9ad439` |
+
+임시 프로젝트는 Git 저장소가 아니므로 packet의 `git`은 null이다. 기준 HEAD는 사용한 AIWF checkout의 문맥이며 서비스 코드의 Git 버전으로 취급하지 않는다. [범위 기록](evidence/local-pilot-20261003/scope.json)은 보관 시점의 도구 hash와 최종 입력 hash를 추가로 남긴다.
+
+현재 CLI는 코드·테스트 hash나 실행 시점·exit code를 자동 확인하지 않는다. 이번 실행 기록은 에이전트가 별도로 수집한 자료이며 새로운 evidence schema나 CLI 기능이 아니다. packet의 `command`는 설명 필드이고 CLI는 그 명령을 실행하지 않았다. 갱신된 pin에서 옛 로그를 넣는 일을 현재 CLI가 막는다고 주장하지 않는다.
+
+모든 packet은 `awaiting_review`, acceptance `not_recorded`, evidence trust `reported_untrusted`다. 실패 packet 생성의 exit 0은 **실패를 포함한 파일 저장 성공**이다. 최종 packet에서도 로그인·UI·실제 사람 검토는 `not_run`/미검증으로 남아 있다. readback은 작성자의 기계적 확인이며 독립 의미 검토나 사람 승인이 아니다.
+
+## 생산성 판단과 다음 범위
+
+버전 조회를 포함한 파일럿 명령 18개와 보관본 검사 2개의 프로세스 wall time 합계는 약 **0.879초**다. 이는 이 컴퓨터의 작은 예제에서 명령 실행에 쓴 시간이며 문서 작성·검토·코딩·사람의 활성 시간이 아니다. 사람 시간은 `not_measured`이고 절감률은 계산하지 않는다.
+
+명령 선택, 로그 저장, 상태 전사, 근거 묶기, 입력·로그 hash 확인이 반복되는 지점은 관찰했다. 그러나 하나의 UC를 변경·재실행한 결과이므로 독립 UC 2개 이상의 비용 측정 기준을 충족하지 않는다. 새 runner나 packet v2의 도입 근거로 확대하지 않는다.
+
+다음 적용 범위는 사용자가 지정한 실제 소비 프로젝트·UC다. 우선 동일한 연결표와 실제 사람의 packet 검토 기록을 사용한다. 검사 경로·누락 확인이 문제면 후보 A인 읽기 전용 `verify`를, 전사·수집 비용이 확인되면 후보 B의 최소 runner를 검토한다. 이번 결과만으로 구현을 시작할 범위를 늘리지 않는다.
+
+## 사람이 검토할 항목
+
+| 항목 | 현재 상태 |
+| --- | --- |
+| 실제 소비 프로젝트 / UC | 미지정; 로컬 예제만 실행 |
+| 검토자 / 검토 시각 | 미기록 |
+| 읽은 packet / spec digest / 코드·테스트 hash | 실제 검토자가 기록해야 함 |
+| BR-002의 글자 수·null·타입 정책과 업무 의미 | 로컬 예제 결정, 휴먼 리뷰 대기 |
+| 범위 판단 / 자료 재요청 / 수정 요청 | 미기록 |
+| 리뷰 준비·읽기·수정의 사람 활성 시간 | not_measured |
+
+기존 70개 한글 검토 문서의 실제 휴먼 리뷰 상태도 바꾸지 않았다. plugin README의 원문·한글본과 관리 목록을 함께 갱신했다. 저장소 유지보수 검사의 최신 결과는 아래에 별도로 기록하며 과거 검증을 이번 성공으로 전사하지 않는다.
+
+미검증 범위는 로그인·권한·submitter_id, UI와 오류·접수 표시, 실제 DB·동시성·지속성·Decimal 정밀도, 업무 수용·제품 효과, 지원 하한 Node 20/Python 3.9, stack 앱, Sprintable·원격 승인·무인 실행이다.
+
+## 이번 변경 후 저장소 검증
+
+| 검사 | 최신 결과 | 실행 기록 |
+| --- | --- | --- |
+| `npm test` | 85 passed / 0 failed; pretest의 한글 문서 검사 통과 | [기록](evidence/local-pilot-20261003/maintenance/node.json) |
+| `npm run check:deps` | Node 소스 6개의 의존성·로컬 import 통과 | [기록](evidence/local-pilot-20261003/maintenance/dependencies.json) |
+| `npm run validate:spec-plugin` | upstream 31개 스킬·71개 resource의 보관 hash, 참조·manifest 통과 | [기록](evidence/local-pilot-20261003/maintenance/provenance.json) |
+| `npm run test:spec-upstream` | Python self-test 3개 통과 | [기록](evidence/local-pilot-20261003/maintenance/upstream.json) |
+| `npm run validate:spec-example` | 기존 예제 0 errors / 0 warnings / 0 infos | [기록](evidence/local-pilot-20261003/maintenance/example.json) |
+| `npm run docs:check` / `docs:check:local` | 70개 문서의 원문·번역·참조 및 로컬 snapshot 정합성 통과, 휴먼 리뷰 기록 0 | [문서](evidence/local-pilot-20261003/maintenance/docs.json), [로컬](evidence/local-pilot-20261003/maintenance/local-docs.json) |
+| 보관 README의 pin·packet 재현 안내 | 새 임시 프로젝트에서 새 로그로 실행, exit 0 | [명령·출력 기록](evidence/local-pilot-20261003/maintenance/readme-replay.json) |
+
+이 검증은 원래 파일럿 20개 명령의 시간 합계와 별개다. Node 회귀 suite의 선택적 외부 upstream reference checkout은 없어서 새 byte 대조를 수행하지 않았다. 저장소에 기록된 upstream hash 대조는 통과했다. 별도 build/typecheck/lint 명령은 이 저장소에 없으며 구조 검사·의존성 검사·회귀 검증의 범위를 보존한다.

package/docs/modernization/PILOT-UC-001.ko.md

@@ -0,0 +1,79 @@
+# UC-001 파일럿 계획과 종료 기준
+
+작성: 2026-10-03. 상태: **로컬 예제 실행 완료, 실제 제품 적용·휴먼 리뷰 대기**. [Claude 두 세션의 지적](CLAUDE-PLAN-REVIEW-2026-10-03.ko.md)을 반영한다. 실행 전 정한 범위와 기준을 아래에 유지하고 실제 결과는 [별도 기록](PILOT-RESULT-2026-10-03.ko.md)으로 연결한다.
+
+## 이번에 실행할 범위
+
+소비 프로젝트가 아직 지정되지 않아 기존 지출 제출 예제를 별도 임시 프로젝트로 구성한다. `UC-001`의 서비스 부분과 현재 CLI의 명세 고정·변경 감지·검증 packet 흐름을 실행한다. 이것은 실제 회사 제품의 도입 파일럿이나 새 프로젝트 개발 시간 비교가 아니라 **로컬 예제의 실행·변경 검증**이다. 실제 소비 프로젝트 경로와 UC는 사용자에게 별도로 요청했다.
+
+기준 자료는 [명세 예제](../../examples/spec-workflow/README.md)와 [이전 서비스 구현·테스트](evidence/full-test-20261003/)다. 과거 실행 결과를 복사해 이번 성공으로 표시하지 않고, 현재 도구로 다시 실행한다. historical 파일은 수정하지 않는다.
+
+이번 변경은 엔터티 모델에 이미 적힌 `description` 길이 200을 UC·테스트·구현에 명시적으로 연결하는 것이다. 예제 파일럿의 “자”는 Unicode code point로 정의한다. 빈 문자열·생략·null은 빈 사용 내용으로 취급하고, 그 밖의 입력은 문자열이어야 한다. 실제 제품의 글자 수·null·공백 정책 결정으로 확대하지 않는다.
+
+## 실행 순서
+
+1. 기준 예제의 명세와 기존 서비스·12개 테스트를 임시 프로젝트에 복사한다. 구현 계획과 UC/BR/TC→검사·미검증 표를 `docs/plans/UC-001.md`에 먼저 작성한다.
+2. 현재 Python 구조 검사와 서비스 테스트를 실행하고 실제 로그·exit code를 남긴다. 명세를 pin한 뒤 기준 packet을 생성·읽어 확인한다.
+3. 임시 프로젝트의 명세에 `BR-002` 사용 내용 조건과 A3 길이 오류, 대응 TC 검증을 추가한다. pin 갱신 전에 `check`와 `packet`이 drift를 보고·거부하는지 확인한다.
+4. 구조·의미를 별도로 확인한 뒤 pin을 명시적으로 갱신한다. 새 요구사항을 검증하는 테스트를 추가하고 **구현 수정 전의 실제 실패**를 기록한다. 실패 packet도 남긴다.
+5. 임시 프로젝트의 서비스 구현을 수정해 길이·타입·선택 입력을 검증한다. 동일 명세와 새 테스트를 다시 실행하고 새 로그로 최종 packet을 만든다.
+6. 정상·대안·실패 흐름과 미검증 범위를 로그·테스트 이름·명세 ID로 확인한다. 실제 사람 검토를 위한 한국어 기록 양식을 남긴다.
+
+## 명세·검사 정의의 위치와 책임
+
+이번 파일럿의 구현 계획·명세와 검사 연결표는 `docs/plans/UC-001.md`에 둔다. 이 경로의 Markdown은 현재 CLI의 pin 대상이다. 명령을 자동 실행하는 설정 파일이 아니며, 현재 에이전트가 요청된 범위의 프로젝트 도구를 사용해 실행한다.
+
+| 정의 | 책임·버전 확인 |
+| --- | --- |
+| UC·소속 BR·TC·검사 연결, 실제 명령, 입력 파일, 미검증 이유 | 소비 프로젝트의 `docs/plans/UC-001.md`; 명세 pin에 전체 파일 포함 |
+| 실행 당시 코드·테스트 hash, 명령 argv·cwd, 시각·exit code·로그 hash | 이번 실행 기록에 보관; 현재 CLI가 자동 확인한다고 주장하지 않음 |
+| 이후 CLI 실행 계약을 확장할 경우 | AIWF의 `aiwf-spec`/CLI 소유. upstream core의 형식·원문은 수정하지 않음 |
+
+향후 runner의 최초 후보는 이 계획 안의 명시적인 검사 ID·argv·입력 파일 목록을 사용하는 방식이다. 파서/schema는 아직 채택하지 않는다. runner 착수 시에는 선택한 계획의 bytes와 pin 일치, 선택한 검사 ID·실제 argv, 실행 전후 입력 hash를 연결해야 한다. 계획·매핑·명령이 바뀌면 기존 결과를 최신 검증으로 재사용하지 않는다. 이미 부여된 실행 권한을 별도 `--yes`로 다시 요구하는 절차는 기본 계약으로 넣지 않는다.
+
+## 검증과 완료 조건
+
+| 항목 | 이번 로컬 실행의 완료 조건 |
+| --- | --- |
+| 기준선 | 구조 검사와 기존 서비스 12개 테스트의 실제 실행 기록, 기준 pin·packet readback |
+| 명세 변경 | 구조 검사 통과, pin 전 drift 탐지, drift 상태 packet 생성 거부 |
+| 요구사항 대비 구현 | 길이 초과를 구현 수정 전 테스트가 실패로 검출, 수정 후 동일 검사 통과 |
+| 실패 보존 | 실패 검사·미실행 검사를 포함한 packet 생성·readback; packet 생성 성공을 테스트 성공으로 표시하지 않음 |
+| 최종 결과 | 새 로그로 최종 packet 생성, `awaiting_review`·acceptance `not_recorded`, pin/spec digest 일치 |
+| 재현성 | 최종 docs/src/tests, 실행 명령·exit code·입력·로그 hash 보관; 새 프로세스에서 서비스 검사 재실행 |
+| 문서 | 원문·한글 README·관련 기록 갱신과 `npm run docs:check` 통과 |
+
+위 항목은 에이전트의 로컬 검증 완료 기준이다. 실제 소비 프로젝트의 파일럿 완료에는 사용자 지정 프로젝트·UC와 실제 검토자의 결과가 추가로 필요하다. 예제 실행만으로 그 단계를 완료했다고 기록하지 않는다.
+
+오류가 있는 자료를 성공으로 묶으면 해당 단계를 수정·재검증한다. 알려지지 않은 도구·입력·의미 판단은 미검증으로 남긴다. 환경 접근이나 정책상 실행 불가가 발생하면 성공 기록 없이 원인을 보관한다. 반복 루프나 자동 retry를 새 기능으로 추가하지 않는다.
+
+## 측정과 확장 판단
+
+이번에는 각 명령의 실제 시작·종료 시각과 프로세스 wall time, 실제 로그, 실패·미실행·전사 항목을 기록한다. 에이전트의 편집·검토 시간이 사람의 활성 작업 시간이나 개발 생산성을 뜻하지 않으므로, 사람이 측정하지 않은 값은 `not_measured`로 둔다. 같은 UC를 연습·재실행한 시간은 독립적인 두 UC의 비교 자료로 쓰지 않는다.
+
+실제 제품 적용을 위한 탐색 기준은 **비교 가능한 독립 UC 2개 이상에서 같은 준비·전사 작업이 반복되고, 측정한 사람의 활성 시간이 합계 10분 이상**일 때 해당 자동화의 최소 범위를 검토하는 것이다. 10분은 이번 계획의 제안 기준이며 입증된 손익이나 일반 기준이 아니다. 사용자와 실제 기록에 맞춰 조정할 수 있다. 결정적 검사 누락·오래된 로그 오인은 시간과 별개로 정확성 문제로 우선 처리한다.
+
+기준을 충족해도 자동으로 기능을 추가하지 않는다. 실행·기록·유지비용과 범위를 비교한다. 자동화 없이 자료 준비가 충분하면 **새 기능 없이 파일럿을 종료**한다. 이번 예제 한 번의 결과로 runner·packet v2·문서 보고서·병렬 실행 도입을 결정하지 않는다.
+
+## 실제 사람의 검토 기록
+
+사용자의 “진행”은 작업 실행 지시다. 아래 항목의 의미 검토·업무 수용을 대신하는 기록으로 사용하지 않는다.
+
+| 항목 | 기록할 값 |
+| --- | --- |
+| 검토자 / 검토 시각 | 아직 미기록 |
+| 읽은 packet / 명세 digest / 코드·테스트 hash | 실제 검토 시 기록 |
+| 범위에 대한 판단 | 수용 / 수정 요청 / 판단 보류와 이유 |
+| 자료 부족으로 재요청한 항목·횟수 | 실제 검토 시 기록 |
+| 기능·명세 의미 때문에 수정한 항목 | 자료 준비 문제와 구분 |
+| 리뷰 준비·읽기·수정에 쓴 활성 시간 | 사람이 측정한 값만 기록 |
+
+## 남는 미검증 범위
+
+- 로그인·제출자 계정·실제 권한·submitter_id 관계.
+- UI 입력·오류 메시지·접수 화면·브라우저 TC 전체 흐름.
+- 실제 DB·프로세스 간 지속성·동시성·금액 Decimal 정밀도.
+- 실제 업무 규정·고객 요구·제품 도입 효과·휴먼 수용.
+- 지원 하한 Node 20/Python 3.9, stack별 앱, Sprintable·원격 승인·무인 실행.
+
+실행 결과는 별도 기록으로 연결하고, AI 리뷰나 자동 검사만으로 이 목록을 지우지 않는다.

package/docs/modernization/PLAN.md

@@ -0,0 +1,28 @@
+# AIWF modernization — 2026-10-02
+
+Historical plan. Legacy-retention decisions are superseded by [LEGACY-REMOVAL-PLAN.md](LEGACY-REMOVAL-PLAN.md) on 2026-10-03.
+
+## Target result
+
+Move AIWF from Claude-specific task bookkeeping toward durable, use-case-driven specifications consumed by existing coding agents. Reuse the AI Unified Process core rather than rebuilding its methodology. Keep specifications in Git and prepare reviewable evidence for future Sprintable integration.
+
+## First implementation boundary
+
+1. Add an isolated `aiwf-spec` plugin from upstream core skills and validators, pinned to an exact commit; retain Apache-2.0 LICENSE, NOTICE and change notices.
+2. Add a dependency-free local CLI for preserving project initialization, spec snapshots, change detection, and evidence packets. It records reported checks and cannot grant approval or assert business acceptance.
+3. Add portable skill installation, a complete worked example, provenance checks, and end-to-end validation.
+4. Document verified Sprintable contracts and a proposed adapter. Do not write to production or imply synchronization exists.
+
+Legacy commands stay available during the first slice. Their later removal is a separate migration after a pilot establishes the new path. No new dependencies. No model SDK, scheduler, chat interface or backend rewrite in this slice.
+
+## Behavior and verification
+
+Before changing legacy behavior, establish targeted regression coverage. This slice adds independent entry points; tests cover preservation, malformed inputs, draft/missing specs, pin drift, failed/unexecuted checks, file boundaries and actual CLI execution. Run upstream validator self-tests and validate a real example end to end. Inspect packaged files so the plugin, scripts and notices ship. Report legacy-suite/environment gaps separately.
+
+## Stop condition
+
+A fresh local project can initialize without losing files; an example can pass structural lint, pin specs, detect changed specs, and generate a packet with inspectable logs. The direction, provenance, migration boundary and remaining Sprintable work are written down. This is a verified local foundation, not a completed automation platform.
+
+## Original-preserving skill update
+
+The user requests skills as unchanged as possible. First add regressions for exact upstream core hashes and opt-in stack installation. Restore all seven core SKILL.md files from the verified latest upstream commit, and import the four stack skill bundles and their supporting resources without editing upstream bytes. Keep host portability and AIWF evidence guidance in the separate workflow skill. Apply name/reference mappings only to installed copies. Validate every imported resource hash, all manifests, core/stack installation, upstream self-tests, the worked example and packaged contents. Keep existing installed user skills protected from overwrites.

package/docs/modernization/SKILLS.ko.md

@@ -0,0 +1,105 @@
+# AIWF 스킬 인벤토리
+
+작성: 2026-10-02, 2026-10-03 core 분리, 2026-10-04 문서 동기화 스킬 반영. 기준 upstream: AIUP marketplace `065dadda0f696c29ff2bacbda31b38152082e6fa`.
+
+## 요약
+
+- upstream 스킬 31개 + AIWF 자체 `workflow`, `sync-docs` 2개 + 선택 위임 스킬 2개 = 총 35개 제공.
+- 방법론 core는 `plugins/aiwf-core`(`aiup-core` v2.19.0 스킬 7개).
+- AIWF 래퍼는 `plugins/aiwf-spec`(`workflow`, `sync-docs` 2개, 0.2.0).
+- 선택 위임 애드온은 `plugins/aiwf-delegate-claude`와 `plugins/aiwf-delegate-codex`에 각각 스킬 1개를 둔다. 기본 설치에는 포함되지 않는다.
+- stack 4개 플러그인: 24개 (vaadin-jooq 8, angular-jpa 6, blazor-dotnet 5, nestjs-nextjs 5).
+- 원본(vendored)은 upstream 바이트 그대로 두고 이름·명령 참조 변환은 설치본에만 적용한다.
+
+## Core: plugins/aiwf-core
+
+원본은 `aiup-core` v2.19.0(Simon Martinelli)이다. 7개 SKILL.md는 upstream 바이트와 동일하고 참조 문서와 Python 검사기도 수정하지 않았다. 유일한 upstream 소스 수정은 `NOTICE`에 AIWF 출처를 덧붙인 것이다. host 중립 작업 추적·증거 경계 지침은 여기가 아니라 `aiwf-spec`의 `workflow`에 있다. AIWF가 추가한 파일은 `README.md`, `UPSTREAM.json`, `.claude-plugin/plugin.json`뿐이다.
+
+이전에는 이 7개를 `aiwf-spec`에 넣어 방법론 core와 AIWF 래퍼가 한 플러그인에 섞였는데, 2026-10-03에 원본 바이트 그대로 `aiwf-core`로 옮겨 분리했다.
+
+| 설치 이름 (Codex) | 원본 스킬 |
+|---|---|
+| `aiwf-requirements` | `requirements` |
+| `aiwf-use-case-diagram` | `use-case-diagram` |
+| `aiwf-use-case-spec` | `use-case-spec` |
+| `aiwf-entity-model` | `entity-model` |
+| `aiwf-test-case` | `test-case` |
+| `aiwf-spec-review` | `spec-review` |
+| `aiwf-reverse-engineer` | `reverse-engineer` |
+
+구조 검사기는 `skills/spec-review/scripts/spec_lint.py`, 유스케이스·테스트 검사기는 `skills/use-case-spec/scripts/validate_use_case.py`와 `skills/test-case/scripts/bpmn_paths.py`에 있다.
+
+## Wrapper: plugins/aiwf-spec
+
+AIWF가 추가한 `workflow`와 `sync-docs`를 담는다. upstream 스킬이 없으므로 자체 `UPSTREAM.json`도 없고 core의 [UPSTREAM.json](../../plugins/aiwf-core/UPSTREAM.json)을 가리킨다. `LICENSE`/`NOTICE`(Apache-2.0)만 함께 유지한다.
+
+| 설치 이름 (Codex) | 원본 스킬 | 구분 |
+|---|---|---|
+| `aiwf-workflow` | (AIWF) | 자체 |
+| `aiwf-sync-docs` | (AIWF) | 개발 후 영향 문서 동기화 |
+
+## Optional delegates: plugins/aiwf-delegate-<target>
+
+Claude와 Codex용 위임 스킬은 서로 독립된 선택 애드온이다. vendored upstream이 아니며 각각 자체 플러그인 안에 `delegate-claude` 또는 `delegate-codex` 스킬 하나를 둔다. Codex 설치 스크립트는 `--delegate claude` 또는 `--delegate codex`를 선택한 경우에만 `aiwf-delegate-<target>` 이름으로 복사한다. skills.sh 설치는 원래 `delegate-<target>` 이름을 사용한다. Claude Code marketplace 항목은 `/aiwf-delegate-claude:delegate-claude` 및 `/aiwf-delegate-codex:delegate-codex`로 호출한다.
+
+두 스킬 모두 직접 호출만 허용한다. 교차 CLI는 현재 요청에 명시된 `--cross-cli` 토큰이 있을 때만 실행한다. 기본은 읽기 전용이며, 현재 요청에 쓰기 요청과 명시 범위가 함께 있어야 한다. 실제 변경은 대상 CLI의 자체 권한 정책이 허용해야 한다.
+
+## Stacks: plugins/aiwf-<stack>
+
+각 플러그인은 upstream 플러그인을 바이트 단위로 그대로 복사한 것이다. `skills/`, `rules/`, `agents/`, `LICENSE`, `NOTICE`는 수정하지 않았고 AIWF가 추가한 파일은 `README.md`, `UPSTREAM.json`, `.claude-plugin/plugin.json`뿐이다. 파일 hash는 각 플러그인의 UPSTREAM.json에 기록한다.
+
+| 플러그인 | upstream | 버전 | 작성자 | 스킬 수 | 스킬 |
+|---|---|---|---|---|---|
+| `plugins/aiwf-vaadin-jooq` | `aiup-vaadin-jooq` | 2.20.0 | Simon Martinelli | 8 | `implement`, `implement-hilla`, `flyway-migration`, `coverage-check`, `karibu-test`, `browserless-test`, `hilla-test`, `playwright-test` |
+| `plugins/aiwf-angular-jpa` | `aiup-angular-jpa` | 0.7.0 | Marc Affolter | 6 | `implement`, `flyway-migration`, `coverage-check`, `spring-boot-test`, `vitest-test`, `playwright-test` |
+| `plugins/aiwf-blazor-dotnet` | `aiup-blazor-dotnet` | 0.7.0 | Carl J. Mosca | 5 | `implement`, `ef-migration`, `bunit-test`, `dotnet-test`, `playwright-test` |
+| `plugins/aiwf-nestjs-nextjs` | `aiup-nestjs-nextjs` | 0.4.0 | Swift Ugandan | 5 | `implement`, `drizzle-migration`, `nest-test`, `react-test`, `playwright-test` |
+
+`vaadin-jooq`와 `angular-jpa`는 `agents/uc-coverage.md`를 함께 가져온다. `blazor-dotnet`과 `nestjs-nextjs`는 호스트 에이전트를 포함하지 않는다. `rules/mcp-servers.md`는 모든 stack에 포함되며 문서 참고용이다.
+
+## 원본과 설치본 정책
+
+| 구분 | 위치 | 내용 |
+|---|---|---|
+| 원본(vendored) | `plugins/aiwf-core/`, `plugins/aiwf-spec/`, `plugins/aiwf-<stack>/` | upstream 바이트 그대로. 이름·참조를 바꾸지 않는다. |
+| 설치본 | 대상 프로젝트 `.agents/skills/` | 복사 후 설치 이름으로 변환. core/spec `aiwf-*`, stack `aiwf-<stack>-*`. |
+
+설치 시 SKILL.md `name`과 Markdown 본문의 `/skill`, `skill` 참조를 설치 이름으로 바꾸고 파일 끝에 AIWF 설치 수정 주석을 붙인다. vendored 원본은 변환하지 않는다. 이름 변환은 설치된 Markdown에만 적용되며, Java/TSX 같은 비-Markdown 참조 파일의 주석에 남은 upstream 명령 이름은 그대로 둔다. 복사본은 파일일 뿐이며 네이티브 Codex 서브에이전트를 등록하지 않는다. `agents/uc-coverage.md` 같은 에이전트 프롬프트는 리소스로 설치되고 실행에는 호스트 매핑이 필요하며, 그 매핑은 `workflow` 스킬이 설명한다. 선택 위임 스킬도 하위 에이전트 런타임을 설치하지 않는다.
+
+## 설치
+
+Claude Code는 marketplace 항목을 쓴다. core는 `aiwf-core`(필수), 래퍼는 `aiwf-spec`(선택), stack은 `aiwf-<stack>`를 opt-in으로 설치한다. 스킬은 `/aiwf-core:use-case-spec`, `/aiwf-spec:workflow`, `/aiwf-nestjs-nextjs:implement`처럼 플러그인 이름으로 한정해 호출한다.
+
+```text
+/plugin marketplace add moonklabs/aiwf
+/plugin install aiwf-core@aiwf-plugins
+/plugin install aiwf-spec@aiwf-plugins
+/plugin install aiwf-nestjs-nextjs@aiwf-plugins
+```
+
+Codex는 checkout에서 `scripts/install-spec-skills.mjs`로 설치한다. 기본으로 `aiwf-core` 7개와 `aiwf-spec`의 `workflow`, `sync-docs` 2개를 설치하고, `--stack`은 네 값 중 하나이며 그 stack을 추가한다.
+
+```bash
+# 미리보기: 쓰기 없음
+node scripts/install-spec-skills.mjs --project /path/to/project --dry-run
+node scripts/install-spec-skills.mjs --project /path/to/project --stack nestjs-nextjs --dry-run
+
+# 실제 설치
+node scripts/install-spec-skills.mjs --project /path/to/project
+node scripts/install-spec-skills.mjs --project /path/to/project --stack nestjs-nextjs
+```
+
+위 두 실제 설치 줄은 대안 관계이며 순서대로 실행하는 것이 아니다. 기본 설치가 core+workflow+sync-docs 스킬을 이미 만들면, 뒤이은 `--stack` 설치는 overwrite 없음 원칙 때문에 거부된다. 이미 존재하는 대상 스킬이 있으면 설치를 거부하고 아무것도 덮어쓰지 않는다. `--force` 같은 강제 플래그는 없다. 기존 설치를 갱신하려면 별도로 검토한 마이그레이션이 필요하다. 설치기는 MCP 서버를 자동 구성하지 않으며 새 의존성도 추가하지 않는다.
+
+## 최신 pin 갱신 절차
+
+저장소에 upstream을 자동으로 따라가는 `sync` 명령은 없다. 다음을 수동으로 한다.
+
+1. upstream을 fetch하고 대상 커밋을 검토한다. 예: `git ls-remote https://github.com/AI-Unified-Process/marketplace HEAD`.
+2. 대상 플러그인(core `plugins/aiwf-core`, stack `plugins/aiwf-<stack>`)의 `skills/`, `rules/`, `agents/`, `LICENSE`, `NOTICE`를 가져온다. vendored 파일은 upstream 바이트 그대로 둔다. `aiwf-spec`는 자체 upstream이 없다.
+3. 각 플러그인의 `UPSTREAM.json`에서 `commit`, `upstream_version`, `upstream_sha256`을 갱신한다. core `NOTICE`처럼 불가피한 수정은 `modifications`/`modified_sha256`에 기록한다.
+4. upstream 버전이나 스킬 집합이 바뀌면 테스트와 validator에 하드코딩된 버전/스킬 개수 상수도 함께 갱신한다.
+5. 검증: `node --test tests/spec-workflow/stack-provenance.test.mjs`, `npm run validate:spec-plugin`, `npm run test:spec`, `npm run test:spec-upstream`.
+6. 패키징: `npm pack --dry-run`으로 포함 파일을 확인한다.
+
+바이트 대조는 선택적 참조 checkout(`AIWF_AIUP_REFERENCE`)이 있을 때 추가로 수행한다. 출처 hash와 설치 이름 변환은 각각 `stack-provenance.test.mjs`와 `install-skills.test.mjs`가 검사한다.

package/docs/modernization/SPRINTABLE.ko.md

@@ -0,0 +1,47 @@
+# Sprintable 연동 계약 초안
+
+2026-10-02, Sprintable 로컬 코드 HEAD `3998f00a4`와 이 세션의 MCP 도구 선언을 읽어서 작성했다. 배포 서버를 호출하거나 프로젝트 데이터를 수정하지 않았다. 아래는 연결 설계이며 현재 AIWF에는 업로드/동기화 구현이 없다.
+
+## 확인된 현재 기능
+
+| 기능 | 확인한 계약 | AIWF에서 사용할 방법 |
+|---|---|---|
+| 문서 | `sprintable_create_doc`: project_id, slug, title, content, content_format | packet을 사람이 읽을 Markdown Doc으로 등록 |
+| 문서 변경 | `sprintable_update_doc`: expected_updated_at | 최신 문서를 읽고 동시 수정 충돌 방지 |
+| 증거 | `sprintable_add_evidence`: work_item_id, work_item_type story/task, type report, ref, source, note, payload | 작업에 해당 Doc와 packet 버전 연결 |
+| 승인 상신 | `sprintable_submit_for_approval`: doc_id, gate_type doc_approval/concept_approval, work_item_id/type, approver_member_id | 실제 필요한 승인 요청 생성; 승인 결정을 대신하지 않음 |
+| 시각 자료 spec pin | ArtifactSpecPin: 노드 또는 좌표에 연결되는 주석 | 저장소 명세 pin과 별도 개념 |
+
+로컬 backend의 concept approval은 `doc.content` UTF-8의 SHA256을 봉인한다. AIWF 파일들의 byte SHA256과 같은 값이 아니다. Doc에 저장소 명세 digest를 포함하고, 승인 시점의 Doc 본문 hash와 함께 연결해야 한다.
+
+근거 경로: `backend/sprintable_mcp/tools/docs.py`, `tools/evidence.py`, `backend/app/models/doc.py`, `models/visual_artifact.py`, `services/doc.py`, `routers/evidence.py`, `services/evidence_service.py`. 이 경로들은 별도 Sprintable 저장소에 있으며, AIWF 구현을 의미하지 않는다.
+
+## 제안하는 최소 어댑터
+
+1. 사용자 설정으로 `project_id`, story/task ID, 저장소 원격 주소를 연결한다. 임의의 기본 프로젝트로 업로드하지 않는다.
+2. 현재 명세가 pin과 같은지 확인하고, 실제 Git commit/head 및 수정 여부를 수집한다. packet에는 개별 파일 digest, 검사 명령, 보고 결과, 로그, 미검증 사항을 포함한다.
+3. 안정적인 packet ID와 버전을 부여하고, 동일 전송 재시도에서 기존 문서를 먼저 읽는다. slug만으로 멱등성을 보장한다고 가정하지 않는다. 로컬 전송 기록에는 doc_id와 content hash를 보관한다.
+4. `create_doc`로 검토 문서를 등록하고 `get_doc`로 실제 저장된 본문을 확인한다.
+5. `add_evidence`에 `type: report`, Doc 참조와 메타데이터를 넣고 evidence_id를 보관한다. payload의 임의 `kind: review_packet`은 현재 backend 등록형에 없어서 거부될 수 있다. kind 없는 버전 명시 메타데이터 또는 별도 backend 스키마 확장이 필요하다.
+6. 필요한 경우 문서를 concept approval로 상신해 gate_id를 기록한다. 문서 작성자/구현자와 승인자, 업무 수용을 별도로 기록한다.
+7. 명세 digest 또는 리뷰 문서가 변경되면 기존 승인을 재사용하지 않는다. 재상신/무효화 동작은 실제 backend와 종단간 검증한 뒤 활성화한다.
+
+예상 메타데이터는 다음과 같다. 이것은 제안이며 기존 Sprintable 전용 검증 스키마가 아니다.
+
+```json
+{
+  "schema": "aiwf.review_packet.v1",
+  "doc": "entity:doc:<doc-id>",
+  "packet_id": "<stable-id>",
+  "repo": "<repository-url>",
+  "commit_sha": "<commit>",
+  "spec_digest": "<manifest-sha256>",
+  "specs": [
+    { "id": "UC-001", "path": "docs/use_cases/UC-001-submit-expense.md", "sha256": "<file-sha256>" }
+  ]
+}
+```
+
+## 종단간 성공 조건
+
+실제 선택된 테스트 프로젝트에서 Doc 생성·본문 readback·evidence 연결·승인 게이트 생성이 모두 확인되어야 한다. 같은 전송을 재시도해 중복이 없는지 확인한다. 명세가 바뀌었을 때 오래된 packet/승인으로 완료 처리되지 않아야 한다. 업로드 실패를 성공으로 표시하지 않아야 한다. 이 검증 전에는 동기화 완료 또는 승인 안전성을 주장하지 않는다.

package/docs/modernization/SYNC-DOCS-VALIDATION-2026-10-04.ko.md

@@ -0,0 +1,38 @@
+# sync-docs 추가와 검증 기록
+
+작성: 2026-10-04. 대상: 이 작업 checkout. 휴먼 검토·제품 적용은 미확인.
+
+## 반영 내용
+
+AIWF 소유 `aiwf-spec` 0.2.0에 [sync-docs 실행 원문](../../plugins/aiwf-spec/skills/sync-docs/SKILL.md)과 [한글 검토본](../ko-skills/aiwf-spec/skills/sync-docs/SKILL.ko.md)을 추가했다. workflow는 구현 완료 전에 영향 문서를 동기화하거나 문서 영향이 없는 이유를 기록하도록 갱신했다. 프로젝트 설치기는 스킬 폴더를 동적으로 탐색하므로 설치 코드의 변경 없이 기본 9개 스킬에 `aiwf-sync-docs`를 포함한다. 새 CLI 명령이나 자동 실행 서비스는 추가하지 않았다.
+
+## 실제 검증
+
+| 검사 | 결과 |
+| --- | --- |
+| `npm test` | 88개 통과, 실패 0. 한글 문서 검사도 pretest에서 통과 |
+| `npm run validate:spec-plugin` | upstream 스킬 31개 및 리소스 해시 보존, AIWF 자체 스킬 4개, manifest·참조 검사 통과 |
+| `npm run check:deps` | 기존 Node 소스 6개 검사 통과, 의존성 추가 없음 |
+| `npm run test:spec-upstream` | Python 검사기 self-test 3종 통과 |
+| `npm run validate:spec-example` | 기존 명세 예제 오류·경고 0 |
+| 공식 skills CLI의 로컬 목록 조회 | aiwf-spec에서 workflow와 sync-docs를 발견 |
+| 공식 skills CLI의 단독 설치 | 임시 Codex 프로젝트 `.agents/skills/sync-docs/SKILL.md`, Claude 프로젝트 `.claude/skills/sync-docs/SKILL.md` 생성. 원문 바이트 동일 |
+| npm package dry run | 새 실행 스킬 포함, `docs/ko-skills/` 검토 보관소 제외 확인 |
+
+스킬 생성 도구의 `quick_validate.py`는 기본·번들 Python에 PyYAML이 없어 실행하지 못했다. 새 의존성은 설치하지 않았다. frontmatter 발견과 실제 설치는 기존 공식 skills CLI로, 리소스·패키지·번역·설치 이름은 저장소 검사기로 확인했다. 이를 해당 Python 도구의 통과로 표현하지 않는다.
+
+## 독립 에이전트의 실행 예제
+
+임시 작업 공간에 기존 지출 예제의 문서·코드·테스트를 복사했다. 요청은 설명 길이를 200에서 150 Unicode code points로 변경한 결과를 문서에 반영하고 다른 업무 정책은 유지하는 것이었다. 입력 코드에는 이 길이 변경과 금액 0을 허용하는 변경을 함께 넣었다. 평가 에이전트에는 예상 답이나 의심 결함을 알려주지 않고 스킬, 요청, 코드·문서·테스트와 diff만 제공했다.
+
+평가 에이전트는 UC-001 BR-002/A3, TC-002, 데이터 모델, 계획과 README의 길이 기준을 갱신했다. BR-001의 양수 정책은 유지하고 금액 0 허용을 구현 회귀로 보고했다. 기존 UC ID와 비영향 문서를 유지했으며 코드·테스트를 수정하지 않은 것을 메인 담당자가 확인했다.
+
+기존 서비스 검사는 23개 중 17개 통과, 6개 실패였다. 실패는 이전 길이·메시지를 기대한 검사 5개와 금액 0 거부 검사 1개다. 새 길이의 ASCII·astral Unicode 150/151 경계 보조 확인과 문서 구조 검사는 통과했다. 실패를 전체 테스트 통과로 바꾸거나 요구사항을 코드에 맞춰 완화하지 않았다. UI·실제 DB·배포·휴먼 수용은 확인하지 않았다.
+
+평가 도중 저장소 번역 관리 파일을 작성 중이어서 AIWF `docs:check` 실패도 보고되었다. 이는 당시 중간 상태의 기록이다. 원문·번역·manifest 갱신 후 메인의 최종 검사는 71개 문서·37개 스킬 검토본으로 통과했다. 과거 관찰을 현재 실패라고 해석하지 않는다.
+
+## 한계와 휴먼 검토
+
+이 기록은 로컬 설치와 한 번의 독립 에이전트 실행 예제다. 모든 소비 프로젝트·스택·호스트의 자동 선택 또는 반복 실행 품질을 보증하지 않는다. 실행 지시는 에이전트가 수행하며 CLI가 문서·구현 정합성을 강제하는 것은 아니다. 원문 및 한글본의 검토 상태는 `awaiting_review`다.
+
+스킬 원문·한글본, workflow 완료 조건과 플러그인 README를 함께 검토한다. 코드 결함을 요구사항으로 바꾸지 않는 처리, 미구현·미검증 상태 보존, 비교 범위와 pin 갱신 책임이 주요 검토 대상이다. 이번 작업에서 commit·push·npm 배포는 수행하지 않았다.