feature-loop-harness-cli 0.1.0

package/templates/default/README.md

@@ -0,0 +1,251 @@
+# Feature Loop Harness
+
+![image](https://res.cloudinary.com/dddvvp9de/image/upload/v1780124834/FeatureLoopHarness_zndch9.png)
+
+Feature Loop Harness, 또는 `flh`,는 Codex로 프로젝트를 진행할 때 설계, 문서화, 기능 구현, 리뷰, 커밋 흐름을 일정한 순서로 제한하는 workflow harness다.
+
+핵심은 Codex `UserPromptSubmit` hook, `AGENTS.md`, 문서 템플릿, pre-commit guard를 함께 사용해 “아직 준비되지 않은 작업”이 바로 실행되거나 커밋되는 것을 막는 것이다.
+
+상세 매뉴얼은 [HARNESS_MANUAL.md](HARNESS_MANUAL.md)를 참고한다.
+
+## Install
+
+### Requirements
+
+- `git`
+- `node`
+- `npm`
+- `python3`
+- `PyYAML`
+- `Codex CLI`
+
+Codex Desktop App을 주로 사용하더라도 project-local hook 승인에는 Codex CLI 사용을 권장한다.
+
+### Clone
+
+```sh
+git clone https://github.com/jkuminga/FeatureLoopHarness <PROJECT_DIR>
+cd <PROJECT_DIR>
+```
+
+새 프로젝트 repo로 사용할 경우 `origin`을 본인 repo로 바꾼다.
+
+```sh
+git remote remove origin
+git remote add origin <YOUR_PROJECT_REPO_URL>
+git push -u origin main
+```
+
+기본 브랜치가 `master`라면 `main` 대신 `master`를 사용한다.
+
+### Dependencies
+
+```sh
+npm install
+```
+
+이 명령은 Husky와 lint-staged를 설치하고 Git pre-commit hook을 연결한다.
+
+### Enable Codex Hook
+
+flh는 사용자 요청이 Codex에 전달되기 전에 `UserPromptSubmit` hook으로 현재 상태와 요청 의도를 검사한다.
+
+Codex CLI를 프로젝트 루트에서 실행한다.
+
+```sh
+codex
+```
+
+최초 실행 시 CLI가 project-local hook을 감지하고 실행 승인 여부를 물어볼 수 있다. 자동 안내가 나오지 않으면 Codex CLI 안에서 다음 명령을 실행한다.
+
+```text
+/hooks
+```
+
+`UserPromptSubmit` hook의 설정과 스크립트 경로를 확인한 뒤, Codex가 해당 hook을 실행해도 된다고 승인한다. hook 파일이나 `.codex/hooks.json`을 수정하면 다시 승인해야 할 수 있다.
+
+### Verify
+
+```sh
+npm test
+printf '아키텍처 설계하자' | .codex/hooks/user-prompt-submit.sh
+codex exec '아키텍처 설계하자'
+```
+
+설정이 정상이라면 Codex 실행 시 `UserPromptSubmit` hook이 동작하고, 현재 workflow state에 맞지 않는 요청은 block된다.
+
+## Start A Project
+
+처음 상태는 `.flh/runtime/STATE.md`의 `current_state: MVP_DEFINITION`이다.
+
+Codex에서 MVP 정의부터 시작한다.
+
+```text
+MVP 정리하자
+```
+
+이후 각 단계의 문서를 완성하면 다음 단계 요청을 보낸다. hook은 현재 상태, 요청 의도, 문서 완료 조건을 확인한 뒤 허용 가능한 경우에만 상태를 전이한다.
+
+```text
+MVP 정리하자
+아키텍처 설계하자
+기능 목록 정리하자
+데이터 모델 설계하자
+API 설계하자
+프론트 디자인 정리하자
+기능 구현 시작하자
+```
+
+## Core Flow
+
+```text
+MVP_DEFINITION
+-> ARCHITECTURE_DESIGN
+-> FEATURE_INDEX_DEFINITION
+-> DATA_MODEL_DEFINITION
+-> API_DESIGN
+-> FRONTEND_DESIGN
+-> FEATURE_IMPLEMENTATION
+```
+
+주요 파일:
+
+- `.flh/runtime/STATE.md`: 현재 workflow state
+- `.flh/workflow/flow.yml`: 상태와 허용 request type
+- `.flh/workflow/state-actions.yml`: 상태별 작업 규칙
+- `.flh/workflow/docs-spec.yml`: 문서 완료 조건
+- `.flh/workflow/transition-guards.yml`: 상태 전이 guard
+- `.flh/workflow/request-patterns.yml`: 자연어 요청 분류 패턴
+- `AGENTS.md`: Codex 실행 규칙
+
+## Prefix Modes
+
+flh는 사용자 프롬프트 prefix로 작업 의도를 강하게 제한한다.
+
+### `/q`
+
+질문 모드다.
+
+- 답변만 허용한다.
+- 파일 생성, 수정, 삭제를 하지 않는다.
+- `STATE.md`를 갱신하지 않는다.
+- 테스트, 커밋, push, merge, workflow pipeline을 실행하지 않는다.
+
+### `/d`
+
+문서 및 하네스 제어 모드다.
+
+- `docs/`, `.flh/`, `AGENTS.md`, `README.md`, `.codex/`, `tests/hooks/`, `.husky/`, `package.json`, `package-lock.json` 같은 문서/하네스 유지보수 파일만 수정한다.
+- source 구현 작업을 하지 않는다.
+- 사용자가 명시적으로 요청한 경우에만 커밋 또는 push할 수 있다.
+- merge는 하지 않는다.
+
+### No Prefix
+
+일반 작업 모드다.
+
+- 현재 `.flh/runtime/STATE.md`의 `current_state`를 기준으로 동작한다.
+- 기능 구현은 `current_state`가 `FEATURE_IMPLEMENTATION`일 때만 진행한다.
+- 현재 state에서 허용되지 않는 요청은 hook 또는 agent 규칙에 의해 block된다.
+
+## Must-Know Policies
+
+### 1. `STATE.md`가 기준이다
+
+`.flh/runtime/STATE.md`의 YAML frontmatter가 유일한 machine-readable runtime state다.
+
+에이전트와 hook은 항상 이 값을 기준으로 현재 단계와 허용 작업을 판단한다.
+
+### 2. 문서는 `completed`가 되어야 다음 단계로 간다
+
+각 단계의 문서는 `.flh/workflow/docs-spec.yml` 조건을 만족해야 한다.
+
+필수 섹션, YAML 필드, TODO 제거 조건을 만족하지 못하면 상태 전이가 block될 수 있다.
+
+### 3. `docs/source-layout.yml`은 source 변경의 기준이다
+
+source file 변경이 감지되면 pre-commit guard는 `docs/source-layout.yml`을 기준으로 source root와 package 정보를 판단한다.
+
+이 파일이 `completed` 상태가 아니거나 source root가 맞지 않으면 source 변경 커밋이 막힐 수 있다.
+
+### 4. `active/` 또는 `review/`에 기능이 있으면 새 기능을 시작하지 않는다
+
+기능 상태는 `docs/features/` 아래 디렉토리 위치로 판단한다.
+
+```text
+backlog -> ready -> active -> review -> done
+```
+
+`docs/features/active/` 또는 `docs/features/review/`에 기능 디렉토리가 있으면 새 기능 구현을 시작하지 않는다.
+
+### 5. source 변경은 허용 브랜치에서만 커밋한다
+
+일반 source 변경은 다음 브랜치 prefix에서만 허용된다.
+
+```text
+feat/*
+fix/*
+refactor/*
+```
+
+main/master에서는 일반 source 변경 커밋이 막힌다.
+
+예외는 다음 두 가지뿐이다.
+
+- source scaffold baseline
+- database baseline
+
+두 예외 모두 `.flh/runtime/STATE.md`의 approval 기록이 필요하다.
+
+### 6. Review patch는 별도 lightweight flow를 따른다
+
+`docs/features/review/`에 기능이 있으면 사용자 수정 요청은 기본적으로 해당 기능을 대상으로 한다.
+
+Review patch는 `.flh/docs/REVIEW_PATCH_PIPELINE.md`를 따르며, 기능 하나당 하나의 `fix/*` branch/worktree를 `done/` 이동 전까지 재사용한다.
+
+Review patch의 기본 커밋 정책은 사용자 명시 커밋 방식이다. 수정과 검증은 수행할 수 있지만, 커밋은 사용자가 요청했을 때 수행한다.
+
+### 7. DB baseline은 Prisma-only다
+
+DB-backed project의 공식 자동 baseline은 Prisma 기준으로만 수행한다.
+
+DB를 사용하지 않는 프로젝트는 `.flh/runtime/STATE.md`에 다음 approval을 남겨 1.6 DB baseline 단계를 통과한다.
+
+```yaml
+approvals:
+  database_baseline:
+    required: false
+    skipped: true
+```
+
+DB-backed project는 실제 Prisma baseline 배포와 검증 후 다음 approval이 필요하다.
+
+```yaml
+approvals:
+  database_baseline:
+    required: true
+    verified: true
+```
+
+### 8. 비밀값은 기록하지 않는다
+
+API key, token, password, DB connection string은 `STATE.md`, 기능 문서, 매뉴얼, README에 기록하지 않는다.
+
+필요한 값은 `.env`, 배포 플랫폼 secret, 또는 사용자가 지정한 안전한 위치에 둔다.
+
+## Useful Commands
+
+```sh
+npm test
+python3 -m unittest tests/hooks/test_user_prompt_submit.py tests/hooks/test_pre_commit.py
+printf '아키텍처 설계하자' | .codex/hooks/user-prompt-submit.sh
+git status
+```
+
+## Documents
+
+- [HARNESS_MANUAL.md](HARNESS_MANUAL.md): 전체 하네스 매뉴얼
+- [.flh/docs/PROJECT_WORKFLOW.md](.flh/docs/PROJECT_WORKFLOW.md): 프로젝트 workflow 설명
+- [.flh/docs/FEATURE_IMPLEMENTATION_PIPELINE.md](.flh/docs/FEATURE_IMPLEMENTATION_PIPELINE.md): 기능 구현 파이프라인
+- [.flh/docs/REVIEW_PATCH_PIPELINE.md](.flh/docs/REVIEW_PATCH_PIPELINE.md): review patch 파이프라인
+- [AGENTS.md](AGENTS.md): Codex 실행 규칙

package/templates/default/docs/API.md

@@ -0,0 +1,41 @@
+---
+status: template
+---
+
+# API.md
+
+이 문서는 실제 프로젝트의 API 경계와 공통 규칙을 정의하기 위한 템플릿이다.
+
+하네스 자체의 API를 작성하지 않는다.
+실제 프로젝트를 시작할 때 이 템플릿을 프로젝트 내용으로 채우고 `status: completed`로 변경한다.
+
+---
+
+## API Areas
+
+{{TODO_API_AREAS}}
+
+---
+
+## Endpoint Draft
+
+{{TODO_ENDPOINT_DRAFT}}
+
+---
+
+## Authentication and Authorization
+
+{{TODO_AUTHENTICATION_AND_AUTHORIZATION}}
+
+---
+
+## Request and Response Rules
+
+{{TODO_REQUEST_AND_RESPONSE_RULES}}
+
+---
+
+## Error Response Rules
+
+{{TODO_ERROR_RESPONSE_RULES}}
+

package/templates/default/docs/ARCHITECTURE.md

@@ -0,0 +1,86 @@
+---
+status: template
+---
+
+# ARCHITECTURE.md
+
+이 문서는 실제 프로젝트의 시스템 아키텍처를 정의하기 위한 템플릿이다.
+
+하네스 자체의 아키텍처를 작성하지 않는다.
+실제 프로젝트를 시작할 때 이 템플릿을 프로젝트 내용으로 채우고 `status: completed`로 변경한다.
+
+---
+
+## System Overview
+
+{{TODO_SYSTEM_OVERVIEW}}
+
+---
+
+## Tech Stack
+
+{{TODO_TECH_STACK}}
+
+---
+
+## Source Layout
+
+{{TODO_SOURCE_LAYOUT}}
+
+이 섹션의 결정은 `docs/source-layout.yml`에도 기계가 읽을 수 있는 형태로 기록한다.
+`docs/source-layout.yml`은 아키텍처 단계에서 사용자에게 확인해야 하는 필수 결정 체크리스트로 사용한다.
+
+---
+
+## Package Layout
+
+{{TODO_PACKAGE_LAYOUT}}
+
+---
+
+## Testing Strategy
+
+{{TODO_TESTING_STRATEGY}}
+
+단위, 통합, E2E, 컴포넌트 테스트 도구를 source package별로 결정한다.
+이 결정은 `docs/source-layout.yml`의 `source_roots.*.testing`에도 기계가 읽을 수 있는 형태로 기록한다.
+
+---
+
+## Modules
+
+{{TODO_MODULES}}
+
+---
+
+## Data Flow
+
+{{TODO_DATA_FLOW}}
+
+---
+
+## External Dependencies
+
+{{TODO_EXTERNAL_DEPENDENCIES}}
+
+---
+
+## Runtime Environment
+
+{{TODO_RUNTIME_ENVIRONMENT}}
+
+---
+
+## Scaffold Policy
+
+{{TODO_SCAFFOLD_POLICY}}
+
+아키텍처 단계에서는 필요한 source directory와 `.gitkeep`만 생성한다.
+프레임워크 scaffold와 실제 구현 코드는 기능 구현 단계에서 다룬다.
+최초 source package scaffold baseline에서 기본 root scaffold category에 없는 root file이 필요하면 `docs/source-layout.yml`의 `project.scaffold_extra_root_files`에 명시한다.
+
+---
+
+## Constraints
+
+{{TODO_CONSTRAINTS}}

package/templates/default/docs/DB_SCHEMA.md

@@ -0,0 +1,149 @@
+---
+status: template
+---
+
+# DB_SCHEMA.md
+
+이 문서는 실제 프로젝트의 데이터 모델 baseline을 정의하기 위한 템플릿이다.
+
+하네스 자체의 DB schema를 작성하지 않는다.
+실제 프로젝트를 시작할 때 이 템플릿을 프로젝트 내용으로 채우고 `status: completed`로 변경한다.
+
+이 문서는 프로젝트 전체 데이터 모델의 단일 truth source다.
+`DATA_MODEL_DEFINITION` 단계에서는 실제 `schema.prisma` 또는 migration 파일을 생성하지 않는다.
+대신 이 문서를 `FEATURE_IMPLEMENTATION` 단계의 `1.6. Baseline DB Deployment`에서 즉시 `schema.prisma`로 변환할 수 있는 수준의 명세로 완성한다.
+
+---
+
+## Core Entities
+
+{{TODO_CORE_ENTITIES}}
+
+| Entity | Purpose | Owner | Lifecycle | Notes |
+| --- | --- | --- | --- | --- |
+| {{TODO_ENTITY}} | {{TODO_PURPOSE}} | {{TODO_OWNER}} | {{TODO_LIFECYCLE}} | {{TODO_NOTES}} |
+
+---
+
+## Entity Specifications
+
+{{TODO_ENTITY_SPECIFICATIONS}}
+
+각 entity는 Prisma model로 변환 가능하도록 field 단위로 작성한다.
+
+### {{TODO_ENTITY_NAME}}
+
+| Field | Prisma Type | DB Type | Required | Default | Unique | Index | Relation | Notes |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| id | {{TODO_PRISMA_TYPE}} | {{TODO_DB_TYPE}} | yes | {{TODO_DEFAULT}} | yes | primary | none | {{TODO_NOTES}} |
+
+필드 작성 규칙:
+
+- `Required`는 `yes` 또는 `no`로 작성한다.
+- nullable field는 `Required`를 `no`로 작성한다.
+- default 값이 없으면 `none`으로 작성한다.
+- unique/index가 없으면 `none`으로 작성한다.
+- relation field는 아래 `Relation Specifications`의 relation ID를 참조한다.
+
+---
+
+## Relation Specifications
+
+{{TODO_RELATION_SPECIFICATIONS}}
+
+| Relation ID | From Entity | From Field | To Entity | To Field | Cardinality | Required | onDelete | onUpdate | Notes |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| {{TODO_RELATION_ID}} | {{TODO_FROM_ENTITY}} | {{TODO_FROM_FIELD}} | {{TODO_TO_ENTITY}} | {{TODO_TO_FIELD}} | {{TODO_CARDINALITY}} | {{TODO_REQUIRED}} | {{TODO_ON_DELETE}} | {{TODO_ON_UPDATE}} | {{TODO_NOTES}} |
+
+관계 작성 규칙:
+
+- `Cardinality`는 `one-to-one`, `one-to-many`, `many-to-one`, `many-to-many` 중 하나로 작성한다.
+- foreign key를 가지는 field를 `From Field`에 명확히 작성한다.
+- `onDelete`와 `onUpdate`는 Prisma에서 사용할 값을 명시한다.
+- relation name이 필요하면 `Notes`에 Prisma relation name을 작성한다.
+
+---
+
+## Indexes and Constraints
+
+{{TODO_INDEXES_AND_CONSTRAINTS}}
+
+| Entity | Type | Fields | Name | Purpose | Notes |
+| --- | --- | --- | --- | --- | --- |
+| {{TODO_ENTITY}} | {{TODO_INDEX_OR_UNIQUE_OR_CONSTRAINT}} | {{TODO_FIELDS}} | {{TODO_NAME}} | {{TODO_PURPOSE}} | {{TODO_NOTES}} |
+
+---
+
+## Enums
+
+{{TODO_ENUMS}}
+
+| Enum | Values | Used By | Notes |
+| --- | --- | --- | --- |
+| {{TODO_ENUM_NAME}} | {{TODO_VALUES}} | {{TODO_USED_BY}} | {{TODO_NOTES}} |
+
+---
+
+## Ownership and Permissions
+
+{{TODO_OWNERSHIP_AND_PERMISSIONS}}
+
+| Entity | Owner Field | Access Rule | Write Rule | Delete Rule | Notes |
+| --- | --- | --- | --- | --- | --- |
+| {{TODO_ENTITY}} | {{TODO_OWNER_FIELD}} | {{TODO_ACCESS_RULE}} | {{TODO_WRITE_RULE}} | {{TODO_DELETE_RULE}} | {{TODO_NOTES}} |
+
+---
+
+## ID Strategy
+
+{{TODO_ID_STRATEGY}}
+
+ID 작성 규칙:
+
+- 각 entity의 primary key 방식을 명시한다.
+- UUID, cuid, autoincrement 등 생성 전략을 명시한다.
+- 외부 공개 ID와 내부 DB ID가 다르면 둘 다 명시한다.
+
+---
+
+## Lifecycle Policy
+
+{{TODO_LIFECYCLE_POLICY}}
+
+각 entity의 생성, 수정, soft delete, hard delete, archive 정책을 명시한다.
+
+---
+
+## Common Field Policy
+
+{{TODO_COMMON_FIELD_POLICY}}
+
+공통 field가 있다면 적용 대상과 Prisma 변환 규칙을 명시한다.
+
+| Field | Prisma Type | Default | Applies To | Notes |
+| --- | --- | --- | --- | --- |
+| {{TODO_FIELD}} | {{TODO_PRISMA_TYPE}} | {{TODO_DEFAULT}} | {{TODO_ENTITIES}} | {{TODO_NOTES}} |
+
+---
+
+## Prisma Mapping Notes
+
+{{TODO_PRISMA_MAPPING_NOTES}}
+
+`FEATURE_IMPLEMENTATION`의 `1.6. Baseline DB Deployment`에서 `schema.prisma`를 생성할 때 적용할 Prisma mapping 규칙을 작성한다.
+
+- model 이름
+- field 이름
+- relation 이름
+- `@map` 또는 `@@map` 필요 여부
+- provider별 주의사항
+- Prisma schema로 표현하기 어려운 제약 여부
+
+---
+
+## Migration Notes
+
+{{TODO_MIGRATION_NOTES}}
+
+`DATA_MODEL_DEFINITION` 단계에서는 Prisma 파일이나 migration 파일을 생성하지 않는다.
+이 섹션에는 `1.6. Baseline DB Deployment`에서 `schema.prisma`, baseline migration, deploy/verify script를 생성할 때 필요한 주의사항만 기록한다.

package/templates/default/docs/DESIGN.md

@@ -0,0 +1,52 @@
+---
+status: template
+---
+
+# DESIGN.md
+
+이 문서는 실제 프로젝트의 프론트엔드 디자인 지침을 저장하는 산출물이다.
+
+하네스 자체의 디자인 지침을 작성하지 않는다.
+실제 프로젝트 진행 시 다음 두 방식 중 하나를 선택한다.
+
+- 외부에서 사용 중인 `DESIGN.md`를 이 경로에 가져오고 `.flh/runtime/STATE.md`의 `approvals.design.approved`를 `true`로 기록한다.
+- 이 하네스 흐름 안에서 직접 `DESIGN.md`를 작성하고 `status: completed`로 변경한다.
+
+외부 `DESIGN.md`는 frontmatter가 없을 수 있다.
+그 경우 문서 형식 검증 대신 사용자 승인 기록을 전이 조건으로 사용한다.
+
+---
+
+## Layout Principles
+
+{{TODO_LAYOUT_PRINCIPLES}}
+
+---
+
+## Component Principles
+
+{{TODO_COMPONENT_PRINCIPLES}}
+
+---
+
+## State Loading and Error
+
+{{TODO_STATE_LOADING_AND_ERROR}}
+
+---
+
+## Form Rules
+
+{{TODO_FORM_RULES}}
+
+---
+
+## Responsive Rules
+
+{{TODO_RESPONSIVE_RULES}}
+
+---
+
+## Accessibility
+
+{{TODO_ACCESSIBILITY}}

package/templates/default/docs/MVP.md

@@ -0,0 +1,47 @@
+---
+status: template
+---
+
+# MVP.md
+
+이 문서는 실제 프로젝트의 MVP를 정의하기 위한 템플릿이다.
+
+하네스 자체의 MVP를 작성하지 않는다.
+실제 프로젝트를 시작할 때 이 템플릿을 프로젝트 내용으로 채우고 `status: completed`로 변경한다.
+
+---
+
+## MVP Goal
+
+{{TODO_MVP_GOAL}}
+
+---
+
+## Target Users
+
+{{TODO_TARGET_USERS}}
+
+---
+
+## Core Problem
+
+{{TODO_CORE_PROBLEM}}
+
+---
+
+## In Scope
+
+{{TODO_IN_SCOPE}}
+
+---
+
+## Out of Scope
+
+{{TODO_OUT_OF_SCOPE}}
+
+---
+
+## Success Criteria
+
+{{TODO_SUCCESS_CRITERIA}}
+

package/templates/default/docs/QUALITY_SCORE.md

@@ -0,0 +1,54 @@
+---
+status: template
+---
+
+# QUALITY_SCORE.md
+
+기능별 최종 품질 점수를 한눈에 보기 위한 전역 인덱스다.
+
+이 파일에는 상세 평가 내용을 쓰지 않는다.
+상세 평가는 각 기능 디렉토리의 `QUALITY_SCORE.md`에 기록한다.
+
+전역 인덱스의 목적은 리팩토링, 수정, 개선이 필요한 기능을 빠르게 찾는 것이다.
+
+---
+
+## Score Index
+
+| Feature ID | Feature | Score | Grade | Last Evaluated | Notes | Detail |
+| --- | --- | ---: | --- | --- | --- | --- |
+
+첫 기능 평가가 완료되면 이 표에 행을 추가한다.
+
+예시:
+
+```md
+| FEAT-001 | Login | 82 | B | 2026-05-26 | E2E stable, minor UX improvement candidate | docs/features/review/FEAT-001-login/QUALITY_SCORE.md |
+```
+
+---
+
+## Grade Rule
+
+| Score | Grade | Meaning |
+| ---: | --- | --- |
+| 90-100 | A | Stable and polished |
+| 80-89 | B | Good, minor improvements possible |
+| 70-79 | C | Acceptable, improvement candidate |
+| 0-69 | D | Rework required |
+
+---
+
+## Gate Rule
+
+- `70`점 이상이면 커밋 가능하다.
+- `70`점 미만이면 수정 후 재검증한다.
+- 치명 조건이 있으면 점수와 관계없이 커밋하지 않는다.
+
+치명 조건:
+
+- E2E failure
+- SPEC scope violation
+- DB_SCHEMA conflict
+- Security risk
+- Broken primary user flow