timsquad 3.3.0 → 3.5.0

package/templates/platforms/claude-code/scripts/completion-guard.sh

@@ -0,0 +1,93 @@
+#!/bin/bash
+# Completion Guard — Stop Hook
+# 1. Implementation phase에서 테스트 미실행 시 블로킹 (decision: block)
+# 2. 세션 노트 컨텍스트를 systemMessage로 주입 (컨텍스트 생존 메모)
+# 3. 컨텍스트 윈도우 85% 경고
+#
+# Input: JSON via stdin (Claude Code hook protocol)
+# Output: JSON with decision (block) or systemMessage
+
+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
+  echo '{}'
+  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 not in a TimSquad project, allow
+if [ ! -d "$PROJECT_ROOT/.timsquad" ]; then
+  echo '{}'
+  exit 0
+fi
+
+BLOCK_REASON=""
+
+# ── 1. Test execution gate (implementation phase only) ──
+# 자기 보고 금지: 테스트 exit code로 완료를 판정한다.
+# stop_hook_active=false일 때만 블로킹 (1회 기회 부여, 루프 방지는 섹션 0에서 처리)
+PHASE_FILE="$PROJECT_ROOT/.timsquad/state/current-phase.json"
+if [ -f "$PHASE_FILE" ]; then
+  PHASE=$(jq -r '.current // .current_phase // .phase // "unknown"' "$PHASE_FILE" 2>/dev/null || echo "unknown")
+  if [ "$PHASE" = "implementation" ]; then
+    SESSION_STATE="$PROJECT_ROOT/.timsquad/.daemon/session-state.json"
+    if [ -f "$SESSION_STATE" ]; then
+      BASH_COMMANDS=$(jq -r '.metrics.bashCommands // 0' "$SESSION_STATE" 2>/dev/null || echo "0")
+      if [ "$BASH_COMMANDS" -eq 0 ] 2>/dev/null; then
+        BLOCK_REASON="[Completion Guard] 이번 세션에서 테스트가 실행되지 않았습니다. 프로젝트의 테스트를 실행하여 변경사항을 검증한 후 완료하세요."
+      fi
+    fi
+  fi
+fi
+
+# ── 2. Session notes context injection ──
+SESSION_CTX=""
+NOTES_FILE="$PROJECT_ROOT/.timsquad/.daemon/session-notes.jsonl"
+if [ -f "$NOTES_FILE" ]; then
+  LAST_LINE=$(tail -1 "$NOTES_FILE" 2>/dev/null || echo "")
+  if [ -n "$LAST_LINE" ]; then
+    TURN=$(echo "$LAST_LINE" | jq -r '.turn // 0' 2>/dev/null)
+    TOOLS=$(echo "$LAST_LINE" | jq -r '.metrics.tools // 0' 2>/dev/null)
+    FAILS=$(echo "$LAST_LINE" | jq -r '.metrics.fails // 0' 2>/dev/null)
+    AGENTS=$(echo "$LAST_LINE" | jq -r '(.activeAgents // []) | join(", ")' 2>/dev/null)
+    FILES=$(echo "$LAST_LINE" | jq -r '(.recentFiles // [])[:5] | map(split("/") | last) | join(", ")' 2>/dev/null)
+
+    CTX_PCT=$(echo "$LAST_LINE" | jq -r '.contextPct // 0' 2>/dev/null)
+
+    SESSION_CTX="[Session] Turn $TURN | Tools: $TOOLS"
+    [ "$FAILS" != "0" ] && [ "$FAILS" != "null" ] && SESSION_CTX="$SESSION_CTX (Fail: $FAILS)"
+    [ -n "$AGENTS" ] && [ "$AGENTS" != "null" ] && SESSION_CTX="$SESSION_CTX | Active: $AGENTS"
+    [ -n "$FILES" ] && [ "$FILES" != "null" ] && SESSION_CTX="$SESSION_CTX | Files: $FILES"
+
+    # ── 3. Context window monitor (85% threshold) ──
+    if [ "$CTX_PCT" -ge 85 ] 2>/dev/null; then
+      SESSION_CTX="$SESSION_CTX\\n⚠ [Context ${CTX_PCT}%] 컨텍스트 윈도우 85% 이상 사용. 중요 정보를 session-notes에 기록하고, 현재 태스크를 정리한 뒤 완료하세요."
+    elif [ "$CTX_PCT" -ge 70 ] 2>/dev/null; then
+      SESSION_CTX="$SESSION_CTX | Ctx: ${CTX_PCT}%"
+    fi
+  fi
+fi
+
+# ── 4. Combine and output ──
+# BLOCK_REASON이 있으면 decision:block으로 강제 속행 (세션 컨텍스트 포함)
+if [ -n "$BLOCK_REASON" ]; then
+  FULL_REASON="$BLOCK_REASON"
+  [ -n "$SESSION_CTX" ] && FULL_REASON="$BLOCK_REASON
+$SESSION_CTX"
+  jq -n --arg reason "$FULL_REASON" '{"decision": "block", "reason": $reason}'
+elif [ -n "$SESSION_CTX" ]; then
+  jq -n --arg msg "$SESSION_CTX" '{"systemMessage": $msg}'
+else
+  echo '{}'
+fi

