@uzysjung/agent-harness 26.83.0

package/templates/rules/change-management.md

@@ -0,0 +1,80 @@
+# Change Management
+
+## Change Request (CR) Classification
+
+구현 중 SPEC/PRD 변경이 필요한 경우:
+
+| 유형 | 기준 | 처리 |
+|------|------|------|
+| **Clarification** | 이미 합의된 내용의 구체화 | 에이전트가 즉시 반영 + Change Log 기록 |
+| **Minor** | 현재 Phase 내부에 국한 | 에이전트가 제안 → **인간 승인** → Change Log |
+| **Major** | AC/Phase/Non-Goals/DO NOT CHANGE 영향 | **인간 결정 필수** → Change Log + 영향 분석 |
+
+## Classification Rules
+
+```
+IF AC의 Pass/Fail에 영향           → Major
+IF 다른 Phase의 입력/산출물에 영향  → Major
+IF DO NOT CHANGE 영역에 영향        → Major
+IF Non-Goals 경계에 영향            → Major
+IF 현재 Phase 내부에 국한           → Minor
+IF 합의 내용의 구체화               → Clarification
+```
+
+## DO NOT CHANGE Protection
+
+- SPEC/PRD의 DO NOT CHANGE 영역은 **절대 수정 금지**.
+- 수정이 불가피한 경우: Major CR 작성 → 인간 결정 대기.
+- 안정적으로 보이는 영역도 수정 전 확인: "이 부분도 수정 범위입니까?"
+
+## Decision Log (ADR)
+
+구현 중 SPEC에 명시되지 않은 의사결정은 `docs/decisions/` 에 ADR로 기록:
+
+```markdown
+# ADR-NNN: [결정 제목]
+- Status: Proposed | Accepted | Superseded | Deprecated
+- Date: YYYY-MM-DD
+- PR: #123 (제안/승인 PR 링크)
+- Supersedes: ADR-MMM (있으면)
+- Context: [왜 결정이 필요했는가]
+- Decision: [무엇을 결정했는가]
+- Alternatives: [검토 후 기각된 대안]
+- Consequences: [이 결정의 영향]
+```
+
+### ADR Status 흐름
+
+```
+Proposed → Accepted → (Superseded by ADR-N | Deprecated)
+   ↓
+ (Rejected — 별도 ADR 안 만듦, PR comment에 사유 기록)
+```
+
+| Status | 의미 | 다음 가능 transition |
+|--------|------|-------------------|
+| **Proposed** | PR 작성 + 검토 중. 아직 적용 X | Accepted, (Rejected) |
+| **Accepted** | 머지됨. 본 결정에 따라 코드/문서 작성 | Superseded, Deprecated |
+| **Superseded** | 다른 ADR이 본 결정을 대체 | (terminal — `Supersedes:` 필드로 link) |
+| **Deprecated** | 더 이상 유효하지 않으나 대체 ADR 없음 | (terminal — 사유 PR/section 기록) |
+
+### 채택 프로세스
+
+1. **Proposed**: 의사결정 필요 시 ADR 초안 PR 생성. Status: Proposed.
+2. **검토**: PR review에서 Alternatives + Consequences 검증.
+3. **Accepted**: 머지 직전 Status: Accepted, PR 번호 채움.
+4. **변경**: 새 ADR로 Supersedes/Deprecates 명시. 기존 ADR Status 갱신.
+
+### 어떤 결정이 ADR 대상인가
+
+- **대상**: 아키텍처 변경, 외부 의존성 도입/제거, 데이터 모델 변경, 보안 정책, breaking API
+- **비대상**: 한 함수의 구현 디테일, 임시 워크어라운드, 명백한 버그 fix
+
+## Savepoint Protocol
+
+Major CR 적용 전, 또는 주요 변경점에서 savepoint 생성:
+
+```bash
+git add -A && git commit -m "chore: savepoint before [변경 설명]"
+```
+

package/templates/rules/cli-development.md

