@torus-engineering/tas-kit 1.13.0 → 2.1.0

package/.tas/rules/common/build-debug-loop.md

@@ -0,0 +1,233 @@
+# Build & Debug Loop
+
+Protocol for Step 3.5 in `/tas-dev`. Runs in **main session** (required for MCP browser tools).
+
+## Stack Commands
+
+| Stack | Start command | Ready signal | Browser check |
+|---|---|---|---|
+| `.NET` | `dotnet run` | `Now listening on:` | No |
+| `Next.js` | `npm run dev` | `Ready in` / `✓ compiled` | Yes |
+| `NestJS` | `npm run start:dev` | `Nest application successfully started` | No (API only) |
+| `Astro` | `npm run dev` | `astro  v` + port line | Yes |
+| `ReactJS` | `npm run dev` OR `npm start` | `compiled successfully` / `Local:` | Yes |
+| `React Native` | `npx expo start` | `Metro waiting on` | No (native) |
+| `Python FastAPI` | `uvicorn main:app --reload` | `Application startup complete` | No (API only) |
+| `Python Django` | `python manage.py runserver` | `Starting development server at` | No (API only) |
+| `Python Flask` | `flask run` OR `python app.py` | `Running on http://` | No (API only) |
+| `Node.js` | `npm run start` OR `node src/index.js` | Port listen line OR exit code 0 | No |
+
+**Port detection**: extract port from ready signal line. Default fallbacks: .NET→5000, Next.js→3000, NestJS→3000, Astro→4321, React→3000, Python→8000, Flask→5000, Node→3000.
+
+**Working dir**: use path from Feature Technical Plan's stack section. If absent, infer from `package.json` / `*.csproj` / `*.py` location relative to changed files.
+
+## Loop Protocol
+
+```
+max_attempts = tas.yaml[build_debug_attempts] ?? 3
+attempt = 0
+server_pid = null
+
+PRE-FLIGHT (before loop): run Pre-flight Cleanup (see section below).
+
+try:
+  while attempt < max_attempts:
+    1. Start server (background process, timeout 60s waiting for ready signal)
+       → capture PID returned by Bash run_in_background → server_pid = PID
+    2. Capture stdout + stderr for 30s after ready (or until crash)
+    3. Evaluate result:
+       a. Server crashed (exit code != 0 OR no ready signal in 60s)
+          → extract error lines → call build-resolver agent with error context
+          → apply returned fix → kill_server(server_pid) → attempt++ → retry
+       b. Server up but error patterns in log (see Error Patterns below)
+          → same as (a)
+       c. Server up, no errors → proceed to Browser Check (if applicable)
+          → if browser check passes → kill_server(server_pid) → PASS, exit loop
+          → if browser check fails → call build-resolver with browser error context
+            → apply fix → kill_server(server_pid) → attempt++ → retry
+    4. After applying fix: tick attempted action in log
+
+  if attempt >= max_attempts:
+    STOP. Output warning block (see Warning Format below).
+    Do NOT proceed to Step 4 review.
+
+finally:
+  TEAR DOWN (always): kill_server(server_pid) if alive. See Tear Down section.
+```
+
+**MANDATORY**: kill_server() must run on every exit path — PASS, FAIL, max_attempts, exception, user interrupt. Orphan dev servers cause RAM exhaustion, port conflicts, and `.next`/`node_modules/.cache` corruption on next run.
+
+## Pre-flight Cleanup
+
+Run **before** loop starts. Kills orphan dev servers from prior runs/crashes that hold target port or pile up RAM.
+
+### Windows (PowerShell)
+```powershell
+# Kill process holding target port (if any)
+$port = {target_port}
+$conn = Get-NetTCPConnection -LocalPort $port -State Listen -ErrorAction SilentlyContinue
+if ($conn) {
+  $procId = $conn.OwningProcess
+  $proc = Get-Process -Id $procId -ErrorAction SilentlyContinue
+  if ($proc -and $proc.ProcessName -match '^(node|dotnet|python|npm)$') {
+    Stop-Process -Id $procId -Force
+    Write-Host "Killed stale $($proc.ProcessName) PID=$procId on port $port"
+  }
+}
+```
+
+### Unix (bash)
+```bash
+port={target_port}
+pid=$(lsof -ti :$port 2>/dev/null)
+if [ -n "$pid" ]; then
+  pname=$(ps -p $pid -o comm= 2>/dev/null)
+  case "$pname" in
+    node|dotnet|python|python3|npm) kill -9 $pid; echo "Killed stale $pname PID=$pid on port $port" ;;
+  esac
+fi
+```
+
+**Safety**: only kill if process name matches dev server pattern (`node`/`dotnet`/`python`/`npm`). Skip kill if foreign process — surface port conflict to user instead.
+
+## Tear Down
+
+Run on **every** loop exit path (success, failure, exception, interrupt).
+
+### Windows
+```powershell
+$pid = {server_pid}
+if ($pid) {
+  # Graceful: kill process tree (dev servers spawn child workers)
+  taskkill /PID $pid /T 2>$null
+  Start-Sleep -Seconds 3
+  # Force if still alive
+  if (Get-Process -Id $pid -ErrorAction SilentlyContinue) {
+    taskkill /PID $pid /T /F 2>$null
+  }
+}
+```
+
+### Unix
+```bash
+pid={server_pid}
+if [ -n "$pid" ] && kill -0 $pid 2>/dev/null; then
+  # SIGTERM tree (negative PID = process group)
+  kill -TERM -$pid 2>/dev/null || kill -TERM $pid
+  sleep 3
+  # SIGKILL if still alive
+  kill -0 $pid 2>/dev/null && (kill -KILL -$pid 2>/dev/null || kill -KILL $pid)
+fi
+```
+
+**Why graceful first**: SIGTERM lets Next.js/Vite finish writing `.next`/`.vite` cache. SIGKILL mid-write corrupts cache → next start fails with ENOENT/SyntaxError on chunk files.
+
+**Multi-stack runs**: tear down current stack's server BEFORE starting next stack. Never overlap.
+
+## Error Patterns (log scan)
+
+Match any of these as "error in log" even when exit code = 0:
+
+- `.NET`: `Unhandled exception`, `Application is shutting down`, `fail:`
+- `Node/TS`: `Error:`, `UnhandledPromiseRejection`, `Cannot find module`, `SyntaxError`
+- `NestJS`: `[ExceptionHandler]`, `Nest can't resolve dependencies`
+- `Python`: `Traceback (most recent call last)`, `ModuleNotFoundError`, `ImportError`
+- `React/Next`: `Failed to compile`, `Module not found`, `error TS`
+- `Astro`: `[ERROR]`, `Build failed`
+
+## Browser Check (frontend stacks only)
+
+Token-cheap path: **single curl snapshot + Grep presence test**. No MCP browser, no screenshot, no headless render.
+
+### Single-snapshot rule
+
+Fetch each URL **once per session**. Cache to `.tas/tmp/snap-{slug}.html`. Re-Grep the cached file for every subsequent check. Re-fetch only if server code changed since last snapshot.
+
+### 1. HTTP status probe (cheapest)
+```bash
+curl -sI http://localhost:{port}{path}
+```
+FAIL if status ≥ 500, or status ≠ expected from AC.
+
+### 2. HTML snapshot
+```bash
+mkdir -p .tas/tmp
+curl -s -o .tas/tmp/snap-{slug}.html -w "%{http_code}\n" http://localhost:{port}{path}
+```
+FAIL if exit ≠ 0 or file size < 200 bytes (likely blank/error page).
+
+### 3. Section-presence Grep (no re-fetch)
+For each expected element from AC "Then" clause:
+```
+Grep -F "{expected marker}" .tas/tmp/snap-{slug}.html
+```
+Markers: heading text, element id, data-testid attr, route-specific class. FAIL if any required marker missing.
+
+### 4. Error-overlay Grep
+```
+Grep -i -E "(unhandled|exception|stack trace|error overlay|hydration failed)" .tas/tmp/snap-{slug}.html
+```
+FAIL if any match (inline error page rendered).
+
+### 5. AC-based API verification
+```
+For each AC with HTTP verb + path (GET/POST/PUT/DELETE /path):
+  curl -s -w "\n%{http_code}" http://localhost:{port}{path}
+  check status matches expected
+  Grep response body for fields from AC "Then" clause
+```
+Skip if no HTTP endpoint patterns in ACs.
+
+## Context to pass build-resolver agent
+
+```
+Stack: {stack}
+Command run: {command}
+Attempt: {N} of {max}
+Exit code: {code}
+Error output:
+{last 50 lines of stdout+stderr}
+Browser errors (if any):
+{console errors list}
+AC being verified (if functional check):
+{AC text}
+Feature scope files: {list of files changed in this stack}
+```
+
+## Warning Format (max attempts exceeded)
+
+```
+⚠️ Build debug limit reached ({N}/{max} attempts) — manual intervention required.
+
+Stack: {stack}
+Command: {command}
+
+Issues found:
+{numbered list of distinct errors across all attempts}
+
+Actions taken:
+{numbered list of fixes attempted, each with: attempt N → fix description}
+
+Last build-resolver diagnosis:
+{paste diagnosis from final attempt}
+
+Predicted root cause:
+{build-resolver's last "Root cause" field}
+
+Recommended next step:
+{build-resolver's "Fix" field from last attempt}
+```
+
+## Logging
+
+After loop completes (pass or fail), append to Feature Technical file `## Build Debug Log` section (create if absent):
+
+```markdown
+## Build Debug Log
+
+### {datetime} — {stack}
+- Result: PASS / FAIL (attempt {N}/{max})
+- Command: {command}
+- Attempts: {list each attempt + outcome}
+- Fixes applied: {list}
+```

