aiwf 0.3.22 → 0.4.0

package/docs/modernization/evidence/local-pilot-20261003/project/docs/entity_model.md

@@ -0,0 +1,33 @@
+# Entity Model
+
+> Status: Draft
+
+## Entity Relationship Diagram
+
+```mermaid
+erDiagram
+    SUBMITTER ||--o{ EXPENSE_REPORT : "submits"
+```
+
+### SUBMITTER
+
+지출 내역을 제출하는 사람을 나타낸다.
+
+| Attribute | Description        | Data Type | Length/Precision | Validation Rules      |
+|-----------|--------------------|-----------|------------------|-----------------------|
+| id        | 제출자 고유 식별자 | Long      | 19               | Primary Key, Sequence |
+| name      | 제출자 이름        | String    | 100              | Not Null              |
+
+### EXPENSE_REPORT
+
+제출된 지출 내역 한 건을 나타낸다.
+
+| Attribute    | Description      | Data Type | Length/Precision | Validation Rules                    |
+|--------------|------------------|-----------|------------------|-------------------------------------|
+| id           | 지출 내역 식별자 | Long      | 19               | Primary Key, Sequence               |
+| amount       | 제출 금액        | Decimal   | 10,2             | Not Null, greater than 0  |
+| description  | 사용 내용        | String    | 200 code points  | Optional; BR-002                    |
+| submitted_at | 제출 시각        | DateTime  | -                | Not Null                            |
+| submitter_id | 제출자 참조      | Long      | 19               | Not Null, Foreign Key (SUBMITTER.id) |
+
+**Constraints:** 지출 내역의 금액은 0보다 커야 한다. 사용 내용은 Unicode code point 200개 이하여야 하며 생략·null은 빈 문자열로 정규화한다 (UC-001 BR-002). 실제 DB와 업무 정책은 이번 서비스 파일럿에서 검증하지 않는다.

package/docs/modernization/evidence/local-pilot-20261003/project/docs/glossary.md

@@ -0,0 +1,9 @@
+# Glossary
+
+> Status: Reviewed
+
+| Term      | Definition                                                     | Avoid     |
+|-----------|----------------------------------------------------------------|-----------|
+| 제출자    | 지출 내역을 작성해 제출하는 사람.                              | 신청자    |
+| 지출 내역 | 정산을 위해 제출하는 금액과 사용 내용의 묶음.                  | 경비 청구 |
+| 승인자    | 제출된 지출 내역을 검토하고 승인 여부를 결정하는 사람.         |           |

package/docs/modernization/evidence/local-pilot-20261003/project/docs/plans/UC-001.md

@@ -0,0 +1,20 @@
+# UC-001 서비스 파일럿 구현 계획
+
+범위: 가상 지출 제출의 서비스 부분. 실제 로그인·UI·DB·업무 수용은 별도 미검증이다.
+
+## 명세와 실행 검사의 연결
+
+| Check ID | 명세 범위 | 실행 명령 | 입력 | 미검증 사항 |
+| --- | --- | --- | --- | --- |
+| C-STRUCTURE | FR-001 / UC-001 / TC-001 / TC-002 / 문서 연결 | 저장소 core의 spec_lint.py --strict --no-baseline --format json | docs/ 전체 pin 대상 | 한국어 의미·업무 수용 |
+| C-SERVICE | UC-001 BR-001/BR-002, 기본 흐름의 기록·접수번호, A1 / A2 / A3, TC-001/TC-002 서비스 부분 | node --test tests/expense.test.mjs | src/expense.mjs, tests/expense.test.mjs | UI·계정·DB·동시성 |
+| C-UI | UC-001 화면·접수표시 / TC-001/TC-002 전체 흐름 | 실제 앱 미지정 | 아직 없음 | not_run: UI와 인증 앱 없음 |
+| C-HUMAN | 명세 의미·업무 수용 | 실제 사람의 packet 검토 | 해당 명세·packet·코드 | not_run: 실제 검토자 기록 없음 |
+
+## 변경·검증 원칙
+
+BR-002 검사 이름은 ASCII/astral Unicode의 200/201 경계, 숫자·배열·객체 타입 거부, 생략·null·빈 문자열 정규화와 TC-002의 201→200 수정 흐름을 식별한다. 기존 기록이 있는 상태에서 잘못된 입력이 기록을 바꾸지 않는지 검증한다. TC-002의 화면 메시지와 로그인은 C-UI에 남긴다.
+
+명세·매핑·명령 변경은 pin drift로 확인한다. 코드·테스트의 bytes hash는 실행 기록에서 별도로 남기며 current CLI가 이를 검증한다고 주장하지 않는다. 새로운 명세에서 과거 성공 로그를 사용하지 않고 해당 단계의 명령을 다시 실행한다.
+
+이 파일은 pin에 포함된 검토 문서다. 현재 CLI는 표에 있는 명령을 자동 실행하지 않는다. 실패와 not_run을 보존하고 packet은 awaiting_review로 유지한다.

package/docs/modernization/evidence/local-pilot-20261003/project/docs/requirements.md