@@ -0,0 +1,39 @@
+# CLI / Bash Development Rules
+
+tooling Track 전용. 기본 bash 규약(shebang/quoting/local/backticks/stderr)은 shellcheck가 처리. 여기는 프로젝트 특화만.
+
+## Cross-Platform (BSD vs GNU)
+
+macOS(BSD)와 Linux(GNU) 양쪽 지원이 필수인 경우:
+
+| 명령 | BSD | GNU | 회피 |
+|------|-----|-----|------|
+| `sed -i` | `sed -i ''` | `sed -i` | `-i.bak` + `rm *.bak` 또는 분기 |
+| `date` | `date -j` | `date -d` | `if command -v gdate` 폴백 |
+| `readlink -f` | 미지원 | 지원 | `cd "$(dirname $f)" && pwd` |
+
+차이가 큰 명령은 `command -v` 폴백 필수.
+
+## set 플래그
+
+- `set -e` + `|| true` 혼용 금지 (의도 불분명). 실패 허용 섹션은 명시적 try 블록으로
+- plugin 설치 등 실패 허용 구간에서 `set -e` 비활성화 가능
+- `set -o pipefail`은 파이프 실패 검출 필요 시
+
+## Hook Script 규약
+
+PreToolUse hook 작성 시:
+- stdin으로 JSON 받음 → `jq` 또는 `grep` 폴백 (jq 미설치 환경 대응)
+- **차단**: `exit 2` + stderr에 사유
+- **통과**: `exit 0` (출력 없음)
+- async hook은 10초 이내 완료
+
+## 임시 파일
+
+`/tmp/file.txt` 같은 **고정 경로 금지** — 세션 충돌. `mktemp`/`mktemp -d` 사용.
+
+## Testing
+
+- **shellcheck**: 필수 정적 분석
+- **bats**: 단위 테스트 (optional)
+- **수동**: `echo '{"...": "..."}' | bash hook.sh` heredoc/pipe로 stdin mock

package/templates/rules/code-style.md

@@ -0,0 +1,23 @@
+# Code Style
+
+포매터/린터 설정(ruff, prettier, eslint, tsconfig strict, naming)은 각 프로젝트 config 파일이 SSOT. 여기는 Rule로 강제할 비구조적 원칙만.
+
+## 불변성
+
+기존 객체 mutation 금지. 새 객체 생성(spread/immer). 외부 상태 공유 시 side effect 숨은 버그의 주 원인.
+
+## 크기/복잡도 상한
+
+- 파일: 800줄 상한. 초과 시 분리.
+- 함수: 50줄 상한.
+- 중첩: 4레벨 상한. early return으로 평탄화.
+
+상한 초과는 곧 리팩터링 시그널. 예외가 있으면 주석으로 사유 명시.
+
+## 하드코딩/매직 넘버 금지
+
+상수 또는 환경 변수. 의미 있는 이름 필수.
+
+## 타입 강도
+
+`any`/`type: ignore` 최소화. 불가피 시 한 줄 사유 주석. 이외 명명/포매팅은 linter가 판정.

package/templates/rules/data-analysis.md