package/.tas/rules/common/code-review.md

@@ -1,3 +1,7 @@
+---
+model: opus
+---
+
 # Code Review Standards
 
 ## Purpose

package/.tas/rules/common/feature-done.md

@@ -0,0 +1,42 @@
+# Definition of Done — Feature
+
+Workflow gate used by `/tas-dev` Step 5 — verify each item before marking the Feature `Done`.
+
+## Code
+
+- [ ] Code implemented per all Acceptance Criteria (Given/When/Then)
+- [ ] Follows conventions in CLAUDE.md
+- [ ] Each public method has doc comment (XML doc / JSDoc / docstring)
+- [ ] No dead code, no commented-out blocks, no debug prints
+
+## Testing
+
+- [ ] Unit tests pass (Happy + Edge + Negative tables from Feature-Technical)
+- [ ] Functional tests run if Func-Test-Spec exists (`/tas-functest-mobile` / `/tas-functest-web`)
+- [ ] No regression on existing tests
+- [ ] Coverage ≥ 80% on changed files (per `tdd.md`)
+
+## Review
+
+- [ ] Code review passed (per `.tas/rules/common/code-review.md`)
+- [ ] Security review: no Critical/High open findings
+- [ ] If `auto_review: true`, automated review pass
+
+## Documentation
+
+- [ ] If Technical-file `sad_impact: true` → `docs/sad.md` updated AND Changelog has entry referencing `Feature-{NNN}` (gate; per `.tas/rules/common/sad-impact.md`)
+- [ ] If API/schema changed beyond SAD scope, related docs updated (README, API docs)
+- [ ] If new ADR was needed, ADR file created and linked from Feature-Technical
+- [ ] Feature Changelog has entry for this dev cycle
+
+## Status
+
+- [ ] Feature `Status:` updated in Feature file
+- [ ] `project-status.yaml` updated (`features.{ID}.status`, `done_date`)
+- [ ] Commit message follows conventions in CLAUDE.md
+- [ ] If using ADO: `/ado-update feature {ado-id} --status "Done"` run
+
+## Release Gate (PE owns)
+
+- [ ] Acceptance criteria verified by PE — all G/W/T pass on staging
+- [ ] Ready for production release

