timsquad 3.7.0 → 3.8.0

package/templates/base/scripts/cleanup-trails.sh

@@ -0,0 +1,44 @@
+#!/usr/bin/env bash
+# cleanup-trails.sh — trail 아카이브 10개 초과 시 자동 정리
+# Usage: bash .timsquad/scripts/cleanup-trails.sh [project_root] [max_count]
+# Output: JSON {archived, remaining}
+set -euo pipefail
+
+ROOT="${1:-.}"
+MAX_COUNT="${2:-10}"
+TRAILS_DIR="$ROOT/.timsquad/trails"
+ARCHIVE_DIR="$TRAILS_DIR/.archive"
+
+if [ ! -d "$TRAILS_DIR" ]; then
+  echo '{"archived":0,"remaining":0,"reason":"trails directory not found"}'
+  exit 0
+fi
+
+# Count trail files (exclude .archive directory)
+trail_files=()
+while IFS= read -r -d '' f; do
+  trail_files+=("$f")
+done < <(find "$TRAILS_DIR" -maxdepth 1 -type f -print0 | sort -z)
+
+count=${#trail_files[@]}
+
+if [ "$count" -le "$MAX_COUNT" ]; then
+  echo '{"archived":0,"remaining":'"$count"'}'
+  exit 0
+fi
+
+# Archive oldest files beyond MAX_COUNT
+to_archive=$((count - MAX_COUNT))
+archive_month=$(date -u +%Y-%m)
+archive_dest="$ARCHIVE_DIR/$archive_month"
+mkdir -p "$archive_dest"
+
+archived=0
+for ((i=0; i<to_archive; i++)); do
+  file="${trail_files[$i]}"
+  mv "$file" "$archive_dest/"
+  ((archived++))
+done
+
+remaining=$((count - archived))
+echo '{"archived":'"$archived"',"remaining":'"$remaining"',"archive_path":"'"$archive_dest"'"}'

package/templates/base/scripts/generate-prd-traceability.sh

@@ -0,0 +1,91 @@
+#!/usr/bin/env bash
+# generate-prd-traceability.sh — planning.md ↔ PRD 추적성 매트릭스 생성
+# Usage: bash .timsquad/scripts/generate-prd-traceability.sh [project_root]
+# Output: .timsquad/reports/traceability-matrix.md
+set -euo pipefail
+
+ROOT="${1:-.}"
+PRD="$ROOT/.timsquad/ssot/prd.md"
+PLANNING="$ROOT/.timsquad/ssot/planning.md"
+REPORT_DIR="$ROOT/.timsquad/reports"
+OUTPUT="$REPORT_DIR/traceability-matrix.md"
+
+if [ ! -f "$PRD" ]; then
+  echo '{"status":"skip","reason":"prd.md not found"}'
+  exit 0
+fi
+
+if [ ! -f "$PLANNING" ]; then
+  echo '{"status":"skip","reason":"planning.md not found"}'
+  exit 0
+fi
+
+mkdir -p "$REPORT_DIR"
+
+# Extract PRD feature sections (## headings)
+prd_features=()
+while IFS= read -r line; do
+  if [[ "$line" =~ ^##[[:space:]]+(.+) ]]; then
+    prd_features+=("${BASH_REMATCH[1]}")
+  fi
+done < "$PRD"
+
+# Extract planning tasks with their phase/sequence context
+declare -A task_map
+current_phase=""
+current_seq=""
+
+while IFS= read -r line; do
+  if [[ "$line" =~ ^##[[:space:]]+Phase.*\(([A-Z][0-9]+)\) ]]; then
+    current_phase="${BASH_REMATCH[1]}"
+  elif [[ "$line" =~ ^##[[:space:]]+.+\(([A-Z][0-9]+-S[0-9]+)\) ]]; then
+    current_seq="${BASH_REMATCH[1]}"
+  elif [[ "$line" =~ ^###[[:space:]]+(.+)\(([A-Z][0-9]+-S[0-9]+-T[0-9]+)\) ]]; then
+    task_title="${BASH_REMATCH[1]}"
+    task_id="${BASH_REMATCH[2]}"
+    task_map["$task_id"]="$current_phase | $current_seq | $task_title"
+  fi
+done < "$PLANNING"
+
+# Generate traceability matrix
+{
+  echo "# PRD Traceability Matrix"
+  echo ""
+  echo "> Generated: $(date -u +%Y-%m-%dT%H:%M:%SZ)"
+  echo ""
+  echo "| PRD Feature | Mapped Tasks | Coverage |"
+  echo "|-------------|-------------|----------|"
+
+  mapped=0
+  total=${#prd_features[@]}
+
+  for feature in "${prd_features[@]}"; do
+    # Find tasks that reference this feature (case-insensitive partial match)
+    feature_lower=$(echo "$feature" | tr '[:upper:]' '[:lower:]')
+    matching_tasks=""
+
+    for task_id in "${!task_map[@]}"; do
+      task_lower=$(echo "${task_map[$task_id]}" | tr '[:upper:]' '[:lower:]')
+      if [[ "$task_lower" == *"$feature_lower"* ]] || [[ "$feature_lower" == *"$task_lower"* ]]; then
+        matching_tasks+="$task_id "
+      fi
+    done
+
+    if [ -n "$matching_tasks" ]; then
+      echo "| $feature | $(echo "$matching_tasks" | xargs | tr ' ' ', ') | Mapped |"
+      ((mapped++))
+    else
+      echo "| $feature | — | **Unmapped** |"
+    fi
+  done
+
+  echo ""
+  if [ "$total" -gt 0 ]; then
+    coverage=$((mapped * 100 / total))
+    echo "**Coverage:** $mapped / $total ($coverage%)"
+  else
+    echo "**Coverage:** No PRD features found"
+  fi
+} > "$OUTPUT"
+
+echo '{"status":"ok","output":"'"$OUTPUT"'","features":'"$total"',"mapped":'"$mapped"'}'

package/templates/base/scripts/manage-fp-registry.sh

@@ -0,0 +1,83 @@
+#!/usr/bin/env bash
+# manage-fp-registry.sh — audit False Positive 자동 필터링
+# Usage: bash .timsquad/scripts/manage-fp-registry.sh [project_root]
+#        bash .timsquad/scripts/manage-fp-registry.sh . add "pattern-id"
+#        bash .timsquad/scripts/manage-fp-registry.sh . exclude "pattern-id"
+# Output: JSON fp-registry
+set -euo pipefail
+
+ROOT="${1:-.}"
+ACTION="${2:-scan}"
+PATTERN_ID="${3:-}"
+REGISTRY="$ROOT/.timsquad/retrospective/fp-registry.json"
+RETRO_DIR="$ROOT/.timsquad/retrospective"
+
+if ! command -v jq &>/dev/null; then
+  echo '{"error":"jq is required"}' >&2
+  exit 1
+fi
+
+# Initialize registry if missing
+if [ ! -f "$REGISTRY" ]; then
+  mkdir -p "$RETRO_DIR"
+  echo '{"patterns":[],"excluded":[]}' > "$REGISTRY"
+fi
+
+case "$ACTION" in
+  scan)
+    # Scan retrospective cycles for repeated feedback patterns
+    CYCLES_DIR="$RETRO_DIR/cycles"
+    if [ ! -d "$CYCLES_DIR" ]; then
+      cat "$REGISTRY"
+      exit 0
+    fi
+
+    # Count feedback pattern occurrences across cycles
+    pattern_counts=$(find "$CYCLES_DIR" -name '*.json' -type f -exec \
+      jq -r '.problem[]? // empty' {} \; 2>/dev/null | \
+      sort | uniq -c | sort -rn | head -20)
+
+    # Update registry: patterns with 3+ occurrences → candidate FP
+    while IFS= read -r line; do
+      [ -z "$line" ] && continue
+      count=$(echo "$line" | awk '{print $1}')
+      pattern=$(echo "$line" | sed 's/^[[:space:]]*[0-9]*[[:space:]]*//')
+      [ "$count" -lt 3 ] && continue
+
+      # Add/update in registry
+      existing=$(jq -r --arg p "$pattern" '.patterns[] | select(.id == $p) | .id' "$REGISTRY" 2>/dev/null)
+      if [ -z "$existing" ]; then
+        jq --arg p "$pattern" --argjson c "$count" \
+          '.patterns += [{"id": $p, "count": $c, "last_occurrence": (now | todate)}]' \
+          "$REGISTRY" > "$REGISTRY.tmp" && mv "$REGISTRY.tmp" "$REGISTRY"
+      else
+        jq --arg p "$pattern" --argjson c "$count" \
+          '(.patterns[] | select(.id == $p)) |= (.count = $c | .last_occurrence = (now | todate))' \
+          "$REGISTRY" > "$REGISTRY.tmp" && mv "$REGISTRY.tmp" "$REGISTRY"
+      fi
+    done <<< "$pattern_counts"
+
+    cat "$REGISTRY"
+    ;;
+
+  add)
+    [ -z "$PATTERN_ID" ] && { echo '{"error":"pattern id required"}' >&2; exit 1; }
+    jq --arg p "$PATTERN_ID" \
+      'if (.patterns | map(.id) | index($p)) then . else .patterns += [{"id": $p, "count": 1, "last_occurrence": (now | todate)}] end' \
+      "$REGISTRY" > "$REGISTRY.tmp" && mv "$REGISTRY.tmp" "$REGISTRY"
+    cat "$REGISTRY"
+    ;;
+
+  exclude)
+    [ -z "$PATTERN_ID" ] && { echo '{"error":"pattern id required"}' >&2; exit 1; }
+    jq --arg p "$PATTERN_ID" \
+      'if (.excluded | index($p)) then . else .excluded += [$p] end' \
+      "$REGISTRY" > "$REGISTRY.tmp" && mv "$REGISTRY.tmp" "$REGISTRY"
+    cat "$REGISTRY"
+    ;;
+
+  *)
+    echo '{"error":"unknown action: '"$ACTION"'. Use scan|add|exclude"}' >&2
+    exit 1
+    ;;
+esac

package/templates/base/scripts/validate-gherkin.sh

@@ -0,0 +1,113 @@
+#!/usr/bin/env bash
+# validate-gherkin.sh — BDD feature 파일 구문 검증
+# Usage: bash .timsquad/scripts/validate-gherkin.sh [features_dir]
+# Output: JSON {valid, errors, total_files}
+set -euo pipefail
+
+FEATURES_DIR="${1:-features}"
+
+if [ ! -d "$FEATURES_DIR" ]; then
+  echo '{"valid":true,"errors":[],"total_files":0,"reason":"features directory not found"}'
+  exit 0
+fi
+
+errors=()
+total=0
+
+while IFS= read -r file; do
+  ((total++))
+  line_num=0
+  has_feature=false
+  has_scenario=false
+  in_scenario=false
+  step_order=""  # track Given/When/Then order
+
+  while IFS= read -r line; do
+    ((line_num++))
+    trimmed=$(echo "$line" | sed 's/^[[:space:]]*//')
+
+    # Skip empty lines and comments
+    [[ -z "$trimmed" || "$trimmed" == \#* ]] && continue
+
+    # Feature keyword
+    if [[ "$trimmed" =~ ^Feature:[[:space:]]*.+ ]]; then
+      has_feature=true
+      continue
+    fi
+
+    # Scenario / Scenario Outline
+    if [[ "$trimmed" =~ ^(Scenario|Scenario\ Outline):[[:space:]]*.+ ]]; then
+      has_scenario=true
+      in_scenario=true
+      step_order=""
+      continue
+    fi
+
+    # Step keywords
+    if [[ "$trimmed" =~ ^(Given|When|Then|And|But)[[:space:]]+ ]]; then
+      keyword="${BASH_REMATCH[1]}"
+      if [[ "$keyword" == "Given" ]]; then
+        if [[ "$step_order" == *"Then"* ]]; then
+          errors+=("{\"file\":\"$file\",\"line\":$line_num,\"msg\":\"Given after Then\"}")
+        fi
+        step_order+="Given "
+      elif [[ "$keyword" == "When" ]]; then
+        step_order+="When "
+      elif [[ "$keyword" == "Then" ]]; then
+        step_order+="Then "
+      fi
+      continue
+    fi
+
+    # Examples keyword (only valid in Scenario Outline)
+    if [[ "$trimmed" =~ ^Examples: ]]; then
+      continue
+    fi
+
+    # Table rows
+    if [[ "$trimmed" =~ ^\| ]]; then
+      continue
+    fi
+
+    # Tags
+    if [[ "$trimmed" =~ ^@ ]]; then
+      continue
+    fi
+
+    # Background
+    if [[ "$trimmed" =~ ^Background: ]]; then
+      continue
+    fi
+
+    # Rule (Gherkin 6)
+    if [[ "$trimmed" =~ ^Rule:[[:space:]]*.+ ]]; then
+      continue
+    fi
+
+    # Doc strings
+    if [[ "$trimmed" == '"""' || "$trimmed" == '```' ]]; then
+      continue
+    fi
+
+  done < "$file"
+
+  # Validate structure
+  if ! $has_feature; then
+    errors+=("{\"file\":\"$file\",\"line\":1,\"msg\":\"Missing Feature keyword\"}")
+  fi
+  if ! $has_scenario; then
+    errors+=("{\"file\":\"$file\",\"line\":1,\"msg\":\"No Scenario defined\"}")
+  fi
+
+done < <(find "$FEATURES_DIR" -name '*.feature' -type f | sort)
+
+# Build JSON output
+if [ ${#errors[@]} -eq 0 ]; then
+  echo '{"valid":true,"errors":[],"total_files":'"$total"'}'
+  exit 0
+else
+  error_json=$(printf '%s,' "${errors[@]}")
+  error_json="[${error_json%,}]"
+  echo '{"valid":false,"errors":'"$error_json"',"total_files":'"$total"'}'
+  exit 1
+fi

package/templates/base/skills/tsq-controller/SKILL.md

@@ -4,39 +4,63 @@ description: |
   Context DI 컨테이너. 서브에이전트 위임 시 compiled spec을 의존성으로 주입.
   서브에이전트 호출, Task() 위임, 에이전트 실행 시 자동 트리거.
   Use when: "구현해줘", "테스트해줘", "리뷰해줘", "설계해줘", 서브에이전트 위임
-version: "2.1.0"
-tags: [tsq, controller, di, context-injection]
+version: "3.0.0"
+tags: [tsq, controller, di, context-injection, hybrid]
 user-invocable: false
 ---
 
-# Controller (Context DI Container)
+# Controller (Hybrid — Context DI + CLI)
 
 서브에이전트에게 작업을 위임할 때 컨텍스트를 자동 해석하고 주입하는 컨테이너.
+v3.0: 결정론적 로직(상태, 순서, 게이트)은 `tsq next` CLI로 이동. Controller는 판단(스펙 결정, 품질 평가, 프롬프트 구성)에 집중.
 
 ## Contract
 
 - **Trigger**: 서브에이전트 위임 시 (구현, 테스트, 리뷰 등)
-- **Input**: 에이전트 파일 + prerequisites + compiled specs
+- **Input**: `tsq next` JSON + 에이전트 파일 + compiled specs
 - **Output**: 조합된 프롬프트로 Task() 실행
 - **Error**: spec stale 시 `tsq compile` 재실행 안내
 
 ## Protocol
 
-1. **Memory 참조**: `memory/` 디렉토리의 모든 .md 파일 Read
-2. **SSOT Map 참조**: `.timsquad/ssot-map.yaml` → 티어 compiled spec 목록 확인
-3. **Capability Token 발급**: `.timsquad/state/controller-active` + `allowed-paths.txt` 생성
-4. **에이전트 파일 확인**: `.claude/agents/{agent}.md` 읽기
-5. **Prerequisites 파싱**: `<prerequisites>` 태그에서 SSOT 목록 추출
-6. **Spec Resolve**: `references/`에서 해당 compiled spec 로드
-7. **Stale 체크**: `.compile-manifest.json` hash 비교
-8. **방법론 참조**: `config.yaml`의 `methodology.development` → 해당 스킬 Protocol 로드
-9. **프롬프트 조합**: tsq-protocol + **phase-memory carry-over** + memory + specs + methodology + phase 제약 + 지시
-   - `.timsquad/state/phase-memory.md` 존재 시 carry-over/주의 섹션을 프롬프트 앞에 강제 삽입
-   - 미존재 시 스킵 (초기 프로젝트)
-10. **Task() 호출**: 조합된 프롬프트로 서브에이전트 실행. 에이전트 파일의 `model` 필드가 있으면 Task()의 model 파라미터로 전달 (예: model: sonnet → 빠른 모델, model: opus → 정밀 모델)
-11. **Completion Report 검증**: 5개 필드(Task, Status, Files, Tests, Notes) 확인 — 누락 시 재요청
-12. **완료 트리거**: Triggers 섹션의 해당 규칙 수행
-13. **Capability Token 회수**: `controller-active` + `allowed-paths.txt` 삭제
+1. **다음 태스크 조회**: `tsq next` 실행 → JSON 출력에서 taskId, phaseId, sequenceId, title, agent 추출
+   - `all_complete` → 사용자에게 완료 안내
+   - `error` → planning.md 부재 시 `/tsq-decompose` 안내
+2. **Task Context 기록**: `.timsquad/.daemon/task-context.json`에 현재 태스크 정보 저장 (SubagentStop hook이 읽음)
+3. **Memory 참조**: `memory/` 디렉토리의 모든 .md 파일 Read
+4. **SSOT Map 참조**: `.timsquad/ssot-map.yaml` → 티어 compiled spec 목록 확인
+5. **Capability Token 발급**: `.timsquad/state/controller-active` + `allowed-paths.txt` 생성
+6. **에이전트 파일 확인**: `.claude/agents/{agent}.md` 읽기
+7. **Prerequisites 파싱**: `<prerequisites>` 태그에서 SSOT 목록 추출
+8. **Spec Resolve**: `references/`에서 해당 compiled spec 로드
+9. **Meta Index 쿼리**: `.timsquad/.daemon/task-context.json` 읽기 → scope 파일 구조를 프롬프트에 주입 (Daemon이 자동 갱신)
+10. **Stale 체크**: `.compile-manifest.json` hash 비교
+11. **방법론 참조**: `config.yaml`의 `methodology.development` → 해당 스킬 Protocol 로드
+12. **프롬프트 조합**: tsq-protocol + **phase-memory carry-over** + memory + specs + meta-index scope + methodology + phase 제약 + 지시
+    - `.timsquad/state/phase-memory.md` 존재 시 carry-over/주의 섹션을 프롬프트 앞에 강제 삽입
+13. **Model Routing → Task() 호출**: Model Routing 테이블에 따라 최종 모델을 결정한 뒤, 조합된 프롬프트로 서브에이전트 실행. 결정된 모델을 Task()의 model 파라미터로 전달
+14. **Completion Report 검증**: 5개 필드(Task, Status, Files, Tests, Notes) 확인 — 누락 시 재요청
+15. **Capability Token 회수**: `controller-active` + `allowed-paths.txt` 삭제
+16. **다음 태스크**: Step 1로 돌아가서 반복 (또는 Phase 완료 시 Librarian 호출)
+
+> 이전(v2.1)에서 Controller가 직접 하던 작업의 코드 이동:
+> - ~~planning.md 파싱~~ → `tsq next` CLI (결정론적)
+> - ~~workflow.json 갱신~~ → SubagentStop hook이 `tsq next --complete` 자동 호출
+> - ~~Phase 완료 판정~~ → completion-guard hook이 `tsq next --phase-status` 호출
+> - ~~phase-memory append~~ → SubagentStop hook이 자동 append
+
+## Model Routing
+
+`references/model-routing.md` 참조. `config.yaml`의 `model_routing` 설정(enabled, strategy)에 따라 태스크 복잡도 기반 모델 동적 선택.
+- **aggressive**: 최대 haiku 사용 (비용 최적화)
+- **balanced**: phase 적합 모델 (기본값)
+- **conservative**: 최대 opus 사용 (품질 우선, fintech 기본)
+
+## Wave Dispatch (병렬)
+
+`references/wave-dispatch.md` 참조. `tsq next --wave`로 독립 태스크를 Wave로 묶어 동시 실행.
+- `waveSize > 1` → 병렬 Task() 호출, 태스크별 Capability Token 개별 발급
+- `waveSize === 1` → 기존 순차 Protocol 따름
 
 ## Delegation Rules
 
@@ -47,28 +71,27 @@ user-invocable: false
 
 ## Triggers
 
-동기(Controller) = 프로세스 강제, 게이트 판정. 비동기(Daemon) = 관찰, 로그 기록. Daemon 장애 시 Controller는 정상 동작.
+코드 강제(Hook/CLI) + LLM 판단(Controller) 하이브리드. Daemon 장애 시 Controller는 정상 동작.
 
-### task-complete (동기)
-1. **Completion Report 검증** — 5개 필드(Task, Status, Files, Tests, Notes) 확인, 누락 시 재요청
-2. **단위 테스트 확인** — Status=pass 필수, fail 시 Developer에 재위임
-3. **L1 로그 + Decision Log 확인** — Daemon이 L1 생성 (SubagentStop Hook). Daemon 장애 시 Controller가 수동 기록
-4. **workflow.json 갱신** — `.timsquad/state/workflow.json`에 완료된 task/sequence/phase 상태 기록 (compact 후 재개 시 진행 상태 복구용)
-5. **Sequence 완료 판정**: 해당 sequence의 expected_agents 모두 완료 → sequence-complete
-6. **미완료 시**: 다음 태스크 위임. planning.md의 해당 Task 산출물(출력 파일)이 이미 존재하면 스킵하고 그 다음 Task로 진행 (세션 재개 시 중복 작업 방지)
+### task-complete
+- **Hook 자동 처리**: SubagentStop hook → `tsq next --complete` → workflow.json 갱신 + phase-memory append
+- **Controller 판단** (LLM):
+  1. Completion Report 검증 — 5필드 확인, 누락 시 재요청
+  2. 단위 테스트 확인 — Status=pass 필수, fail 시 Developer에 재위임
+  3. L1 로그 확인 — Daemon이 L1 생성 (SubagentStop Hook). Daemon 장애 시 수동 기록
+  4. 다음 태스크 → `tsq next` 실행하여 다음 미완료 태스크로 진행
 
-### sequence-complete (동기)
+### sequence-complete
 1. **통합 게이트**: `npm run test:integration` + `tsc --noEmit` — 실패 시 차단, Developer에 수정 위임
 2. **L2 로그 확인**: `.timsquad/logs/sequences/{seq-id}.md` 존재 확인
-3. **문서 갱신 체크**: ROADMAP/STATUS/CHANGELOG stale 여부 (7일 이상 미수정 시 경고)
-3.5. **Spec Compliance 체크**: 해당 Sequence의 Sub-PRD Must-Have 목록과 완료된 Task 산출물을 대조. 누락 항목이 있으면 경고 표시 (block 아님 — 다른 Sequence나 Phase에서 처리 가능). 경고 내용을 L2 로그에 기록
-4. **Phase 완료 판정**: 모든 시퀀스 완료 → phase-complete
-
-### phase-complete (동기)
-1. **E2E 게이트**: `npm run test:e2e` — 실패 시 차단
-2. **L3 로그 + Phase Gate 확인**: `.timsquad/logs/phases/{phase-id}.md` 존재
-3. **Librarian 호출**: Task(librarian) — Phase Memory 아카이브 + 새 HEAD 생성 + Trail + 리포트
-4. **사용자 안내**: "Phase {id} 완료. 다음 단계: (1) `/tsq-retro` — 회고 실행, (2) `/clear` — 컨텍스트 초기화 (phase-memory 자동 주입됩니다)"
+3. **Spec Compliance 체크**: Sub-PRD Must-Have vs 완료 산출물 대조 (경고, block 아님)
+
+### phase-complete
+- **Hook 자동 감지**: completion-guard → `tsq next --phase-status` → Phase 완료 시 systemMessage로 안내
+- **Controller 판단** (LLM):
+  1. E2E 게이트: `npm run test:e2e` — 실패 시 차단
+  2. Librarian 호출: Task(librarian) — Phase Memory 아카이브 + 새 HEAD 생성
+  3. 사용자 안내: "`/tsq-retro` → `/clear`"
 
 ### ssot-changed (비동기, Daemon 전담)
 Daemon이 파일 감시로 `.compile-manifest.json` 갱신. 다음 Controller 실행 시 Stale 체크로 감지.

package/templates/base/skills/tsq-controller/references/model-routing.md

@@ -0,0 +1,38 @@
+---
+title: Model Routing
+category: reference
+---
+
+# Model Routing Reference
+
+`config.yaml`의 `model_routing.enabled`가 `true`이면 아래 테이블에 따라 모델을 동적 선택.
+`false`이면 에이전트 파일의 `model` 필드(기본값)를 그대로 사용.
+
+## Strategy별 라우팅 테이블
+
+| 에이전트 | 태스크 유형 | aggressive | balanced | conservative |
+|---------|-----------|-----------|----------|-------------|
+| **Architect** | 설계/리뷰 | sonnet | opus | opus |
+| **Developer** | 복잡한 구현 (아키텍처 변경, 복잡한 비즈니스 로직) | sonnet | sonnet | opus |
+| **Developer** | 일반 구현 | haiku | sonnet | sonnet |
+| **Developer** | 단순 구현 (CRUD, 스캐폴딩, 보일러플레이트) | haiku | haiku | sonnet |
+| **QA** | 코드 리뷰 | haiku | sonnet | opus |
+| **Security** | 보안 검토 | sonnet | sonnet | opus |
+| **DBA** | DB 설계/마이그레이션 | sonnet | sonnet | opus |
+| **Designer** | UI/UX 설계 | haiku | sonnet | sonnet |
+| **Librarian** | 문서 기록 | haiku | haiku | sonnet |
+
+## 복잡도 판정 기준
+
+- **복잡**: 아키텍처 결정, 다중 모듈 연동, 상태 머신, 보안 로직, 트랜잭션
+- **일반**: 단일 모듈 기능 구현, API 엔드포인트, 컴포넌트 개발
+- **단순**: CRUD, 설정 파일 수정, 타입 정의, 보일러플레이트, 문서 갱신
+
+## 적용 절차
+
+1. `config.yaml` → `model_routing` 섹션 읽기
+2. `enabled: false`이면 에이전트 기본 모델 사용 → 종료
+3. 태스크 설명 + phase에서 복잡도 판정 (복잡/일반/단순)
+4. 라우팅 테이블에서 `strategy` 열의 모델 선택
+5. 선택된 모델을 Task()의 `model` 파라미터로 전달
+6. Completion Report 첫 줄에 `[MODEL: {selected}]` 표기

package/templates/base/skills/tsq-controller/references/wave-dispatch.md

@@ -0,0 +1,50 @@
+---
+title: Wave Dispatch
+category: reference
+---
+
+# Wave Dispatch — 병렬 서브에이전트 실행
+
+## 개요
+
+`tsq next --wave` 실행 시 의존성이 충족된 독립 태스크를 Wave로 반환.
+Controller는 Wave 내 태스크를 동시에 Task() 호출하여 속도를 3-5x 향상.
+
+## 프로토콜
+
+1. `tsq next --wave` 실행 → `{ wave: [...tasks], waveSize, parallel }` JSON
+2. `waveSize === 1` → 단일 태스크, 기존 순차 Protocol 12-16 따름
+3. `waveSize > 1` → 병렬 디스패치:
+   a. 각 태스크에 대해 개별 Capability Token 발급 (`.timsquad/state/cap-{taskId}`)
+   b. 각 태스크의 Model Routing 독립 수행
+   c. 모든 Task()를 동시 호출 (Agent tool 병렬 호출)
+   d. 모든 완료 후 각 Completion Report 검증
+   e. 개별 Capability Token 회수
+4. Wave 완료 → 다시 Step 1로 (다음 Wave 조회)
+
+## 의존성 분석 규칙
+
+- `dependencies` 없는 태스크: 즉시 실행 가능
+- `dependencies` 있는 태스크: 모든 선행 태스크 완료 후 실행 가능
+- 같은 Sequence 내 태스크도 의존성 없으면 병렬 가능
+- 순환 의존성 감지 시: fallback으로 첫 번째 태스크만 반환
+
+## Capability Token (병렬)
+
+```
+# 순차 (기존)
+.timsquad/state/controller-active
+.timsquad/state/allowed-paths.txt
+
+# 병렬 (Wave)
+.timsquad/state/cap-P1-S001-T001
+.timsquad/state/cap-P1-S001-T002
+```
+
+병렬 실행 시 각 태스크에 독립 토큰을 발급하여 격리. 완료 시 개별 회수.
+
+## 제약
+
+- 같은 Phase 내 태스크만 Wave로 묶음 (Phase 간 병렬 불가)
+- Wave 내 태스크가 같은 파일을 수정하면 충돌 가능 — outputs 필드로 사전 감지
+- Wave 크기 상한: 5 (Claude Code 동시 에이전트 제한)

package/templates/base/skills/tsq-full/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: tsq-full
+description: |
+  Controller 경유 풀 파이프라인 실행. Phase-Sequence-Task DAG를 순차적으로 진행하며
+  각 단계마다 게이트 검증(unit→integration→e2e), Librarian 기록, Phase Memory carry-over를 수행한다.
+  세션이 끊겨도 workflow.json에서 마지막 위치를 복원하여 이어서 진행한다.
+  Use when: "/tsq-full", "전체 구현", "풀 파이프라인", "본격적으로 시작",
+  "새 기능 개발", "인증 시스템 구현", "결제 모듈 만들어", "대규모 리팩토링",
+  "Phase 진행", "Phase 2부터", "파이프라인 재개", "이어서 진행",
+  또는 planning.md 기반으로 여러 태스크를 연속 실행해야 할 때.
+  다단계 기능, 여러 파일/모듈에 걸친 구현, 아키텍처 변경이면 이 스킬을 사용한다.
+version: "1.0.0"
+tags: [tsq, full, controller, pipeline]
+user-invocable: true
+---
+
+# /tsq-full — Controller 경유 풀 파이프라인
+
+Phase-Sequence-Task 전체 워크플로우를 Controller 경유로 실행한다.
+planning.md 기반으로 체계적 구현, 게이트 검증, Librarian 기록까지 수행하는 이유:
+다단계 작업에서 각 Phase의 산출물이 다음 Phase의 입력이 되므로, 게이트로 품질을 보장하지 않으면
+후속 작업에서 누적 결함이 발생하기 때문이다.
+
+## Pre-conditions
+
+1. **planning.md 필수**: `.timsquad/ssot/planning.md` 존재 확인
+   - 없으면 → "`/tsq-decompose`로 실행 계획을 먼저 생성하세요" 안내
+2. **SSOT 충족**: PRD + requirements 최소 작성 완료
+   - 미충족 → "`/tsq-start`로 온보딩을 먼저 진행하세요" 안내
+
+## Protocol
+
+1. **다음 태스크 조회**: `tsq next` CLI 실행 → 다음 미완료 태스크 JSON 확인
+   - `all_complete` → 모든 태스크 완료. 사용자에게 안내
+   - `error: planning.md not found` → `/tsq-decompose` 안내
+2. **Controller 풀 실행** (tsq-controller Protocol 전체 수행):
+   - `tsq next`가 반환한 태스크부터 순차 진행
+   - Sequence 내 Task 위임 (Developer → QA)
+   - 게이트 검증: unit → integration → e2e
+   - Librarian 호출 (Phase 완료 시)
+   - Phase Memory carry-over
+3. **Phase 완료 안내**: "`/tsq-retro` 회고 → `/clear` 컨텍스트 초기화"
+
+> workflow.json 갱신은 SubagentStop hook이 `tsq next --complete`를 자동 호출하여 처리.
+> Phase 완료 감지는 completion-guard hook이 `tsq next --phase-status`를 호출하여 처리.
+
+## Resumption
+
+세션이 끊긴 후 `/tsq-full`을 다시 실행하면:
+- `tsq next`가 workflow.json 기반으로 다음 미완료 Task를 자동 결정
+- 이미 완료된 Task는 자동 스킵
+- 컨텍스트 압축 후에도 phase-memory.md의 Progress 섹션에서 진행 상황 복원
+
+## vs /tsq-quick
+
+| 항목 | /tsq-full | /tsq-quick |
+|------|-----------|-----------|
+| Phase-Sequence-Task | O (전체) | X (단일) |
+| Controller 경유 | O | O |
+| SSOT/메모리 참조 | O | O |
+| 게이트 | unit → integration → e2e | unit만 |
+| Librarian 호출 | O | X |
+| planning.md 필요 | O | X |
+
+## Usage
+
+```
+/tsq-full
+/tsq-full Phase 2부터 재개
+```