@@ -0,0 +1,61 @@
+# Data Analysis Rules
+
+data Track에서 적용.
+
+## DuckDB Patterns
+
+- 파일 직접 쿼리: `SELECT * FROM 'data.parquet'`, `read_csv_auto('data.csv')`
+- CTE 적극 활용 — 서브쿼리 중첩 대신 CTE 체이닝
+- Window functions는 별도 CTE로 분리
+- `SELECT *` 금지 — 필요한 컬럼만
+
+```sql
+WITH daily_metrics AS (
+    SELECT date, SUM(revenue) AS total_revenue
+    FROM read_parquet('sales/*.parquet')
+    GROUP BY date
+),
+moving_avg AS (
+    SELECT *, AVG(total_revenue) OVER (ORDER BY date ROWS 6 PRECEDING) AS ma7
+    FROM daily_metrics
+)
+SELECT * FROM moving_avg WHERE date >= '2026-01-01';
+```
+
+## Trino Federation
+
+- 카탈로그 명시: `catalog.schema.table`
+- 크로스 소스 JOIN 시 작은 테이블을 드라이빙 테이블로
+- `EXPLAIN ANALYZE`로 쿼리 플랜 확인
+
+## pandas / polars
+
+- **polars 우선** (대용량, 성능)
+- pandas 사용 시: `df.copy()` 후 변환. 원본 수정 금지.
+- 체이닝: pipe 패턴 사용
+
+```python
+result = (
+    df.lazy()
+    .filter(pl.col("status") == "active")
+    .group_by("category")
+    .agg(pl.col("revenue").sum())
+    .sort("revenue", descending=True)
+    .collect()
+)
+```
+
+## ML Pipeline
+
+1. 데이터 분리: train/val/test (시계열은 시간 순서 유지)
+2. 전처리: `sklearn.pipeline.Pipeline` + `ColumnTransformer`
+3. 베이스라인: 가장 단순한 모델 먼저 (LogisticRegression, XGBoost)
+4. 평가: cross_val_score, 혼동 행렬, 비즈니스 메트릭
+5. 실험 추적: MLflow (run_name, params, metrics, artifacts)
+
+## Visualization
+
+- EDA: matplotlib/seaborn (정적)
+- 인터랙티브: plotly
+- PySide6 임베딩: `matplotlib.backends.backend_qtagg`
+- 차트에 제목, 축 레이블, 범례 필수

package/templates/rules/database.md

@@ -0,0 +1,29 @@
+# Database Rules
+
+csr-fastify, csr-fastapi Track에서 적용.
+
+## ORM & Migration
+
+- **SQLModel** + asyncpg (Python). SQLAlchemy Core 접근 가능.
+- **Alembic**으로만 마이그레이션. 수동 DDL 금지.
+- 마이그레이션 생성: `alembic revision --autogenerate -m "description"`
+- 마이그레이션 적용: `alembic upgrade head`
+
+## Model Conventions
+
+- PK: `id = Field(default_factory=uuid4, primary_key=True)` (UUID v4)
+- `created_at`, `updated_at` 필수 (서버 사이드 타임스탬프).
+- 소프트 삭제 시: `deleted_at: datetime | None = None`
+
+## Query Patterns
+
+- **N+1 방지**: eager loading (`selectinload`, `joinedload`)
+- **페이징**: cursor 기반 (offset 기반 대규모에서 성능 저하)
+- **인덱스**: WHERE/ORDER BY에 사용되는 컬럼에 인덱스 추가
+- `SELECT *` 금지 — 필요한 컬럼만
+
+## Safety
+
+- 파라미터화된 쿼리만 사용. 문자열 결합 금지.
+- 스키마 변경은 Major Change Request 대상.
+- 프로덕션 DB 직접 접근 금지. 마이그레이션 통해서만.

package/templates/rules/design-workflow.md

@@ -0,0 +1,17 @@
+# Design Workflow
+
+UI가 포함된 작업 시 적용 (csr-*, ssr-*).
+
+## Pre-Build 필수 확인
+
+1. `DESIGN.md` 존재 → 디자인 방향/톤 참조
+2. `.impeccable.md` 존재 → 브랜드/청중/톤 컨텍스트 참조
+3. 둘 다 없으면 `/teach`로 컨텍스트 설정 먼저
+
+Impeccable 스킬 목록/상세는 스킬 카탈로그 참조. 여기서 나열하지 않는다.
+
+## 원칙
+
+- Generic AI 미학 금지 — 대담한 방향 + 일관성.
+- 컴포넌트 라이브러리(shadcn/ui 등) 스타일과 충돌하지 않도록.
+- 접근성 WCAG 2.1 AA 이상.

package/templates/rules/error-handling.md

@@ -0,0 +1,23 @@
+# Error Handling
+
+"에러 무시 금지", "빈 catch 금지"는 linter가 처리. 여기는 프로젝트 특화 규약만.
+
+## 에러 응답 포맷 (FastAPI 백엔드)
+
+구조화된 JSON. 스택트레이스/내부 경로/DB 쿼리 등 민감 정보 노출 금지.
+
+```json
+{ "success": false, "error": { "code": "...", "message": "..." } }
+```
+
+커스텀 예외 클래스 + 전역 exception handler로 일관성 유지. 에러 로깅 시 context 필수(request_id, user_id, endpoint).
+
+## 외부 API 호출
+
+timeout + 1회 재시도(exponential backoff). 무한 재시도 금지.
+
+## 프론트엔드
+
+- Route 레벨 `ErrorBoundary` 배치.
+- 사용자 메시지는 친화적으로, 기술 세부사항은 콘솔만.
+- Form 검증은 schema 기반(zod 등).

