feature-loop-harness-cli 0.1.0

package/templates/default/.flh/docs/PROJECT_WORKFLOW.md

@@ -0,0 +1,270 @@
+# PROJECT_WORKFLOW.md
+
+하네스가 실제 프로젝트에 적용할 프로젝트 전체 워크플로우를 정의한다.
+
+이 문서는 하네스 자체의 MVP, 아키텍처, DB, API, 프론트엔드 설계를 기록하는 문서가 아니다.
+이 문서는 앞으로 하네스를 적용받는 실제 프로젝트가 어떤 순서로 문서를 완성하고 기능 구현 단계로 진입해야 하는지를 설명한다.
+
+---
+
+## Purpose
+
+하네스의 핵심 목적은 실제 구현을 기능 단위로 통제하는 것이다.
+
+이를 위해 기능 구현에 들어가기 전 실제 프로젝트는 다음 산출물을 순서대로 준비해야 한다.
+
+- MVP 정의
+- 시스템 아키텍처 정의
+- 기능 목록 정의
+- 데이터 모델 baseline 정의
+- API 경계 정의
+- 디자인 지침 정의
+- 기능 단위 구현 진입
+
+프로젝트 레벨 상태 전이는 `.flh/runtime/STATE.md`와 `.flh/workflow/*` 설정으로 관리한다.
+기능 단위 구현은 `FEATURE_IMPLEMENTATION` 상태에서만 `.flh/docs/FEATURE_IMPLEMENTATION_PIPELINE.md`를 기준으로 진행한다.
+
+---
+
+## Runtime Files
+
+프로젝트 전체 워크플로우는 다음 파일들이 제어한다.
+
+- `.flh/runtime/STATE.md`: 현재 상태, 완료 상태, 승인 기록
+- `.flh/workflow/flow.yml`: 상태 목록, 상태별 허용 request_type, next state
+- `.flh/workflow/state-actions.yml`: 현재 상태에서 에이전트가 수행할 짧은 체크리스트와 허용 write 범위
+- `.flh/workflow/docs-spec.yml`: 문서별 완료 판정 기준
+- `.flh/workflow/transition-guards.yml`: 상태 전이별 guard 조합
+
+사람이 읽는 설명은 이 문서에 둔다.
+훅이 파싱하는 규칙은 `.flh/workflow/*.yml`에 둔다.
+
+---
+
+## State Flow
+
+```text
+MVP_DEFINITION
+-> ARCHITECTURE_DESIGN
+-> FEATURE_INDEX_DEFINITION
+-> DATA_MODEL_DEFINITION
+-> API_DESIGN
+-> FRONTEND_DESIGN
+-> FEATURE_IMPLEMENTATION
+```
+
+상태 전이는 기본적으로 순차적으로만 진행한다.
+현재 상태와 요청이 요구하는 상태 사이에 여러 단계가 있으면, 중간 transition guard를 모두 통과해야 한다.
+
+---
+
+## Manual Step Skip
+
+사용자는 `/d` 문서 및 하네스 제어 모드를 사용해 프로젝트 workflow 단계를 명시적으로 skip 처리할 수 있다.
+
+skip은 하네스가 자동 판정하지 않는다.
+특정 단계가 현재 프로젝트에 필요 없는지 여부는 사용자가 책임지는 수동 운영 결정이다.
+
+단, 다음 기반 단계는 이후 workflow 신뢰도를 크게 좌우하므로 skip하지 않는다.
+
+- `MVP_DEFINITION`
+- `ARCHITECTURE_DESIGN`
+- `FEATURE_INDEX_DEFINITION`
+
+skip된 단계의 산출물은 completed artifact로 가정하지 않는다.
+필요하면 `.flh/runtime/STATE.md`에 skip한 상태와 이유를 기록한다.
+
+---
+
+## 1. MVP Definition
+
+실제 프로젝트의 MVP 범위를 정의하는 단계다.
+
+템플릿 문서:
+
+- `docs/MVP.md`
+
+이 문서는 하네스 패키지에서 템플릿으로 제공된다.
+실제 프로젝트가 시작되면 사용자가 해당 프로젝트의 내용으로 채운다.
+
+완료 기준은 `.flh/workflow/docs-spec.yml`의 `mvp` 항목을 따른다.
+
+---
+
+## 2. Architecture Design
+
+실제 프로젝트의 시스템 아키텍처를 정의하는 단계다.
+
+템플릿 문서:
+
+- `docs/ARCHITECTURE.md`
+- `docs/source-layout.yml`
+
+포함해야 하는 대표 항목:
+
+- 시스템 개요
+- 기술 스택
+- source layout
+- package layout
+- testing strategy
+- 주요 모듈
+- 데이터 흐름
+- 외부 의존성
+- 실행 환경
+- scaffold 정책
+- 아키텍처 제약사항
+
+`docs/source-layout.yml`은 아키텍처 단계에서 결정한 source directory, project-level persistence 여부, database provider, package별 framework/runtime/language/module, testing tool, lint/format tooling을 기계가 읽을 수 있게 기록하는 manifest다.
+에이전트는 이 파일을 아키텍처 단계의 필수 결정 체크리스트로 사용하고, TODO 또는 누락 필드가 있으면 사용자에게 먼저 질문한다.
+에이전트는 이 파일에 적힌 source directory만 생성하고, 빈 디렉토리에는 `.gitkeep`만 둔다.
+아키텍처 단계에서는 framework scaffold나 실제 구현 코드를 생성하지 않는다.
+테스트 도구 설치와 설정은 최초 기능 구현 전에 수행하는 source package scaffold baseline에서 다룬다.
+DB 사용 여부는 `project.persistence.database_required`에 기록한다.
+DB를 사용하지 않는 프로젝트는 `database_required: false`와 `database_provider: none`으로 표시한다.
+
+완료 기준은 다음을 따른다.
+
+- `.flh/workflow/docs-spec.yml`의 `architecture` 항목
+- `.flh/workflow/docs-spec.yml`의 `source_layout` 항목
+- `.flh/workflow/transition-guards.yml`의 `ARCHITECTURE_DESIGN_TO_FEATURE_INDEX_DEFINITION` 항목
+
+---
+
+## 3. Feature Index Definition
+
+실제 프로젝트의 기능 후보 목록과 우선순위를 정의하는 단계다.
+
+템플릿 문서:
+
+- `docs/features/feature-index.md`
+
+이 단계에서는 기능별 상세 구현 문서를 만들지 않는다.
+기능 목록, 요약, 우선순위, 핵심 요구사항만 정리한다.
+
+기능의 실제 진행 상태는 `feature-index.md`가 아니라 `docs/features/*/` 디렉토리 위치를 기준으로 판단한다.
+
+완료 기준은 `.flh/workflow/docs-spec.yml`의 `feature_index` 항목을 따른다.
+
+---
+
+## 4. Data Model Definition
+
+실제 프로젝트의 데이터 모델 baseline을 정의하는 단계다.
+이 단계는 Prisma 파일을 생성하는 단계가 아니라, 프로젝트 전체 DB schema의 단일 truth source인 `docs/DB_SCHEMA.md`를 완성하는 단계다.
+
+템플릿 문서:
+
+- `docs/DB_SCHEMA.md`
+
+금지되는 작업:
+
+- `app/be/prisma/schema.prisma` 생성/수정
+- `app/be/prisma/migrations/**` 생성/수정
+- `app/be/package.json` 생성/수정
+- 루트 `package.json`의 DB forwarding script 생성/수정
+- 실제 DB 서버 배포
+
+목표는 `docs/DB_SCHEMA.md`를 `schema.prisma`로 즉시 변환할 수 있는 Prisma-ready 명세로 확정하는 것이다.
+entity field, Prisma type, DB type, nullable, default, unique, index, relation, enum, constraint, ownership, lifecycle, Prisma mapping note, migration note가 문서 안에 충분히 구체적으로 있어야 한다.
+
+실제 `schema.prisma`, baseline migration, DB deploy/verify script 생성과 실제 DB 서버 배포/검증은 DB-backed project에서만 `FEATURE_IMPLEMENTATION` 상태의 `1.6. Baseline DB Deployment`에서 수행한다.
+DB를 사용하지 않는 프로젝트는 같은 단계에서 DB 배포를 실행하지 않고 skip approval을 기록한다.
+두 경우 모두 결과는 `.flh/runtime/STATE.md`의 `approvals.database_baseline`에 기록한다.
+
+완료 기준은 다음을 따른다.
+
+- `.flh/workflow/docs-spec.yml`의 `db_schema` 항목
+- `.flh/workflow/transition-guards.yml`의 `DATA_MODEL_DEFINITION_TO_API_DESIGN` 항목
+
+---
+
+## 5. API Design
+
+실제 프로젝트의 API 경계와 공통 규칙을 정의하는 단계다.
+
+템플릿 문서:
+
+- `docs/API.md`
+
+포함해야 하는 대표 항목:
+
+- API 영역
+- endpoint 초안
+- 인증/인가 원칙
+- request/response 규칙
+- 에러 응답 규칙
+
+완료 기준은 `.flh/workflow/docs-spec.yml`의 `api` 항목을 따른다.
+
+---
+
+## 6. Frontend Design
+
+실제 프로젝트의 디자인 지침을 확정하는 단계다.
+
+산출물:
+
+- `docs/DESIGN.md`
+
+이 단계에 처음 진입하면 사용자에게 다음 중 하나를 선택하게 한다.
+
+1. 외부에서 사용 중인 `DESIGN.md`를 가져와 사용한다.
+2. 이 하네스 흐름 안에서 `DESIGN.md`를 함께 작성한다.
+
+외부 `DESIGN.md`를 사용하는 경우 해당 파일은 frontmatter나 하네스 템플릿 섹션을 갖지 않을 수 있다.
+이 경우 `.flh/runtime/STATE.md`의 `approvals.design.approved`가 `true`이면 완료 조건을 통과할 수 있다.
+
+직접 작성하는 경우 완료 기준은 `.flh/workflow/docs-spec.yml`의 `design` 항목을 따른다.
+
+전이 조건은 `docs/DESIGN.md` 완료 또는 `approvals.design.approved` 중 하나를 허용한다.
+
+---
+
+## 7. Feature Implementation
+
+프로젝트 전체 워크플로우가 완료되어 기능 단위 구현으로 진입 가능한 상태다.
+
+이 상태 이후 실제 구현은 다음 기준을 따른다.
+
+- `AGENTS.md`
+- `.flh/docs/FEATURE_IMPLEMENTATION_PIPELINE.md`
+- `docs/features/feature-index.md`
+- `docs/features/*/FEAT-XXX-*` 내부 기능 문서
+
+첫 기능 구현을 시작하기 전에는 baseline DB deployment를 확인한다.
+아직 실제 DB 서버에 baseline schema가 배포/검증되지 않았다면 필요한 환경값을 사용자에게 요청하고 배포/검증을 수행한다.
+
+프로젝트 레벨 훅은 기능 구현 세부사항을 판단하지 않는다.
+훅은 프로젝트가 기능 구현 상태에 진입 가능한지만 판단한다.
+
+---
+
+## Template Document Rule
+
+하네스 패키지는 주요 프로젝트 문서를 템플릿 상태로 제공할 수 있다.
+
+템플릿 문서는 존재만으로 완료된 것으로 보지 않는다.
+훅의 전이 검증은 다음 기준을 함께 확인한다.
+
+- frontmatter status
+- 필수 섹션 존재 여부
+- placeholder 제거 여부
+- 최소 내용 충족 여부
+
+현재 하네스 구현 과정에서는 실제 프로젝트의 MVP, 아키텍처, DB, API, 디자인 내용을 작성하지 않는다.
+
+---
+
+## Non-goals
+
+프로젝트 레벨 훅은 다음을 하지 않는다.
+
+- 기능 구현 코드 작성
+- 기능별 테스트 작성
+- 기능별 체크리스트 수행
+- 기능별 설계 세부 판단
+- 일반 workflow 전이 과정에서의 커밋/푸쉬/머지 수행
+- 리팩토링 범위 판단
+
+위 작업은 `FEATURE_IMPLEMENTATION` 상태에서 기능 단위 구현 파이프라인이 관리한다.
+단, `/d` 문서 모드에서 사용자가 명시적으로 요청한 문서/하네스 변경 커밋과 푸쉬는 `AGENTS.md`의 `/d` 예외 규칙을 따른다. 머지는 `/d`에서도 허용하지 않는다.

