@torus-engineering/tas-kit 1.10.0 → 1.12.0

package/.tas/rules/typescript/patterns.md

@@ -0,0 +1,142 @@
+---
+paths:
+  - "**/*.ts"
+  - "**/*.tsx"
+  - "**/*.js"
+  - "**/*.jsx"
+---
+# TypeScript/JavaScript Patterns
+
+> This file extends [common/patterns.md](../common/patterns.md) with TypeScript/JavaScript specific content.
+
+## API Response Format
+
+```typescript
+interface ApiResponse<T> {
+  success: boolean
+  data?: T
+  error?: string
+  meta?: {
+    total: number
+    page: number
+    limit: number
+  }
+}
+```
+
+## Custom Hooks Pattern
+
+```typescript
+export function useDebounce<T>(value: T, delay: number): T {
+  const [debouncedValue, setDebouncedValue] = useState<T>(value)
+
+  useEffect(() => {
+    const handler = setTimeout(() => setDebouncedValue(value), delay)
+    return () => clearTimeout(handler)
+  }, [value, delay])
+
+  return debouncedValue
+}
+```
+
+## Repository Pattern
+
+```typescript
+interface Repository<T> {
+  findAll(filters?: Filters): Promise<T[]>
+  findById(id: string): Promise<T | null>
+  create(data: CreateDto): Promise<T>
+  update(id: string, data: UpdateDto): Promise<T>
+  delete(id: string): Promise<void>
+}
+```
+
+## Performance Anti-Patterns
+
+Avoid these in Node.js backends:
+
+- **Sequential awaits that could be parallel**: use `Promise.all()` when calls are independent
+- **CPU-blocking on event loop**: offload heavy computation to worker threads
+- **Missing connection pooling**: never create a new DB connection per request — use pooled clients
+- **ORM N+1**: missing `include`/`select` in Prisma/Sequelize — use eager loading or DataLoader for GraphQL
+- **Large file reads without streaming**: avoid `fs.readFile` on large files — use streams instead
+
+## N+1 Query Prevention (Batch Fetch)
+
+```typescript
+// BAD: N+1 queries
+const markets = await getMarkets()
+for (const market of markets) {
+  market.creator = await getUser(market.creator_id)  // N queries
+}
+
+// GOOD: Batch fetch — 2 queries total
+const markets = await getMarkets()
+const creatorIds = markets.map(m => m.creator_id)
+const creators = await getUsers(creatorIds)
+const creatorMap = new Map(creators.map(c => [c.id, c]))
+markets.forEach(m => { m.creator = creatorMap.get(m.creator_id) })
+```
+
+## Centralized Error Handler
+
+Custom `ApiError` class + single error mapper for API routes.
+
+```typescript
+class ApiError extends Error {
+  constructor(public statusCode: number, message: string, public isOperational = true) {
+    super(message)
+    Object.setPrototypeOf(this, ApiError.prototype)
+  }
+}
+
+export function errorHandler(error: unknown): Response {
+  if (error instanceof ApiError) {
+    return NextResponse.json({ error: error.message }, { status: error.statusCode })
+  }
+  if (error instanceof z.ZodError) {
+    return NextResponse.json({ error: 'Validation failed', details: error.errors }, { status: 400 })
+  }
+  console.error('Unexpected error:', error)
+  return NextResponse.json({ error: 'Internal server error' }, { status: 500 })
+}
+```
+
+## Cache-Aside Pattern
+
+```typescript
+async function getMarketWithCache(id: string): Promise<Market> {
+  const cacheKey = `market:${id}`
+  const cached = await redis.get(cacheKey)
+  if (cached) return JSON.parse(cached)
+
+  const market = await db.markets.findUnique({ where: { id } })
+  if (!market) throw new ApiError(404, 'Market not found')
+
+  await redis.setex(cacheKey, 300, JSON.stringify(market))  // 5 min TTL
+  return market
+}
+```
+
+Invalidate on writes: `await redis.del(\`market:\${id}\`)` after update/delete.
+
+## Retry with Exponential Backoff
+
+```typescript
+async function fetchWithRetry<T>(fn: () => Promise<T>, maxRetries = 3): Promise<T> {
+  let lastError: Error
+  for (let i = 0; i < maxRetries; i++) {
+    try {
+      return await fn()
+    } catch (error) {
+      lastError = error as Error
+      if (i < maxRetries - 1) {
+        await new Promise(r => setTimeout(r, Math.pow(2, i) * 1000))  // 1s, 2s, 4s
+      }
+    }
+  }
+  throw lastError!
+}
+```
+
+Use for transient failures (network, upstream API). Do NOT retry on 4xx client errors.