package/templates/rules/gates-taxonomy.md

@@ -0,0 +1,21 @@
+# Gates Taxonomy
+
+워크플로우 검증 체크포인트가 매핑되는 4가지 게이트 유형. CLAUDE.md P9(Circuit Breakers)와 함께 적용.
+
+## 유형
+
+| 유형 | 언제 | 동작 | 복구 |
+|------|------|------|------|
+| **Pre-flight** | 작업 시작 전 | 전제조건 미충족 시 차단. 부분 작업 없음 | 전제조건 수정 후 재시도 |
+| **Revision** | 산출물 품질 불만족 | 수정 루프. 반복 상한 필수 (비용 비례) | 피드백 반영 → 재평가. 이슈 감소 없으면 조기 escalation |
+| **Escalation** | 자동 해결 불가 | 옵션 제시 + 사용자 입력 대기 | 사용자 선택 후 선택된 경로로 재개 |
+| **Abort** | 지속 시 손상/낭비 | 즉시 중단, 상태 보존, 사유 보고 | 근본 원인 수정 후 체크포인트에서 재시작 |
+
+## 선택 휴리스틱
+
+1. **Pre-flight 먼저** — 파일 존재/설정 읽기로 확인 가능한 값싼 검증
+2. 산출물 **생산 후** 품질 체크 → Revision (상한 필수)
+3. Revision 루프 해결 불가 → Escalation
+4. 계속 진행이 **위험하면** → Abort
+
+값싼 pre-flight로 최대한 걸러내고, 비싼 혹은 사용자 의사결정이 필요한 경우에만 상위 유형으로 넘긴다.

package/templates/rules/git-policy.md