package/templates/platforms/claude-code/scripts/phase-guard.sh

@@ -0,0 +1,79 @@
+#!/bin/bash
+# Phase Guard — PreToolUse Hook
+# Enforces phase restrictions on file operations.
+# planning/design phase: blocks src/** writes
+# implementation phase: blocks .timsquad/ssot/** writes
+#
+# Input: JSON via stdin (Claude Code hook protocol)
+# Output: JSON with permissionDecision (allow/deny)
+
+set -e
+
+# Read hook input from stdin (non-blocking)
+INPUT=""
+if read -t 1 -r line; then
+  INPUT="$line"
+fi
+
+# If no input, allow (fail-open for safety)
+if [ -z "$INPUT" ]; then
+  echo '{"hookSpecificOutput":{"permissionDecision":"allow"}}'
+  exit 0
+fi
+
+# Extract file path from tool input
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // .tool_input.filePath // ""' 2>/dev/null || echo "")
+
+# If no file path, allow (not a file operation)
+if [ -z "$FILE_PATH" ] || [ "$FILE_PATH" = "null" ]; then
+  echo '{"hookSpecificOutput":{"permissionDecision":"allow"}}'
+  exit 0
+fi
+
+# Find project root (look for .timsquad directory)
+PROJECT_ROOT="$(pwd)"
+while [ "$PROJECT_ROOT" != "/" ]; do
+  if [ -d "$PROJECT_ROOT/.timsquad" ]; then
+    break
+  fi
+  PROJECT_ROOT="$(dirname "$PROJECT_ROOT")"
+done
+
+# If not in a TimSquad project, allow
+if [ ! -d "$PROJECT_ROOT/.timsquad" ]; then
+  echo '{"hookSpecificOutput":{"permissionDecision":"allow"}}'
+  exit 0
+fi
+
+# Read current phase
+PHASE_FILE="$PROJECT_ROOT/.timsquad/state/current-phase.json"
+if [ ! -f "$PHASE_FILE" ]; then
+  echo '{"hookSpecificOutput":{"permissionDecision":"allow"}}'
+  exit 0
+fi
+
+PHASE=$(jq -r '.current // .current_phase // .phase // "unknown"' "$PHASE_FILE" 2>/dev/null)
+
+# Normalize file path (make relative to project root)
+REL_PATH="${FILE_PATH#$PROJECT_ROOT/}"
+
+# Phase enforcement rules
+case "$PHASE" in
+  planning|design)
+    # Block source code modifications during planning/design
+    if echo "$REL_PATH" | grep -qE '^src/|^lib/|^app/|^pages/|^components/'; then
+      jq -n --arg phase "$PHASE" '{hookSpecificOutput:{permissionDecision:"deny"},systemMessage:("[Phase Guard] " + $phase + " phase에서 코드 수정이 금지됩니다. SSOT 문서 작성을 먼저 완료하세요.")}'
+      exit 0
+    fi
+    ;;
+  implementation)
+    # Block SSOT modifications during implementation (prevent drift)
+    if echo "$REL_PATH" | grep -qE '^\.timsquad/ssot/'; then
+      echo '{"hookSpecificOutput":{"permissionDecision":"deny"},"systemMessage":"[Phase Guard] implementation phase에서 SSOT 직접 수정이 금지됩니다. 변경이 필요하면 PM에게 L2 피드백을 보고하세요."}'
+      exit 0
+    fi
+    ;;
+esac
+
+# Default: allow
+echo '{"hookSpecificOutput":{"permissionDecision":"allow"}}'

package/templates/platforms/claude-code/scripts/safe-guard.sh