package/.tas/rules/typescript/security.md

@@ -0,0 +1,88 @@
+---
+paths:
+  - "**/*.ts"
+  - "**/*.tsx"
+  - "**/*.js"
+  - "**/*.jsx"
+---
+# TypeScript/JavaScript Security
+
+> This file extends [common/security.md](../common/security.md) with TypeScript/JavaScript specific content.
+
+## Secret Management
+
+```typescript
+// NEVER: Hardcoded secrets
+const apiKey = "sk-proj-xxxxx"
+
+// ALWAYS: Environment variables
+const apiKey = process.env.OPENAI_API_KEY
+
+if (!apiKey) {
+  throw new Error('OPENAI_API_KEY not configured')
+}
+```
+
+## JWT Token Validation
+
+```typescript
+import jwt from 'jsonwebtoken'
+
+interface JWTPayload {
+  userId: string
+  email: string
+  role: 'admin' | 'user'
+}
+
+export function verifyToken(token: string): JWTPayload {
+  try {
+    return jwt.verify(token, process.env.JWT_SECRET!) as JWTPayload
+  } catch {
+    throw new ApiError(401, 'Invalid token')
+  }
+}
+
+export async function requireAuth(request: Request): Promise<JWTPayload> {
+  const token = request.headers.get('authorization')?.replace('Bearer ', '')
+  if (!token) throw new ApiError(401, 'Missing authorization token')
+  return verifyToken(token)
+}
+```
+
+Always verify `JWT_SECRET` is set at boot. Never log tokens. Use short TTL (15min) + refresh tokens.
+
+## Role-Based Access Control (RBAC)
+
+```typescript
+type Permission = 'read' | 'write' | 'delete' | 'admin'
+
+const rolePermissions: Record<User['role'], Permission[]> = {
+  admin: ['read', 'write', 'delete', 'admin'],
+  moderator: ['read', 'write', 'delete'],
+  user: ['read', 'write'],
+}
+
+export function hasPermission(user: User, permission: Permission): boolean {
+  return rolePermissions[user.role].includes(permission)
+}
+
+export function requirePermission(permission: Permission) {
+  return (handler: (req: Request, user: User) => Promise<Response>) =>
+    async (req: Request) => {
+      const user = await requireAuth(req)
+      if (!hasPermission(user, permission)) throw new ApiError(403, 'Insufficient permissions')
+      return handler(req, user)
+    }
+}
+
+// Usage
+export const DELETE = requirePermission('delete')(async (req, user) => {
+  // handler with verified permission
+})
+```
+
+Check authorization at the route level (not inside business logic). Resource-level ownership checks (e.g., `if (resource.userId !== user.id)`) belong in service layer.
+
+## Agent Support
+
+- Use **security-reviewer** skill for comprehensive security audits

package/{.claude → .tas}/rules/typescript/testing.md

@@ -12,7 +12,3 @@ paths:
 ## E2E Testing
 
 Use **Playwright** as the E2E testing framework for critical user flows.
-
-## Agent Support
-
-- **e2e-runner** - Playwright E2E testing specialist

package/{.claude → .tas}/rules/web/coding-style.md

@@ -1,5 +1,3 @@
-> This file extends [common/coding-style.md](../common/coding-style.md) with web-specific frontend content.
-
 # Web Coding Style
 
 ## File Organization

package/.tas/tas-example.yaml

@@ -1,19 +1,19 @@
-# .tas/tas-example.yaml - Reference template cho tas.yaml ở root
-# Copy file này ra root (tas.yaml) và điền thông tin dự án.
-# File này CHỈ chứa flow và logic của TAS.
-# Tech stack, coding conventions, build commands thuộc về CLAUDE.md.
+# .tas/tas-example.yaml - Reference template for tas.yaml at root
+# Copy this file to root (tas.yaml) and fill in project information.
+# This file ONLY contains TAS flow and logic.
+# Tech stack, coding conventions, build commands belong in CLAUDE.md.
 
 project:
   name: "My Project"
   code: "PROJ"              # Prefix for file naming: PROJ-Epic-001, PROJ-Feature-001, etc.
   type: greenfield          # greenfield | brownfield
-  description: "Mô tả ngắn về dự án"
+  description: "Brief project description"
 
 # Azure DevOps integration
 ado:
-  enabled: true                 # false nếu project không dùng ADO
-  organization: "https://dev.azure.com/torus-bellesoft"
-  project_id: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
+  enabled: true                 # false if project doesn't use ADO
+  organization: "https://dev.azure.com/torus-engineering"
+  project_id: "f80dac23-9fa5-4b8e-a1db-da4d5aea7b31"
 
 team:
   - name: "Nguyen Van A"
@@ -118,9 +118,8 @@ models:
     tas-feature: sonnet
     tas-story: sonnet
     tas-dev: sonnet
-    tas-review-code: opus
+    tas-review: opus
     tas-brainstorm: opus
     tas-bug: sonnet
-    tas-verify: haiku
     tas-status: haiku
-    tas-security-check: opus
+    tas-security: opus

package/.tas/templates/ADR.md

@@ -1,47 +1,47 @@
-# ADR-{NNN}: {Title}
-
-> **Status:** Proposed | Accepted | Deprecated | Superseded
-> **Date:** [Date]
-> **Author:** [SE name]
-> **Supersedes:** [ADR-NNN nếu có]
-> **Related:** [ADR-NNN nếu có]
-
-## Context
-[Mô tả bối cảnh dẫn đến quyết định này. Vấn đề cần giải quyết là gì?]
-
-## Decision
-[Mô tả quyết định kiến trúc đã chọn.]
-
-## Rationale
-[Tại sao chọn hướng này? Lý do kỹ thuật và kinh doanh.]
-
-## Alternatives Considered
-
-### Alternative 1: [Tên]
-- **Pros:** [ưu điểm]
-- **Cons:** [nhược điểm]
-- **Lý do không chọn:** [giải thích]
-
-### Alternative 2: [Tên]
-- **Pros:** [ưu điểm]
-- **Cons:** [nhược điểm]
-- **Lý do không chọn:** [giải thích]
-
-## Consequences
-
-### Positive
-- [consequence 1]
-- [consequence 2]
-
-### Negative
-- [consequence 1]
-- [consequence 2]
-
-### SAD Updates
-*(Liệt kê các thay đổi cần cập nhật vào docs/sad.md - chỉ thêm khi ADR ảnh hưởng đến kiến trúc chung)*
-- [ ] [thay đổi 1]
-- [ ] [thay đổi 2]
-
-## Changelog
-| Date | Changes | Author |
-|------|---------|--------|
+# ADR-{NNN}: {Title}
+
+> **Status:** Proposed | Accepted | Deprecated | Superseded
+> **Date:** [Date]
+> **Author:** [SE name]
+> **Supersedes:** [ADR-NNN if any]
+> **Related:** [ADR-NNN if any]
+
+## Context
+[Describe context leading to this decision. What problem needs solving?]
+
+## Decision
+[Describe the chosen architectural decision.]
+
+## Rationale
+[Why choose this approach? Technical and business reasons.]
+
+## Alternatives Considered
+
+### Alternative 1: [Name]
+- **Pros:** [advantages]
+- **Cons:** [disadvantages]
+- **Why not chosen:** [explanation]
+
+### Alternative 2: [Name]
+- **Pros:** [advantages]
+- **Cons:** [disadvantages]
+- **Why not chosen:** [explanation]
+
+## Consequences
+
+### Positive
+- [consequence 1]
+- [consequence 2]
+
+### Negative
+- [consequence 1]
+- [consequence 2]
+
+### SAD Updates
+*(List changes needed to update docs/sad.md - only add when ADR affects overall architecture)*
+- [ ] [change 1]
+- [ ] [change 2]
+
+## Changelog
+| Date | Changes | Author |
+|------|---------|--------|

package/.tas/templates/AGENTS.md