@@ -0,0 +1,10 @@
+# Requirements
+
+> Status: Reviewed
+
+## Functional Requirements
+
+| ID     | Title          | User Story                                                                  | Priority | Status |
+|--------|----------------|-----------------------------------------------------------------------------|----------|--------|
+| FR-001 | 지출 내역 제출 | As a 제출자, I want 지출 내역을 제출하기 so that 승인자가 검토할 수 있다.   | High     | Open   |
+

package/docs/modernization/evidence/local-pilot-20261003/project/docs/test_cases/TC-001-submit-expense.md

@@ -0,0 +1,37 @@
+# Test Case: 지출 내역 제출
+
+## Overview
+
+**ID:** TC-001  
+**Goal:** 제출자가 지출 내역을 제출하고 접수 번호를 받는 흐름을 끝까지 확인한다.  
+**Priority:** High  
+**Status:** Reviewed  
+
+## Roles
+
+- 제출자 (지출 금액과 사용 내용을 입력하고 제출한다)
+
+## Preconditions
+
+- 제출자 계정이 준비되어 있다 (테스트 데이터 시드)
+
+## Flow
+
+| Step | Name | Description | Test Data | Use Case |
+|------|------|-------------|-----------|----------|
+| 1 | 제출 시작 | 제출자가 지출 내역 제출을 시작한다 | - | [UC-001](../use_cases/UC-001-submit-expense.md) |
+| 2 | 잘못된 금액 입력 | 제출자가 금액과 사용 내용을 입력한다 | -100, 팀 회식 | [UC-001](../use_cases/UC-001-submit-expense.md) |
+| 3 | 오류 확인 | 금액 오류 메시지가 표시되고 제출된 내역이 없음을 확인한다 | - | - |
+| 4 | 금액 수정 | 제출자가 금액을 수정한다 | 12000 | [UC-001](../use_cases/UC-001-submit-expense.md) |
+| 5 | 제출 확정 | 제출자가 제출을 확정한다 | - | [UC-001](../use_cases/UC-001-submit-expense.md) |
+| 6 | 접수 확인 | 접수 번호가 표시되는지 확인한다 | - | - |
+
+## Validation
+
+1. **접수 상태**: 최종 지출 내역이 제출 상태로 표시된다.
+2. **금액 보존**: 기록된 금액이 12000으로 표시된다.
+
+## Postconditions
+
+- 지출 내역 1건이 제출 상태로 남는다 (금액 12000, 사용 내용 팀 회식).
+- 접수 번호가 기록된다.

package/docs/modernization/evidence/local-pilot-20261003/project/docs/test_cases/TC-002-description-limit.md

@@ -0,0 +1,42 @@
+# Test Case: 사용 내용 길이 수정 후 제출
+
+## Overview
+
+**ID:** TC-002  
+**Goal:** 사용 내용 길이 오류 후 수정하여 접수하는 UC-001 BR-002/A3 흐름을 확인한다.  
+**Priority:** High  
+**Status:** Draft  
+
+## Roles
+
+- 제출자 (사용 내용을 수정하고 제출한다)
+
+## Preconditions
+
+- 제출자 계정이 준비되어 있다 (UI는 이번 파일럿에서 미실행)
+- 기존 지출 내역 1건이 저장되어 있다
+
+## Flow
+
+| Step | Name | Description | Test Data | Use Case |
+|------|------|-------------|-----------|----------|
+| 1 | 제출 시작 | 제출자가 지출 내역 제출을 시작한다 | - | [UC-001](../use_cases/UC-001-submit-expense.md) |
+| 2 | 길이 초과 입력 | 제출자가 금액과 사용 내용을 입력한다 | 12000, a 201개 | [UC-001](../use_cases/UC-001-submit-expense.md) |
+| 3 | 오류 확인 | 사용 내용 길이 오류와 기존 기록 보존을 확인한다 | - | - |
+| 4 | 사용 내용 수정 | 제출자가 사용 내용을 수정한다 | a 200개 | [UC-001](../use_cases/UC-001-submit-expense.md) |
+| 5 | 제출 확정 | 제출자가 제출을 확정한다 | - | [UC-001](../use_cases/UC-001-submit-expense.md) |
+| 6 | 접수 확인 | 새 접수 번호와 최종 내용을 확인한다 | - | - |
+
+## Validation
+
+1. **길이 경계**: ASCII 및 astral Unicode 각각 200 code points는 저장되고 201은 기록 전에 거부된다.
+2. **타입·선택 입력**: 숫자·배열·객체는 거부되고 생략·null·빈 문자열은 빈 문자열로 기록된다.
+3. **기존 기록 보존**: 모든 거부 후 이전 기록은 변경되지 않는다.
+4. **수정 접수**: 사용 내용을 201에서 200으로 수정한 뒤 새 접수 번호로 저장된다.
+
+## Postconditions
+
+- 이전 지출 내역 1건과 새 제출 1건이 남는다.
+- 새 내용은 a 200개이며 새 접수 번호가 기록된다.
+
+서비스 검사는 저장·거부·수정만 다룬다. 로그인·화면·오류 표시·접수 화면은 미검증이다.