package/templates/default/.flh/docs/REVIEW_PATCH_PIPELINE.md

@@ -0,0 +1,166 @@
+# Review Patch Pipeline
+
+Review Patch Pipeline은 최초 기능 구현이 끝나고 `docs/features/review/`에 위치한 기능에 대해, 사용자의 수정 요청을 처리하는 lightweight pipeline이다.
+
+이 단계는 full feature implementation pipeline을 다시 실행하지 않는다.
+이미 구현된 기능을 대상으로 최소 범위의 수정, 검증, 품질 점수 갱신, 최종 완료 처리를 수행한다.
+
+---
+
+## 1. Target Feature
+
+`docs/features/review/`에 기능 디렉토리가 있으면, 사용자의 수정 요청은 기본적으로 해당 기능을 대상으로 한다.
+
+`review/`에는 동시에 하나의 기능만 존재해야 한다.
+`review/`에 기능이 있는 동안에는 새 기능 구현을 시작하지 않는다.
+
+수정 요청이 review 대상 기능과 관련 있는지 먼저 확인한다.
+요청 범위가 현재 review 기능과 맞지 않거나, 새 기능 구현에 가까운 경우에는 바로 수정하지 말고 사용자에게 확인한다.
+
+---
+
+## 2. Review Branch and Worktree
+
+Review patch가 source file 변경을 포함하는 경우 main/master에서 직접 수정하거나 커밋하지 않는다.
+
+리뷰 대상 기능마다 하나의 `fix/*` branch/worktree를 생성한다.
+이 branch/worktree는 해당 기능이 `docs/features/done/`으로 이동하기 전까지 계속 재사용한다.
+
+예시:
+
+```text
+feature: docs/features/review/FEAT-001-login
+branch: fix/FEAT-001-login-review
+worktree: FEAT-001-login-review
+```
+
+이미 해당 review branch/worktree가 존재하면 새로 만들지 않고 기존 branch/worktree에서 이어서 작업한다.
+
+source 변경이 없는 docs-only review patch도 review branch/worktree가 이미 있으면 같은 branch/worktree에 포함한다.
+이렇게 하면 사용자가 review 중 요청한 변경사항을 하나의 기능 단위 흐름으로 유지할 수 있다.
+
+---
+
+## 3. Patch Scope
+
+수정은 사용자가 요청한 내용에 한정한다.
+
+관련 없는 리팩토링, 기능 추가, 설계 변경은 하지 않는다.
+수정 중 요구사항 변경이 필요하다고 판단되면, 코드 수정 전에 해당 기능의 `SPEC.md`, `CHECKLIST.md`, `TEST_CASES.md`를 먼저 갱신한다.
+
+변경 범위가 데이터 모델, API 계약, 공통 디자인 규칙에 영향을 준다면 관련 문서도 함께 확인한다.
+단, review patch는 기존 기능을 보정하는 흐름이므로 변경 범위가 커지면 사용자에게 먼저 보고한다.
+
+---
+
+## 4. Patch Log and Artifacts
+
+Review patch 과정에서 생성되는 검증 자료와 실패 기록은 해당 기능 디렉토리의 `artifacts/review-patches/` 아래에 저장한다.
+
+권장 경로:
+
+```text
+docs/features/review/FEAT-XXX-name/artifacts/review-patches/YYYY-MM-DD-short-summary/
+```
+
+저장할 수 있는 항목:
+
+- 사용자 수정 요청 요약
+- 실행한 검증 명령
+- Playwright screenshot, trace, report
+- 실패 원인과 재시도 기록
+- 환경 문제로 검증하지 못한 경우의 blocker 기록
+
+---
+
+## 5. Verification
+
+수정 후 관련 테스트를 실행한다.
+
+UI/UX 변경이 포함된 경우 Playwright 기반 검증을 수행한다.
+Playwright 검증이 실패하면 원인을 수정하고 다시 검증한다.
+
+환경, 의존성, 외부 서비스 문제로 검증이 불가능하면 임의로 통과 처리하지 않는다.
+해당 blocker와 확인 가능한 증거를 `artifacts/review-patches/` 아래에 기록하고 사용자에게 보고한다.
+
+---
+
+## 6. Quality Score
+
+수정이 기능 품질에 영향을 주면 해당 기능의 `QUALITY_SCORE.md`를 갱신한다.
+
+품질 점수 변경이 필요한 경우:
+
+- 요구사항 충족 범위가 바뀐 경우
+- 테스트 또는 검증 결과가 바뀐 경우
+- UI/UX 안정성이 개선되거나 악화된 경우
+- 에러 처리, 접근성, edge case 대응이 바뀐 경우
+
+단순 문구 수정이나 품질 판단에 영향을 주지 않는 작은 정리는 품질 점수를 갱신하지 않을 수 있다.
+
+---
+
+## 7. Commit Policy
+
+Review patch의 기본 커밋 정책은 사용자 명시 커밋 방식이다.
+
+에이전트는 review patch 요청을 받으면 수정, 검증, 필요한 artifacts 기록, 품질 점수 갱신까지 수행할 수 있다.
+다만 커밋은 사용자가 명시적으로 커밋을 요청했을 때 해당 review branch에서 수행한다.
+
+사용자가 커밋을 요청하기 전까지는 같은 review branch/worktree에 변경사항을 유지할 수 있다.
+사소한 수정 요청이 여러 번 이어지는 경우, 사용자가 커밋을 요청하는 시점에 하나의 커밋으로 묶을 수 있다.
+변경 목적이 서로 다르거나 사용자가 분리를 요청한 경우에는 여러 커밋으로 나눌 수 있다.
+
+main/master에는 source 변경을 직접 커밋하지 않는다.
+커밋 범위는 review 대상 기능에 한정한다.
+
+커밋 전에는 다음을 확인한다.
+
+- 변경이 사용자 요청 범위 안에 있는지
+- 관련 테스트 또는 검증을 실행했는지
+- 필요한 artifacts가 feature directory 아래에 기록되었는지
+- 품질 점수 갱신이 필요한지
+
+---
+
+## 8. Completion
+
+사용자가 명시적으로 해당 기능의 검토 완료를 승인하기 전까지 기능 디렉토리는 `docs/features/review/`에 유지한다.
+
+완료 승인으로 볼 수 있는 표현은 명확해야 한다.
+예를 들어 "완료", "done으로 이동", "최종 승인", "이 기능 끝"처럼 review 종료 의도가 분명해야 한다.
+
+사용자가 완료를 승인하면 다음을 수행한다.
+
+1. 최종 검증을 실행한다.
+2. 필요한 품질 점수와 feature index를 갱신한다.
+3. 기능 디렉토리를 `docs/features/review/`에서 `docs/features/done/`으로 이동한다.
+4. 아직 커밋되지 않은 review 변경사항이 있으면 review branch에서 커밋한다.
+5. review branch를 main/master로 merge한다.
+6. review worktree와 branch를 정리한다.
+
+완료 승인이 없다면 review branch/worktree는 유지하고, 이후 같은 review 기능에 대한 수정 요청은 같은 branch/worktree에서 이어서 처리한다.
+
+---
+
+## 9. Conflict Handling
+
+Review patch 중 충돌이 발생하면 관련 파일과 충돌 이유를 먼저 파악한다.
+
+충돌 해결이 단순하고 review 요청 범위 안에 있으면 최소 수정으로 해결한다.
+충돌 원인이 요구사항 변경, 데이터 모델 변경, API 계약 변경처럼 review 범위를 넓히는 경우에는 임의로 해결하지 말고 사용자에게 보고한다.
+
+---
+
+## 10. Rules Summary
+
+- `docs/features/review/`에 있는 기능이 review patch의 기본 대상이다.
+- review patch는 full feature implementation pipeline을 다시 실행하지 않는다.
+- source 변경이 있으면 main/master에서 직접 커밋하지 않는다.
+- 하나의 review 기능은 `done/`으로 이동하기 전까지 하나의 `fix/*` branch/worktree를 재사용한다.
+- review patch commit은 사용자가 명시적으로 커밋을 요청했을 때 수행한다.
+- 수정 범위는 사용자가 요청한 내용에 한정한다.
+- UI/UX 변경은 Playwright 기반 검증을 수행한다.
+- 검증 자료와 blocker는 `artifacts/review-patches/` 아래에 기록한다.
+- 품질에 영향이 있으면 `QUALITY_SCORE.md`를 갱신한다.
+- 사용자가 명시적으로 완료를 승인하기 전까지 `review/`에서 `done/`으로 이동하지 않는다.