@@ -0,0 +1,37 @@
+# Project Context
+
+## Tech Stack
+<!-- Specify your backend, frontend, database, infrastructure, and CI/CD -->
+- Backend: [e.g., .NET 8, Node.js, Python]
+- Frontend: [e.g., ReactJS, Vue, Angular]
+- Database: [e.g., PostgreSQL, MySQL, MongoDB]
+- Infrastructure: [e.g., AWS, Azure, GCP]
+- CI/CD: [e.g., GitHub Actions, Azure DevOps, Jenkins]
+
+## Conventions
+<!-- Define coding standards and patterns used in this project -->
+- Branching: [e.g., git-flow, trunk-based, GitHub flow]
+- Commit: [e.g., conventional commits, custom format]
+- Naming: [e.g., PascalCase for classes, camelCase for variables]
+- Test framework: [e.g., xUnit, Jest, pytest]
+
+## Architecture
+<!-- Reference key architecture documents -->
+- System design: see [docs/sad.md](docs/sad.md)
+- Architecture decisions: see [docs/adr/](docs/adr/)
+
+## Build & Test
+<!-- Commands for building, testing, and linting -->
+- Build: [e.g., dotnet build, npm run build]
+- Test: [e.g., dotnet test, npm test]
+- Lint: [e.g., dotnet format, npm run lint]
+
+## Environment Setup
+<!-- Prerequisites for running this project -->
+- [e.g., Node.js 20+, .NET 8 SDK, Python 3.11+]
+- [e.g., Azure CLI with specific extensions]
+- [e.g., Required environment variables in .env file]
+
+## Key Workflows
+<!-- Common commands for this project -->
+Type /[command-name] to [describe what it does].

package/.tas/templates/API-Test-Spec.md

@@ -28,7 +28,7 @@ framework: xUnit
 
 ## Version History
 
-> Mỗi API version có section riêng biệt. APPEND-ONLY: không sửa version cũ.
+> Each API version has separate section. APPEND-ONLY: don't modify old versions.
 
 | Version | Status | Created | Description |
 |---------|--------|---------|-------------|
@@ -354,7 +354,7 @@ framework: xUnit
 
 ## Story-Specific Test Cases (Optional)
 
-> Nếu spec được generate từ Story, thêm AC mapping ở đây.
+> If spec generated from Story, add AC mapping here.
 
 | AC ID | AC Description | Test Case IDs |
 |-------|----------------|---------------|
@@ -365,7 +365,7 @@ framework: xUnit
 
 ## Regression Tests (Optional)
 
-> Test cases cho bugs đã được tìm thấy và fix.
+> Test cases for bugs that were found and fixed.
 
 | Bug ID | Description | Test Case ID | Date Added |
 |--------|-------------|--------------|------------|

package/.tas/templates/Bug.md

@@ -1,67 +1,67 @@
----
-ado_id:
-ado_type: Bug
-ado_title: "{Title}"
-ado_state: New
-ado_assigned_to:
-ado_created:
-last_ado_sync:
-parent_ado_id:
----
-# Bug-{NNN}: {Title}
-
-> **Status:** New | Committed | In Progress | Deploy Test | Verify Test | Deploy Stag | Verify Stag | Deploy Prod | Verify Prod | Done
-> **Feature:** Feature-{NNN}
-> **Severity:** Critical | High | Medium | Low
-> **Found in:** Test | Staging | Production
-> **Found by:** {PE/SE name}
-> **Assigned to:** {SE name}
-> **Created:** {Date}
-
-## Description
-{Mô tả bug ngắn gọn}
-
-## Steps to Reproduce
-1. {Step 1}
-2. {Step 2}
-3. {Step 3}
-
-## Expected Behavior
-{Kết quả mong đợi}
-
-## Actual Behavior
-{Kết quả thực tế}
-
-## Evidence
-{Screenshots, logs, error messages}
-
-## Root Cause Analysis
-*SE điền khi phân tích*
-- **Root Cause:** {Mô tả nguyên nhân gốc}
-- **Affected Files:** {Danh sách file liên quan}
-- **Impact Scope:** {Ảnh hưởng đến những chức năng nào khác}
-
-## Regression Test Cases
-*SE thiết kế trước khi fix*
-
-| ID | Description | Input | Expected | Status |
-|----|-------------|-------|----------|--------|
-| RT-1 | Reproduce bug case | {input} | {expected} | - |
-| RT-2 | Related regression | {input} | {expected} | - |
-
-## Fix Notes
-*SE ghi sau khi fix*
-- **Fix Description:** {Mô tả cách fix}
-- **Files Changed:** {Danh sách file đã sửa}
-- **Commit:** {commit hash}
-
-## Verify Notes
-*PE ghi khi verify*
-
-| Date | Environment | Result | Verified by | Notes |
-|------|-------------|--------|-------------|-------|
-| {Date} | {env} | Pass/Fail | {PE name} | {notes} |
-
-## Changelog
-| Date | Changes | Author |
-|------|---------|--------|
+---
+ado_id:
+ado_type: Bug
+ado_title: "{Title}"
+ado_state: New
+ado_assigned_to:
+ado_created:
+last_ado_sync:
+parent_ado_id:
+---
+# Bug-{NNN}: {Title}
+
+> **Status:** New | Committed | In Progress | Deploy Test | Verify Test | Deploy Stag | Verify Stag | Deploy Prod | Verify Prod | Done
+> **Feature:** Feature-{NNN}
+> **Severity:** Critical | High | Medium | Low
+> **Found in:** Test | Staging | Production
+> **Found by:** {PE/SE name}
+> **Assigned to:** {SE name}
+> **Created:** {Date}
+
+## Description
+{Brief bug description}
+
+## Steps to Reproduce
+1. {Step 1}
+2. {Step 2}
+3. {Step 3}
+
+## Expected Behavior
+{Expected result}
+
+## Actual Behavior
+{Actual result}
+
+## Evidence
+{Screenshots, logs, error messages}
+
+## Root Cause Analysis
+*SE fills when analyzing*
+- **Root Cause:** {Root cause description}
+- **Affected Files:** {List of related files}
+- **Impact Scope:** {Affected functionality}
+
+## Regression Test Cases
+*SE designs before fixing*
+
+| ID | Description | Input | Expected | Status |
+|----|-------------|-------|----------|--------|
+| RT-1 | Reproduce bug case | {input} | {expected} | - |
+| RT-2 | Related regression | {input} | {expected} | - |
+
+## Fix Notes
+*SE fills after fixing*
+- **Fix Description:** {Fix description}
+- **Files Changed:** {List of changed files}
+- **Commit:** {commit hash}
+
+## Verify Notes
+*PE fills when verifying*
+
+| Date | Environment | Result | Verified by | Notes |
+|------|-------------|--------|-------------|-------|
+| {Date} | {env} | Pass/Fail | {PE name} | {notes} |
+
+## Changelog
+| Date | Changes | Author |
+|------|---------|--------|