@@ -0,0 +1,102 @@
+# Git Policy
+
+CLAUDE.md Git Policy의 프로젝트 레벨 확장. 중복 내용 제거.
+
+## Commit 메시지
+
+Conventional Commits: `<type>: <description>`
+Types: feat, fix, refactor, docs, test, chore, perf, ci
+
+커밋 메시지는 **why 중심**. what은 diff가 보여준다. Breaking change는 body에 `BREAKING CHANGE:` 표기.
+
+## Branch 명명
+
+`feat/<name>`, `fix/<name>`, `refactor/<name>`.
+
+## PR
+
+- Issue 링크: `Closes #N`
+- 전체 커밋 이력 분석 (`git diff [base]...HEAD`)
+- 요약에 변경 + 테스트 계획 포함
+- 새 branch는 `-u` 플래그로 push
+
+## Safety
+
+- `--force`, `reset --hard`, hook 검증 우회 플래그 (`--no` + `verify` 옵션 결합 형태) 사용 금지 (명시적 요청 제외)
+- git config 수정 금지
+- `.env`, credentials, lock 파일 커밋 금지
+
+## Session Cleanup (필수)
+
+세션 종료 / `/clear` / `/compact` **직전** 다음 절차 강제:
+
+1. `gh pr list --state open` 실행 — open PR 잔존 여부 확인
+2. 잔존 PR 발견 시:
+   - 자동 머지 금지 — **사용자 명시 합의 필수**
+   - 각 PR 상태 보고: `# / title / branch / CI status / mergeable`
+   - 다음 행동 옵션 제시: 머지 / 그대로 두기 / draft 전환 / 취소
+
+### "build/verify/review gate ✓" ≠ "main 반영"
+
+ship 보고 시 두 상태를 **반드시 분리**해서 보여줄 것:
+
+- **Local gate 상태**: build/verify/review checkbox completed (`.claude/gate-status.json`)
+- **Remote 상태**: PR merged into main + tag pushed + release 게시
+
+gate ✓ 만 보고 ship 완료라 단정하지 않는다. open PR 1건이라도 있으면 cycle 미완.
+
+### 보고 형식 예
+
+```
+gate:  build ✓ / verify ✓ / review ✓ / ship ✓  (local gate-status)
+main:  PR #123 merged ✓ / tag v26.39.3 pushed ✓ / release ✓
+       OR
+       PR #123 OPEN — CI pass / mergeable / 사용자 결정 대기
+```
+
+## Post-Merge Cleanup (필수)
+
+PR 머지 직후 stale branch 누적 방지. Session Cleanup 의 "open PR 점검" 과 보완 관계.
+
+1. **머지 시 remote branch 자동 삭제** — `gh pr merge <num> --squash --delete-branch`
+   - GitHub repo settings 의 "Automatically delete head branches" 토글이 켜져 있으면 `--delete-branch` 생략 가능. 둘 중 1개는 항상 적용
+2. **local main 동기화** — `git checkout main && git pull --ff-only`
+3. **local feature branch 삭제** — `git branch -d <branch>`
+   - squash merge 후엔 git 가 "unmerged" 경고 → 같은 변경 내용 확인 후 `-D` 사용 가능
+4. **정기 stale 점검** (선택) — `git branch --merged main | grep -v '^\*\| main$'` 으로 잔존 확인
+
+### 보고 형식 보강
+
+ship 보고에 branch cleanup 상태 한 줄 추가:
+
+```
+gate:  build ✓ / verify ✓ / review ✓ / ship ✓
+main:  PR #123 merged ✓ / tag v26.39.6 ✓ / release ✓
+branch: fix/foo deleted (local + remote) ✓
+       OR
+branch: fix/foo OPEN — 삭제 필요
+```
+
+## Versioning Convention (절대 위반 금지)
+
+**형식**: `vMAJOR.MINOR.PATCH`
+
+- **Major = `year - 2000`** (CalVer-like)
+  - 2025 = `v25.x.x`
+  - **2026 = `v26.x.x`**
+  - 2027 = `v27.x.x`
+- **Minor**: feature bump (BREAKING change여도 같은 year 내에서는 Minor만 bump)
+- **Patch**: bug fix only
+
+**Year 변경 시점에만 Major bump**. SemVer-식 BREAKING → Major 적용 **금지**.
+
+### Pre-tag checklist (모든 ship 전)
+
+1. `git tag -l | sort -V | tail -5` 마지막 정상 태그 확인
+2. 당해년도 매핑 검증 — `date +%Y` % 100 = 다음 Major
+3. SPEC/ADR/문서 본문에 "v(year+1).x" 같은 미래 태그 텍스트 보이면 **즉시 컨벤션 검증** — 그대로 따르지 말 것
+4. 위반 의심 시 ship 중단 + 사용자 컨펌
+
+### Drift Period (사후 정리)
+
+2026-04-18 ~ 2026-04-30: v27.0.0 ~ v28.0.0 (21건) 컨벤션 위반 누적 → 2026-04-30 일괄 rename to v26.18.0 ~ v26.38.0. 상세 ADR-007 참조.

package/templates/rules/htmx.md