package/.tas/rules/common/post-implementation-review.md

@@ -1,3 +1,7 @@
+---
+model: opus
+---
+
 # Post-Implementation Review (Isolated Agent)
 
 After implementing or fixing, run review through **independent Agent** — don't use current session to avoid reviewer bias from implementation process.

package/.tas/rules/common/project-status.md

@@ -3,6 +3,8 @@
 File `project-status.yaml` at project root is aggregate index of project status.
 Commands update this file after each artifact or status change.
 
+> **Schema v3 (Feature-only):** Epic and Story are removed. Features are stored in a flat map at the root.
+
 ## Always update
 
 ```yaml
@@ -15,6 +17,12 @@ Update when creating new or changing version:
 
 ```yaml
 artifacts:
+  brd:
+    file: docs/brd.md
+    status: Draft | Review | Approved
+    last_updated: YYYY-MM-DD
+    version: "1.0"
+
   prd:
     file: docs/prd.md
     status: Draft | Review | Approved
@@ -40,26 +48,34 @@ artifacts:
     last_updated: YYYY-MM-DD
 ```
 
-## Epics / Features / Stories
+## Features (flat map — no Epic / Story nesting)
+
+Update when creating a Feature or changing its status / plan_status.
+
+```yaml
+features:
+  Feature-001:
+    path: docs/features/{CODE}-Feature-001-{slug}/
+    file: docs/features/{CODE}-Feature-001-{slug}/{CODE}-Feature-001-{slug}.md
+    technical_file: docs/features/{CODE}-Feature-001-{slug}/{CODE}-Feature-001-{slug}-Technical.md
+    title: "..."
+    stack: app | web | service | integration
+    status: New | In Design | In Development | Done | Removed
+    plan_status: pending | completed
+    plan_date: YYYY-MM-DD                 # set by /tas-plan
+    done_date: YYYY-MM-DD                 # set when status flips to Done
+```
 
-Update when creating new or changing status:
+## Bugs
 
 ```yaml
