timsquad 3.4.0 → 3.6.0

package/templates/base/skills/security/rules/dependency-security.md

@@ -0,0 +1,69 @@
+---
+title: Dependency Security
+impact: HIGH
+tags: security, dependencies, npm-audit, supply-chain, license
+---
+
+# Dependency Security
+
+## npm audit
+```bash
+# Check for known vulnerabilities
+npm audit
+
+# Fix automatically where possible
+npm audit fix
+
+# Fail CI on critical/high vulnerabilities
+npm audit --audit-level=high
+```
+
+- Run `npm audit` in CI pipelines; block merges on high/critical findings
+- Review advisories before applying `npm audit fix --force` (may include breaking changes)
+- Use tools like `socket.dev` or `snyk` for deeper analysis
+
+## Lockfile Integrity
+- Always commit `package-lock.json` to version control
+- Use `npm ci` in CI/CD (respects lockfile exactly, fails on mismatch)
+- Review lockfile diffs in PRs for unexpected changes
+```bash
+# CI install — strict, reproducible
+npm ci
+
+# Never use `npm install` in CI — it can modify the lockfile
+```
+
+## Supply Chain Attack Prevention
+- Pin exact versions for critical dependencies
+- Verify package provenance when available (`npm audit signatures`)
+- Be cautious with post-install scripts; audit new dependencies before adding
+```bash
+# Check what scripts a package runs
+npm explain <package>
+npm pack <package> --dry-run  # inspect contents before install
+
+# Disable scripts for untrusted packages
+npm install --ignore-scripts <package>
+```
+
+- Prefer well-maintained packages with large user bases
+- Monitor for typosquatting (e.g., `lodash` vs `l0dash`)
+- Use `npm-shrinkwrap.json` for published packages requiring locked deps
+
+## License Compliance
+```bash
+# Check licenses of all dependencies
+npx license-checker --summary
+npx license-checker --failOn 'GPL-3.0;AGPL-3.0'
+```
+
+- Define an allowlist of acceptable licenses for the project
+- Block copyleft licenses (GPL, AGPL) in proprietary codebases
+- Document license policy and automate checks in CI
+
+## Checklist
+- `npm audit` runs in CI; high/critical findings block deployment
+- `package-lock.json` committed; CI uses `npm ci`
+- New dependencies reviewed for maintenance status, size, and scripts
+- License compliance checked automatically; policy documented
+- Lockfile diffs reviewed in pull requests

package/templates/base/skills/security/rules/input-validation.md

@@ -0,0 +1,68 @@
+---
+title: Input Validation
+impact: CRITICAL
+tags: security, validation, sanitization, injection
+---
+
+# Input Validation
+
+## Principle
+Never trust user input. Validate, sanitize, and constrain all external data before processing.
+
+## Allowlist Over Denylist
+```typescript
+// Bad: denylist — easy to bypass
+const forbidden = ['<script>', 'onclick', 'onerror'];
+if (forbidden.some(f => input.includes(f))) throw new Error('Invalid');
+
+// Good: allowlist — only permit known-safe values
+const ALLOWED_ROLES = ['admin', 'editor', 'viewer'] as const;
+if (!ALLOWED_ROLES.includes(role)) throw new Error('Invalid role');
+```
+
+## Schema Validation
+```typescript
+import { z } from 'zod';
+
+const UserInput = z.object({
+  name: z.string().min(1).max(100).trim(),
+  email: z.string().email().max(254),
+  age: z.number().int().min(0).max(150),
+});
+
+// Validate at boundary (controller/handler)
+const data = UserInput.parse(req.body);
+```
+
+## Parameterized Queries
+```typescript
+// Bad: string interpolation — SQL injection risk
+const q = `SELECT * FROM users WHERE id = '${id}'`;
+
+// Good: parameterized query
+const q = 'SELECT * FROM users WHERE id = $1';
+await db.query(q, [id]);
+
+// Good: ORM with type-safe parameters
+await userRepo.findOneBy({ id: parseInt(id, 10) });
+```
+
+## Sanitize HTML Output
+```typescript
+// Bad
+element.innerHTML = userInput;
+
+// Good: escape or use textContent
+element.textContent = userInput;
+
+// Good: DOMPurify for rich content
+import DOMPurify from 'dompurify';
+element.innerHTML = DOMPurify.sanitize(userInput);
+```
+
+## Checklist
+- Validate type, length, format, and range at the application boundary
+- Use allowlists for enumerated values (roles, statuses, types)
+- Use parameterized queries or ORM — never interpolate user input into SQL
+- Sanitize output based on context (HTML, URL, SQL, shell)
+- Reject unexpected fields; do not pass raw request bodies to business logic