@@ -0,0 +1,42 @@
+# htmx Rules
+
+ssr-htmx Track에서 적용.
+
+## Core Patterns
+
+- `hx-swap` 기본값: `innerHTML`. 명시적으로 지정.
+- `hx-trigger` 항상 명시. 암묵적 트리거에 의존하지 않음.
+- `hx-boost` 내비게이션 링크에만. 폼이나 API 호출에 사용 금지.
+- `hx-indicator` 필수 — 네트워크 요청 시 사용자에게 로딩 표시.
+
+## Partial Responses
+
+- htmx 요청에 대한 응답은 **부분 HTML**만 반환.
+- Jinja2 `block`/`macro`로 부분 템플릿 정의.
+- 전체 페이지 렌더링 금지 (htmx 요청인 경우).
+
+```python
+@app.get("/items/{id}")
+async def get_item(request: Request, id: int):
+    item = await fetch_item(id)
+    if request.headers.get("HX-Request"):
+        return templates.TemplateResponse("partials/item.html", {"item": item})
+    return templates.TemplateResponse("pages/item.html", {"item": item})
+```
+
+## htmx + Alpine.js Boundary
+
+- **htmx**: 서버 상호작용 (데이터 로드, 폼 제출, 부분 업데이트)
+- **Alpine.js**: 클라이언트 전용 상호작용 (토글, 드롭다운, 탭)
+- 둘을 혼합하지 않음. 서버 상태는 htmx, 클라이언트 상태는 Alpine.
+
+## Chart.js Coexistence
+
+- htmx로 차트 영역 업데이트 전 기존 Chart 인스턴스 반드시 `destroy()`.
+- 병렬 `htmx.ajax()` 호출 금지 — 순차 실행.
+- 차트 컨테이너에 고정 높이 부여 (CLS 방지).
+
+## Security
+
+- 모든 mutation(POST/PUT/DELETE)에 CSRF 토큰 필수.
+- `hx-vals`로 민감 데이터 전송 금지.

package/templates/rules/nextjs.md

@@ -0,0 +1,35 @@
+# Next.js Rules
+
+ssr-nextjs Track에서 적용.
+
+## Routing
+
+- **App Router only**. Pages Router 사용 금지.
+- 동적 라우트: `[param]` / `[...catchAll]`
+- Route Groups: `(group)` 으로 레이아웃 공유
+- `generateStaticParams` 사용하여 정적 경로 사전 생성
+
+## Server vs Client Components
+
+- **기본은 Server Component**. `'use client'`는 필요할 때만.
+- `'use client'` 사용 시점: useState, useEffect, 이벤트 핸들러, 브라우저 API
+- 서버/클라이언트 경계를 최대한 아래로 밀어내기. 가능한 한 작은 client component.
+
+## Data Fetching
+
+- `fetch` 옵션 명시적으로 지정:
+  - `{ cache: 'force-cache' }` — 정적 데이터
+  - `{ cache: 'no-store' }` — 동적 데이터
+  - `{ next: { revalidate: 3600 } }` — ISR
+- Server Actions: `'use server'` 지시어, 폼 mutation에 사용
+
+## Assets
+
+- `next/image`: 모든 이미지에 사용. `<img>` 직접 사용 금지.
+- `next/font`: 폰트 최적화. Google Fonts 등.
+- 환경 변수: 클라이언트 노출 시 `NEXT_PUBLIC_` 접두사.
+
+## Middleware
+
+- `middleware.ts`: 인증 리다이렉트, locale 감지에만 사용.
+- 무거운 로직 금지 — middleware는 edge에서 실행.

package/templates/rules/playwright-launch.md