-epics:
-  Epic-001:
-    path: docs/epics/{code}-Epic-001-{slug}/
-    status: Draft | Active | Done
+bugs:
+  Bug-001:
+    file: docs/bugs/Bug-001-{slug}.md
+    status: Open | In Progress | Fixed | Verified | Closed
+    severity: Critical | High | Medium | Low
     title: "..."
-    effort: S | M | L | XL
-    features:
-      Feature-001:
-        status: New | In Progress | Ready To Verify | Verified | Done
-        title: "..."
-        stories:
-          Story-001:
-            status: New | Committed | In Progress | Deploy Test | Verify Test | Done
-            title: "..."
-            plan_status: pending | completed
+    feature_id: Feature-NNN              # if linked
 ```
 
 ## ADRs
@@ -78,3 +94,4 @@ adrs:
 - If key doesn't exist yet: add new
 - If key exists: update value
 - Version: minor (+0.1) when updating content; major (+1.0) when large structure change
+- **Never add `epics:` or `stories:` keys** — schema v3 dropped them

package/.tas/rules/common/sad-impact.md

@@ -0,0 +1,81 @@
+# SAD Impact Detection
+
+Single source of truth for "does this change affect `docs/sad.md`?" Consumed by `/tas-plan`, `/tas-dev`, `/tas-bug`, `/tas-fix`, `/tas-debug`.
+
+## When to read this file
+
+- `/tas-plan` Step 5 — fill `## SAD Impact Matrix` in Feature-Technical file
+- `/tas-bug` analyze step — fill `## SAD Impact Matrix` in Bug file
+- `/tas-dev` Step 5 / `/tas-bug` post-fix — check `sad_impact` flag, auto-invoke `/tas-sad` if true
+- `/tas-fix` / `/tas-debug` — run grep heuristic (Quick Heuristic section below); if hit → stop + escalate
+
+## 8 Trigger Categories
+
+Each category covers a class of changes that requires a SAD section update + Changelog entry. Mark `Detected: Yes` if any signal in the category applies.
+
+| # | Category | Signals to detect | SAD section(s) | ADR-worthy? |
+|---|----------|------------------|----------------|-------------|
+| 1 | **Tech Stack** | New runtime library (package.json / *.csproj / requirements.txt add), new SaaS runtime dep (Stripe, Auth0, Sendgrid), DB engine swap or new DB instance, license-risk dep (GPL/AGPL) | §4 Technology Baseline (4.2 Stack / 4.3 Dependencies) | If swap or vendor lock-in |
+| 2 | **System Boundary** | New actor / user role / service account, new external system, new egress target (3rd-party API / domain), new webhook (in or out) | §5 System Context, §9 Integration | If new trust boundary |
+| 3 | **Container / Topology** | New service / cache (Redis, Memcached) / queue (Kafka, SQS, RabbitMQ) / scheduled job / file storage (S3, blob), monolith → microservice split, stateful service where was stateless | §6 Logical View, §7 Component View | Yes for split / stateful shift |
+| 4 | **Data Architecture** | New table / schema, new column on PII-classified table, retention or archival policy change, sharding / partitioning change, new column-level encryption | §8 Data Architecture & ERD | If data classification shifts |
+| 5 | **API Contract** | New API style (add GraphQL alongside REST), API major-version bump (breaking), auth-scheme change on existing endpoint, new rate-limit / throttling rule, pagination convention change | §9.1 API Design Principles | If breaking or style change |
+| 6 | **Security** | New auth mechanism / token type, RBAC / permission-model change, new secret (API key / cert) — beyond generic ENV, new encryption requirement (KMS, at-rest), new network zone / VPC / subnet, new inbound port or egress firewall rule, new compliance scope (GDPR / PCI / SOC2 expand), new audit-log event class | §10 Security Architecture | Yes for auth / compliance changes |
+| 7 | **NFR / Ops** | New SLO / SLA target, new observability target (metric / dashboard / alert), new circuit breaker / retry / timeout policy, sync → async conversion, DR change (RPO / RTO) | §11 NFR Strategies | If SLO commits |
+| 8 | **Deployment** | New region / AZ, new environment tier (UAT, sandbox), CI/CD pipeline gate change, orchestration change (K8s namespace, ECS task), new CDN config, new production ENV var (≠ dev-only config) | §12 Deployment Topology | If env-tier or pipeline change |
+
+> ADR-worthy = decision is cross-cutting and irreversible. Log to `Architecture Decisions` table with `ADR Candidate: Yes`. ADR creation stays **human-triggered** (`/tas-adr`).
+
+## Quick Heuristic (for `/tas-fix`, `/tas-debug`)
+
+Lightweight commands skip the matrix. Run grep over staged / changed files. Any hit → stop, escalate to `/tas-bug`.
+
+| Signal | File pattern | Category hit |
+|--------|--------------|--------------|
+| New dependency | `package.json`, `*.csproj`, `requirements.txt`, `go.mod`, `Cargo.toml` — diff has `+` on deps section | 1 Tech Stack |
+| New ENV var | `.env*`, `*.env.example`, `appsettings*.json` — diff has new key | 6 / 8 |
+| Dockerfile change | `Dockerfile*`, `docker-compose*.yml` — `EXPOSE`, `ENV`, new service | 3 / 6 / 8 |
+| Migration / schema | `migrations/**`, `*.sql`, EF migration files | 4 Data |
+| Infra-as-code | `terraform/**`, `*.tf`, `cdk/**`, `pulumi/**`, `k8s/**`, `helm/**` | 8 Deployment |
+| CI config | `.github/workflows/**`, `azure-pipelines*.yml`, `.gitlab-ci.yml` | 8 Deployment |
+| New top-level dir under apps/services root | `apps/{new}`, `services/{new}` | 3 Container |
+
+## Matrix Template (paste into Feature-Technical / Bug files)
+
+```markdown
+## SAD Impact Matrix
+> Fill per `.tas/rules/common/sad-impact.md`. Set frontmatter `sad_impact: true` if any row Detected: Yes.
+
+| # | Category | Detected | SAD Section | Change Summary | ADR Candidate |
+|---|----------|----------|-------------|----------------|---------------|
+| 1 | Tech Stack | No | — | — | No |
+| 2 | System Boundary | No | — | — | No |
+| 3 | Container / Topology | No | — | — | No |
+| 4 | Data Architecture | No | — | — | No |
+| 5 | API Contract | No | — | — | No |
+| 6 | Security | No | — | — | No |
+| 7 | NFR / Ops | No | — | — | No |
+| 8 | Deployment | No | — | — | No |
+```
+
+## Auto-invoke `/tas-sad` rules
+
+When `sad_impact: true` in working file:
+
+| Caller | When to invoke | Description argument | Changelog ref |
+|--------|---------------|---------------------|---------------|
+| `/tas-dev` Step 5 | After post-impl review passes | `"Feature-{NNN}: {summary aggregated from matrix Yes rows}"` | `Feature-{NNN}` |
+| `/tas-bug` Status=Committed | After post-fix review passes | `"Bug-{NNN}: {summary}"` | `Bug-{NNN}` |
+| Autonomous mode | Pass `--autonomous=true` flag through | Same as above | Same |
+
+`/tas-sad` UPDATE mode writes Changelog entry to `docs/sad.md`. Caller verifies entry exists before marking Done.
+
+## Done Gate
+
+Used by `/tas-dev` Step 6 and `/tas-bug` Done transition:
+
+```
+if working_file.frontmatter.sad_impact == true:
+  grep docs/sad.md changelog for {Feature-ID | Bug-ID}
+  if no match → BLOCK Done, surface: "SAD updated but Changelog missing ref to {ID}"
+```