@@ -0,0 +1,83 @@
+#!/bin/bash
+# Safe Guard — PreToolUse Hook (Bash)
+# Blocks or escalates destructive shell commands.
+#
+# Input: JSON via stdin (Claude Code hook protocol)
+# Output: JSON with permissionDecision (allow/deny/ask)
+
+set -e
+
+# Read hook input from stdin (non-blocking)
+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 command from tool input
+COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // ""' 2>/dev/null || echo "")
+
+if [ -z "$COMMAND" ] || [ "$COMMAND" = "null" ]; then
+  echo '{"hookSpecificOutput":{"permissionDecision":"allow"}}'
+  exit 0
+fi
+
+# ── DENY: Hard block (exit 0 + permissionDecision deny) ──
+
+# Root deletion
+if echo "$COMMAND" | grep -qE 'rm\s+(-[a-zA-Z]*f[a-zA-Z]*\s+|.*--force\s+)/*$|rm\s+-rf\s+/\s'; then
+  echo '{"hookSpecificOutput":{"permissionDecision":"deny"},"systemMessage":"[Safe Guard] 루트 디렉토리 삭제 명령이 차단되었습니다."}'
+  exit 0
+fi
+
+# git push --force to main/master
+if echo "$COMMAND" | grep -qiE 'git\s+push\s+.*--force.*\s+(main|master)|git\s+push\s+-f\s+.*\s+(main|master)'; then
+  echo '{"hookSpecificOutput":{"permissionDecision":"deny"},"systemMessage":"[Safe Guard] main/master 브랜치에 force push가 차단되었습니다. 일반 push를 사용하세요."}'
+  exit 0
+fi
+
+# git reset --hard
+if echo "$COMMAND" | grep -qE 'git\s+reset\s+--hard'; then
+  echo '{"hookSpecificOutput":{"permissionDecision":"deny"},"systemMessage":"[Safe Guard] git reset --hard가 차단되었습니다. 커밋되지 않은 변경사항이 유실될 수 있습니다."}'
+  exit 0
+fi
+
+# SQL destructive operations
+if echo "$COMMAND" | grep -qiE 'DROP\s+(TABLE|DATABASE|SCHEMA)|TRUNCATE\s+TABLE'; then
+  echo '{"hookSpecificOutput":{"permissionDecision":"deny"},"systemMessage":"[Safe Guard] 파괴적 SQL 명령이 차단되었습니다. 데이터 유실 위험이 있습니다."}'
+  exit 0
+fi
+
+# chmod 777
+if echo "$COMMAND" | grep -qE 'chmod\s+777'; then
+  echo '{"hookSpecificOutput":{"permissionDecision":"deny"},"systemMessage":"[Safe Guard] chmod 777이 차단되었습니다. 최소 권한 원칙을 따르세요."}'
+  exit 0
+fi
+
+# ── ASK: Escalate to user confirmation ──
+
+# npm publish
+if echo "$COMMAND" | grep -qE 'npm\s+publish'; then
+  echo '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"ask","permissionDecisionReason":"npm publish는 패키지를 공개 배포합니다. 계속하시겠습니까?"}}'
+  exit 0
+fi
+
+# git push to main/master (non-force)
+if echo "$COMMAND" | grep -qiE 'git\s+push\s+.*\s+(main|master)|git\s+push\s+(main|master)'; then
+  echo '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"ask","permissionDecisionReason":"main/master 브랜치에 push합니다. 계속하시겠습니까?"}}'
+  exit 0
+fi
+
+# rm -rf (non-root, general)
+if echo "$COMMAND" | grep -qE 'rm\s+(-[a-zA-Z]*r[a-zA-Z]*f|.*-rf)\s'; then
+  echo '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"ask","permissionDecisionReason":"재귀적 삭제 명령입니다. 대상을 확인해주세요."}}'
+  exit 0
+fi
+
+# ── Default: allow ──
+echo '{"hookSpecificOutput":{"permissionDecision":"allow"}}'

package/templates/platforms/claude-code/scripts/skill-rules.json

