@torus-engineering/tas-kit 1.13.0 → 2.1.0

package/.tas/templates/Feature-Technical.md

@@ -0,0 +1,329 @@
+---
+feature_id:           # e.g., Feature-001
+feature_file:         # relative path to Feature .md
+plan_by:              # SE name
+plan_date:
+status: Draft         # Draft | Approved | Implemented
+sad_impact: false     # true if Feature changes/extends SAD
+adr_needed: false     # true if Feature needs new ADR
+split_mode: single    # single | stack-split | sub-feature-split
+---
+# Feature-{NNN}-Technical: {Title}
+
+> Technical plan for `{feature_file}`. Generated by `/tas-plan`.
+> Source of truth for SE during `/tas-dev`.
+
+---
+
+## Context Diagram
+> All containers involved across all stacks. Who calls what, which DBs/external systems are touched.
+
+:::mermaid
+flowchart LR
+  user[User / Caller]
+  web[Web App]
+  service[API Service]
+  integration[Integration Adapter]
+  db[({DB})]
+  ext[{External API / Queue}]
+
+  user --> web
+  web --> service
+  service --> integration
+  integration --> ext
+  service --> db
+:::
+
+- **Stacks involved:** {list only stacks active in this feature — omit others}
+- **Callers / Actors:** {users, internal services, schedulers}
+- **Databases:** {names + tables touched}
+- **External systems:** {third-party APIs, queues, message brokers}
+
+## Data Flow
+> End-to-end data journey across all stacks.
+
+:::mermaid
+graph LR
+  input["{Input: {source}}"]
+  validate["{Validate}"]
+  transform["{Transform}"]
+  persist["{Persist}"]
+
+  input --> validate
+  validate --> transform
+  transform --> persist
+:::
+
+| Step | Stack | Field(s) | Transformation | Destination |
+|------|-------|----------|----------------|-------------|
+| {step} | {stack} | {fields} | {mapping, validation} | {DB column / response / event} |
+
+## API Spec
+> Contracts between stacks (REST, event, queue). Only if feature exposes new/changed interfaces.
+
+| Endpoint / Event | Stack | Method | Request | Response | Status |
+|-----------------|-------|--------|---------|----------|--------|
+| {path/topic} | {service/web} | {GET/POST/EVENT} | {schema} | {schema} | {codes} |
+
+**Error Codes:**
+- {code}: {description}
+
+## ERD
+> Tables involved. New tables, columns, indexes.
+
+:::mermaid
+erDiagram
+  TABLE_A ||--o{ TABLE_B : "1..N"
+  TABLE_A {
+    uuid id PK
+    string name
+  }
+  TABLE_B {
+    uuid id PK
+    uuid a_id FK
+    string status
+  }
+:::
+
+- **New tables:** {list — or "None"}
+- **New columns:** {table.column — or "None"}
+- **New indexes:** {table(column) — or "None"}
+- **Migration script:** {path — or "None"}
+
+## SAD Impact Matrix
+> Fill per `.tas/rules/common/sad-impact.md`. Set frontmatter `sad_impact: true` if any row `Detected: Yes`. ADR Candidate marks decisions human will review for `/tas-adr`.
+
+| # | 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 |
+
+## Architecture Decisions
+> Significant design choices. Document decision + rationale. Flag candidates for ADR review (human decides).
+
+| Decision | Rationale | ADR Candidate |
+|----------|-----------|---------------|
+| {what} | {why — trade-offs, constraints} | {Yes / No} |
+
+## Execution Plan
+> `tas-dev` reads this to orchestrate agents. `split_mode: single` → all stacks in this file. `stack-split` / `sub-feature-split` → each row is a child file.
+> `Parallel Safe: Yes` = no dependency on other rows; can run as concurrent agent.
+
+| # | Part / Stack | File | Depends On | Parallel Safe | Est. Time |
+|---|---|---|---|---|---|
+| 1 | {stack or part-title} | {`this file` or relative child path} | — | Yes / No | {e.g. 2h} |
+
+---
+
+## Stack: Web
+> *(omit this section entirely if Web stack not involved)*
+
+### Logic Flow
+1. {entry point — component/page/route}
+2. {validation / UI state}
+3. {API call / user interaction}
+4. {response handling / state update}
+
+### File Changes
+
+#### Modify
+| File | Change | Reason |
+|------|--------|--------|
+| {path} | {what} | {why} |
+
+#### Create
+| File | Purpose |
+|------|---------|
+| {path} | {what it does} |
+
+#### Delete
+| File | Reason |
+|------|--------|
+| {path} | {why removed} |
+
+### Config
+| Item | Type | Value / Source | Environment |
+|------|------|----------------|-------------|
+| {VAR_NAME} | env var | {description} | dev / staging / prod |
+
+### Unit Test Cases
+> Test ID: `{PROJECT}_F{FEATURE}_AC{N}_UT_NNN_{H|E|N}`
+
+| ID | AC Ref | Type | Description | Input | Expected Output |
+|----|--------|------|-------------|-------|-----------------|
+| {PROJ}_F{NNN}_AC1_UT_001_H | AC-1 | Happy | {description} | {input} | {expected} |
+| {PROJ}_F{NNN}_AC1_UT_001_E | AC-1 | Edge | {description} | {boundary} | {expected} |
+| {PROJ}_F{NNN}_AC1_UT_001_N | AC-1 | Negative | {description} | {invalid} | {error} |
+
+### Tasks
+- [ ] W1: {file + change}
+- [ ] W2: {file + change}
+- [ ] W3: Unit tests for AC-1, AC-2
+
+---
+
+## Stack: Service
+> *(omit this section entirely if Service stack not involved)*
+
+### Logic Flow
+1. {entry point — controller/handler}
+2. {validation / authn-authz}
+3. {business logic — service/use-case}
+4. {persistence / external call}
+5. {response / event emit}
+
+Optional sequence diagram:
+:::mermaid
+sequenceDiagram
+  Caller->>Controller: request
+  Controller->>Service: invoke
+  Service->>Repository: read/write
+  Repository->>DB: query
+  DB-->>Service: rows
+  Service-->>Controller: result
+  Controller-->>Caller: response
+:::
+
+### File Changes
+
+#### Modify
+| File | Change | Reason |
+|------|--------|--------|
+| {path} | {what} | {why} |
+
+#### Create
+| File | Purpose |
+|------|---------|
+| {path} | {what it does} |
+
+#### Delete
+| File | Reason |
+|------|--------|
+| {path} | {why removed} |
+
+### Config
+| Item | Type | Value / Source | Environment |
+|------|------|----------------|-------------|
+| {VAR_NAME} | env var | {description} | dev / staging / prod |
+
+### Unit Test Cases
+> Test ID: `{PROJECT}_F{FEATURE}_AC{N}_UT_NNN_{H|E|N}`
+
+| ID | AC Ref | Type | Description | Input | Expected Output |
+|----|--------|------|-------------|-------|-----------------|
+| {PROJ}_F{NNN}_AC1_UT_001_H | AC-1 | Happy | {description} | {input} | {expected} |
+| {PROJ}_F{NNN}_AC1_UT_001_E | AC-1 | Edge | {description} | {boundary} | {expected} |
+| {PROJ}_F{NNN}_AC1_UT_001_N | AC-1 | Negative | {description} | {invalid} | {error} |
+
+### Tasks
+- [ ] S1: {file + change}
+- [ ] S2: {file + change}
+- [ ] S3: Unit tests for AC-1, AC-2
+
+---
+
+## Stack: Integration
+> *(omit this section entirely if Integration stack not involved)*
+
+### Logic Flow
+1. {entry point — adapter/client}
+2. {authentication with external system}
+3. {request transform + call}
+4. {response transform + error handling}
+5. {retry / circuit breaker logic}
+
+### File Changes
+
+#### Modify
+| File | Change | Reason |
+|------|--------|--------|
+| {path} | {what} | {why} |
+
+#### Create
+| File | Purpose |
+|------|---------|
+| {path} | {what it does} |
+
+#### Delete
+| File | Reason |
+|------|--------|
+| {path} | {why removed} |
+
+### Config
+| Item | Type | Value / Source | Environment |
+|------|------|----------------|-------------|
+| {VAR_NAME} | env var | {description} | dev / staging / prod |
+| {API_KEY} | secret | {external service name} | all |
+
+### Unit Test Cases
+> Test ID: `{PROJECT}_F{FEATURE}_AC{N}_UT_NNN_{H|E|N}`
+
+| ID | AC Ref | Type | Description | Input | Expected Output |
+|----|--------|------|-------------|-------|-----------------|
+| {PROJ}_F{NNN}_AC1_UT_001_H | AC-1 | Happy | {description} | {input} | {expected} |
+| {PROJ}_F{NNN}_AC1_UT_001_E | AC-1 | Edge | {description} | {boundary} | {expected} |
+| {PROJ}_F{NNN}_AC1_UT_001_N | AC-1 | Negative | {description} | {invalid} | {error} |
+
+### Tasks
+- [ ] I1: {file + change}
+- [ ] I2: {file + change}
+- [ ] I3: Unit tests for AC-1, AC-2
+
+---
+
+## Stack: App
+> *(omit this section entirely if App/mobile stack not involved)*
+
+### Logic Flow
+1. {entry point — screen/view}
+2. {state management / local validation}
+3. {API call / deep link}
+4. {response handling / navigation}
+
+### File Changes
+
+#### Modify
+| File | Change | Reason |
+|------|--------|--------|
+| {path} | {what} | {why} |
+
+#### Create
+| File | Purpose |
+|------|---------|
+| {path} | {what it does} |
+
+#### Delete
+| File | Reason |
+|------|--------|
+| {path} | {why removed} |
+
+### Config
+| Item | Type | Value / Source | Environment |
+|------|------|----------------|-------------|
+| {VAR_NAME} | env var | {description} | dev / staging / prod |
+
+### Unit Test Cases
+> Test ID: `{PROJECT}_F{FEATURE}_AC{N}_UT_NNN_{H|E|N}`
+
+| ID | AC Ref | Type | Description | Input | Expected Output |
+|----|--------|------|-------------|-------|-----------------|
+| {PROJ}_F{NNN}_AC1_UT_001_H | AC-1 | Happy | {description} | {input} | {expected} |
+| {PROJ}_F{NNN}_AC1_UT_001_E | AC-1 | Edge | {description} | {boundary} | {expected} |
+| {PROJ}_F{NNN}_AC1_UT_001_N | AC-1 | Negative | {description} | {invalid} | {error} |
+
+### Tasks
+- [ ] A1: {file + change}
+- [ ] A2: {file + change}
+- [ ] A3: Unit tests for AC-1, AC-2
+
+---
+
+## Changelog
+| Date | Changes | Author |
+|------|---------|--------|

package/.tas/templates/Feature.md

@@ -7,48 +7,72 @@ ado_assigned_to:
 ado_created:
 last_ado_sync:
 parent_ado_id:
+plan_status: pending  # pending | completed (set by /tas-plan)
+plan_date:
+autonomous_run: false  # true if any /tas-plan or /tas-dev step ran with --autonomous=true
+autonomous_run_date:
 ---
+<!-- BOUNDARY: BUSINESS SPEC ONLY. This file contains business requirements, user stories, and acceptance criteria. Schema, SQL, code, migrations, data models, API specs, and all other technical content → Feature-Technical.md. Any agent adding technical sections here is wrong. -->
 # Feature-{NNN}: {Title}
 
-> **Status:** New | Pending | In Design | In Progress | Ready for Dev | In Development | Ready To Verify | Verified | Done | Removed
-> **Epic:** Epic-{NNN}
+> **Status:** New | In Design | In Development | Done | Removed
 > **Owner:** {PE name}
 > **Created:** {Date}
-> **Verified Date:** {Date when status = Verified}
+> **Done Date:** {Date when status = Done}
 
 ## Description
-{Feature description}
+{Short summary — what this feature does and the business value}
 
-## User Stories
-| ID | Story | Priority | Estimate | Status |
-|----|-------|----------|----------|--------|
-| Story-001 | {name} | Must | S | New |
+## User Story
+As a {role}, I want {goal}, so that {benefit}.
+
+## Actor
+{Who interacts with this feature — roles, personas, systems}
+
+## Business Flow
+{Step-by-step business flow / user journey}
+
+## Business Rules
+- BR-1: {rule}
+- BR-2: {rule}
+
+## UI/UX Rules
+- {UI/UX rule or reference to design-spec.md — omit section if backend-only}
+
+## Non-Functional Requirements
+- {Performance, security, scalability, accessibility — measurable when applicable}
 
 ## Acceptance Criteria
-- [ ] AC-1: {criteria}
-- [ ] AC-2: {criteria}
 
-## UI/UX Notes
-{If any, reference to design-spec.md}
+> Each AC drives unit tests (generated by `/tas-plan`) and functional tests (generated by `/tas-functest`).
+> Test ID format: `{PROJECT}_F{NNN}_AC{N}_UT_NNN_{H|E|N}` (unit) or `_FT_NNN_` (functional).
 
-## Technical Notes
-{If any, reference to SAD/ADR}
+### AC-1: {title}
+- **Given** {precondition}
+- **When** {action}
+- **Then** {expected result}
 
-## Integration Test Cases
-PE designs when creating Feature. SE implements in code.
+### AC-2: {title}
+- **Given** {precondition}
+- **When** {action}
+- **Then** {expected result}
 
-| ID | AC Ref | Scenario | Expected Result | Status |
-|----|--------|----------|-----------------|--------|
-| IT-1 | AC-1 | {Integration flow description} | {Expected result} | - |
-| IT-2 | AC-2 | {Integration flow description} | {Expected result} | - |
+## Definition of Done
+- [ ] Technical plan completed (`/tas-plan`)
+- [ ] Code implemented per all AC
+- [ ] Unit tests pass (happy + edge + negative)
+- [ ] Functional tests pass (per `/tas-functest`)
+- [ ] Code review passed (no Critical/High)
+- [ ] No regression on existing tests
+- [ ] Documentation updated (if API/schema changed)
+- [ ] Acceptance criteria verified by PE
+- [ ] Ready for production release
 
-## E2E / Acceptance Test Cases
-PE designs when creating Feature. PE verifies on Staging in Phase 2 using /tas-functest + /tas-e2e.
+## Autonomous Decisions Log
+> Populated only when `autonomous_run: true`. Each entry records a gate that was skipped or a decision auto-made by `/tas-plan` / `/tas-dev` in autonomous mode.
 
-| ID | AC Ref | User Scenario | Steps | Expected Result | Status | Verified Date |
-|----|--------|---------------|-------|-----------------|--------|---------------|
-| E2E-1 | AC-1 | {Scenario} | {Execution steps} | {Expected result} | - | - |
-| E2E-2 | AC-2 | {Scenario} | {Execution steps} | {Expected result} | - | - |
+| Timestamp | Stage | Decision | Rationale |
+|-----------|-------|----------|-----------|
 
 ## Changelog
 | Date | Changes | Author |

package/.tas/templates/Func-Test-Script.md

@@ -2,6 +2,7 @@
 
 > This document defines the conventions for generated functional test scripts.
 > Used by `/tas-functest-mobile` and `/tas-functest-web` commands.
+> Kit v3 — anchored on Feature (no Epic / Story).
 
 ---
 
@@ -11,12 +12,10 @@
 ```
 apps/mobile/e2e/
 ├── features/                           # Layer 2: Functional test scripts
-│   ├── {epic-slug}/
-│   │   ├── {feature-slug}/
-│   │   │   ├── {story-slug}.func.e2e.ts   # One file per story
-│   │   │   ├── helpers.ts                  # Feature-specific helpers (reusable by E2E)
-│   │   │   └── index.ts                    # Barrel export
-│   │   └── ...
+│   ├── {feature-slug}/
+│   │   ├── {feature-slug}.func.e2e.ts  # One file per Feature
+│   │   ├── helpers.ts                  # Feature-specific helpers (reusable by E2E)
+│   │   └── index.ts                    # Barrel export
 │   └── ...
 ├── flows/                              # Layer 3: E2E scripts (separate)
 ├── data/                               # Test data per environment
@@ -33,12 +32,10 @@ apps/mobile/e2e/
 ```
 apps/web/e2e/
 ├── features/                           # Layer 2: Functional test scripts
-│   ├── {epic-slug}/
-│   │   ├── {feature-slug}/
-│   │   │   ├── {story-slug}.func.spec.ts   # One file per story
-│   │   │   ├── helpers.ts
-│   │   │   └── index.ts
-│   │   └── ...
+│   ├── {feature-slug}/
+│   │   ├── {feature-slug}.func.spec.ts # One file per Feature
+│   │   ├── helpers.ts
+│   │   └── index.ts
 │   └── ...
 ├── flows/                              # Layer 3: E2E scripts
 ├── data/
@@ -68,13 +65,12 @@ apps/web/e2e/
 
 ```typescript
 /**
- * Functional Tests: {Story Name}
- * Story: {Story_ID}
+ * Functional Tests: {Feature Name}
  * Feature: {Feature_ID}
- * Epic: {Epic_ID}
- * 
+ * Stack: app
+ *
  * Generated by /tas-functest-mobile
- * Spec: docs/epics/{epic-dir}/{feature-dir}/Func-Test-{story-slug}.md
+ * Spec: docs/features/{feature-dir}/Func-Test-Spec.md
  */
 
 import { device, element, expect, by, waitFor } from 'detox';
@@ -84,10 +80,9 @@ import { login, navigateTo } from '../../helpers/test-utils';
 
 const testData = loadTestData();
 
-describe('{Feature Name} - {Story Name}', () => {
+describe('{Feature Name}', () => {
   beforeAll(async () => {
     await device.launchApp({ newInstance: true });
-    // Setup: login, navigate to target screen, etc.
   });
 
   beforeEach(async () => {
@@ -95,7 +90,7 @@ describe('{Feature Name} - {Story Name}', () => {
   });
 
   // AC Reference: AC-1
-  describe('{PROJECT}_E{EPIC}_F{FEATURE}_S{STORY}_FT_001_H', () => {
+  describe('{PROJECT}_F{FEATURE}_AC1_FT_001_H', () => {
     it('should {happy path description}', async () => {
       // Given: {precondition}
       // When: {action}
@@ -106,13 +101,10 @@ describe('{Feature Name} - {Story Name}', () => {
   });
 
   // AC Reference: AC-1
-  describe('{PROJECT}_E{EPIC}_F{FEATURE}_S{STORY}_FT_002_N', () => {
+  describe('{PROJECT}_F{FEATURE}_AC1_FT_002_N', () => {
     it('should {negative scenario description}', async () => {
-      // Given: {precondition}
-      // When: {invalid action}
       await element(by.id(TEST_IDS.FEATURE.INPUT)).typeText('invalid');
       await element(by.id(TEST_IDS.FEATURE.SUBMIT)).tap();
-      // Then: {error handling}
       await expect(element(by.id(TEST_IDS.FEATURE.ERROR))).toBeVisible();
     });
   });
@@ -125,13 +117,12 @@ describe('{Feature Name} - {Story Name}', () => {
 
 ```typescript
 /**
- * Functional Tests: {Story Name}
- * Story: {Story_ID}
+ * Functional Tests: {Feature Name}
  * Feature: {Feature_ID}
- * Epic: {Epic_ID}
- * 
+ * Stack: web
+ *
  * Generated by /tas-functest-web
- * Spec: docs/epics/{epic-dir}/{feature-dir}/Func-Test-{story-slug}.md
+ * Spec: docs/features/{feature-dir}/Func-Test-Spec.md
  */
 
 import { test, expect } from '@playwright/test';
@@ -139,23 +130,19 @@ import { loadTestData, getCredentials } from '../../helpers/data-loader';
 
 const testData = loadTestData();
 
-test.describe('{Feature Name} - {Story Name}', () => {
+test.describe('{Feature Name}', () => {
   test.beforeEach(async ({ page }) => {
-    // Setup: login, navigate to target page, etc.
     await page.goto('/target-page');
   });
 
   // AC Reference: AC-1
-  test.describe('{PROJECT}_E{EPIC}_F{FEATURE}_S{STORY}_FT_001_H', () => {
+  test.describe('{PROJECT}_F{FEATURE}_AC1_FT_001_H', () => {
     test('should {happy path description}', async ({ page }) => {
-      // Given: {precondition}
-      // When: {action}
       await page.getByTestId('feature-element').click();
-      // Then: {expected}
       await expect(page.getByTestId('feature-result')).toBeVisible();
     });
 
-    // Cross-viewport test
+    // Cross-viewport
     for (const viewport of [
       { width: 375, height: 812, name: 'mobile' },
       { width: 768, height: 1024, name: 'tablet' },
@@ -163,19 +150,15 @@ test.describe('{Feature Name} - {Story Name}', () => {
     ]) {
       test(`should work on ${viewport.name}`, async ({ page }) => {
         await page.setViewportSize({ width: viewport.width, height: viewport.height });
-        // Test responsive behavior
       });
     }
   });
 
   // AC Reference: AC-1
-  test.describe('{PROJECT}_E{EPIC}_F{FEATURE}_S{STORY}_FT_002_N', () => {
+  test.describe('{PROJECT}_F{FEATURE}_AC1_FT_002_N', () => {
     test('should {negative scenario description}', async ({ page }) => {
-      // Given: {precondition}
-      // When: {invalid action}
       await page.getByTestId('feature-input').fill('invalid');
       await page.getByTestId('feature-submit').click();
-      // Then: {error handling}
       await expect(page.getByTestId('feature-error')).toBeVisible();
     });
   });
@@ -187,17 +170,10 @@ test.describe('{Feature Name} - {Story Name}', () => {
 ## Data Loading Pattern
 
 ```typescript
-// Import data loader
 import { loadTestData, getCredentials } from '../../helpers/data-loader';
 
-// Load environment-specific data (reads TEST_ENV env var)
 const testData = loadTestData();
-// testData.users.default.email -> "e2e-user@yopmail.com" (from JSON)
-
-// Load credentials (passwords from .env, never from JSON)
 const creds = getCredentials();
-// creds.email -> from JSON
-// creds.password -> from process.env.TEST_USER_PASSWORD
 ```
 
 ---
@@ -205,11 +181,8 @@ const creds = getCredentials();
 ## describe/it Block Naming Convention
 
 ```typescript
-// Top-level: Feature + Story name
-describe('{Feature Name} - {Story Name}', () => {
-  // Mid-level: Full FT ID (enables grep by test ID)
-  describe('{PROJECT}_E{EPIC}_F{FEATURE}_S{STORY}_FT_001_H', () => {
-    // Leaf: Human-readable description
+describe('{Feature Name}', () => {
+  describe('{PROJECT}_F{FEATURE}_AC1_FT_001_H', () => {
     it('should {action} when {condition}', async () => { ... });
   });
 });
@@ -222,7 +195,7 @@ describe('{Feature Name} - {Story Name}', () => {
 Feature-specific helpers should be exported for Layer 3 (E2E) reuse:
 
 ```typescript
-// features/{epic}/{feature}/helpers.ts
+// features/{feature-slug}/helpers.ts
 export async function fillLoginForm(email: string, password: string) {
   await element(by.id(TEST_IDS.AUTH.LOGIN.EMAIL_INPUT)).typeText(email);
   await element(by.id(TEST_IDS.AUTH.LOGIN.PASSWORD_INPUT)).typeText(password);
@@ -245,8 +218,8 @@ These helpers are imported by E2E flow scripts in `flows/` to avoid duplication.
 ```json
 {
   "scripts": {
-    "functest:mobile:{feature-slug}": "detox test --configuration ios.sim.debug --testPathPattern='features/{epic}/{feature}'",
-    "functest:web:{feature-slug}": "npx playwright test --grep '@{feature-slug}' e2e/features/{epic}/{feature}",
+    "functest:mobile:{feature-slug}": "detox test --configuration ios.sim.debug --testPathPattern='features/{feature-slug}'",
+    "functest:web:{feature-slug}": "npx playwright test e2e/features/{feature-slug}",
     "functest:mobile:all": "detox test --configuration ios.sim.debug --testPathPattern='features/'",
     "functest:web:all": "npx playwright test e2e/features/"
   }