timsquad 3.4.0 → 3.6.0

package/templates/base/timsquad/ssot/test-spec.template.md

@@ -178,7 +178,17 @@ describe('UserService', () => {
 
 ---
 
-## 5. 테스트 자동화
+## 5. 테스트 게이트
+
+TimSquad 워크플로우에서 자동 실행되는 테스트 게이트 설정.
+
+### 5.0 게이트별 실행 명령
+
+| 게이트 | 실행 시점 | 명령 | 타임아웃 |
+|--------|----------|------|---------|
+| Task (Unit) | Task 완료 시 | `npm run test:unit` | 120s |
+| Sequence (Integration + Build) | Sequence 완료 시 | `npm run test:integration` + `tsc --noEmit` | 300s |
+| Phase (E2E) | Phase 완료 시 | `npm run test:e2e` | 300s |
 
 ### 5.1 CI 파이프라인
 

package/templates/base/timsquad/ssot-map.template.yaml

@@ -0,0 +1,41 @@
+# SSOT Map — 티어별 문서 주입 기준
+# Tier 0: 모든 작업에 항상 주입 (Hook → systemMessage)
+# Tier 1: Phase 시작 시 Controller가 주입
+# Tier 2: Sequence 범위 문서 (Controller가 선택 주입)
+# Tier 3: 개별 Task에 필요한 구체 spec (Controller가 선택 주입)
+
+tier-0-always:
+  description: "모든 작업에 항상 주입되는 제약 문서"
+  inject_via: hook
+  documents:
+    - compiled: rules/security-constraints.md
+      source: security-spec.md
+    - compiled: rules/completion-criteria.md
+      source: requirements.md
+
+tier-1-phase:
+  description: "Phase 시작 시 controller가 주입하는 방향성 문서"
+  inject_via: controller
+  documents:
+    - compiled: references/prd-summary.spec.md
+      source: prd.md
+    - compiled: references/architecture.spec.md
+      source: planning.md
+
+tier-2-sequence:
+  description: "Sequence 범위의 기능별 문서"
+  inject_via: controller
+  documents:
+    - compiled: references/service.spec.md
+      source: service-spec.md
+    - compiled: references/data-design.spec.md
+      source: data-design.md
+
+tier-3-task:
+  description: "개별 Task에 필요한 구체 spec"
+  inject_via: controller
+  documents:
+    - compiled: references/error-codes.spec.md
+      source: error-codes.md
+    - compiled: references/functional.spec.md
+      source: functional-spec.md

package/templates/platforms/claude-code/rules/api-conventions.md

@@ -0,0 +1,12 @@
+---
+paths:
+  - "src/api/**/*.ts"
+  - "src/routes/**/*.ts"
+  - "src/controllers/**/*.ts"
+---
+
+- RESTful 네이밍 사용 (복수형 리소스, kebab-case)
+- 에러 응답 표준 형식: `{ code: string, message: string, details?: unknown }`
+- HTTP 상태 코드 정확히 매핑 (200/201/400/401/403/404/500)
+- 요청 validation은 엔드포인트 진입 시점에서 수행
+- 비즈니스 로직은 서비스 레이어에 위치 (컨트롤러에 직접 작성 금지)

package/templates/platforms/claude-code/rules/build-gate.md

@@ -0,0 +1,28 @@
+---
+description: 빌드 게이트. 변경 파일의 TypeScript 에러를 자동 감지하여 완료 차단.
+globs:
+  - "src/**/*.ts"
+  - "src/**/*.tsx"
+---
+
+# 빌드 게이트 (Build Gate)
+
+## 자동 검증
+
+매 턴 종료 시 변경된 TypeScript 파일에 대해 `tsc --noEmit`을 실행합니다.
+- 변경 파일에 에러가 있으면 **완료를 차단**하고 에러 목록을 제공
+- 기존 파일의 pre-existing 에러는 무시 (변경 파일만 필터링)
+- `stop_hook_active` 플래그로 1회만 차단 (무한루프 방지)
+
+## 블로킹 수신 시 대응
+
+`[Build Gate]` 블로킹 메시지를 받으면:
+1. 제시된 TypeScript 에러를 확인하세요
+2. 해당 파일을 열어 에러를 수정하세요
+3. 수정 후 작업을 마무리하세요
+
+## 참고
+
+- 전체 `tsc --noEmit` 실행 (incremental 가능)
+- 변경 파일 감지: `git diff --name-only HEAD -- '*.ts' '*.tsx'`
+- 타임아웃: 30초

package/templates/platforms/claude-code/rules/completion-verification.md

@@ -0,0 +1,30 @@
+---
+description: 완료 검증 루프. 자기 보고 금지, exit code로 완료 판정.
+globs:
+  - "**/*"
+---
+
+# 완료 검증 루프 (Completion Verification)
+
+## 원칙: 자기 보고 금지
+
+"작업을 완료했습니다"라고 자체 판단하지 마세요. 객관적 증거(테스트 exit code)가 완료를 판정합니다.
+
+## 자동 검증 (Stop Hook)
+
+Implementation phase에서 턴이 종료될 때:
+1. 세션 내 Bash 명령 실행 이력 확인
+2. 테스트가 한 번도 실행되지 않았으면 **블로킹** — 강제로 테스트 실행 요구
+3. `stop_hook_active` 플래그로 1회만 블로킹 (무한루프 방지)
+
+## 블로킹 수신 시 대응
+
+`[Completion Guard]` 블로킹 메시지를 받으면:
+1. 프로젝트의 테스트 명령을 실행하세요 (`npm test`, `pytest` 등)
+2. 실패한 테스트가 있으면 수정하세요
+3. 모든 테스트 통과 후 작업을 마무리하세요
+
+## 참고
+
+- Planning/Design phase에서는 블로킹하지 않음 (코드 변경이 없으므로)
+- 세션 컨텍스트(`[Session]`)는 블로킹 여부와 무관하게 항상 주입됨

package/templates/platforms/claude-code/rules/context-monitor.md

@@ -0,0 +1,23 @@
+---
+description: 컨텍스트 윈도우 모니터. 85% 임계값 도달 시 사전 대응.
+globs:
+  - ".timsquad/.daemon/**"
+---
+
+# 컨텍스트 윈도우 모니터 (Context Window Monitor)
+
+## 자동 감지
+매 턴 종료 시 `[Session]` 메시지에 컨텍스트 사용률이 포함됩니다.
+- 70% 이상: `Ctx: XX%` 표시
+- 85% 이상: 경고 메시지 발생
+
+## 85% 경고 수신 시 대응 절차
+1. **현재 태스크 상태 기록**: 진행 중인 작업, 결정사항, 다음 단계를 정리
+2. **서브에이전트 완료 대기**: 활성 서브에이전트가 있으면 완료 후 정리
+3. **태스크 마무리**: 현재 태스크를 가능한 완료 지점까지 진행
+4. **컨텍스트 압축 대비**: 자동 압축 후에도 `[Session]` 메시지로 상태 복원 가능
+
+## 참고
+- 기본 컨텍스트 윈도우: 200K 토큰 (Sonnet 기준)
+- 자동 압축은 75-95% 사이에서 발생 (Claude Code 내부 휴리스틱)
+- 사용률은 최신 턴의 input 토큰 기준 (누적 아님)

package/templates/platforms/claude-code/rules/librarian-constraints.md

@@ -0,0 +1,11 @@
+---
+paths:
+  - ".timsquad/**"
+  - "docs/**"
+---
+
+Librarian 에이전트가 이 경로에서 작업할 때:
+- 문서 작성/갱신 허용
+- 소스 코드(src/, lib/, app/) 수정 절대 금지
+- 기록, 분석, 리포트 작성만 수행
+- 코드 변경이 필요한 사항은 피드백으로 라우팅

package/templates/platforms/claude-code/rules/plan-review.md

@@ -0,0 +1,45 @@
+---
+description: 계획 품질 검증 루프. Full Mode에서 구현 전 필수 수행.
+globs:
+  - ".timsquad/ssot/**"
+  - ".timsquad/state/**"
+---
+
+# 계획 품질 검증 (Plan Review Protocol)
+
+## 언제 수행하나
+`tsq f`로 Full Mode 진입 시, SSOT 체크 후 / 에이전트 위임 전.
+
+## 검증 축 (3-Axis Plan Review)
+
+### Axis P1: 요구사항 명확성
+- 태스크가 구체적 행동(what)과 완료 조건(done-when)을 포함하는가
+- 모호한 용어 없이 검증 가능한 기준이 있는가
+- SSOT 문서(requirements.md, functional-spec.md)에 근거가 있는가
+
+### Axis P2: 기술 분해 품질
+- 단일 시퀀스로 완료 가능한 크기인가 (아니면 분할 필요)
+- 에이전트 위임이 명확한가 (developer/dba/qa 중 누구에게)
+- 의존성 순서가 올바른가 (DB 먼저 → API → 프론트 등)
+
+### Axis P3: 리스크 & 빠진 것
+- 기존 코드에 영향을 주는 부분이 식별되었는가
+- 에러/엣지 케이스 대응이 계획에 포함되었는가
+- 보안/성능 고려사항이 누락되지 않았는가
+
+## 검증 결과 분류
+
+| 결과 | 조건 | 액션 |
+|------|------|------|
+| ✅ PASS | 3축 모두 충족 | 구현 진행 |
+| 🔄 REVISE (1/2) | 1-2축 미충족, 자체 보완 가능 | PM이 계획 보완 후 재검증 |
+| ❌ ESCALATE | 3축 미충족 or 2회 재검토 후에도 미충족 | 사용자에게 확인 요청 (L3) |
+
+## 재검토 규칙
+- 최대 2회 재검토 (iteration 1 → 2 → 실패 시 ESCALATE)
+- 매 재검토마다 어떤 축이 미충족인지 명시
+- REVISE 시 SSOT 보완이 필요하면 먼저 SSOT 수정 후 재검증
+- 2회 이내 PASS 시 "Plan Review: PASS (iteration N)" 기록 후 진행
+
+## 상세 체크 항목
+knowledge/checklists/plan-quality.md 참조.

package/templates/platforms/claude-code/rules/quality-guards.md

@@ -0,0 +1,43 @@
+---
+description: 품질 가드 시스템. 파괴적 명령 차단, 페이즈 제한, 완료 검증.
+globs:
+  - "**/*"
+---
+
+# 품질 가드 시스템 (Quality Guards)
+
+## 가드 목록
+
+### 1. Safe Guard (PreToolUse/Bash)
+Bash 명령 실행 전 파괴적 명령을 차단합니다.
+
+**차단 (DENY)**:
+- `rm -rf /` — 루트 삭제
+- `git push --force` (main/master) — force push
+- `git reset --hard` — 커밋되지 않은 변경 유실
+- `DROP TABLE`, `TRUNCATE TABLE` — 데이터 파괴
+- `chmod 777` — 보안 위반
+
+**확인 요청 (ASK)**:
+- `npm publish` — 패키지 배포
+- `git push` (main/master) — 메인 브랜치 push
+- `rm -rf` (일반) — 재귀 삭제
+
+### 2. Phase Guard (PreToolUse/Write|Edit)
+페이즈에 따라 파일 수정을 제한합니다.
+
+- **planning/design**: `src/`, `lib/`, `app/` 등 코드 수정 차단
+- **implementation**: `.timsquad/ssot/` 직접 수정 차단
+
+### 3. Completion Guard (Stop)
+매 턴 종료 시 세션 컨텍스트를 주입하고, 필요 시 경고합니다.
+
+- 세션 상태 (턴, 도구, 에이전트, 파일) 주입
+- implementation phase에서 테스트 미실행 경고
+- 컨텍스트 윈도우 85% 이상 시 경고
+
+## 가드가 차단한 경우
+
+1. **DENY된 경우**: 차단 사유를 확인하고 안전한 대안을 사용하세요
+2. **ASK로 에스컬레이션된 경우**: 사용자에게 확인을 요청합니다
+3. **Phase 제한인 경우**: 현재 페이즈에 맞는 작업을 수행하세요

package/templates/platforms/claude-code/rules/session-notes.md

@@ -0,0 +1,18 @@
+---
+description: 컨텍스트 생존 메모. 세션 압축 후 작업 연속성 유지.
+globs:
+  - ".timsquad/.daemon/**"
+---
+
+# 세션 컨텍스트 복원 (Session Notes)
+
+## 자동 주입
+매 턴 종료 시 `[Session]` 시스템 메시지가 자동 주입됩니다.
+- 현재 턴 번호, 도구 사용 횟수, 활성 서브에이전트, 최근 수정 파일
+
+## 압축 감지 후 대응
+컨텍스트가 압축된 것 같으면 (이전 대화 내용이 요약되어 있으면):
+1. `[Session]` 메시지의 턴/도구/에이전트 정보로 현재 진행 상태 파악
+2. 필요 시 `.timsquad/.daemon/session-notes.jsonl`을 직접 읽어 이전 턴 이력 확인
+3. 최근 수정 파일들을 Read로 다시 확인하여 작업 컨텍스트 복원
+4. `.timsquad/logs/sessions/` 하위 세션 로그에서 상세 이벤트 확인 가능

package/templates/platforms/claude-code/rules/skill-suggest.md

@@ -0,0 +1,27 @@
+---
+description: 런타임 스킬 제안. 프롬프트 분석 후 관련 스킬 자동 추천.
+globs:
+  - "**/*"
+---
+
+# 런타임 스킬 제안 (Skill Suggest)
+
+## 자동 감지
+
+매 프롬프트 제출 시 `[Skill Suggest]` 메시지가 주입될 수 있습니다.
+- 사용자 프롬프트의 키워드/패턴을 분석하여 관련 스킬 추천
+- 배포된 스킬만 추천 (프로젝트에 없는 스킬은 무시)
+
+## 제안 수신 시 대응
+
+`[Skill Suggest] 관련 스킬이 감지되었습니다: ...` 메시지를 받으면:
+1. 추천된 스킬의 `rules/` 디렉토리를 확인하세요
+2. 현재 태스크에 관련된 규칙을 참조하여 품질을 높이세요
+3. 스킬이 현재 작업과 무관하면 무시해도 됩니다
+
+## 스킬 규칙 위치
+
+배포된 스킬: `.claude/skills/{skill-name}/`
+- `SKILL.md` — 스킬 개요
+- `rules/` — 구체적 규칙 (on-demand 참조)
+- `references/` — 참고 자료

package/templates/platforms/claude-code/rules/test-conventions.md

@@ -0,0 +1,13 @@
+---
+paths:
+  - "tests/**/*.test.ts"
+  - "tests/**/*.spec.ts"
+  - "**/*.test.ts"
+  - "**/*.spec.ts"
+---
+
+- describe/it 중첩 3단계 이하 유지
+- 테스트 데이터는 인라인 또는 fixtures/ 디렉토리 사용
+- 각 테스트는 독립적 (공유 상태 금지, beforeEach에서 초기화)
+- 테스트 이름은 "should + 기대 동작" 형식
+- mock은 최소 범위로 사용 (외부 의존성만 mock)

package/templates/platforms/claude-code/scripts/build-gate.sh

@@ -0,0 +1,73 @@
+#!/bin/bash
+# Build Gate — Stop Hook
+# 변경된 TypeScript 파일에 tsc 에러가 있으면 완료를 차단한다.
+# 변경 파일만 필터링하여 기존 에러는 무시.
+#
+# Input: JSON via stdin (Claude Code hook protocol)
+# Output: JSON with decision (block) or empty
+
+set -e
+
+# ── 0. Stop hook loop prevention ──
+INPUT=$(cat 2>/dev/null || echo "")
+STOP_HOOK_ACTIVE=$(echo "$INPUT" | jq -r '.stop_hook_active // false' 2>/dev/null || echo "false")
+if [ "$STOP_HOOK_ACTIVE" = "true" ]; then
+  exit 0
+fi
+
+# Find project root
+PROJECT_ROOT="$(pwd)"
+while [ "$PROJECT_ROOT" != "/" ]; do
+  if [ -d "$PROJECT_ROOT/.timsquad" ]; then
+    break
+  fi
+  PROJECT_ROOT="$(dirname "$PROJECT_ROOT")"
+done
+
+if [ ! -d "$PROJECT_ROOT/.timsquad" ]; then
+  exit 0
+fi
+
+# ── 1. Get changed TypeScript files ──
+cd "$PROJECT_ROOT"
+CHANGED_TS=$(git diff --name-only --diff-filter=ACMR HEAD -- '*.ts' '*.tsx' 2>/dev/null || echo "")
+
+# No TypeScript files changed → pass
+if [ -z "$CHANGED_TS" ]; then
+  exit 0
+fi
+
+# ── 2. Run tsc --noEmit ──
+TSC_OUTPUT=$(npx tsc --noEmit 2>&1 || true)
+
+# tsc passed → allow stop
+if [ -z "$TSC_OUTPUT" ]; then
+  exit 0
+fi
+
+# ── 3. Filter errors to changed files only ──
+RELEVANT_ERRORS=""
+while IFS= read -r file; do
+  # tsc 에러 형식: src/foo.ts(12,5): error TS2345: ...
+  FILE_ERRORS=$(echo "$TSC_OUTPUT" | grep -F -- "$file" 2>/dev/null || true)
+  if [ -n "$FILE_ERRORS" ]; then
+    RELEVANT_ERRORS="${RELEVANT_ERRORS}${FILE_ERRORS}
+"
+  fi
+done <<< "$CHANGED_TS"
+
+# No errors in changed files → pre-existing errors, ignore
+if [ -z "$RELEVANT_ERRORS" ]; then
+  exit 0
+fi
+
+# ── 4. Block with error details ──
+# 에러 수 계산
+ERROR_COUNT=$(echo "$RELEVANT_ERRORS" | grep -c "error TS" 2>/dev/null || echo "0")
+
+REASON="[Build Gate] 변경된 파일에 TypeScript 에러 ${ERROR_COUNT}개가 있습니다. 수정 후 완료하세요.
+
+${RELEVANT_ERRORS}"
+
+jq -n --arg reason "$REASON" '{"decision": "block", "reason": $reason}'
+exit 0

package/templates/platforms/claude-code/scripts/change-scope-guard.sh

@@ -0,0 +1,113 @@
+#!/usr/bin/env bash
+# change-scope-guard.sh — PreToolUse Hook (Edit/Write)
+# Tracks cumulative file changes and enforces SCR (Single Change Rule).
+# 3 files: warning, 6 files: block, >100 lines total: warning
+#
+# Input: JSON via stdin (Claude Code hook protocol)
+# Output: JSON with permissionDecision (allow/deny/ask)
+#
+# State file: /tmp/tsq-scope-guard-${SESSION_ID:-default}.json
+
+set -euo pipefail
+
+WARN_FILES=3
+BLOCK_FILES=6
+WARN_LINES=100
+
+# Session-scoped state file
+SESSION_ID="${CLAUDE_SESSION_ID:-default}"
+STATE_FILE="/tmp/tsq-scope-guard-${SESSION_ID}.json"
+
+# Read hook input from stdin
+INPUT=""
+if read -t 1 -r line; then
+  INPUT="$line"
+fi
+
+# Fail-open: no input → allow
+if [ -z "$INPUT" ]; then
+  echo '{"hookSpecificOutput":{"permissionDecision":"allow"}}'
+  exit 0
+fi
+
+# Extract tool name
+TOOL_NAME=""
+if command -v jq >/dev/null 2>&1; then
+  TOOL_NAME=$(echo "$INPUT" | jq -r '.toolName // empty' 2>/dev/null || true)
+fi
+
+# Only track Edit and Write tools
+if [ "$TOOL_NAME" != "Edit" ] && [ "$TOOL_NAME" != "Write" ]; then
+  echo '{"hookSpecificOutput":{"permissionDecision":"allow"}}'
+  exit 0
+fi
+
+# Extract file path from tool input
+FILE_PATH=""
+if command -v jq >/dev/null 2>&1; then
+  FILE_PATH=$(echo "$INPUT" | jq -r '.toolInput.file_path // empty' 2>/dev/null || true)
+fi
+
+if [ -z "$FILE_PATH" ]; then
+  echo '{"hookSpecificOutput":{"permissionDecision":"allow"}}'
+  exit 0
+fi
+
+# Initialize state file if needed
+if [ ! -f "$STATE_FILE" ]; then
+  echo '{"files":[],"total_lines":0}' > "$STATE_FILE"
+fi
+
+# Read current state
+if command -v jq >/dev/null 2>&1; then
+  CURRENT_FILES=$(jq -r '.files[]' "$STATE_FILE" 2>/dev/null || true)
+  TOTAL_LINES=$(jq -r '.total_lines // 0' "$STATE_FILE" 2>/dev/null || echo "0")
+else
+  echo '{"hookSpecificOutput":{"permissionDecision":"allow"}}'
+  exit 0
+fi
+
+# Check if file is already tracked
+ALREADY_TRACKED=false
+while IFS= read -r f; do
+  if [ "$f" = "$FILE_PATH" ]; then
+    ALREADY_TRACKED=true
+    break
+  fi
+done <<< "$CURRENT_FILES"
+
+# Add new file if not tracked
+if [ "$ALREADY_TRACKED" = false ]; then
+  jq --arg fp "$FILE_PATH" '.files += [$fp]' "$STATE_FILE" > "${STATE_FILE}.tmp" && mv "${STATE_FILE}.tmp" "$STATE_FILE"
+fi
+
+# Estimate line changes (for Edit: old_string length approximation)
+if [ "$TOOL_NAME" = "Edit" ]; then
+  NEW_LINES=$(echo "$INPUT" | jq -r '.toolInput.new_string // ""' 2>/dev/null | wc -l || echo "0")
+  TOTAL_LINES=$((TOTAL_LINES + NEW_LINES))
+  jq --argjson tl "$TOTAL_LINES" '.total_lines = $tl' "$STATE_FILE" > "${STATE_FILE}.tmp" && mv "${STATE_FILE}.tmp" "$STATE_FILE"
+fi
+
+# Count unique files
+FILE_COUNT=$(jq '.files | length' "$STATE_FILE" 2>/dev/null || echo "0")
+
+# Decision logic
+if [ "$FILE_COUNT" -ge "$BLOCK_FILES" ]; then
+  MSG="SCR violation: ${FILE_COUNT} files modified (limit: ${BLOCK_FILES}). Split into smaller tasks."
+  echo "{\"hookSpecificOutput\":{\"permissionDecision\":\"deny\",\"message\":\"${MSG}\"}}"
+  exit 0
+fi
+
+if [ "$FILE_COUNT" -ge "$WARN_FILES" ]; then
+  MSG="SCR warning: ${FILE_COUNT} files modified. Consider splitting this task."
+  echo "{\"hookSpecificOutput\":{\"permissionDecision\":\"allow\",\"message\":\"${MSG}\"}}"
+  exit 0
+fi
+
+if [ "$TOTAL_LINES" -ge "$WARN_LINES" ]; then
+  MSG="Large change: ~${TOTAL_LINES} lines modified across ${FILE_COUNT} files."
+  echo "{\"hookSpecificOutput\":{\"permissionDecision\":\"allow\",\"message\":\"${MSG}\"}}"
+  exit 0
+fi
+
+echo '{"hookSpecificOutput":{"permissionDecision":"allow"}}'