@@ -0,0 +1,85 @@
+{
+  "threshold": 4,
+  "rules": [
+    {
+      "skill": "mobile/flutter",
+      "keywords": ["flutter", "widget", "riverpod", "stateless", "stateful", "플러터"],
+      "patterns": ["(build|create|implement|add).*?(app|screen|page|widget)"]
+    },
+    {
+      "skill": "mobile/dart",
+      "keywords": ["dart", "freezed", "isolate"],
+      "patterns": []
+    },
+    {
+      "skill": "frontend/react",
+      "keywords": ["react", "component", "hook", "useState", "useEffect", "리액트", "컴포넌트"],
+      "patterns": ["(create|build|refactor).*?(component|page|layout)"]
+    },
+    {
+      "skill": "frontend/nextjs",
+      "keywords": ["nextjs", "next.js", "app router", "server component", "middleware"],
+      "patterns": ["(ssr|server.*render|static.*generat)"]
+    },
+    {
+      "skill": "backend/node",
+      "keywords": ["express", "fastify", "middleware", "api endpoint", "route"],
+      "patterns": ["(create|add|implement).*?(api|endpoint|route|server)"]
+    },
+    {
+      "skill": "database",
+      "keywords": ["database", "sql", "migration", "schema", "table", "index", "데이터베이스", "스키마"],
+      "patterns": ["(create|modify|add|alter).*?(table|column|index|migration)"]
+    },
+    {
+      "skill": "database/prisma",
+      "keywords": ["prisma", "prisma schema", "prisma migrate"],
+      "patterns": []
+    },
+    {
+      "skill": "methodology/debugging",
+      "keywords": ["debug", "bug", "error", "crash", "fix", "디버그", "버그", "에러"],
+      "patterns": ["(why|how).*?(fail|break|crash|error|not work)"]
+    },
+    {
+      "skill": "methodology/tdd",
+      "keywords": ["tdd", "test-driven", "vitest", "jest", "테스트 주도"],
+      "patterns": ["(write|add|create).*?test"]
+    },
+    {
+      "skill": "methodology/ddd",
+      "keywords": ["ddd", "domain-driven", "aggregate", "bounded context", "도메인 주도"],
+      "patterns": []
+    },
+    {
+      "skill": "security",
+      "keywords": ["security", "owasp", "vulnerability", "xss", "csrf", "injection", "보안", "취약점"],
+      "patterns": ["(security|auth|permission).*?(review|audit|check)"]
+    },
+    {
+      "skill": "testing",
+      "keywords": ["test", "coverage", "assertion", "mock", "stub", "테스트"],
+      "patterns": ["(increase|improve).*?coverage"]
+    },
+    {
+      "skill": "architecture",
+      "keywords": ["architecture", "system design", "api design", "adr", "아키텍처", "설계"],
+      "patterns": ["(design|architect|structure).*?(system|api|service)"]
+    },
+    {
+      "skill": "typescript",
+      "keywords": ["typescript", "type", "interface", "generic", "타입"],
+      "patterns": ["(type|typing).*?(error|issue|strict)"]
+    },
+    {
+      "skill": "ui-design",
+      "keywords": ["ui", "ux", "design system", "responsive", "accessibility", "a11y"],
+      "patterns": ["(design|redesign|improve).*?(ui|layout|interface)"]
+    },
+    {
+      "skill": "planning",
+      "keywords": ["prd", "requirements", "specification", "기획", "요구사항"],
+      "patterns": ["(write|create|draft).*?(prd|spec|requirement)"]
+    }
+  ]
+}

package/templates/platforms/claude-code/scripts/skill-suggest.sh