@@ -0,0 +1,66 @@
+# Playwright Launch
+
+브라우저를 띄워 **사용자가 직접 사용**하는 모든 상황 (E2E 수동 확인, UX 비교, fidelity audit, OAuth 1회 로그인 등) 에 적용. 핵심 원칙: **영속 profile + Chrome for Testing 별도 binary + 자동화 0 patten**. MCP 일회성 context = 휘발 → 입력 버벅임. 정리하고 영속 profile로 재기동.
+
+## 절대 금지
+
+- `mcp__chrome-devtools__*` 로 **사용자 활성 Chrome** attach (입력 latency)
+- Playwright MCP (`mcp__plugin_playwright__*`) **일회성** browser context — 영속 profile dir 없음 → IndexedDB / cookie / localStorage / SW 휘발 → 매 launch 마다 재로그인 + 버벅임
+- `browser.newContext()` 일회성 패턴
+- **사용자 OAuth 입력 시점에 자동화 process 동시 실행** (CDP latency)
+- reference SaaS (Linear / Notion / Jira 등) 측 `page.goto(URL)` 또는 `page.reload()` — sidebar click only
+
+## 필수 패턴
+
+1. **영속 profile dir** — 프로젝트별 분리, 매 iter 재사용. cookie + IndexedDB + Service Worker 영구 보존.
+   - 예: `~/.<project>-dev-audit-profile`, `~/.<reference>-audit-profile`, `${PROJECT_PROFILE_DIR}` env var
+2. **Chrome for Testing 별도 binary** — `npx playwright install chromium` 으로 받은 `~/Library/Caches/ms-playwright/chromium-*/chrome-mac-arm64/Google Chrome for Testing.app`. 사용자 일반 Chrome 과 완전 분리.
+3. **사용자 키 입력 시 자동화 layer 0** — main session 은 chromium 창 띄우기만. **사용자가 키보드 직접 입력**. 자동화 capture/검증은 **별도 process** (`node scripts/<launch>.mjs`) 에서 입력 끝난 후.
+4. **자체 구현 측 = dev bypass auth** — Google OAuth 등 webdriver 차단 회피. 예: `POST /api/v1/_dev/test-login` 으로 JWT cookie 발급.
+
+## 표준 launch 스크립트 골격
+
+```js
+import { chromium } from 'playwright';
+
+const PROFILE_DIR = process.env.PROJECT_PROFILE_DIR || `${process.env.HOME}/.<project>-audit-profile`;
+const TARGET = process.env.PROJECT_URL || 'http://localhost:<port>';
+const TEST_KEY = process.env.E2E_TEST_KEY || 'e2e-dev-key';
+
+const ctx = await chromium.launchPersistentContext(PROFILE_DIR, {
+  headless: false,
+  viewport: { width: 1440, height: 900 },
+  args: ['--disable-blink-features=AutomationControlled', '--no-first-run', '--no-default-browser-check'],
+});
+const page = ctx.pages()[0] ?? (await ctx.newPage());
+
+// (선택) dev bypass auth — same-origin cookie 자동 저장
+await page.goto(`${TARGET}/`, { waitUntil: 'domcontentloaded' });
+await ctx.request.post(`${TARGET}/api/v1/_dev/test-login`, {
+  data: { key: TEST_KEY, email: 'e2e@example.local' },
+});
+await page.reload({ waitUntil: 'networkidle' });
+
+// 창 떠 있게 두고 자동화 detach — 사용자가 직접 사용.
+// ctx.close() 호출 금지.
+```
+
+## 사용 패턴
+
+### A. 사용자가 직접 보고 싶을 때 (most common)
+
+1. `pkill -f "playwright|Chrome for Testing"` 기존 launcher 정리 (선택)
+2. `node scripts/<project>-launch.mjs` 실행 (chromium 창 살아있어야 함, 백그라운드 X)
+3. 사용자에게 "URL: localhost:<port>, 로그인됨, 직접 사용하세요" 보고
+4. **MCP playwright 로 추가 navigation/evaluate 금지** — 사용자 입력과 충돌
+
+### B. fidelity 비교 / audit 자동 capture
+
+1. `node scripts/<audit>.mjs` — launchPersistentContext + 비교 시나리오 자동 click
+2. 산출물 = `docs/research/<ref>_audit_<sprint>/iter_<N>/`
+
+## 위반 시 즉시 조치
+
+1. 일회성 Playwright MCP context 사용 발견 → 닫고 영속 profile launcher 로 재기동
+2. `chrome-devtools` MCP attach 발견 → 즉시 detach + Playwright 영속 패턴 전환
+3. 사용자가 "버벅인다" / "느리다" 호소 → 본 rule 위반 확인 1순위

package/templates/rules/pyside6.md