package/.tas/templates/Design-Spec.md

@@ -1,36 +1,36 @@
-# Design Specification
-
-> **Status:** Draft | Approved
-> **Last Updated:** [Date]
-> **Author:** [PE name]
-> **PRD Reference:** docs/prd.md
-
----
-
-## 1. Overview
-{Tổng quan design}
-
-## 2. User Flows
-<!-- Dùng Mermaid flowchart, :::mermaid wrapper, không dùng () -->
-
-## 3. Screen Descriptions
-
-### Screen 1: {Name}
-- **Purpose:** {mục đích}
-- **Key Elements:** {thành phần chính}
-- **Actions Available:** {hành động người dùng có thể thực hiện}
-
-## 4. Navigation Structure
-<!-- Dùng Mermaid flowchart -->
-
-## 5. Interaction Patterns
-{Mô tả patterns: form submission, search, pagination...}
-
-## 6. Responsive Behavior
-{Mô tả breakpoints và behavior thay đổi}
-
----
-
-## Changelog
-| Date | Changes | Author |
-|------|---------|--------|
+# Design Specification
+
+> **Status:** Draft | Approved
+> **Last Updated:** [Date]
+> **Author:** [PE name]
+> **PRD Reference:** docs/prd.md
+
+---
+
+## 1. Overview
+{Design overview}
+
+## 2. User Flows
+<!-- Use Mermaid flowchart, :::mermaid wrapper, no () -->
+
+## 3. Screen Descriptions
+
+### Screen 1: {Name}
+- **Purpose:** {purpose}
+- **Key Elements:** {key elements}
+- **Actions Available:** {user actions available}
+
+## 4. Navigation Structure
+<!-- Use Mermaid flowchart -->
+
+## 5. Interaction Patterns
+{Describe patterns: form submission, search, pagination...}
+
+## 6. Responsive Behavior
+{Describe breakpoints and behavior changes}
+
+---
+
+## Changelog
+| Date | Changes | Author |
+|------|---------|--------|

package/.tas/templates/E2E-Execution-Report.md

@@ -51,7 +51,7 @@ environment: # dev | staging | prod
 ### {Test ID}: {Test Description}
 
 **AC Reference**: AC-{N}
-**Failure Reason**: {Mô tả ngắn gọn LÝ DO fail — ví dụ: "Button 'Submit' không hiển thị sau khi nhập email hợp lệ", "API trả về 401 thay vì 200", "Timeout sau 5s chờ màn hình Home load"}
+**Failure Reason**: {Brief description of WHY it failed — e.g.: "Button 'Submit' not visible after entering valid email", "API returns 401 instead of 200", "Timeout after 5s waiting for Home screen to load"}
 **Error Type**: {Assertion Failure | Timeout | Crash | Element Not Found}
 **Error Message**:
 ```