package/templates/base/skills/security/rules/secrets-management.md

@@ -0,0 +1,65 @@
+---
+title: Secrets Management
+impact: HIGH
+tags: security, secrets, env, gitignore, rotation
+---
+
+# Secrets Management
+
+## Never Hardcode Secrets
+```typescript
+// Bad: hardcoded secret
+const API_KEY = 'sk-1234567890abcdef';
+const DB_URL = 'postgres://admin:password@db:5432/prod';
+
+// Good: environment variables
+const API_KEY = process.env.API_KEY;
+const DB_URL = process.env.DATABASE_URL;
+
+// Better: secret manager for production
+const API_KEY = await secretManager.getSecret('api-key');
+```
+
+## Environment Variables
+- Use `.env` files for local development only
+- Load with `dotenv` at application entry point, not in library code
+- Validate required env vars at startup
+```typescript
+const required = ['DATABASE_URL', 'JWT_SECRET', 'API_KEY'];
+for (const key of required) {
+  if (!process.env[key]) throw new Error(`Missing env var: ${key}`);
+}
+```
+
+## .gitignore Rules
+```gitignore
+# Must be in .gitignore — never commit secrets
+.env
+.env.local
+.env.*.local
+*.pem
+*.key
+```
+
+- Use `.env.example` with placeholder values for documentation
+- Run `git log --all -p -- .env` to verify secrets were never committed
+- If a secret was committed, rotate it immediately — git history persists
+
+## Secret Rotation
+- Rotate secrets on a regular schedule (90 days recommended)
+- Support dual-read during rotation (accept old + new key simultaneously)
+- Automate rotation via secret manager (AWS Secrets Manager, Vault, etc.)
+- Revoke old secrets after confirming the new ones work
+
+## Production Practices
+- Use a dedicated secret manager (AWS Secrets Manager, HashiCorp Vault, GCP Secret Manager)
+- Grant least-privilege access to secrets per service
+- Audit secret access logs regularly
+- Never log secret values; mask them in error output
+
+## Checklist
+- No secrets in source code, config files, or container images
+- `.env` and key files listed in `.gitignore`
+- Required env vars validated at startup with clear error messages
+- Secrets rotated on schedule; old secrets revoked
+- Production uses a secret manager, not plain env vars