@@ -0,0 +1,105 @@
+#!/bin/bash
+# Skill Suggest — UserPromptSubmit Hook
+# 사용자 프롬프트를 분석하여 관련 스킬을 제안한다.
+# 키워드/패턴 매칭 기반, advisory only (블로킹 안 함).
+#
+# Input: JSON via stdin (Claude Code hook protocol, .prompt 필드 포함)
+# Output: JSON with additionalContext (스킬 제안)
+
+set -e
+
+# Read hook input
+INPUT=$(cat 2>/dev/null || echo "")
+if [ -z "$INPUT" ]; then
+  exit 0
+fi
+
+PROMPT=$(echo "$INPUT" | jq -r '.prompt // ""' 2>/dev/null || echo "")
+if [ -z "$PROMPT" ] || [ "$PROMPT" = "null" ]; 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
+
+# Load skill rules
+RULES_FILE="$PROJECT_ROOT/.claude/scripts/skill-rules.json"
+if [ ! -f "$RULES_FILE" ]; then
+  exit 0
+fi
+
+THRESHOLD=$(jq -r '.threshold // 4' "$RULES_FILE" 2>/dev/null || echo "4")
+PROMPT_LOWER=$(echo "$PROMPT" | tr '[:upper:]' '[:lower:]')
+
+# Match skills
+MATCHES=""
+RULE_COUNT=$(jq '.rules | length' "$RULES_FILE" 2>/dev/null || echo "0")
+
+i=0
+while [ "$i" -lt "$RULE_COUNT" ]; do
+  SKILL=$(jq -r ".rules[$i].skill" "$RULES_FILE" 2>/dev/null)
+  SCORE=0
+
+  # Check if skill is deployed
+  SKILL_DIR="$PROJECT_ROOT/.claude/skills/$SKILL"
+  if [ ! -d "$SKILL_DIR" ]; then
+    i=$((i + 1))
+    continue
+  fi
+
+  # Keyword matching (2 points each)
+  KW_COUNT=$(jq ".rules[$i].keywords | length" "$RULES_FILE" 2>/dev/null)
+  j=0
+  while [ "$j" -lt "$KW_COUNT" ]; do
+    KW=$(jq -r ".rules[$i].keywords[$j]" "$RULES_FILE" 2>/dev/null)
+    if echo "$PROMPT_LOWER" | grep -qi -- "$KW" 2>/dev/null; then
+      SCORE=$((SCORE + 2))
+    fi
+    j=$((j + 1))
+  done
+
+  # Pattern matching (4 points each)
+  PAT_COUNT=$(jq ".rules[$i].patterns | length" "$RULES_FILE" 2>/dev/null)
+  k=0
+  while [ "$k" -lt "$PAT_COUNT" ]; do
+    PAT=$(jq -r ".rules[$i].patterns[$k]" "$RULES_FILE" 2>/dev/null)
+    if [ -n "$PAT" ] && echo "$PROMPT_LOWER" | grep -qiE -- "$PAT" 2>/dev/null; then
+      SCORE=$((SCORE + 4))
+    fi
+    k=$((k + 1))
+  done
+
+  # Threshold check
+  if [ "$SCORE" -ge "$THRESHOLD" ]; then
+    if [ -n "$MATCHES" ]; then
+      MATCHES="$MATCHES, $SKILL"
+    else
+      MATCHES="$SKILL"
+    fi
+  fi
+
+  i=$((i + 1))
+done
+
+# Output suggestion if matches found
+if [ -n "$MATCHES" ]; then
+  SUGGESTION="[Skill Suggest] 관련 스킬이 감지되었습니다: $MATCHES. 해당 스킬의 rules/를 참조하면 더 높은 품질의 결과를 얻을 수 있습니다."
+  jq -n --arg ctx "$SUGGESTION" '{
+    hookSpecificOutput: {
+      hookEventName: "UserPromptSubmit",
+      additionalContext: $ctx
+    }
+  }'
+fi
+
+exit 0

package/templates/platforms/claude-code/settings.json

@@ -1,23 +1,131 @@
 {
   "hooks": {
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash .claude/scripts/skill-suggest.sh",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash .claude/scripts/phase-guard.sh",
+            "timeout": 3
+          }
+        ]
+      },
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash .claude/scripts/safe-guard.sh",
+            "timeout": 3
+          }
+        ]
+      },
+      {
+        "matcher": "Task",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "tsq daemon notify subagent-start 2>/dev/null || true",
+            "timeout": 3
+          }
+        ]
+      }
+    ],
+    "SubagentStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "tsq daemon notify subagent-start 2>/dev/null || true",
+            "timeout": 3
+          }
+        ]
+      }
+    ],
+    "SubagentStop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "tsq daemon notify subagent-stop 2>/dev/null || true",
+            "timeout": 3
+          }
+        ]
+      }
+    ],
     "SessionStart": [
       {
         "hooks": [
           {
             "type": "command",
-            "command": "tsq daemon start --jsonl \"$CLAUDE_TRANSCRIPT_PATH\" 2>/dev/null || true",
+            "command": "tsq daemon start 2>/dev/null || true",
             "timeout": 5
           }
         ]
       }
     ],
+    "PostToolUse": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "tsq daemon notify tool-use --status success 2>/dev/null || true",
+            "timeout": 3
+          }
+        ]
+      }
+    ],
+    "PostToolUseFailure": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "tsq daemon notify tool-use --status failure 2>/dev/null || true",
+            "timeout": 3
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "tsq daemon notify stop 2>/dev/null || true",
+            "timeout": 3
+          },
+          {
+            "type": "command",
+            "command": "bash .claude/scripts/completion-guard.sh",
+            "timeout": 5
+          },
+          {
+            "type": "command",
+            "command": "bash .claude/scripts/build-gate.sh",
+            "timeout": 30
+          }
+        ]
+      }
+    ],
     "SessionEnd": [
       {
         "hooks": [
           {
             "type": "command",
-            "command": "tsq daemon stop 2>/dev/null || true",
-            "timeout": 10
+            "command": "tsq daemon notify session-end 2>/dev/null || true",
+            "timeout": 5
           }
         ]
       }