package/docs/modernization/evidence/local-pilot-20261003/project/docs/use_cases/UC-001-submit-expense.md

@@ -0,0 +1,76 @@
+# Use Case: 지출 내역 제출
+
+## Overview
+
+**Use Case ID:** UC-001  
+**Use Case Name:** 지출 내역 제출  
+**Primary Actor:** 제출자  
+**Goal:** 제출자가 지출 내역을 제출하여 승인자가 검토할 수 있게 한다.  
+**Trigger:** 제출자가 지출 내역 제출을 요청한다.  
+**Status:** Draft  
+
+**Requirements:** [FR-001](../requirements.md)
+
+## Preconditions
+
+- 제출자가 시스템에 로그인되어 있다
+- 제출할 지출 내역의 금액과 사용 내용을 알고 있다
+
+## Main Success Scenario
+
+1. 제출자가 지출 내역 제출을 시작한다.
+2. 시스템이 지출 내역 입력 화면을 표시한다.
+3. 제출자가 지출 금액과 사용 내용을 입력한다.
+4. 시스템이 입력한 금액이 0보다 크고 사용 내용이 BR-002 조건을 만족하는지 확인한다.
+5. 제출자가 제출을 확정한다.
+6. 시스템이 지출 내역을 제출 상태로 기록하고 접수 번호를 표시한다.
+
+## Alternative Flows
+
+### A1: 유효하지 않은 금액
+
+**Trigger:** 입력한 금액이 0 이하이다 (step 4)  
+**Flow:**
+
+1. 시스템이 금액은 0보다 커야 한다는 메시지를 표시한다.
+2. 제출자가 금액을 수정한다.
+3. Use case continues at step 4.
+
+### A2: 제출 처리 실패
+
+**Trigger:** 시스템이 지출 내역을 기록할 수 없다 (step 6)  
+**Flow:**
+
+1. 시스템이 제출을 완료하지 못했음을 알린다.
+2. Use case ends.
+
+### A3: 유효하지 않은 사용 내용
+
+**Trigger:** 사용 내용이 문자열이 아니거나 Unicode code point 200개를 초과한다 (step 4)  
+**Flow:**
+
+1. 시스템이 사용 내용의 타입 또는 길이 오류를 알리고 새 기록을 만들지 않는다.
+2. 제출자가 사용 내용을 수정한다.
+3. Use case continues at step 4.
+
+## Postconditions
+
+### Success Postconditions
+
+- 지출 내역이 제출 상태로 기록되어 있다
+- 제출자에게 접수 번호가 부여되어 있다
+
+### Failure Postconditions
+
+- 지출 내역이 제출 상태로 기록되지 않는다
+- 기존에 기록된 지출 내역은 변경되지 않는다
+
+## Business Rules
+
+### BR-001: 금액 조건
+
+제출하는 지출 금액은 0보다 커야 한다.
+
+### BR-002: 사용 내용 조건
+
+사용 내용은 선택 입력이다. 생략·null·빈 문자열은 빈 문자열로 기록한다. 그 밖의 값은 문자열이어야 하고, Unicode code point 기준 200개 이하여야 한다. UTF-16 code unit 수나 사용자 인식 글자 단위로 세지 않는다. 초과 또는 타입 오류는 기록 전에 거부하며 기존 기록을 보존한다. 이 조건은 로컬 예제 파일럿의 결정이고 실제 업무 정책은 미검토다.

package/docs/modernization/evidence/local-pilot-20261003/project/docs/use_cases.puml

@@ -0,0 +1,12 @@
+@startuml Use Cases Overview
+left to right direction
+
+actor "제출자" as submitter
+
+rectangle "지출 정산 시스템" {
+    usecase "UC-001\n지출 내역 제출" as UC001
+}
+
+submitter --> UC001
+
+@enduml

package/docs/modernization/evidence/local-pilot-20261003/project/docs/vision.md

@@ -0,0 +1,21 @@
+# Vision
+
+> Status: Reviewed
+
+## Product
+
+지출 정산 시스템
+
+## Problem
+
+팀 구성원이 지출 내역을 구두나 메신저로 보고하면 승인자가 금액과 사용 내용을 다시 확인해야 하므로 누락과 착오가 생긴다.
+
+## Outcome
+
+제출자가 지출 내역을 제출하면 접수 번호를 받고, 승인자가 검토할 수 있는 상태가 된다.
+
+## Non-Goals
+
+- 지출 승인과 반려 결정
+- 회계 시스템으로의 자동 전기
+- 지출 증빙 이미지의 자동 인식

package/docs/modernization/evidence/local-pilot-20261003/project/src/expense.mjs