package/templates/base/skills/spec/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: spec
+description: |
+  SSOT(Single Source of Truth) 문서 존재 여부를 확인하고, 미존재 시 구현 전 스펙 작성을 안내한다.
+  `/spec <기능명>`으로 호출하면 해당 기능의 SSOT 문서를 찾아 상태를 보고한다.
+  스펙 없이 구현하는 것을 방지하여 문서-코드 일관성을 유지한다.
+version: "1.0.0"
+tags: [spec, ssot, gate, documentation]
+depends_on: [tsq-protocol]
+conflicts_with: []
+user-invocable: true
+argument-hint: "[기능명] — SSOT 문서 존재 여부 확인"
+---
+
+# Spec Gate
+
+SSOT 문서 존재 여부를 확인하여 스펙 없는 구현을 방지한다.
+
+## Contract
+
+- **Trigger**: `/spec` 호출 또는 구현 시작 전 자동 확인
+- **Input**: `$ARGUMENTS` (기능명) 또는 미지정 시 전체 SSOT 상태
+- **Output**: SSOT 상태 리포트 (존재/stale/미존재) + 권장 액션
+- **Error**: SSOT 디렉토리 자체가 없을 경우 "NOT FOUND" 안내
+- **Dependencies**: tsq-protocol
+
+## Protocol
+
+1. **SSOT 검색**: `$ARGUMENTS`로 전달된 기능명으로 `.timsquad/ssot/` 디렉토리 탐색
+2. **존재 확인**: 해당 기능의 스펙 문서(PRD, 설계문서, API 스펙) 존재 여부 판단
+3. **상태 판정**:
+   - **존재 + 최신**: 스펙 요약 출력 + "구현 가능" 안내
+   - **존재 + stale**: "스펙 갱신 필요" + `tsq compile` 재실행 안내
+   - **미존재**: advisory 경고 + 스펙 작성 가이드 제공
+4. **결과 리포트**: 상태 + 권장 액션을 구조화하여 출력
+
+## Verification
+
+| Check | Method | Pass Criteria |
+|-------|--------|---------------|
+| SSOT 파일 존재 | `.timsquad/ssot/` 탐색 | 관련 문서 1개 이상 |
+| stale 여부 | compile-manifest hash 비교 | hash 일치 |
+| 스펙 커버리지 | 기능 키워드 매칭 | 해당 기능 언급 존재 |
+
+## Quick Rules
+
+### Gate 동작
+- **미존재 시**: advisory 경고 (차단 아님)
+  ```
+  [SPEC GATE] 기능 "{name}"에 대한 SSOT 문서가 없습니다.
+  스펙 먼저 작성하세요: .timsquad/ssot/{name}.md
+  가이드: PRD → 설계문서 → Compiled Spec 순서
+  ```
+- **stale 시**: `tsq compile` 재실행 안내
+  ```
+  [SPEC GATE] SSOT 문서가 최신이 아닙니다. `tsq compile` 재실행 필요.
+  ```
+- **Phase gate에서만 실제 차단** (일반 사용 시 advisory)
+- `$ARGUMENTS` 미지정 시 전체 SSOT 상태 요약
+- PRD, 설계문서, API 스펙 모두 SSOT로 인정

package/templates/base/skills/stability-verification/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: stability-verification
+description: |
+  프로젝트 안정성 검증 스킬. 릴리스/스프린트 완료 전 6-Layer 자동+수동 검증 수행.
+  L0(정적분석) → L1(유닛테스트) → L2(보안스캔) → L3(쉘스크립트) → L4(통합) → L5(패키지).
+  각 레이어는 fail-closed(기본) 또는 fail-open 정책 적용.
+  사용 시점: 릴리스 전, 스프린트 완료 시, 보안 감사 요청 시.
+version: "1.0.0"
+tags: [verification, security, quality, release]
+user-invocable: false
+---
+
+# Stability Verification
+
+프로젝트 안정성을 6-Layer 피라미드로 검증한다. 빠르고 저렴한 검사부터 실행하여 초기 실패를 빠르게 잡는다.
+
+## Philosophy
+
+- **빠른 것부터**: L0(5초) → L5(30초) 순서로 실행, 첫 실패 시 멈춤
+- **Fail-closed 기본**: 모든 레이어는 기본 차단, 명시적 opt-out만 허용
+- **자동 + 수동 병행**: L0~L5는 스크립트 자동화, L6는 사람이 확인
+
+## Resources
+
+| Priority | Type | Resource | Description |
+|----------|------|----------|-------------|
+| CRITICAL | script | [verify.sh](scripts/verify.sh) | 전체 레이어 오케스트레이터 |
+| CRITICAL | rule | [verification-layers](rules/verification-layers.md) | 6-Layer 정의 + 실패 정책 |
+| HIGH | rule | [verification-workflow](rules/verification-workflow.md) | 검증 실행 워크플로우 패턴 |
+| HIGH | ref | [security-fix-patterns](references/security-fix-patterns.md) | 취약점별 수정 패턴 모음 |
+| MEDIUM | ref | [release-checklist](references/release-checklist.md) | L6 수동 릴리스 체크리스트 |
+
+## Quick Rules
+
+### 검증 실행
+- `bash .claude/skills/stability-verification/scripts/verify.sh` 로 전체 실행
+- `--layer L0` 으로 특정 레이어만 실행
+- `--skip L3` 으로 특정 레이어 건너뛰기
+
+### Fail Policy
+- L0(정적분석), L1(유닛테스트), L5(패키지): **항상 fail-closed**
+- L2(보안): critical/high = fail-closed, moderate/low = fail-open
+- L3(쉘테스트), L4(통합): fail-closed, `--skip` 가능
+
+### 이슈 발견 시 수정 워크플로우
+1. 이슈 분류 (CRITICAL > HIGH > MEDIUM > LOW)
+2. 수정 패턴 리서치 (스킬 검색 + 웹 참조)
+3. 수정 계획 수립 (패턴 기반)
+4. 수정 적용 + 재검증
+
+## Checklist
+
+| Priority | Item |
+|----------|------|
+| CRITICAL | `tsc --noEmit` 에러 0개 |
+| CRITICAL | `npm run test:unit` 전체 통과 |
+| CRITICAL | `execSync` 대신 `execFileSync` (커맨드 인젝션 방지) |
+| HIGH | `shellcheck --severity=warning` 모든 .sh 경고 0개 |
+| HIGH | `npm audit --audit-level=high` 취약점 0개 |
+| HIGH | JSON 출력은 `jq -n --arg` 사용 (문자열 보간 금지) |
+| HIGH | jq 호출에 `|| echo ""` fail-open 폴백 |
+| MEDIUM | `npm pack --dry-run` 의도한 파일만 포함 |
+| MEDIUM | `.gitignore`에 .env, *.pem, *.key 포함 |
+| MEDIUM | `grep -- "$var"` 분리자 사용 |

