aiwf 0.3.22 → 0.4.0

package/README.md

@@ -1,298 +1,112 @@
-# AIWF (AI Workflow Framework)
+# AIWF — specifications, implementation and evidence
 
-[Read in Korean (한국어로 보기)](README.ko.md)
+[한국어](README.ko.md)
 
-[![NPM Version](https://img.shields.io/npm/v/aiwf.svg)](https://www.npmjs.com/package/aiwf)
-[![License](https://img.shields.io/npm/l/aiwf.svg)](https://github.com/moonklabs/aiwf/blob/main/LICENSE)
-[![Downloads](https://img.shields.io/npm/dm/aiwf.svg)](https://www.npmjs.com/package/aiwf)
+Read the [Korean skill review documents](docs/ko-skills/README.md) before feature work. Update affected originals, translations and review records together; run `npm run docs:check` before concluding a task. Translation and automated checks do not constitute human approval. See the [optional Claude/Codex delegation design](docs/modernization/DELEGATION-OPTIONAL.ko.md).
 
-## What is AIWF?
+AIWF keeps use-case specifications in Git, lets existing Claude Code/Codex agents implement them, and records inspectable verification evidence.
 
-AIWF is an AI-powered workflow framework that enables autonomous software development with Claude Code. It provides intelligent command sets and workflow definitions that allow AI to manage entire project lifecycles - from planning to deployment - with minimal human intervention.
+Modernization started on 2026-10-02. The specification workflow is split across two plugins: **`aiwf-core`**, the AIUP-derived methodology core (seven upstream skills for requirements, use cases, entities and specification review), and **`aiwf-spec`**, the AIWF wrapper whose `workflow` skill uses the repository CLI and whose `sync-docs` skill maintains affected documents after development for non-overwriting initialization, specification pins, drift detection and review packets. Two separate Claude/Codex delegation add-ons are available by choice. Sprintable synchronization and unattended execution are planned, not implemented. These features describe this checkout; do not assume they are present in the previously published npm release.
 
-This project is an updated version of [Simone](https://github.com/Helmi/claude-simone).
+See the [direction](docs/modernization/DIRECTION.ko.md), [validation record](docs/modernization/VALIDATION.md), [Sprintable adapter proposal](docs/modernization/SPRINTABLE.ko.md) and [worked example](examples/spec-workflow/README.md).
 
-## ✨ Core Features
+The [CLI productivity analysis (Korean)](docs/modernization/CLI-PRODUCTIVITY.ko.md) proposes a real use-case pilot before read-only verification and optional checks with versioned execution records. Synchronized documentation remains a quality requirement at every step. These extensions are proposals, not implemented commands.
 
-### 🤖 **Agent-Based Autonomous Development**
-Multi-agent architecture where AIWF acts as the master orchestrator managing entire development workflows, while Claude Code operates as specialized subagents handling specific tasks. YOLO mode enables completely autonomous development - AI handles planning, coding, testing, and deployment without human intervention. Built-in checkpoint system ensures resilience and recovery.
+Two independent Claude sessions assessed the reviewed proposal as conditionally suitable. The [Korean plan review](docs/modernization/CLAUDE-PLAN-REVIEW-2026-10-03.ko.md) preserves their concerns and original input. The revised [pilot plan](docs/modernization/PILOT-UC-001.ko.md) and [local execution result](docs/modernization/PILOT-RESULT-2026-10-03.ko.md) record drift refusal and failing-to-passing service tests. Actual product adoption, human review and productivity gains remain unverified; no proposed CLI commands were added.
 
-### 🧠 **Intelligent Task Management**  
-Workflow-based state management with dependency tracking, priority calculation, and smart task recommendations. AI understands project context and suggests optimal next actions.
+## Start with this checkout
 
-### 🎭 **Specialized AI Personas**
-Five expert personas (Architect, Security, Frontend, Backend, Data Analyst) with specialized knowledge bases and context-aware compression for domain-specific optimization.
+Node.js 20+; Python 3.9+ for structural lint. The new Node CLI has no external dependencies. The target project directory must already exist.
 
-### 🧬 **Advanced Context Engineering**
-Intelligent context construction and optimization that maximizes AI effectiveness while minimizing token usage. Dynamic context compression, workflow-aware prompt engineering, and automatic relevance filtering ensure AI always has the right information at the right time.
-
-### 💡 **Smart Context Management**
-Token-efficient context strategies with automatic compression, intelligent chunking, and relevance scoring. Maintains comprehensive project understanding while optimizing for AI model limits and performance.
-
-### 🔄 **Multi-Agent Architecture** 
-AIWF operates as the master orchestration agent that coordinates complex development workflows. Claude Code instances function as specialized subagents, each handling specific domains like coding, testing, or documentation. This distributed approach enables parallel processing, fault tolerance, and specialized expertise application.
+```bash
+node src/cli/spec-cli.js init --root /path/to/project --name "Our service"
+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 --stack nestjs-nextjs
+node scripts/install-spec-skills.mjs --project /path/to/project --delegate codex --dry-run
+```
 
-### 🔗 **Seamless Integration**
-Native support for Claude Code, Cursor, Windsurf, GitHub, and Git with automated hooks, issue creation, and PR management.
+By default Codex installs the `aiwf-core` seven skills plus the `aiwf-spec` `workflow` and `sync-docs` skills as `aiwf-requirements`, `aiwf-use-case-spec`, ..., `aiwf-workflow`, `aiwf-sync-docs`, with their full references, parsers and attribution. `--stack` selects one of `vaadin-jooq`, `angular-jpa`, `blazor-dotnet` or `nestjs-nextjs` and adds that stack; existing skills are never overwritten and there is no force flag. Live host skill selection and model execution remain separate pilot checks.
 
-### ✅ **Robust Validation System**
-Advanced installation validation with intelligent file checking, dependency verification, and automated troubleshooting. Enhanced validation architecture ensures reliable framework setup and operation.
+After development, use Codex's `aiwf-sync-docs` or Claude Code's `/aiwf-spec:sync-docs` with the change intent, comparison scope and UC IDs. The workflow includes this before completion; it updates affected documents and preserves implementation gaps and unverified behavior. See the [installation and standalone skills CLI guide](plugins/aiwf-spec/README.md#synchronize-documents-after-development) and [Korean review copy](docs/ko-skills/aiwf-spec/skills/sync-docs/SKILL.ko.md). This is a skill, not a new `aiwf-spec` CLI command.
 
-## 📦 Installation
+Delegation is opt-in: `--delegate claude` and `--delegate codex` add only the selected skill; repeat the option to add both. Claude Code users can instead install either marketplace add-on. To install one portable skill with the skills CLI for Codex or Claude Code, choose both the skill and agent explicitly:
 
-### Global Installation (Recommended)
+The GitHub-based skills.sh commands below become available after these changes are published to the repository.
 
 ```bash
-npm install -g aiwf
+npx skills add https://github.com/moonklabs/aiwf --skill delegate-claude --agent codex
+npx skills add https://github.com/moonklabs/aiwf --skill delegate-codex --agent codex
+npx skills add https://github.com/moonklabs/aiwf --skill delegate-claude --agent claude-code
+npx skills add https://github.com/moonklabs/aiwf --skill delegate-codex --agent claude-code
 ```
 
-### First Time Setup
+These skills run only when invoked directly. Native delegation is used when the current host matches the target. Starting the other CLI requires the literal `--cross-cli` token in the current request; naming a target alone does not authorize another process. Cross-CLI tasks are read-only by default. A write requires that same request to explicitly ask for changes and state their scope. The CLI runs under the same OS account, directory and environment, follows its own permission policy, and does not inherit the host's sandbox or approvals. See the [delegation design](docs/modernization/DELEGATION-OPTIONAL.ko.md).
 
-After global installation, navigate to your project directory and run:
+## Plugins
 
-```bash
-aiwf install
-```
+31 upstream AIUP skills are vendored unchanged plus AIWF's own `workflow`, `sync-docs` and two optional delegation skills (35 total available). `aiwf-core` holds the seven upstream skills; `aiwf-spec` holds the AIWF `workflow` and `sync-docs`.
 
-The installer will guide you through:
+| Plugin | Role | Contents |
+|---|---|---|
+| `aiwf-core` | Methodology core (required) | 7 upstream skills, byte-identical (2.19.0) |
+| `aiwf-spec` | AIWF wrapper (optional) | AIWF `workflow` and `sync-docs` |
+| `aiwf-delegate-claude` | Optional delegation add-on | `delegate-claude` |
+| `aiwf-delegate-codex` | Optional delegation add-on | `delegate-codex` |
+| `aiwf-vaadin-jooq` | Stack | 8 upstream skills (2.20.0) |
+| `aiwf-angular-jpa` | Stack | 6 upstream skills (0.7.0) |
+| `aiwf-blazor-dotnet` | Stack | 5 upstream skills (0.7.0) |
+| `aiwf-nestjs-nextjs` | Stack | 5 upstream skills (0.4.0) |
 
-1. **Language Selection**: Choose between English and Korean
-2. **Project Setup**: Initialize AIWF in your current directory
-3. **Claude Commands**: Install language-specific commands
-4. **Documentation**: Download guides and templates
-5. **Validation**: Comprehensive installation verification and troubleshooting
+Each plugin vendors the upstream files it imports with a per-plugin `UPSTREAM.json` (`skills/` plus, for stacks, `rules/` and any `agents/`, `LICENSE`, `NOTICE`). The only upstream source change is the AIWF attribution appended to the `aiwf-core` NOTICE; every other vendored file is byte-identical. `aiwf-spec` has no upstream of its own and links the core [UPSTREAM.json](plugins/aiwf-core/UPSTREAM.json). Installation copies files: it does not register native Codex subagents or configure MCP. Bundled agent prompts such as `agents/uc-coverage.md` are copied as resources, and the `workflow` skill describes the host mapping. See [SKILLS.ko.md](docs/modernization/SKILLS.ko.md) for names, counts and the pin-update procedure.
 
-## 🚀 Getting Started Guide
+For Claude Code, add this checkout's absolute path as a local marketplace during development, then install the core, the wrapper and any stack you need (`aiwf-core`, `aiwf-spec`, `aiwf-<stack>`) and invoke a qualified command such as `/aiwf-core:use-case-spec`, `/aiwf-spec:workflow` or `/aiwf-nestjs-nextjs:implement`. After publishing these changes, the remote marketplace source can be `moonklabs/aiwf`.
 
-### Step 1: Installation
-```bash
-# Install globally
-npm install -g aiwf
-
-# Setup in your project directory
-cd your-project
-aiwf install
-```
+## Workflow
 
-### Step 2: Project Planning Phase
-Enter **Plan Mode** - describe what you want to build and your project goals. **Do not start coding yet.**
-- Engage in thorough Q&A to clarify objectives
-- Define project scope and requirements
-- Set clear success criteria
-
-### Step 3: Initialize Project Framework
-```bash
-# Create/update Claude configuration
-/init
+Write vision → requirements → glossary/entities → use cases → test definitions. For existing applications, draft observed behavior using `reverse-engineer`. Keep IDs stable and use canonical `docs/use_cases/UC-*.md` and `docs/test_cases/TC-*.md` paths. Implementation plans and architecture documents live under `docs/plans/` and `docs/architecture/`.
 
-# Initialize AIWF framework (creates first milestone)
-/project:aiwf:aiwf_initialize
-```
+Use English structural headings and status tokens. Korean prose is supported, but structural lint does not guarantee Korean semantic completeness.
 
-### Step 4: Create Sprint Plans
 ```bash
-# Generate sprints from milestone (first sprint becomes active)
-/project:aiwf:aiwf_create_sprints_from_milestone M01
-
-# If only one milestone exists, you can omit the milestone code
-/project:aiwf:aiwf_create_sprints_from_milestone
+python3 plugins/aiwf-core/skills/spec-review/scripts/spec_lint.py \
+  --docs /path/to/project/docs --strict --no-baseline
+node src/cli/spec-cli.js pin --root /path/to/project
+node src/cli/spec-cli.js check --root /path/to/project --json
 ```
 
-### Step 5: Review and Refine
-Review generated plans and refine through Q&A until satisfied with the approach.
-
-### Step 6: Generate Task Lists
-```bash
-# Create detailed tasks for active sprint (first task becomes active)
-/project:aiwf:aiwf_create_sprint_tasks
-```
+Initialization creates Draft templates; complete them and add UC/TC documents before pinning. Review meaning separately from structural lint. A pin records byte-level SHA256 hashes; it grants no approval. After a reviewed spec change, explicitly refresh the pin with `--refresh` and rerun affected checks.
 
-### Step 7: Execute Development
-```bash
-# Execute individual task
-/project:aiwf:aiwf_do_task [task-id]
+Implement with the current project's tools, execute actual checks, and save logs. Create an evidence JSON file:
 
-# OR run autonomous development for entire sprint
-/project:aiwf:aiwf_yolo
+```json
+{
+  "checks": [
+    {"name": "UC-001 regression", "command": "npm test", "status": "passed", "log": "artifacts/test.log"},
+    {"name": "Business acceptance", "command": "stakeholder review", "status": "not_run"}
+  ],
+  "unverified": ["Stakeholder acceptance has not been recorded"]
+}
 ```
 
-**YOLO Mode** orchestrates multiple Claude Code subagents to execute all sprint tasks continuously without interruption. The master agent coordinates planning while specialized subagents handle coding, testing, documentation, and commits automatically.
-
-### Key Commands
-
-- **Initialize**: `/project:aiwf:aiwf_initialize` - Initial project setup
-- **Plan**: `/project:aiwf:aiwf_create_milestone_plan` - Create milestone plans
-- **Sprint**: `/project:aiwf:aiwf_create_sprints_from_milestone` - Generate sprints
-- **Task**: `/project:aiwf:aiwf_do_task` - Execute tasks
-- **Review**: `/project:aiwf:aiwf_code_review` - Code review
-- **GitHub Integration**: `/project:aiwf:aiwf_issue_create`, `/project:aiwf:aiwf_pr_create`
-- **AI Personas**: `/project:aiwf:aiwf_ai_persona_architect`, `/project:aiwf:aiwf_ai_persona_debugger`, etc.
-
-### 🚀 YOLO Mode - Autonomous AI Development
-
-Revolutionary multi-agent orchestration that enables completely autonomous development workflows. AIWF acts as the master agent coordinating multiple Claude Code subagents:
+This is an input-format example, not a test result. Executed checks require log files inside the project root. The CLI records submitted command strings and never executes them.
 
 ```bash
-# Full autonomous development - AI handles everything
-/project:aiwf:aiwf_yolo
-
-# Target specific sprint execution  
-/project:aiwf:aiwf_yolo S03
-
-# Continuous multi-sprint development
-/project:aiwf:aiwf_yolo sprint-all
-```
-
-Master agent analyzes requirements and coordinates specialized subagents that create tasks, write code, run tests, and commit changes - achieving true multi-agent autonomous software development.
-
-## 🛠️ CLI Tools
-
-AIWF provides several specialized CLI tools for different aspects of project management:
-
-### Main CLI Commands
-- `aiwf install` - Install AIWF framework in current project
-- `aiwf create-project` - Create new project from templates
-- `aiwf compress` - Context compression for token optimization
-- `aiwf token` - Token usage monitoring and management
-- `aiwf persona` - AI persona management
-- `aiwf evaluate` - AI response and code quality evaluation
-
-### Sprint Management (`aiwf-sprint`)
-- `aiwf-sprint create` - Create new independent sprint
-- `aiwf-sprint list` - List all sprints
-- `aiwf-sprint status` - Show sprint status and progress
-- `aiwf-sprint task create` - Add tasks to sprint
-- `aiwf-sprint task execute` - Execute sprint tasks
-
-### Checkpoint System (`aiwf-checkpoint`)
-- `aiwf-checkpoint create` - Create project checkpoint for rollback
-- `aiwf-checkpoint list` - List all available checkpoints
-- `aiwf-checkpoint restore` - Restore project to previous checkpoint
-
-### Language Management (`aiwf-lang`)
-- `aiwf-lang status` - Check current language settings
-- `aiwf-lang set ko` - Switch to Korean
-- `aiwf-lang set en` - Switch to English
-
-### Cache Management (`aiwf-cache`)
-- `aiwf-cache download` - Download templates to local cache
-- `aiwf-cache list` - List all cached templates
-- `aiwf-cache clean` - Clean cache storage
-- `aiwf-cache update` - Update cached templates
-- `aiwf-cache status` - Check cache status and usage
-
-## 📁 What Gets Installed
-
-### Directory Structure
-
-```text
-your_project/
-├── .aiwf/                        # Project management root
-│   ├── 00_PROJECT_MANIFEST.md    # Central tracking document
-│   ├── 01_PROJECT_DOCS/          # Project documentation
-│   ├── 02_REQUIREMENTS/          # Milestone requirements
-│   ├── 03_SPRINTS/              # Sprint execution tracking
-│   ├── 04_GENERAL_TASKS/        # Standalone tasks
-│   ├── 05_ARCHITECTURAL_DECISIONS/ # ADR documents
-│   ├── 10_STATE_OF_PROJECT/     # Project state snapshots
-│   ├── 98_PROMPTS/              # Useful AI prompts
-│   └── 99_TEMPLATES/            # Document templates
-├── .claude/commands/aiwf/       # Language-specific Claude commands
-├── .cursor/rules/               # Cursor IDE development rules
-└── .windsurf/rules/             # Windsurf IDE development rules
+node src/cli/spec-cli.js packet --root /path/to/project --evidence /path/to/project/evidence.json
 ```
 
-### Language-Specific Content
-
-Based on your language selection, you'll get:
-
-**English Version (`en/`)** (Default):
-
-- English Claude commands
-- English documentation and templates
-- Standard project management content
-
-**Korean Version (`ko/`)**:
-
-- Korean Claude commands (with `_kr` suffix available)
-- Korean documentation and templates
-- Localized project management content
-
-## 🏗️ Code Architecture
-
-### Optimized Validation System
-
-AIWF features a significantly improved validation system that ensures reliable installation and operation:
+The packet embeds logs and their hashes, specification digests, Git context when available, reported results and limitations. It preserves failed/unexecuted checks and stays `awaiting_review`. Results are not independently verified; human acceptance, approval, merge and deployment need their own evidence. Existing packets require explicit `--force` to overwrite.
 
-#### Key Improvements in v0.3.18+
-- **86% Code Reduction**: Streamlined validator.js from 348 lines to 48 lines
-- **Unified Interface**: Single `validateInstallation()` function replaces 3 redundant methods
-- **Constants-Based Configuration**: All validation parameters centralized in `VALIDATION_CONSTANTS`
-- **Enhanced Error Reporting**: Specific, actionable error messages with detailed diagnostics
+## Validate
 
-#### VALIDATION_CONSTANTS Structure
-```javascript
-const VALIDATION_CONSTANTS = {
-  MIN_FILE_SIZE: 10,              // Minimum file size requirement
-  MIN_RULE_FILE_SIZE: 50,         // Minimum size for AI tool rule files
-  MIN_FILE_COUNT: {
-    CURSOR_MDC: 2,                // Required .mdc files for Cursor
-    WINDSURF_MD: 2,               // Required .md files for Windsurf  
-    CLAUDE_COMMANDS: 4            // Required command files for Claude
-  }
-};
+```bash
+npm run test:spec
+npm run validate:spec-plugin
+npm run test:spec-upstream
 ```
 
-#### Validation Features
-- **Multi-Tool Support**: Validates Claude Code, Cursor, Windsurf, and Gemini CLI
-- **File Integrity Checks**: Size validation, accessibility verification, and structure validation
-- **Intelligent Error Recovery**: Detailed troubleshooting guidance for failed validations
-- **Performance Optimized**: Faster execution with reduced memory footprint
-
-### Clean Architecture Principles
-
-The codebase follows clean architecture principles for maintainability and extensibility:
-
-#### Eliminated Code Duplication
-- **Unified Validation Logic**: Consolidated validation functions eliminate redundancy
-- **Shared Constants**: Centralized configuration reduces maintenance overhead
-- **Streamlined Error Handling**: Consistent error reporting across all validation types
-
-#### Improved Developer Experience
-- **Clear Separation of Concerns**: Validation, file management, and error reporting are properly isolated
-- **Maintainable Code Structure**: Reduced complexity makes the codebase easier to understand and modify
-- **Performance Benefits**: Optimized code paths improve installation speed and reliability
-
-## 📚 Documentation
-
-### Core Documentation
-- [Commands Guide](docs/COMMANDS_GUIDE.md) - Complete list of AIWF commands
-- [CLI Usage Guide](docs/CLI_USAGE_GUIDE.md) - Detailed CLI tool documentation
-- [Getting Started](docs/GETTING_STARTED.md) - Quick start guide for new users
-- [Development Guide](docs/DEVELOPMENT_GUIDE.md) - Contributing to AIWF
-
-### Feature Guides
-- [Independent Sprint Guide](docs/guides/independent-sprint-guide.md) - YOLO-focused sprint creation
-- [Checkpoint System Guide](docs/guides/checkpoint-system-guide.md) - Recovery and progress tracking
-- [AI Personas Guide](docs/guides/ai-personas-guide.md) - Using specialized AI personas
-- [Context Compression Guide](docs/guides/context-compression-guide.md) - Token optimization strategies
-- [Feature Git Integration Guide](docs/guides/feature-git-integration-guide.md) - Git hooks and tracking
-
-### Technical Documentation
-- [Architecture](docs/ARCHITECTURE.md) - System architecture and design
-- [State Management Guide](docs/STATE_MANAGEMENT_GUIDE.md) - Workflow-based state system
-- [AI Workflow](docs/AI-WORKFLOW.md) - AI integration patterns
-- [API Reference](docs/API_REFERENCE.md) - Programmatic usage
-- [Complete API Reference](docs/API_REFERENCE_FULL.md) - Comprehensive API documentation
-- [Validator API Reference](docs/VALIDATOR_API.md) - Validation system API documentation
-- [Code Cleanup Guide](docs/CODE_CLEANUP_GUIDE.md) - Code cleanup principles and patterns
-- [Troubleshooting](docs/TROUBLESHOOTING.md) - Common issues and solutions
-
-## 📖 Source
-
-This installer fetches the AIWF framework from:
-<https://github.com/moonklabs/aiwf>
+The old installer, language/sprint/persona/YOLO commands, duplicate skill collections and legacy plugins have been removed. The npm package exposes only `aiwf-spec`, with no external Node dependencies. `npm test` runs the current regression suite. This is a breaking change from the old framework; previously installed project data is untouched.
 
-## 📝 License
+## Attribution and licenses
 
-MIT
+The `aiwf-core` methodology plugin and the four stack plugins derive from the [AI Unified Process marketplace](https://github.com/AI-Unified-Process/marketplace) at commit `065dadda0f696c29ff2bacbda31b38152082e6fa`: `aiwf-core` and `aiwf-vaadin-jooq` by Simon Martinelli, `aiwf-angular-jpa` by Marc Affolter, `aiwf-blazor-dotnet` by Carl J. Mosca and `aiwf-nestjs-nextjs` by Swift Ugandan. Each plugin's `UPSTREAM.json` records the exact source commit, original hashes and modifications. Existing AIWF code remains [MIT](LICENSE); imported plugins carry [Apache-2.0](plugins/aiwf-core/LICENSE) and [NOTICE](plugins/aiwf-core/NOTICE).

package/docs/modernization/BROWNFIELD-GREENFIELD.ko.md

@@ -0,0 +1,105 @@
+# 브라운필드와 그린필드 작업 가이드
+
+작성: 2026-10-04. 상태: 제안, 휴먼 검토 대기.
+
+AIWF의 기존 명세·검증 흐름을 프로젝트의 출발점에 맞춰 적용하는 가이드다. 새로운 스킬이나 CLI 모드를 구현한 기록이 아니다. 상세 역설계는 [깊은 역설계 검토안](DEEP-REVERSE-ENGINEERING.ko.md)을 따른다.
+
+## 출발점과 공통 원칙
+
+| 구분 | 브라운필드: 운영·개발 중인 기존 시스템 | 그린필드: 새 제품·시스템 |
+| --- | --- | --- |
+| 출발점 | 현재 구현, 사용자 업무, 기존 데이터·연동 계약 | 해결할 문제, 대상 사용자, 제약과 가설 |
+| 첫 질문 | 무엇을 개선하며 무엇을 유지해야 하는가? | 누구의 어떤 목표를 먼저 달성할 것인가? |
+| 초기 조사 | 현행 동작과 변경 영향 범위 | 요구사항과 중요한 불확실성 |
+| 검증 기준 | 보존할 기존 동작 + 요청한 변경 | 명세한 동작 + 실제 사용 가치 |
+| 주요 위험 | 회귀, 데이터 손상, 기존 연동과의 비호환 | 잘못된 가정, 과도한 설계, 불필요한 기능 |
+
+두 경우 모두 유스케이스 하나를 문서 → 구현 → 실제 검증까지 연결하고 반복한다. 작업의 종류가 개선, 버그 수정, 신규 기능, 분석 중 무엇인지와 종료 지점을 먼저 정한다. 분석만 요청했다면 구현으로 자동 확장하지 않는다.
+
+## 브라운필드 진행 순서
+
+1. **변경 목표를 먼저 정한다.** 해결할 문제, 기대 결과, 유지할 동작, 이번에 건드리지 않을 범위를 쓴다. 예를 들어 “지출 제출에 승인을 추가하되 기존 조회와 제출 데이터는 유지한다”처럼 구체화한다.
+2. **현재 실행 기준을 확보한다.** 커밋·미커밋 변경, 환경, 설정, 스키마 버전과 기존 테스트 결과를 기록한다. 현재 실패도 숨기지 않고 실행 불가, 기존 결함, 원인 미확인으로 분류한다. 기존 실패와 신규 회귀의 구분에 실제 근거를 남긴다.
+3. **전체를 얕게, 변경 주변을 깊게 조사한다.** 시스템 지도에서 관련 UC를 고른다. 호출 경로, 공유 데이터, 권한, 외부 연동, 비동기 작업과 사용자 영향을 추적한다. 먼저 모든 기능을 완벽하게 문서화하는 것을 변경 착수의 조건으로 만들지 않는다. 변경 과정에서 영향 범위가 넓어지면 해당 부분을 추가 조사한다.
+4. **현행 동작을 근거와 함께 기록한다.** 기존 UC/용어/엔티티 문서를 활용하고 빠진 부분만 복원한다. 중요한 보존 동작에 기존 테스트를 연결하고, 부족하면 현재 동작을 재현하는 회귀 테스트를 보강한다. 알려진 버그를 재현한 결과와 유지할 정상 동작을 구분한다.
+5. **변경 차이를 명세한다.** 유지·추가·변경·폐기할 규칙과 대안 흐름, 영향받는 UC, 데이터와 외부 계약을 적는다. 기존 UC가 달라지면 같은 ID를 갱신하고, 독립된 새 사용자 목표라면 새 UC를 추가한다. 같은 엔티티·용어·규칙을 중복 정의하지 않는다.
+6. **변경에 맞는 검증과 이전 계획을 정한다.** 기존 동작을 확인하는 회귀 검증과 새 요구사항 검증을 함께 계획한다. 데이터 변경이 있으면 기존 데이터 변환·누락값·재실행을 확인한다. 연동 변경이 있으면 이전·새 호출자의 호환성을 검토한다. 배포가 필요한 범위에서는 단계적 적용, 관찰 항목과 되돌리기 조건을 정한다. 데이터 변환 후에는 단순 코드 롤백만으로 복구되지 않을 수 있다.
+7. **작은 범위로 구현하고 비교 검증한다.** 개선과 무관한 대규모 정리를 섞지 않는다. 선택한 UC와 공유 경계의 테스트를 실행하고 필요한 통합·전체 검증을 수행한다. 변경 전후 결과와 미검증 항목을 남긴다. 변경 후 문서는 최신 동작에 맞추고 이전 동작은 Git 이력과 분석 근거에 보존한다.
+
+현행 동작 기록은 업무 정책의 승인이 아니다. 정책이 충돌하면 원하는 동작을 결정할 사람과 질문을 식별한다. 이미 사용자가 지시한 변경과 명확한 로컬 구현은 그 권한 안에서 진행한다.
+
+### 기존 시스템에 신규 기능을 추가할 때
+
+신규 화면이나 서비스라도 인증, 데이터, 이벤트, 배포 환경을 기존 시스템과 공유하면 그 경계를 조사해야 한다. 새 기능만 명세하는 것으로 끝내지 않고 영향받는 기존 UC의 유지 조건과 회귀 검증을 연결한다.
+
+가령 기존 지출 제출에 승인 기능을 더한다면 제출·조회 흐름, 승인 권한, 기존 지출의 초기 상태, 상태 변경 알림, 승인 중 수정 가능 여부와 중복 승인 처리를 확인한다. 이것들은 예시 질문이며 실제 정책은 대상 시스템 조사와 사용자 결정에서 정한다.
+
+## 그린필드 진행 순서
+
+1. **문제와 첫 사용자 목표를 정한다.** 대상 사용자, 해결할 문제, 첫 유용한 결과, 성공을 판단할 기준, 제외 범위를 작성한다. 목표가 모호할 때 요구사항을 다듬고, 코드나 기존 자료에서 확인할 수 있는 내용은 먼저 확인한다.
+2. **가정과 제약을 드러낸다.** 핵심 용어, 권한·데이터 정책, 외부 연동, 규모·응답시간 같은 필요한 제약을 정한다. 아직 근거가 없는 것은 가설로 둔다. 검증 가능한 목표에 임의의 수치를 넣어 확정된 요구사항처럼 다루지 않는다.
+3. **큰 불확실성만 짧게 검증한다.** 중요한 외부 연동이나 기술 가능성이 불확실하면 제한된 실험으로 확인한다. 사용자 문제가 불확실하면 사용자 업무와 피드백을 확인한다. 실험 결과를 기록하고 필요한 설계 결정을 남긴다. 전체 아키텍처를 먼저 완성할 필요는 없다.
+4. **첫 UC의 명세와 테스트를 만든다.** 정상·대안 흐름, BR, 필요한 엔티티와 실패 시 보장을 정의하고 테스트에 연결한다. 사용자 목표에 필요한 범위의 설계를 선택한다. 여러 UC를 미리 상세하게 작성하느라 첫 결과를 늦추지 않는다.
+5. **첫 UC를 끝까지 구현한다.** UI가 필요하면 UI부터 서비스·저장·필요한 연동까지 한 흐름을 연결한다. 필요한 프로젝트 실행·테스트 도구와 자동 검사를 마련한다. 실제 입력으로 동작과 오류 흐름을 확인하고 미검증 환경을 명시한다.
+6. **사용 결과로 명세를 갱신하고 확장한다.** 테스트 통과와 사용 가치 검증을 구분한다. 사용자 피드백으로 요구사항과 용어를 수정하고, 다음 UC를 같은 방식으로 추가한다. 구현이 생긴 영역은 이후 변경 때 현행 조사와 회귀 검증을 적용한다.
+
+새 저장소도 기존 플랫폼·인증·DB·외부 API를 사용할 수 있다. 내부 구현은 그린필드여도 그 공유 경계에는 브라운필드의 영향 분석을 적용한다.
+
+## AIWF에서의 연결
+
+- 브라운필드: `reverse-engineer`로 필요한 현행 명세를 복원한 뒤 변경 요구사항 → UC/엔티티 갱신 → `test-case` → `spec-review` → 구현·검증으로 이어간다.
+- 그린필드: `requirements`로 목표·요구사항·용어를 정리하고 필요한 엔티티와 UC → `test-case` → `spec-review` → 첫 구현·검증으로 이어간다. 모호한 목표는 로컬 `grill-with-docs`를 사용할 수 있으나 이 스킬은 현재 core에 내장된 것이 아니다.
+
+형식 검사와 의미 검토 후 계획까지 작성한 명세를 `pin`하고, 구현 후 `check`로 문서 변경을 확인하고 `packet`으로 검증 자료를 묶을 수 있다. 기존 자료는 보존하며 `pin`의 필수 문서·UC/TC 조건을 충족해야 한다. 명세가 바뀌면 변경 근거를 기록하고 기준을 갱신한 뒤 영향받는 검증을 다시 수행한다.
+
+현재 CLI는 역설계, 테스트 실행, 검증 증거의 코드 버전 일치나 휴먼 승인을 자동 보장하지 않는다. 실험·테스트는 프로젝트 도구와 에이전트가 실행하고 정확한 버전·환경·로그를 연결한다. 기능을 병합·배포·업무 수용했다는 판단은 각각의 증거가 필요하다.
+
+## 최소 문서와 휴먼 리뷰
+
+`docs/vision.md`, `requirements.md`, `glossary.md`, `entity_model.md`, `use_cases.puml`과 선택한 UC/TC를 점진적으로 관리한다. 이미 자료가 있으면 그 기준과 연결하며 중복 작성하지 않는다. 브라운필드는 현행 근거와 영향 분석을 `docs/architecture/`에 추가하고, 변경 계획은 `docs/plans/UC-XXX.md`에 둔다. 그린필드는 필요한 설계 결정과 확인하지 못한 가정을 같은 경로에 남긴다.
+
+문서 본문은 사람이 읽을 수 있는 한글로 작성하고 core 파서용 헤딩·ID·상태는 유지한다. 관찰된 사실, 변경 목표와 남은 질문이 한 문장 안에서 섞이지 않도록 쓴다. 원문 스킬을 고도화하면 별도 한글 검토본과 관리 목록을 같은 변경에서 갱신한다.
+
+사람에게는 문서 전체를 반복해서 승인받기보다 유지·변경할 정책, 발견된 충돌, 중요한 설계 선택과 미검증 항목을 명확히 제시한다. 검토한 버전을 기록하고 자동 검사를 사람의 승인으로 바꾸지 않는다.
+
+## 개발 후 현재 기준으로 문서를 유지하는 절차
+
+추가 검토 및 반영: 2026-10-04. 문서 동기화는 AIWF 소유 [sync-docs 원문](../../plugins/aiwf-spec/skills/sync-docs/SKILL.md)과 [한글 검토본](../ko-skills/aiwf-spec/skills/sync-docs/SKILL.ko.md)에 반영했고 workflow의 완료 단계에도 연결했다. 변경 영향 분석·다른 스택의 감사 절차 확대는 후속 검토 사항이다. 아래 가이드가 실제 제품에서 검증되거나 휴먼 승인된 것을 뜻하지 않는다.
+
+개발 완료 시 코드뿐 아니라 영향받는 요구사항·UC·BR·테스트 정의·엔티티·설계·사용 안내가 함께 정리되어야 한다. 매번 전체 문서를 다시 생성하는 방식보다 변경 영향에 따라 기존 문서를 갱신하는 방식으로 운영한다. 문서 영향이 없다면 조사 범위와 그 이유를 남긴다.
+
+“현재”는 작업 브랜치의 구현 버전과 실제 배포 버전을 구분해야 한다. 새 기능이 브랜치에 구현되었다는 이유로 운영 중인 기능이라고 설명하지 않는다. 아직 구현되지 않은 요구사항은 목표로 남기고, 구현·검증·배포 여부와 근거를 별도로 기록한다. 이 표현은 기존 core 상태 값을 바꾸는 새 파서 규약이 아니다.
+
+### 작업마다 수행할 정리
+
+1. **개발 전 영향 목록을 작성한다.** 변경 목표와 diff, 관련 호출자·공유 데이터·권한·이벤트 경계에서 영향받는 UC와 문서를 식별한다. 코드 파일명만으로 문서 대상을 결정하지 않는다.
+2. **개발 중 명세와 구현의 차이를 기록한다.** 요청한 변경이면 관련 명세를 갱신한다. 승인·합의된 의도에 어긋나는 구현이면 코드 결함으로 다룬다. 어느 쪽이 맞는지 불분명하면 충돌로 기록하고 필요한 판단을 요청한다. 코드에 맞추기 위해 요구사항을 무조건 완화하지 않는다.
+3. **검증 후 영향받는 문서를 함께 갱신한다.** UC의 흐름·규칙·사후조건, UC 다이어그램, 데이터·상태 모델, 테스트 시나리오와 실제 구현 연결을 확인한다. 사용법·설정·API 계약·배포 방식이 바뀌면 관련 README와 운영 안내도 반영한다. 설계 결정 기록은 기존 결정의 역사적 이유를 덮어쓰지 않고 후속 결정과 연결한다.
+4. **ID와 링크를 유지한다.** 같은 사용자 목표는 같은 UC ID로 갱신한다. 신규 목표는 새 ID를 부여한다. 폐기·병합한 항목은 대체 항목과 이력을 남기고 끊어진 참조를 해결한다. 사용한 ID를 다른 목표에 재사용하지 않는다. 중요한 BR 연결과 테스트 이름이 변경 과정에서 의미를 잃지 않았는지 확인한다.
+5. **작성과 검토를 나눈다.** 작성 단계가 정리한 문서에 대해 별도 검토 단계에서 코드·명세·테스트 연결과 문서 간 일관성을 확인한다. 독립 에이전트가 없으면 별도 검토 단계였음을 밝히고 독립 리뷰라고 주장하지 않는다. 코드에 테스트가 있다는 사실과 그 테스트를 실행해 통과했다는 사실을 구분한다.
+6. **최종 변경분에 맞는 증거를 남긴다.** 변경 후 테스트 결과와 문서 정합성을 확인하고 남은 미검증 항목을 기록한다. 명세가 변경되면 이유를 설명하고 pin 갱신과 영향받는 테스트 재실행을 수행한다. 문서·코드·검증 근거를 같은 PR에서 검토할 수 있게 한다. 과거 실행 로그를 현재 코드의 검증 근거처럼 재사용하지 않는다.
+
+종료 시 결과에는 영향받은 UC/BR/TC, 갱신 문서, 코드·실행 근거, 남은 불일치·미구현·미검증 항목을 포함한다. 문서가 최신이어야 한다는 요구는 아직 구현하지 않은 목표나 확인하지 못한 조건을 삭제하는 이유가 되지 않는다.
+
+### 필요한 역량과 기존 스킬의 범위
+
+| 역량 | 현재 활용할 것 | 보강할 부분 |
+| --- | --- | --- |
+| 변경 영향 분석 | `reverse-engineer`와 기존 문서·코드 조사 | diff에서 공유 경계를 따라 영향 UC·문서·테스트를 정하는 재사용 절차 |
+| 문서 갱신 | `requirements`, `use-case-spec`, `use-case-diagram`, `entity-model`, `test-case` | 변경 후 이 스킬들의 작성 범위를 묶고 최신 상태를 정리하는 절차 |
+| 문서 정합성 검토 | `spec-review` | 구현 후 영향 문서를 대상으로 다시 검토하는 완료 조건 |
+| 명세와 구현·테스트 대조 | Angular/JPA, Vaadin/jOOQ의 `coverage-check` | 다른 스택에서 사용할 공통 대조 절차와 실제 실행 증거 연결 |
+
+`spec-review`는 문서를 서로 대조하며 코드 구현을 검사하는 스킬이 아니다. 현재 두 `coverage-check` 스킬은 읽기 전용 보고를 작성하고 코드·명세를 수정하거나 테스트를 실행하지 않는다. `aiwf-spec check`도 명세 파일 해시를 비교하므로 문서가 코드에 맞게 최신이라는 증명으로 사용할 수 없다.
+
+AIWF 소유 `workflow`는 완료 전에 `sync-docs`를 사용하도록 갱신했다. 단독 문서 정리에도 재사용할 수 있으며 입력은 기준 버전·변경 범위·변경 의도, 출력은 영향 목록·문서 갱신·불일치 보고와 검증 근거다. Codex 프로젝트 설치기는 `aiwf-sync-docs`로 설치하고 Claude Code는 `/aiwf-spec:sync-docs`로 호출한다. 이 checkout에는 추가되어 있으나 원격 설치에 사용하려면 해당 변경의 게시가 필요하다. 스킬 지시 추가는 자동 동기화 서비스나 정합성 강제 장치의 구현이 아니다.
+
+공통 코드·명세 대조 역시 필요한 역량이지만 기존 스택의 감사 절차를 복제해 별도 기준을 만들지 않는다. 사용할 범위와 책임을 정한 뒤 기존 core 형식과 감사 규칙을 연결한다. 필요 시 영향 분석을 별도 스킬로 분리하되 먼저 workflow에서 반복 사용과 누락을 관찰한다.
+
+실행 지시를 반영하는 후속 변경에서는 AIWF 소유 원문과 한글 검토본, 플러그인 README 양쪽, 카탈로그·manifest를 변경 범위에 맞춰 함께 갱신한다. upstream core의 원문은 보존한다.
+
+## 작업 요청 예시
+
+브라운필드: “지출 승인 추가를 준비한다. 현행 제출 UC와 공유 권한·데이터·알림 경계를 조사해 근거가 있는 현행 명세, 변경 차이, 회귀 테스트 계획을 작성하라. 이번 작업은 분석과 문서까지다.”
+
+그린필드: “직원이 지출을 제출하는 첫 기능을 만든다. 목표·제외 범위와 정상·실패 흐름을 정리하고 UC 하나를 구현·실제 검증까지 완료하라. 미확정 정책과 검증하지 못한 환경을 기록하라.”

package/docs/modernization/CLAUDE-PLAN-REVIEW-2026-10-03.ko.md

@@ -0,0 +1,77 @@
+# Claude 두 세션의 CLI 계획 리뷰
+
+작성: 2026-10-03. 상태: **AI 리뷰 완료, 휴먼 리뷰 대기**.
+
+후속 진행 기록: 사용자의 “진행” 이후 계획을 수정하고 [로컬 예제를 실행](PILOT-RESULT-2026-10-03.ko.md)했다. 이 리뷰가 검토한 bytes는 [검토 당시 고정본](CLI-PRODUCTIVITY-REVIEWED-2026-10-03.ko.md)에 보존했다. [현재 계획](CLI-PRODUCTIVITY.ko.md)과 [파일럿 계획](PILOT-UC-001.ko.md)의 수정·실행은 별도 작업이며 이 리뷰를 새 버전의 검토 통과로 취급하지 않는다. 아래 본문은 리뷰 수행 당시의 판단과 미완료 항목을 기록한다.
+
+사용자 요청 “이계획을 claude 2세션으로 리뷰받아”에 따라 실제 Claude Code 세션 두 개를 실행했다. 검토 대상은 [검토 당시 CLI 생산성 분석과 권고안](CLI-PRODUCTIVITY-REVIEWED-2026-10-03.ko.md)이며, 그 리뷰 작업에서 계획 본문은 수정하지 않았다.
+
+## 결론
+
+두 세션 모두 **조건부 적합**으로 평가했다. 실제 UC 파일럿을 먼저 수행하고, 기존 코딩 에이전트·프로젝트 도구를 사용하며, 문서와 검증 근거를 휴먼 리뷰에 연결하는 방향에는 동의했다. 반면 파일럿의 완료·확장 기준이 구체적이지 않고, 첫 runner에 요구한 계약 범위가 크다는 지적이 공통으로 나왔다.
+
+조정 담당의 판단은 **현재 도구로 파일럿을 진행할 수 있지만, 이 계획을 그대로 runner 구현 명세로 사용하기에는 P1 결정이 남아 있다**는 것이다. 검토 결과를 근거로 새 기능을 구현하거나 승인을 부여하지 않았다.
+
+## 실제 실행과 검토 버전
+
+| 세션 | 담당 | 세션 ID | 요청 모델 / 관측 모델 | 요청 effort / 관측 effort |
+| --- | --- | --- | --- | --- |
+| review-1 | 방향·제품 범위·우선순위·도입 부담 | `0f7eb76e-d5a5-4859-b6a6-9756fa26af16` | `claude-sonnet-5-5` / 동일 | `high` / 미확인 |
+| review-2 | 검증·실행 기록 계약·기존 코드 정합성 | `cab3cadc-37d4-4ebb-a699-0d122c4c3baa` | `claude-sonnet-5-5` / 동일 | `high` / 미확인 |
+
+- Claude Code: `2.1.288`. 설치 경로와 도움말을 확인하고 인증 상태의 loggedIn·인증 방식·provider만 확인했다. 인증 파일이나 토큰을 읽거나 변경하지 않았다.
+- checkout: `/Users/moonklabs/workspace-plugin/aiwf`, 기준 HEAD `fcf5ebc24bcd5e49148290a65ac6e1a5c4b22ba6`. 계획은 미커밋 파일이므로 각 세션에 현재 파일을 읽도록 지시했다.
+- 검토 당시 계획 SHA256: `426d38f8d52001678083979ca7418c64c6d0b780fa8ef504aec1d6aa5c6b7ab8`. 두 실행 후에도 같은 hash임을 확인했다.
+- 두 결과 모두 exit 0, `subtype: success`, `is_error: false`, 권한 거부 0, stderr 0 bytes였다. 종료 코드뿐 아니라 최종 답변과 `modelUsage`의 실제 모델을 확인했다.
+- 결과 JSON에는 실제 적용 effort가 없으므로 요청한 `high`가 관측되었다고 주장하지 않는다.
+- 두 세션에 같은 계획과 저장소 지침을 제공하고 관점을 나눴다. 서로의 결과는 전달하지 않았다. 실제 사용 도구도 `Read`, `Grep`, `Glob`만 확인했다.
+- 파일 편집·셸·테스트·MCP·새 에이전트는 세션에 제공하지 않았다. 리뷰 답변은 테스트 결과나 휴먼 승인으로 취급하지 않는다.
+
+요청에 모델 지정이 없어 이전 파일럿과 같은 Sonnet 5.5를 조정 담당이 선택했다. 로컬 설치된 `claude-sessions` 스킬을 사용했다. 실제 설치 지침은 아래 실행 경로에서 확인할 수 있다.
+
+```text
+/Users/moonklabs/.codex/skills/claude-sessions/SKILL.md
+/Users/moonklabs/.codex/skills/claude-sessions/scripts/run_session.py
+```
+
+CLI·모델 옵션은 실행 전 [Claude CLI 공식 문서](https://code.claude.com/docs/en/cli-reference), [모델·effort 공식 문서](https://code.claude.com/docs/en/model-config)와 설치된 도움말을 대조했다. 두 개의 실제 세션만 시작했으며 모델 변경·추가 리뷰 세션·권한 확대 재시도는 없었다.
+
+## 핵심 지적과 처리 판단
+
+아래 “수용”은 조정 담당이 후속 문서 수정 항목으로 인정했다는 뜻이다. 코드 반영, 계획 수정 완료, 휴먼 승인 또는 Claude의 재검토 통과를 의미하지 않는다. 계획은 검토 버전 그대로 유지했다.
+
+| 우선순위 | 지적 | 출처 | 판단과 최소 후속 작업 |
+| --- | --- | --- | --- |
+| P1 | 파일럿의 완료·확장 기준과 실제 사람 검토 결과의 기록 방법이 부족함 | review-1 | 수용. UC 선정 기준, 단계별 시간·전사·누락 기록, packet을 읽은 사람의 결과·재요청, 종료 조건을 먼저 한 장의 파일럿 문서로 정의한다. 자동화가 필요 없다는 결론도 종료 결과로 인정한다. |
+| P1 | 검사 정의·UC/BR/TC 매핑의 위치, 명세 버전 포함 여부, 실행 시 선택된 정의 확인 계약이 없음 | 두 세션 | 수용. AIWF 자체 계약의 소유는 `aiwf-spec`/CLI에 둔다. 실제 파일 위치와 schema, pin 또는 별도 실행 입력 digest 포함 방식은 runner 착수 전에 확정한다. 매핑·명령이 바뀌면 옛 실행 기록으로 최신 검증을 충족하지 못해야 한다. |
+| P2 | 첫 runner 범위가 입력 manifest·환경·취소·새 packet까지 한꺼번에 포함해 큼 | 두 세션 | 수용. 파일럿에서 측정한 병목에 필요한 범위만 채택하고 상세 receipt 계약은 미채택 후보로 관리한다. 입력을 좁힐 경우 `fresh`의 의미도 해당 선언 범위로 좁힌다. |
+| P2 | 문서 검토 보고서가 본문에서 여전히 “첫 단계”로 보여 파일럿 우선순위와 충돌 | review-1 | 수용. 문서 정합성·한글본 갱신은 계속 먼저 수행한다. 별도 검토 보고서 기능은 사람이 실제로 검토할 때 자료 준비가 병목인지 확인한 뒤 도입한다. 기존 검사 명령의 CI 연결은 별도 저비용 유지보수 후보로 남긴다. |
+| P2 | verify에 Python 시작 오류·JSON 오류·미처리 예외·읽기 중 변경의 분류가 부족함 | review-2 | 수용. `lint_failed`, `tool_error`, `incomplete`, `drift` 등의 보고 계약과 기존 CLI 종료 코드 관계를 정의한다. 도구 실패를 명세 실패나 성공으로 오인하지 않도록 한다. |
+| P2 | packet의 1 MiB 제한을 runner 로그 제한으로 그대로 적용하면 실제 실행 결과 보존에 제약 | review-2 | 수용. 실행 outcome과 로그 수집·packet 생성 상태를 구분하고, 전체 로그 보관·발췌 또는 packet 거부 중 정책을 후속 설계에서 정한다. 현재 v1 제한을 조용히 완화하거나 초과 로그를 완전한 결과로 표시하지 않는다. |
+| P3 | 현재 플러그인 수, runtime 정책 위치, 시점 고정 검증 기록의 표현 점검 필요 | review-1 | 일부 수용. core/workflow/stack 6개와 선택 위임 2개라는 범위를 명확히 설명한다. 과거 기록은 그 당시의 범위로 보존하고 검증 시점을 표시한다. runtime 정책은 파일럿과 별도 결정으로 취급한다. |
+| P3 | packet 숫자 schema와 Sprintable 제안의 문자열 식별자, baseline 무시 정책 명확화 필요 | review-2 | 일부 수용. 현재 packet과 향후 Sprintable 전송 metadata는 다른 계약임을 명시한다. v2 계약에서는 각각의 식별자를 정한다. `--no-baseline`은 이미 workflow의 정책이며 기존 수용 항목도 다시 findings로 나타난다는 안내를 보완한다. |
+
+## 그대로 채택하지 않는 제안과 한계
+
+review-2는 실행 전에 definition hash를 사용자가 지정한 값과 대조하거나 `--yes` 입력을 요구하는 방안을 제안했다. 정의의 변경과 실제 선택된 실행 범위를 확인해야 한다는 문제 제기는 수용한다. 다만 **추가 `--yes`를 모든 실행의 필수 승인 절차로 정하지는 않았다**. 사용자가 이미 지정한 실행 범위와 CLI 호출의 의미를 활용해 불필요한 재확인을 줄이는 계약을 먼저 검토해야 한다. 실제 실행은 이미 부여된 권한 범위에서 이루어져야 한다.
+
+명시적 파일 목록으로 첫 runner 입력을 좁히는 제안도 후보로 수용한다. 이 경우 새 파일·외부 서비스·목록 밖 설정을 검증했다고 주장할 수 없다. 필수 입력을 확인할 수 없는 경우의 `unknown`을 삭제하거나 `passed`로 바꾸지는 않는다.
+
+`spec_lint.py --trace --format json` 재사용은 ID 연결을 읽는 후보이며, reviewer는 그 JSON이 모든 필요한 연결을 제공하는지 확인하지 못했다고 기록했다. trace 출력을 실행 테스트 커버리지로 사용하는 것은 현재 계획의 제한과 맞지 않는다.
+
+review-1의 “사람 검토 0건”은 관리 목록에 실제 리뷰 기록이 없다는 사실이다. 사람이 문서를 읽은 적 자체가 없다고 추정하지 않는다. 준비 시간이 병목인지 역시 아직 측정하지 않았다. review-2의 대형 stack 로그 크기와 Node 20 입력 탐색 비용에 관한 지적은 실행 측정이 아닌 위험 추론이다.
+
+## 각 세션의 전체 최종 답변
+
+- [review-1: 방향·우선순위](reviews/2026-10-03-claude-cli/DIRECTION.ko.md)
+- [review-2: 검증·실행 기록 계약](reviews/2026-10-03-claude-cli/CONTRACTS.ko.md)
+
+각 답변의 파일·행 번호는 검토 당시 계획 hash에 대응한다. 향후 계획을 수정하면 기존 리뷰를 새 버전의 검토 결과로 승격하지 않는다. 추가 검토가 필요하면 새 세션을 임의로 만들지 않고 위 세션 ID를 재개한다.
+
+## 이번 결과 정리의 검증과 남은 것
+
+원본 결과 JSON과 요청·stderr·전체 세션 기록은 저장소 밖의 비공개 임시 경로에 둔다. 저장소에는 최종 리뷰 Markdown과 이 통합 판단만 남긴다. 두 세션의 실제 모델·최종 상태·권한 거부·사용 도구와 계획 hash 일치를 확인했다.
+
+Claude 세션들은 자동 테스트와 앱 실행을 하지 않았다. 앞선 계획의 85개 테스트 통과를 이번 Claude 리뷰에서 재현한 결과로 표시하지 않는다. 결과 문서와 연결된 README·한글본·관리 목록을 갱신한 뒤 조정 담당이 `npm run docs:check`를 별도로 실행해 통과를 확인했다. 관리 문서 70개는 휴먼 리뷰 대기 상태다.
+
+남은 일은 소비 프로젝트·UC와 실제 검토자를 정하고 파일럿 기록을 수행하는 것, 그 근거로 상세 CLI 계약을 채택·축소하는 것, 그리고 한글 문서의 실제 휴먼 리뷰다. 이번 요청 범위는 두 세션의 계획 리뷰이며 파일럿이나 runner 구현은 시작하지 않았다.