@@ -0,0 +1,59 @@
+# PySide6 Rules
+
+data Track에서 적용.
+
+## Architecture
+
+- UI 정의는 코드로 작성. Qt Designer `.ui` 파일 사용 안 함.
+- MVC 패턴: Model(데이터) / View(위젯) / Controller(시그널/슬롯 연결)
+- 메인 윈도우는 `QMainWindow` 상속.
+
+## Signals & Slots
+
+```python
+from PySide6.QtCore import Signal, Slot, QObject
+
+class DataProcessor(QObject):
+    progress = Signal(int)
+    finished = Signal(object)
+
+    @Slot()
+    def process(self):
+        for i in range(100):
+            self.progress.emit(i)
+        self.finished.emit(result)
+```
+
+## Threading (Critical)
+
+- **UI 스레드에서 장시간 작업 금지** (DB 쿼리, 모델 학습, API 호출).
+- `QThread` + Signal로 백그라운드 처리:
+
+```python
+class Worker(QThread):
+    result_ready = Signal(object)
+
+    def run(self):
+        result = heavy_computation()
+        self.result_ready.emit(result)
+```
+
+- UI 업데이트는 반드시 메인 스레드에서 (Signal → Slot 연결로 보장).
+
+## Model/View
+
+- 대용량 데이터: `QAbstractTableModel` 서브클래싱
+- 커스텀 정렬/필터: `QSortFilterProxyModel`
+- 셀 커스터마이징: `QStyledItemDelegate`
+
+## Layout
+
+- `QVBoxLayout` / `QHBoxLayout` 중첩
+- `QSplitter` — 리사이저블 패널
+- `QStackedWidget` — 페이지 전환
+- 위젯 이름은 역할 기반: `self.search_input`, `self.result_table`
+
+## Resources
+
+- `importlib.resources` 또는 `QResource` 사용
+- 아이콘: 벡터(SVG) 우선, 크기별 래스터 제공

package/templates/rules/shadcn.md

@@ -0,0 +1,33 @@
+# shadcn/ui Rules
+
+CSR, ssr-nextjs Track에서 적용.
+
+## Component Management
+
+- CLI로만 추가: `npx shadcn@latest add <component>`
+- `components/ui/` 디렉토리는 **읽기 전용**. 직접 수정 금지.
+- 커스터마이징은 래퍼 컴포넌트로. 원본 ui/ 파일 수정하지 않음.
+
+## Theming
+
+- 60/30/10 컬러 규칙: primary 60%, secondary 30%, accent 10%.
+- 4px 기본 간격 단위 (Tailwind의 spacing scale 사용).
+- 다크 모드: `next-themes` (Next.js) 또는 CSS 변수 토글.
+
+## Forms
+
+- `react-hook-form` + `zod` 조합 사용.
+- shadcn의 Form 컴포넌트 연동.
+- 서버 사이드 검증과 동일한 zod 스키마 공유.
+
+## Accessibility
+
+- WCAG 2.1 AA 이상.
+- 키보드 내비게이션 확인.
+- 아이콘은 `lucide-react`만 사용.
+
+## Registry Safety
+
+- 새 컴포넌트 추가 전 기존 설치 목록 확인.
+- 중복 추가 방지.
+- 버전 충돌 시 lockfile 기준으로 해결.

package/templates/rules/ship-checklist.md

@@ -0,0 +1,24 @@
+# Ship Checklist
+
+`/uzys:ship` 실행 시 아래 모든 항목을 통과해야 배포 가능.
+
+## Pre-Ship Gates
+
+- [ ] **E2E 테스트 통과**: 핵심 사용자 흐름 E2E 테스트 전부 PASS (인증/결제/DB — `/uzys:test` 단계에서 검증됨)
+- [ ] **커버리지 기준 충족**: test-policy.md의 Track별 threshold 확인
+- [ ] **Security Scan 통과**: `npx ecc-agentshield scan` 결과 CRITICAL/HIGH 없음
+- [ ] **의존성 감사 통과**: `npm audit` (Node.js) 또는 `pip audit` (Python) 실행. critical/high 취약점 없음
+- [ ] **SPEC/PRD 정합성**: `bash .claude/hooks/spec-drift-check.sh ship` (exit 2 시 차단)
+- [ ] **Review 게이트 통과**: `/uzys:review`에서 CRITICAL 이슈 없음 확인
+
+## Post-Ship Actions
+
+- SPEC/PRD와 불일치 발견 시: SPEC/PRD 업데이트 → 커밋
+- ADR 기록 필요 시: `docs/decisions/` 에 아키텍처 결정 기록
+- Change Log 최종 확정
+
+## Deployment
+
+- Railway 배포 가능 상태 확인 (Railway MCP/플러그인 사용)
+- Health check 엔드포인트 응답 확인
+- 배포 후 smoke test 실행