package/.tas/rules/common/tdd.md

@@ -1,89 +1,104 @@
-# TDD Workflow Rules
-
-When `use_tdd=true` in `tas.yaml`, enforce strict Red-Green-Refactor cycle.
-No exceptions — every feature starts with test.
-
-## When to Apply
-
-- Implement new feature per Story with clear acceptance criteria
-- Bug fix: write regression test before fixing
-- Refactor: ensure test coverage before changing code
-- DON'T use TDD for: config changes, documentation, pure data migration scripts
-
-## Always / Ask / Never
-
-| | Action |
-|---|---|
-| **Always** | Write test FIRST, run to confirm FAIL, then write code |
-| **Always** | Commit after each successful Green phase |
-| **Always** | Run full test suite after Refactor phase |
-| **Ask** | When acceptance criteria vague — clarify before writing test |
-| **Ask** | When test too hard to write — interface/design may need improvement |
-| **Never** | Write implementation before test (even "just to try") |
-| **Never** | Skip Red phase because "test will obviously fail" |
-| **Never** | Write more than minimal code needed to pass test in Green phase |
-
-## Process
-
-### Red Phase — Write Test First
-
-1. Read acceptance criteria in Story
-2. Write test cases covering each criteria (platform-specific stacks per `/tas-dev`)
-3. Run tests: `npm test` / `yarn test` / `dotnet test` / `python -m pytest`
-4. **Verify**: tests MUST FAIL — if pass immediately → test is wrong, rewrite
-
-### Green Phase — Minimal Code
-
-1. Write minimal code to pass tests
-2. Don't refactor, don't optimize in this phase
-3. Run tests: confirm PASS
-4. **Verify**: all new tests pass, no regression
-
-### Refactor Phase — Clean Up
-
-1. Remove duplication, improve naming, reduce complexity
-2. DON'T change behavior — tests are safety net
-3. Run full test suite after each refactor step
-4. **Verify**: coverage >= 80%, all tests still pass
-5. Commit after successful refactor
-
-## Red Flags
-
-- Test passes on first run before implementation → test doesn't test what it should
-- Test too broad ("everything works") → no value, write more specific test
-- Green phase has too much logic → only write enough to pass, no more
-- Refactor phase makes tests fail → refactor is wrong, roll back step by step
-- Writing multiple tests at once before fixing each → only fix one test at a time
-
-## Verification Checklist
-
-- [ ] Red: test file exists and runs with FAIL output
-- [ ] Green: test output changes from FAIL → PASS after adding implementation
-- [ ] Refactor: `npm test` / `dotnet test` / `pytest` full suite PASS
-- [ ] Coverage report: >= 80% for changed files
-- [ ] No tests skipped or commented out
-
-## Test Naming Convention
-
-```
-{PROJECT}_E{EPIC}_F{FEATURE}_S{STORY}_{TYPE}_{NUMBER}_{MODIFIER}
-```
-
-| TYPE | Meaning | Layer |
-|------|---------|-------|
-| UT | Unit Test | 1 |
-| IT | Integration Test | 1 |
-| API | API Test | 1 |
-| FT | Functional Test | 2 |
-| E2E | End-to-End Test | 3 |
-
-MODIFIER: `H` (Happy), `N` (Negative), `E` (Edge), `S` (Security), `P` (Performance)
-
-## Anti-Rationalization
-
-| Rationalization | Counter |
-|---|---|
-| "Test will obviously fail, no need to run" | Skipping Red phase loses verification point — always run |
-| "Writing test after is faster" | TDD saves more debugging time than time spent writing tests first |
-| "This code is too simple for tests" | Simple today, complex after refactor — tests protect future changes |
-| "Interface not clear, write code first for clarity" | Test hard to write is signal interface needs improvement — Ask, don't skip |
+# TDD Workflow Rules
+
+When `use_tdd=true` in `tas.yaml`, enforce strict Red-Green-Refactor cycle.
+No exceptions — every feature starts with test.
+
+## When to Apply
+
+- Implement new Feature with clear Acceptance Criteria (Given/When/Then)
+- Bug fix: write regression test before fixing
+- Refactor: ensure test coverage before changing code
+- DON'T use TDD for: config changes, documentation, pure data migration scripts
+
+## Always / Ask / Never
+
+| | Action |
+|---|---|
+| **Always** | Write test FIRST, run to confirm FAIL, then write code |
+| **Always** | Commit after each successful Green phase |
+| **Always** | Run full test suite after Refactor phase |
+| **Ask** | When acceptance criteria vague — clarify before writing test |
+| **Ask** | When test too hard to write — interface/design may need improvement |
+| **Never** | Write implementation before test (even "just to try") |
+| **Never** | Skip Red phase because "test will obviously fail" |
+| **Never** | Write more than minimal code needed to pass test in Green phase |
+
+## Process
+
+### Red Phase — Write Test First
+
+1. Read Acceptance Criteria in the Feature, plus Unit Test Cases tables in `Feature-{NNN}-Technical.md`
+2. Write test cases covering each AC (platform-specific stacks per `/tas-dev`)
+3. Run tests: `npm test` / `yarn test` / `dotnet test` / `python -m pytest`
+4. **Verify**: tests MUST FAIL — if pass immediately → test is wrong, rewrite
+
+### Green Phase — Minimal Code
+
+1. Write minimal code to pass tests
+2. Don't refactor, don't optimize in this phase
+3. Run tests: confirm PASS
+4. **Verify**: all new tests pass, no regression
+
+### Refactor Phase — Clean Up
+
+1. Remove duplication, improve naming, reduce complexity
+2. DON'T change behavior — tests are safety net
+3. Run full test suite after each refactor step
+4. **Verify**: coverage >= 80%, all tests still pass
+5. Commit after successful refactor
+
+## Red Flags
+
+- Test passes on first run before implementation → test doesn't test what it should
+- Test too broad ("everything works") → no value, write more specific test
+- Green phase has too much logic → only write enough to pass, no more
+- Refactor phase makes tests fail → refactor is wrong, roll back step by step
+- Writing multiple tests at once before fixing each → only fix one test at a time
+
+## Verification Checklist
+
+- [ ] Red: test file exists and runs with FAIL output
+- [ ] Green: test output changes from FAIL → PASS after adding implementation
+- [ ] Refactor: `npm test` / `dotnet test` / `pytest` full suite PASS
+- [ ] Coverage report: >= 80% for changed files
+- [ ] No tests skipped or commented out
+
+## Test Naming Convention
+
+Anchor on **AC**, not Story (Story removed in kit v3).
+
+```
+{PROJECT}_F{FEATURE}_AC{N}_{TYPE}_{NUMBER}_{MODIFIER}
+```
+
+For E2E (which spans multiple Features), drop the Feature/AC segment:
+
+```
+{PROJECT}_E2E_{NUMBER}_{MODIFIER}        # single-stack
+{PROJECT}_XSTACK_E2E_{NUMBER}_{MODIFIER} # cross-stack
+```
+
+| TYPE | Meaning | Layer |
+|------|---------|-------|
+| UT | Unit Test | 1 |
+| IT | Integration Test | 1 |
+| API | API Test | 1 |
+| FT | Functional Test | 2 |
+| E2E | End-to-End Test | 3 |
+
+MODIFIER: `H` (Happy), `N` (Negative), `E` (Edge), `S` (Security), `P` (Performance)
+
+Examples:
+- `AL_F012_AC1_UT_001_H` — Feature 012, AC-1, Unit Test 001, Happy
+- `AL_F012_AC2_FT_003_N` — Feature 012, AC-2, Functional Test 003, Negative
+- `AL_E2E_005_H`         — End-to-End scenario 005, Happy
+- `AL_XSTACK_E2E_002_H`  — Cross-stack End-to-End scenario 002, Happy
+
+## Anti-Rationalization
+
+| Rationalization | Counter |
+|---|---|
+| "Test will obviously fail, no need to run" | Skipping Red phase loses verification point — always run |
+| "Writing test after is faster" | TDD saves more debugging time than time spent writing tests first |
+| "This code is too simple for tests" | Simple today, complex after refactor — tests protect future changes |
+| "Interface not clear, write code first for clarity" | Test hard to write is signal interface needs improvement — Ask, don't skip |

package/.tas/rules/csharp/api-testing.md

@@ -121,7 +121,7 @@ public abstract class TestBase : IAsyncLifetime
 ```csharp
 // ============================================================
 // {Resource} API Tests — v{N}
-// Spec: {spec-file}  |  Generated: {YYYY-MM-DD}  |  Story: {ID}
+// Spec: {spec-file}  |  Generated: {YYYY-MM-DD}  |  Feature: {ID}
 // APPEND-ONLY: don't modify existing methods.
 // ============================================================
 namespace ApiTests.V{N};
@@ -160,7 +160,7 @@ public async Task ...
 | Insufficient permission | 403 | RBAC / ownership |
 | `{id}` doesn't exist | 404 | Has path param |
 | Required field missing/invalid | 400/422 | Has request body |
-| Business rule (from AC) | 4xx | Story has corresponding AC |
+| Business rule (from AC) | 4xx | Feature has corresponding AC |
 
 ## CI/CD Env Vars