@@ -0,0 +1,48 @@
+/** Process-local persistence for the bounded UC-001 smoke. */
+export class InMemoryExpenseStore {
+  #records = [];
+  #failNext = false;
+
+  failNextWrite() {
+    this.#failNext = true;
+  }
+
+  insert(expense) {
+    // UC-001 A2: fail before mutation, preserving every earlier record.
+    if (this.#failNext) {
+      this.#failNext = false;
+      throw new Error('Expense persistence failed');
+    }
+    const record = structuredClone({
+      ...expense,
+      receiptId: String(this.#records.length + 1),
+    });
+    this.#records.push(record);
+    return structuredClone(record);
+  }
+
+  list() {
+    return structuredClone(this.#records);
+  }
+}
+
+export function submitExpense(store, { amount, description = '' }) {
+  // UC-001 BR-001 / A1: no coercion or non-finite monetary amounts.
+  if (!Number.isFinite(amount) || amount <= 0) {
+    throw new RangeError('Amount must be a positive finite number');
+  }
+  // Pilot UC-001 BR-002 / A3: validate before any store mutation.
+  const normalizedDescription = description ?? '';
+  if (typeof normalizedDescription !== 'string') {
+    throw new TypeError('Description must be a string');
+  }
+  if (Array.from(normalizedDescription).length > 200) {
+    throw new RangeError('Description must be at most 200 Unicode code points');
+  }
+  return store.insert({
+    amount,
+    description: normalizedDescription,
+    status: 'submitted',
+    submitted_at: new Date().toISOString(),
+  });
+}

package/docs/modernization/evidence/local-pilot-20261003/project/tests/expense.test.mjs

@@ -0,0 +1,116 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { InMemoryExpenseStore, submitExpense } from '../src/expense.mjs';
+
+test('UC-001 success persists amount, description, submitted state and receipt', () => {
+  const store = new InMemoryExpenseStore();
+  const first = submitExpense(store, { amount: 12000, description: '팀 회식' });
+  assert.equal(first.amount, 12000);
+  assert.equal(first.description, '팀 회식');
+  assert.equal(first.status, 'submitted');
+  assert.match(first.receiptId, /^\d+$/);
+  assert.ok(Number.isFinite(Date.parse(first.submitted_at)));
+  assert.deepEqual(store.list(), [first]);
+  const second = submitExpense(store, { amount: 0.01 });
+  assert.notEqual(second.receiptId, first.receiptId);
+  assert.equal(store.list().length, 2);
+  first.amount = 1;
+  const snapshot = store.list();
+  snapshot[0].description = 'changed';
+  snapshot.pop();
+  assert.equal(store.list()[0].amount, 12000);
+  assert.equal(store.list()[0].description, '팀 회식');
+  assert.equal(store.list().length, 2);
+});
+
+for (const amount of [0, -1, -100, NaN, Infinity, -Infinity, '12000', null, undefined]) {
+  test(`UC-001 BR-001/A1 rejects ${String(amount)} without changing prior state`, () => {
+    const store = new InMemoryExpenseStore();
+    submitExpense(store, { amount: 25, description: 'earlier' });
+    const before = store.list();
+    assert.throws(() => submitExpense(store, { amount }), {
+      name: 'RangeError', message: 'Amount must be a positive finite number',
+    });
+    assert.deepEqual(store.list(), before);
+  });
+}
+
+test('TC-001 service slice permits correction from -100 to 12000', () => {
+  const store = new InMemoryExpenseStore();
+  assert.throws(() => submitExpense(store, { amount: -100, description: '팀 회식' }), RangeError);
+  assert.deepEqual(store.list(), []);
+  const record = submitExpense(store, { amount: 12000, description: '팀 회식' });
+  assert.deepEqual(store.list(), [record]);
+  assert.equal(record.amount, 12000);
+  assert.equal(record.description, '팀 회식');
+  assert.equal(record.status, 'submitted');
+  assert.ok(record.receiptId);
+});
+
+test('UC-001 A2 storage failure preserves earlier records and permits recovery', () => {
+  const store = new InMemoryExpenseStore();
+  const first = submitExpense(store, { amount: 100, description: 'earlier' });
+  const before = store.list();
+  store.failNextWrite();
+  assert.throws(() => submitExpense(store, { amount: 200, description: 'failed' }),
+    { message: 'Expense persistence failed' });
+  assert.deepEqual(store.list(), before);
+  const recovered = submitExpense(store, { amount: 300, description: 'recovered' });
+  assert.notEqual(recovered.receiptId, first.receiptId);
+  assert.deepEqual(store.list(), [first, recovered]);
+});
+
+for (const [label, unit] of [['ASCII', 'a'], ['astral Unicode', '😀']]) {
+  test(`UC-001 BR-002 accepts 200 ${label} code points`, () => {
+    const store = new InMemoryExpenseStore();
+    const description = unit.repeat(200);
+    const record = submitExpense(store, { amount: 12000, description });
+    assert.equal(record.description, description);
+    assert.equal(Array.from(record.description).length, 200);
+    assert.deepEqual(store.list(), [record]);
+  });
+  test(`UC-001 BR-002/A3 rejects 201 ${label} code points without mutation`, () => {
+    const store = new InMemoryExpenseStore();
+    submitExpense(store, { amount: 25, description: 'earlier' });
+    const before = store.list();
+    assert.throws(() => submitExpense(store, { amount: 12000, description: unit.repeat(201) }), {
+      name: 'RangeError', message: 'Description must be at most 200 Unicode code points',
+    });
+    assert.deepEqual(store.list(), before);
+  });
+}
+
+for (const [label, description] of [['number', 42], ['array', []], ['object', {}]]) {
+  test(`UC-001 BR-002/A3 rejects ${label} description without mutation`, () => {
+    const store = new InMemoryExpenseStore();
+    submitExpense(store, { amount: 25, description: 'earlier' });
+    const before = store.list();
+    assert.throws(() => submitExpense(store, { amount: 12000, description }), {
+      name: 'TypeError', message: 'Description must be a string',
+    });
+    assert.deepEqual(store.list(), before);
+  });
+}
+
+for (const [label, description] of [['omitted', undefined], ['null', null], ['empty', '']]) {
+  test(`UC-001 BR-002 normalizes ${label} optional description to empty string`, () => {
+    const store = new InMemoryExpenseStore();
+    const input = { amount: 12000 };
+    if (label !== 'omitted') input.description = description;
+    const record = submitExpense(store, input);
+    assert.equal(record.description, '');
+    assert.deepEqual(store.list(), [record]);
+  });
+}
+
+test('TC-002 service slice corrects 201 to 200 and preserves earlier records', () => {
+  const store = new InMemoryExpenseStore();
+  const first = submitExpense(store, { amount: 25, description: 'earlier' });
+  const before = store.list();
+  assert.throws(() => submitExpense(store, { amount: 12000, description: 'a'.repeat(201) }), RangeError);
+  assert.deepEqual(store.list(), before);
+  const corrected = submitExpense(store, { amount: 12000, description: 'a'.repeat(200) });
+  assert.equal(corrected.description, 'a'.repeat(200));
+  assert.notEqual(corrected.receiptId, first.receiptId);
+  assert.deepEqual(store.list(), [first, corrected]);
+});

package/docs/modernization/evidence/local-pilot-20261003/scope.json

@@ -0,0 +1,31 @@
+{
+  "kind": "local_example_service_slice",
+  "base_revision": "fcf5ebc24bcd5e49148290a65ac6e1a5c4b22ba6",
+  "original_project_root": "/private/tmp/aiwf-uc001-pilot-l07zou4o/project",
+  "archive_project_root": "/Users/moonklabs/workspace-plugin/aiwf/docs/modernization/evidence/local-pilot-20261003/project",
+  "human_review": "not_recorded",
+  "human_active_time": "not_measured",
+  "reviewed_plan_sha256": "426d38f8d52001678083979ca7418c64c6d0b780fa8ef504aec1d6aa5c6b7ab8",
+  "node": "v22.23.1",
+  "python": "Python 3.14.8",
+  "final_input_sha256": {
+    "docs/entity_model.md": "aeb25fc9017964259e74f99220b87efe13b722bffa716b1b12f3b82f9c7ee5d8",
+    "docs/glossary.md": "093fc46be4b64534e670c046d935fce2287246190390d119f4c2edf43b7aedd9",
+    "docs/plans/UC-001.md": "e54f99e9d9cea07c2f74979f2bd2b0295d451eaf713ade031f76630d8a453491",
+    "docs/requirements.md": "d6190c0cfe5b43cd1fa7ba46fb252a558cc2854b0a5523cce7c2cf34db2c5254",
+    "docs/test_cases/TC-001-submit-expense.md": "f47b50f116ac8af187daf8915382c3a7e084d0110840b8b2cd0413f5d9a5d3b2",
+    "docs/test_cases/TC-002-description-limit.md": "516fa1b0252d8870fe773bcd56b89b1086f45a7f792a573635395e2a89780745",
+    "docs/use_cases/UC-001-submit-expense.md": "f41984bc93f5d352f92bc3f62a1bc6d1dae3d5e931ed5b7ce4d44506afbcf93c",
+    "docs/use_cases.puml": "b693ab2ddf7896b404a5193acd1fe65c3b4e0bb768df56a54360dc0f8c3a412d",
+    "docs/vision.md": "52fabfa494c1419bc1045f3404e26478a523a52c0f9910c40ac0199a7a9455fd",
+    "src/expense.mjs": "8f434f4614809a9ec3c478235232bc0a14b586fab6e7a6c4467e91d7040c0669",
+    "tests/expense.test.mjs": "90b7203d0933c09b63d3d2ba1e302bb45eef8932f2d54837d27194e82a9ad439"
+  },
+  "tool_sha256_at_archive": {
+    "src/cli/spec-cli.js": "52696829099edd56650e7966c14519dd12d09f7368077d63b28e10ad0e905a5c",
+    "src/lib/spec-workflow.js": "1c23a091ac0ed32812adb2f5c889d08fdf8427583f734e8b22eddb1895fa709b",
+    "plugins/aiwf-core/skills/spec-review/scripts/spec_lint.py": "8a70d669f165870045c2174c47073cd3496f9da40de658d9695e876e6620f031",
+    "plugins/aiwf-core/skills/use-case-spec/scripts/validate_use_case.py": "3a4cee5406639eb5406d8ec01bde4d7488ff31e3b8500566011a884bb6622be9",
+    "plugins/aiwf-core/skills/test-case/scripts/bpmn_paths.py": "8821d2fac8334219dda5271ab366d0f681a6a51545aa94bd462964c3598be8fb"
+  }
+}

package/docs/modernization/reviews/2026-10-03-claude-cli/CONTRACTS.ko.md

@@ -0,0 +1,122 @@
+# Claude 계획 리뷰 — 검증·실행 기록 계약
+
+작성: 2026-10-03. 상태: **AI 리뷰 완료, 휴먼 리뷰 대기**.
+
+[검토 대상 계획](../../CLI-PRODUCTIVITY.ko.md), [통합 판단](../../CLAUDE-PLAN-REVIEW-2026-10-03.ko.md).
+
+- 실제 CLI: Claude Code `2.1.288`.
+- 세션 ID: `cab3cadc-37d4-4ebb-a699-0d122c4c3baa`.
+- 요청·관측 모델: `claude-sonnet-5-5` (`modelUsage` 확인).
+- 요청 effort: `high`. 결과 JSON에 실제 적용 effort가 없어 관측 effort는 미확인.
+- 검토 당시 계획 SHA256: `426d38f8d52001678083979ca7418c64c6d0b780fa8ef504aec1d6aa5c6b7ab8`.
+- 실행 결과: exit 0, `subtype: success`, `is_error: false`, 권한 거부 0, stderr 0 bytes.
+- 도구: `Glob, Grep, Read`. 원문 결과를 별도 수정 없이 아래에 옮겼다. 행 번호는 위 hash의 계획을 기준으로 한다.
+- 셸·테스트 실행 및 파일 편집은 리뷰 세션에 제공하지 않았다. 모델 리뷰는 자동 테스트 통과나 휴먼 승인이 아니다.
+
+아래는 최종 리뷰 답변이며, 프롬프트·전체 세션 JSON·실행 로그는 저장소 밖의 비공개 임시 경로에 유지한다.
+
+---
+
+# review-2 결과: 검증/실행 기록 계약 · 기존 코드 정합성 · 최소 구현 복잡성
+
+## 결론: 조건부 적합
+
+계획의 현황 진술은 코드와 맞습니다. 위험을 줄이는 방향도 타당합니다. 다만 "UC/BR/TC→check 매핑과 검사 정의의 위치·신뢰 경계"가 정해져 있지 않습니다. 이 항목은 `fresh` 판정과 opt-in runner 경계의 전제입니다. 또 두 번째 단계를 "하나의 기능 단위"로 묶은 범위(15, 93행)가 첫 구현으로는 큽니다. 아래 P1을 정하고 P2의 범위 축소를 반영하면 구현 착수에 적합합니다.
+
+## 코드와 대조해 맞는 진술 (사실)
+
+- 현재 명령은 `init/pin/check/packet` 4개입니다 (`src/cli/spec-cli.js:33-58`).
+- evidence 입력은 top-level `checks/unverified`만, 검사별로는 `name/command/status/log`만 허용합니다. 그 외 필드는 `evidence_unknown_field`로 거부합니다 (`src/lib/spec-workflow.js:630-661`). 계획의 28행과 121행은 맞습니다.
+- packet은 생성 시점에 `checkSpec`을 호출하고 로그를 읽습니다. `trust: 'reported_untrusted'`와 `acceptance: 'not_recorded'`를 기록합니다 (`spec-workflow.js:755-808`).
+- 로그는 1 MiB 이하의 정확한 UTF-8만 허용합니다 (`spec-workflow.js:734-742`).
+- 모든 구조 검사는 lint가 통합 실행합니다. 누락된 validator와 BPMN parser는 INFO로만 남습니다 (`spec_lint.py:358-364`, `538-544`). lint는 INFO만 있으면 exit 0을 반환합니다 (`spec_lint.py:1210-1212`).
+- `--trace`는 항상 exit 0을 반환하고 lint를 실행하지 않습니다 (`spec_lint.py:1160-1168`).
+- workflow가 이미 `spec_lint.py --strict --no-baseline`을 지시하므로 verify 설계와 일치합니다 (`plugins/aiwf-spec/skills/workflow/SKILL.md:28`).
+
+## 지적
+
+### P1. 검사 정의·매핑의 저장 위치와 신뢰 경계가 미정이다 (`CLI-PRODUCTIVITY.ko.md:97, 102, 111, 113`)
+
+- **근거(사실):**
+  - pin은 `SPEC_DIRS`와 lint baseline만 추적합니다. 매핑이나 검사 정의 파일을 `docs/` 밖에 두면 바뀌어도 drift로 잡히지 않습니다 (`spec-workflow.js:27-39`).
+  - 계획은 "프로젝트가 명시적으로 정의한 검사 ID"를 실행한다고 쓰지만, 정의 파일의 위치·schema는 정하지 않았습니다.
+  - config hash는 receipt 기록 항목(102행)일 뿐, 실행 전 신뢰 확인에 쓰이지 않습니다.
+- **영향(추론):** 저장소에 들어온 정의가 argv를 그대로 실행하게 됩니다. 정의가 바뀌어도 pin이 반응하지 않으면 UC/BR/TC→check 연결의 최신성(`fresh`)을 보장할 수 없습니다. dry-run만으로는 "누가 이 명령을 실행해도 된다고 승인했는가"가 남습니다.
+- **최소 수정안:**
+  1. 정의 파일의 위치와 pin 포함 여부를 계획에서 결정합니다.
+  2. 정의 hash를 receipt에 기록하는 것과 별개로, runner는 실행 시점의 정의 hash를 사용자가 지정한 값과 대조하거나 `--yes` 같은 명시적 호출 입력을 요구합니다. 이 동작 자체가 "묵시 승인 금지" 경계가 됩니다.
+  3. UC/BR/TC ID 존재 검사는 새 파서를 만들지 않고 `spec_lint.py --trace --format json` 출력을 재사용합니다. 이 재사용이 가능한지는 trace JSON 스키마를 읽어 확인하지 못했습니다.
+
+### P2. verify의 "전체 통과" 판정이 lint 출력 해석에 의존하는데 오류 분기가 빠졌다 (`:83-87`, `:134`)
+
+- **근거(사실):**
+  - `load_sibling`은 모든 예외를 삼키고 `None`을 반환합니다 (`spec_lint.py:177-179`).
+  - INFO는 UC 파일이 있을 때(`check_structure`의 `if not specs: return`), 또는 BPMN 파일이 있을 때만 나옵니다. "로드 성공"의 신호는 INFO가 없다는 사실뿐입니다.
+  - Python 미설치나 `spawn ENOENT`, 버전 불일치, 미처리 예외는 계획에 분류가 없습니다. 미처리 예외도 exit 1이라 lint 오류 exit 1과 구분되지 않습니다.
+  - lint의 `--docs` 오류는 exit 2입니다 (`spec_lint.py:1155-1158`). CLI의 exit 2는 사용법 오류입니다 (`spec-cli.js:23`).
+- **영향:** stdout JSON 파싱 성공 여부를 검증하지 않으면 실행 오류가 `lint failed`로, 최악에는 조용한 incomplete 누락으로 이어집니다.
+- **최소 수정안:**
+  1. verify 결과 상태를 `lint_failed`, `tool_error`, `incomplete`, `drift`로 분리합니다. 이때 JSON의 summary 필드가 존재하는지로 판정합니다.
+  2. Python 자식 프로세스에 `-B`를 붙이고, lint 실행 전후 `computePinDigest`를 재계산해 읽기 중 변경도 알립니다. 현재 `load_sibling`은 이미 bytecode 쓰기를 막고 있어(`:171`) readonly 경계 자체는 구현 가능합니다. 다만 CLI 쪽에서도 강제하는 편이 안전합니다.
+  3. verify의 exit code 체계(0/1/2와 incomplete 처리)를 `--help`와 문서에 명시합니다 (`spec-cli.js:148`).
+
+### P2. 첫 runner 범위가 과하다 (`:15, 93-109`)
+
+- **근거(사실):**
+  - 한 단위에 포함된 항목은 다음과 같습니다. 선언 범위의 새 파일을 포함하는 입력 manifest, 제외 정책, 환경 allowlist, 3상태 `fresh/stale/unknown`, 중단 receipt, packet v2입니다.
+  - 현재 코드에는 glob 기능이 없고 spec 디렉터리를 수작업으로 순회합니다 (`spec-workflow.js:142-174`). `package.json`은 Node 20+를 선언하며 의존성이 없습니다 (`package.json:43-45`).
+- **추론:** Node 20 내장 API로 선언 입력의 glob을 만드는 비용이 불확실합니다. 이 점은 확인하지 못했습니다.
+- **최소 수정안(첫 구현):**
+  - 입력은 **명시적 파일 경로 목록의 sha256**으로 시작합니다. glob, 신규 파일 탐지, 환경 allowlist는 파일럿 후로 미룹니다. 환경 allowlist는 비밀값 위험과 비교 대상 정의가 모두 필요합니다.
+  - 상태는 receipt에 `outcome`(passed/failed/start_error/timeout/aborted/not_run), 비교 시 `fresh/stale`로 줄입니다. 선언 입력 hash를 읽지 못한 경우는 `stale`이 아니라 `unknown` 하나로만 둡니다.
+  - 지금 계획의 방향(범위 밖 의존성을 제외 목록으로 명시)은 유지하되, 선언은 사용자가 쓴 경로 목록으로 한정합니다.
+
+### P2. 1 MiB 로그 정책이 runner의 완료 조건과 충돌할 수 있다 (`:117`)
+
+- **근거(사실):** 계획은 "이 제한 안에서 완전한 로그를 수집"하라고 하고, 초과를 성공으로 남기지 않는다고 합니다. 이 제한은 packet이 로그 본문을 packet에 포함하기 때문입니다 (`spec-workflow.js:734, 743-748`).
+- **영향(추론):** Gradle, Maven, Playwright 같은 검사는 1 MiB를 넘기기 쉽습니다. 그러면 정상 통과한 검사가 `incomplete`로 처리되어 runner가 쓸모없어질 수 있습니다. 계획은 이때의 동작을 정하지 않았습니다.
+- **최소 수정안:** receipt의 로그 파일(전체, hash·bytes)과 packet에 포함되는 발췌를 분리합니다. 초과분은 truncated 표시로 자르거나, 초과 시 packet 생성은 거부하되 receipt에는 전체를 보존합니다. 어느 쪽이든 계획에서 하나를 정해야 합니다.
+
+### P3. packet 버전 용어 불일치와 baseline 동작 미기재
+
+- **근거(사실):** 실제 packet은 숫자 `schema_version: 1`이고 `schema` 문자열 필드는 없습니다 (`spec-workflow.js:785`). 반면 Sprintable 설계안은 `"schema": "aiwf.review_packet.v1"`을 씁니다 (`SPRINTABLE.ko.md:33`). 이 불일치는 packet v2를 정의할 때 소비자 호환 계약의 혼선이 됩니다.
+- **근거(사실):** verify는 `--no-baseline`을 강제합니다. 이미 수용된 baseline이 있는 프로젝트는 영원히 exit 0이 안 될 수 있습니다. 계획에 이 동작의 명시가 없습니다.
+- **최소 수정안:** packet v2 착수 시 식별자 방식을 하나로 정합니다. verify 문서에 "baseline 무시, 수용 항목은 findings로 계속 보고"를 한 줄 추가합니다.
+
+## 유지할 강점
+
+- `reported_untrusted`, `acceptance: not_recorded`, awaiting_review를 유지하고 packet exit 0과 runner exit 0의 의미를 분리했습니다 (127행).
+- 파일럿 선행, 병렬·Sprintable·자동 선택을 미루는 우선순위와 측정 지표(수작업 시간, 누락·오래된 로그 재사용 건수)가 적절합니다.
+- "sidecar 파일만으로 packet이 출처를 검증하지 않는다", "receipt는 변조 불가 자료가 아니다"라는 보장 한계를 이미 명시했습니다 (125행). 이 부분은 과장이 아닙니다.
+- verify와 runner의 readonly/opt-in 분리는 구현 가능합니다. 현행 `checkSpec`은 읽기 전용이고, lint는 `--update-baseline` 없이는 쓰지 않습니다 (`spec_lint.py:1176-1180`).
+
+## 이견 없음
+
+- 계획의 "현재 CLI는 lint를 실행하지 않는다"와 "INFO만이면 exit 0"이라는 진술은 코드와 일치합니다.
+- 문서 우선 원칙(원문·한글본·hash 동시 갱신, awaiting_review 유지)은 이 계획과 충돌하지 않습니다.
+
+## 미확인·휴먼 결정
+
+- **미확인:**
+  - Windows `.cmd` 실행과 프로세스 트리 종료, Node 20에서의 glob 대체 비용.
+  - `--trace --format json`이 UC/BR/TC 전체 연결을 담는지 (스키마 미확인).
+  - 계획의 수치(문서 70개, 검토 0개)와 문서 변경 후 hash·README·catalog 일관성은 이 세션 담당 밖이라 확인하지 않았습니다.
+  - 계획 13행의 선행 파일럿 필요성은 다른 세션의 평가 범위입니다.
+- **휴먼 결정:**
+  1. 검사 정의 파일의 위치와 pin 포함 여부, 실행 전 신뢰 확인 방식 (P1).
+  2. 로그 1 MiB 초과 시 정책 (P2).
+  3. 첫 runner의 입력 선언 방식(명시 경로 목록)과 Node 20 하한 (140행의 별도 결정과 연결).
+  4. packet v2의 식별자 방식(P3).
+
+## 수행 기록
+
+- **파일 변경 없음.**
+- **셸·테스트·검사 실행 없음.** `npm test`나 `docs:check`는 실행하지 않았고, 계획 170-175행의 통과 기록을 재현하지 않았습니다.
+- 다른 세션 결과는 보지 않았습니다.
+- **권한 거부 없음.**
+- 읽은 파일:
+  - `AGENTS.md`, `docs/ko-skills/README.md`, `docs/modernization/CLI-PRODUCTIVITY.ko.md`, `docs/modernization/DIRECTION.ko.md`
+  - `src/lib/spec-workflow.js`, `src/cli/spec-cli.js`, `package.json`
+  - `spec_lint.py`(일부), workflow `SKILL.md`(일부), `SPRINTABLE.ko.md`(일부)
+- `tests/spec-workflow/*.test.mjs`는 매칭 횟수만 확인했습니다. 본문은 읽지 않았습니다.
+- 시스템 컨텍스트에 있던 `CLAUDE.md`의 내용은 따랐습니다.