package/templates/base/skills/stability-verification/references/release-checklist.md

@@ -0,0 +1,34 @@
+---
+title: Release Checklist
+category: guide
+---
+
+# L6: 릴리스 체크리스트 (수동)
+
+릴리스 전 사람이 확인하는 항목. `verify.sh`가 커버하지 않는 영역.
+
+## 버전 관리
+- [ ] `package.json` version이 의도한 릴리스 버전과 일치
+- [ ] CHANGELOG.md에 모든 변경사항 반영
+- [ ] Breaking changes 별도 섹션에 기술
+
+## 문서
+- [ ] README.md에 새 기능/명령 반영
+- [ ] PRD.md 버전 히스토리 업데이트
+- [ ] 메모리 파일 현재 상태 반영
+
+## Git
+- [ ] `main` 브랜치에서 릴리스 (clean working tree)
+- [ ] 모든 변경이 커밋됨 (`git status` clean)
+- [ ] 릴리스 태그 생성 (`git tag v{version}`)
+
+## npm 배포
+- [ ] `npm run build` 성공
+- [ ] `npm pack --dry-run` 검토 — 의도한 파일만 포함
+- [ ] `templates/domains/` 미포함 (유료 콘텐츠)
+- [ ] `.env`, `*.key` 등 민감 파일 미포함
+- [ ] `npm publish` 실행
+
+## 배포 후
+- [ ] `npm info timsquad version` 으로 배포 확인
+- [ ] GitHub Release 생성 (해당 시)

package/templates/base/skills/stability-verification/references/security-fix-patterns.md

@@ -0,0 +1,112 @@
+---
+title: Security Fix Patterns
+category: reference
+---
+
+# 보안 수정 패턴 모음
+
+출처: OWASP Node.js Cheat Sheet, ShellCheck Wiki, BashFAQ/048, Shellharden
+
+## 1. 커맨드 인젝션 (Node.js)
+
+### Incorrect
+```typescript
+execSync(`git clone "${url}" "${dir}"`);
+const sanitized = input.replace(/["`$\\]/g, '');
+execSync(`command "${sanitized}"`);
+```
+
+### Correct
+```typescript
+import { execFileSync } from 'child_process';
+execFileSync('git', ['clone', url, dir]);  // shell: false (기본값)
+```
+
+**원칙**: `execSync` → `execFileSync` 배열 기반. 새니타이징은 불완전하므로 의존하지 않는다.
+
+## 2. JSON 구성 (Shell Script)
+
+### Incorrect
+```bash
+echo "{\"key\":\"$VAR\"}"           # $VAR에 " 포함 시 깨짐
+cat > file.json << EOF
+{"key": "$VAR"}
+EOF
+```
+
+### Correct
+```bash
+jq -n --arg key "$VAR" '{"key": $key}'
+jq -n --arg k1 "$A" --arg k2 "$B" '{a: $k1, b: $k2}'
+jq -n --argjson num "$NUMBER" '{count: $num}'  # 숫자/불린
+```
+
+## 3. jq + set -e Fail-Open
+
+### Incorrect
+```bash
+set -e
+VAR=$(echo "$INPUT" | jq -r '.field' 2>/dev/null)  # jq 실패 시 스크립트 종료
+```
+
+### Correct
+```bash
+set -e
+VAR=$(echo "$INPUT" | jq -r '.field // ""' 2>/dev/null || echo "")
+```
+
+## 4. source 대신 안전한 설정 읽기
+
+### Incorrect
+```bash
+source "$HOME/.config"  # 임의 코드 실행 가능
+```
+
+### Correct
+```bash
+VALUE=$(grep -m1 '^KEY=' "$HOME/.config" 2>/dev/null | cut -d'=' -f2- | tr -d '"')
+```
+
+## 5. grep 변수 안전 사용
+
+### Incorrect
+```bash
+grep "$var" file          # $var가 "-e ..."이면 플래그로 해석
+grep "^${file}" output    # $file에 . + [ 등 regex 특수문자
+```
+
+### Correct
+```bash
+grep -- "$var" file       # -- 로 옵션 종료
+grep -F -- "$file" output # -F 로 리터럴 매칭
+```
+
+## 6. 사용자 입력 검증
+
+### Incorrect
+```bash
+PROJECT_NAME="$1"
+echo "name: $PROJECT_NAME" > config.yaml  # 인젝션 가능
+```
+
+### Correct
+```bash
+if [[ ! "$1" =~ ^[a-zA-Z][a-zA-Z0-9_-]{0,63}$ ]]; then
+  echo "Error: invalid name" >&2; exit 1
+fi
+PROJECT_NAME="$1"
+```
+
+## 7. .gitignore 보안 항목
+
+```gitignore
+.env
+.env.*
+!.env.example
+*.pem
+*.key
+*.p12
+*.pfx
+credentials.json
+service-account*.json
+```

package/templates/base/skills/stability-verification/rules/verification-layers.md

@@ -0,0 +1,67 @@
+---
+title: Verification Layers
+description: 6-Layer 안정성 검증 정의. 각 레이어의 검사 항목, 도구, 실패 정책.
+globs:
+  - "**/*"
+---
+
+# Verification Layers
+
+## L0: 정적 분석 (Syntax/Lint) — ~5초, Fail-Closed
+
+| 검사 | 명령 | 대상 |
+|------|------|------|
+| TypeScript 컴파일 | `tsc --noEmit` | src/**/*.ts |
+| ShellCheck | `shellcheck --severity=warning` | **/*.sh |
+| Bash 구문 | `bash -n` | **/*.sh |
+| JSON 유효성 | `jq empty < file.json` | **/*.json |
+
+## L1: 유닛 테스트 — ~10초, Fail-Closed
+
+| 검사 | 명령 |
+|------|------|
+| 전체 유닛 테스트 | `npm run test:unit` |
+| 신규 모듈 테스트 존재 확인 | 수동 확인 |
+
+## L2: 보안 스캔 — ~15초, Critical=Fail-Closed
+
+| 검사 | 명령 | 실패 정책 |
+|------|------|-----------|
+| npm 취약점 | `npm audit --audit-level=high` | critical/high: 차단, moderate/low: 경고 |
+| execSync 인젝션 | `grep -rn 'execSync(' src/` → 변수 보간 확인 | Fail-closed |
+| eval 사용 | `grep -rn 'eval ' **/*.sh` | Fail-closed |
+| 하드코딩 시크릿 | `check-secrets.sh` 또는 수동 검색 | Fail-closed |
+| JSON 문자열 보간 | 쉘 스크립트에서 `echo "{...\"$VAR\"}"` 패턴 확인 | HIGH |
+| .gitignore 보안 | .env, *.pem, *.key 항목 존재 확인 | MEDIUM |
+
+## L3: 쉘 스크립트 테스트 — ~10초, Fail-Closed
+
+| 검사 | 방법 |
+|------|------|
+| 빈 stdin → fail-open | `echo "" \| bash script.sh` |
+| malformed JSON → fail-open | `echo "not json" \| bash script.sh` |
+| 정상 입력 → 기대 출력 | 정상 JSON 파이프 |
+| 특수문자 입력 → JSON 무결성 | 인용부호/개행 포함 입력 |
+| jq fallback 동작 확인 | `|| echo ""` 패턴 존재 확인 |
+
+## L4: 통합/E2E 테스트 — ~30초, Fail-Closed
+
+| 검사 | 명령 |
+|------|------|
+| 통합 테스트 | `npm run test:integration` (있을 경우) |
+| E2E 테스트 | `npm run test:e2e` (있을 경우) |
+| CLI 스모크 테스트 | `node bin/tsq.js --version` |
+
+## L5: 패키지 무결성 — ~10초, Fail-Closed
+
+| 검사 | 명령 |
+|------|------|
+| 빌드 성공 | `npm run build` |
+| 버전 출력 | `node bin/tsq.js --version` |
+| 패키지 내용물 | `npm pack --dry-run` |
+| 민감 파일 미포함 | grep .env/.key/.pem in pack output |
+| 유료 콘텐츠 미포함 | `templates/domains/` 미포함 확인 |
+
+## L6: 릴리스 준비 (수동) — Fail-Closed
+
+`references/release-checklist.md` 참조.

package/templates/base/skills/stability-verification/rules/verification-workflow.md

@@ -0,0 +1,69 @@
+---
+title: Verification Workflow
+description: 안정성 검증 실행 워크플로우. 검증→발견→리서치→수정→재검증 사이클.
+globs:
+  - "**/*"
+---
+
+# Verification Workflow
+
+## 전체 사이클
+
+```
+1. 리서치 → 2. 계획 → 3. 스킬 생성/갱신 → 4. 검증 실행 → 5. 이슈 수정 → 6. 재검증
+     ↑                                                              |
+     └──────────────────── 이슈 발견 시 수정 패턴 리서치 ──────────────┘
+```
+
+## Phase 1: 리서치
+
+검증 시작 전 반드시 수행:
+
+1. **스킬 검색**: `npx skills find "code quality verification"` 등으로 관련 스킬 탐색
+2. **웹 참조**: OWASP, ShellCheck Wiki, npm security best practices 등 참조
+3. **기존 스킬 확인**: `stability-verification` 스킬이 이미 있으면 갱신 여부 판단
+
+## Phase 2: 계획
+
+리서치 결과를 바탕으로 검증 계획 수립:
+
+- 어떤 레이어를 실행할 것인가 (L0~L5 중 해당되는 것)
+- 각 레이어의 fail policy (closed/open)
+- 검증 대상 범위 (전체 프로젝트 vs 변경분)
+
+## Phase 3: 검증 실행
+
+`verify.sh` 또는 수동으로 각 레이어 순차 실행.
+
+## Phase 4: 이슈 발견 시 수정 워크플로우
+
+**중요**: 발견 즉시 수정하지 않는다. 리서치 먼저.
+
+### 수정 프로세스
+
+```
+이슈 분류 (CRITICAL/HIGH/MEDIUM/LOW)
+  → 수정 패턴 리서치
+    - 스킬 검색: `npx skills find "{issue-type} prevention"`
+    - 웹 검색: OWASP, ShellCheck wiki, 전문가 가이드
+  → 수정 계획 수립 (리서치 기반)
+  → 수정 적용
+  → 해당 레이어 재검증
+```
+
+### 수정 패턴 참조
+
+`references/security-fix-patterns.md` — 발견 빈도 높은 취약점별 수정 패턴 모음.
+
+## Phase 5: 재검증
+
+모든 수정 후 전체 레이어 재실행하여 regression 없음을 확인.
+
+## 검증 시점
+
+| 시점 | 레이어 | 범위 |
+|------|--------|------|
+| 커밋 전 | L0, L1 | 변경 파일 |
+| 스프린트 완료 | L0~L5 | 전체 프로젝트 |
+| 릴리스 전 | L0~L6 | 전체 프로젝트 |
+| 보안 감사 요청 | L2 집중 | 전체 프로젝트 |