@edupia-tutor/spec-driven-docs 0.14.0

package/docs/05-reference/trace-schema.md

@@ -0,0 +1,153 @@
+[📚 Docs](../README.md) › [Reference](README.md) › Trace TSV Schema
+
+# Trace TSV Schema
+
+> Schema chuẩn của `.trace/{UC-ID}.tsv` — file trace state per use-case. Mỗi UC một file: 1 header row + 1 data row mỗi scenario. Đây là nguồn dữ liệu cho `/validate-traces` và panel Living Docs.
+
+---
+
+## Mục lục
+
+- [Canonical TSV header](#canonical-tsv-header)
+- [Column reference](#column-reference)
+- [Two independent signals: dev_selftest vs qc_status](#two-independent-signals-dev_selftest-vs-qc_status)
+- [Status computation (validate-traces)](#status-computation-validate-traces)
+- [@trace tags across artifacts](#trace-tags-across-artifacts)
+- [trace-report.json](#trace-reportjson)
+
+---
+
+## Canonical TSV header
+
+Tab-separated, một header row + một data row mỗi scenario. Header chính xác (từ `generate-bdd.tmpl`):
+
+```
+sc_id	sc_title	spec_ver	gen_ver	implemented_by	test_count	test_classes	dev_selftest	dev_selftest_at	qc_status	qc_run_at	qc_owner	qc_blocked_by	prd_version	bdd_version	tech_doc_revision	fe_tech_doc_revision	prd_status	uc_status	fe_phase	status	last_updated
+```
+
+22 cột, theo đúng thứ tự trên.
+
+---
+
+## Column reference
+
+| # | Column | Ý nghĩa | Giá trị khởi tạo (`/generate-bdd`) | Ai ghi |
+|---|--------|---------|------------------------------------|--------|
+| 1 | `sc_id` | `{UC-ID}-SC{N}` — khóa chính của row | `{UC-ID}-SC{N}` | generate-bdd |
+| 2 | `sc_title` | Scenario title text | từ `.feature` | generate-bdd |
+| 3 | `spec_ver` | `@trace.sc_version` hiện tại của scenario | từ `.feature` | generate-bdd / validate-traces (reconcile) |
+| 4 | `gen_ver` | Version tại thời điểm code được sinh | `—` | generate-code |
+| 5 | `implemented_by` | `ClassName.method` cài đặt scenario | `—` | generate-code |
+| 6 | `test_count` | Số test verify scenario | `—` | dev-gen-test |
+| 7 | `test_classes` | Danh sách test class | `—` | dev-gen-test |
+| 8 | `dev_selftest` | Kết quả dev self-check: `pass` / `fail` / `not_run` | `—` | **dev-run-test** |
+| 9 | `dev_selftest_at` | Ngày chạy dev self-check (`YYYY-MM-DD`) | `—` | **dev-run-test** |
+| 10 | `qc_status` | Kết quả QC chính thức: `pass` / `fail` / `skip` / `not_run` | `—` | **qc-run-test** |
+| 11 | `qc_run_at` | Ngày chạy QC (`YYYY-MM-DD`) | `—` | **qc-run-test** |
+| 12 | `qc_owner` | **Đang chờ ai** (PM view) khi SC chưa pass: `dev` / `po` / `—` | `—` | **qc-run-test** / **report-bug** |
+| 13 | `qc_blocked_by` | Artifact liên quan: `BUG-{id}` / `GAP-{id}` / `—` | `—` | **qc-run-test** / **report-bug** |
+| 14 | `prd_version` | `@trace.prd_version` từ `.feature` header | từ `.feature` | generate-bdd |
+| 15 | `bdd_version` | `@trace.bdd_version` từ `.feature` header | từ `.feature` | generate-bdd |
+| 16 | `tech_doc_revision` | **BE** API-contract revision tại thời điểm codegen | `—` | generate-code / review-tech-docs (BE doc) |
+| 17 | `fe_tech_doc_revision` | **FE** client tech-design revision (`{UC-ID}-tech-design-{platform}.md`) tại thời điểm FE integration | `—` | generate-code `--phase=integration` / review-tech-docs (FE doc) |
+| 18 | `prd_status` | `\| **Status** \|` từ PRD metadata | từ PRD | generate-bdd |
+| 19 | `uc_status` | Trạng thái UC: `draft` / `approved` / … | `draft` (UC mới) | generate-bdd |
+| 20 | `fe_phase` | FE phase khi implement (`ui` / `integration`) | `—` | generate-code `--phase` |
+| 21 | `status` | Trạng thái tổng hợp: `OK` / `DRIFT` / `GAP` / `UNTRACKED` | `UNTRACKED` | validate-traces |
+| 22 | `last_updated` | Ngày update gần nhất (`YYYY-MM-DD`) | today | mọi command ghi row |
+
+> **`qc_owner` / `qc_blocked_by` (PM "waiting-on" view):** dành cho PO kiêm PM xem **case nào đang chờ ai**. `/qc-run-test` set khi ghi `qc_status`: product-gap FAIL → `qc_owner=dev`; `skip`/`not_run` do `DOC_GAPS` 🔴 Blocker mở → `qc_owner=po` + `qc_blocked_by=GAP-{id}`; `pass` → cả hai về `—`. `/report-bug` backfill `qc_blocked_by=BUG-{id}` (+ `qc_owner` theo layer) cho SC khớp. `/validate-traces` tổng hợp `waiting_dev` / `waiting_po` cho dashboard.
+
+> **Re-generation rules (generate-bdd):** SC đã có trong TSV & `spec_ver` không đổi → chỉ update `sc_title`, `prd_version`, `bdd_version`, `prd_status`, `uc_status`, `last_updated`. Nếu `spec_ver` đổi → thêm `spec_ver` và set `status = DRIFT` ngay. SC mới → append với `gen_ver`/`implemented_by`/`test_count`/`test_classes`/`dev_selftest`/`dev_selftest_at`/`qc_status`/`qc_run_at`/`qc_owner`/`qc_blocked_by`/`tech_doc_revision`/`fe_tech_doc_revision` = `—`. SC bị xóa khỏi `.feature` → xóa row.
+
+> **Backward-compat:** TSV cũ thiếu cột mới ở header → `/validate-traces` đọc thành giá trị rỗng, không lỗi: `qc_owner`/`qc_blocked_by` (trước 19 cột) → `null`; `fe_tech_doc_revision` (trước 22 cột) → `0`. Lần `/generate-bdd` re-gen kế tiếp tự nâng header lên 22 cột.
+
+---
+
+## Two independent signals: dev_selftest vs qc_status
+
+Trace TSV mang **hai cột tín hiệu độc lập** — không bao giờ trộn:
+
+| | `dev_selftest` (+ `dev_selftest_at`) | `qc_status` (+ `qc_run_at`) |
+|---|--------------------------------------|------------------------------|
+| Ghi bởi | `/dev-run-test` | `/qc-run-test` |
+| Ý nghĩa | Dev tự smoke-check code mình vừa sinh | Kết quả QC automation **chính thức** |
+| Giá trị | `pass` / `fail` / `not_run` | `pass` / `fail` / `skip` / `not_run` |
+| Stack | Dev implementation module | `qc-playwright` module |
+| Coverage chính thức? | **KHÔNG** — chỉ là dev self-check | **CÓ** — official QC result |
+| Keyed by | `@trace.verifies={UC-ID}` | `@trace.verifies={UC-ID}-SC{N}` |
+
+`/validate-traces` chỉ **đọc** hai cột này cho report — không bao giờ ghi đè (mỗi cột do command sở hữu nó quản lý). Living Docs hiển thị cả hai cạnh nhau.
+
+---
+
+## Status computation (validate-traces)
+
+`/validate-traces` tính cột `status` theo thứ tự ưu tiên (rule đầu tiên khớp thì dừng):
+
+| Rule | Status | Điều kiện |
+|------|--------|-----------|
+| 1 | `UNTRACKED` | `implemented_by == —` (chưa sinh code) |
+| 2 | `GAP` | `implemented_by != —` AND (`test_count == —` OR `test_count == 0`) |
+| 3 | `DRIFT` | `spec_ver != gen_ver` (scenario đổi sau lần codegen gần nhất) |
+| 4 | `OK` | tất cả: `spec_ver == gen_ver`, `implemented_by != —`, `test_count > 0` |
+
+Ngoài ra `/validate-traces` còn flag **`PRD_DRIFT`** (PRD version trong code/TSV trễ hơn PRD file hiện tại), **`TECHDOC_DRIFT`** (code BE sinh từ BE-contract revision cũ — so `tech_doc_revision`), và **`FE_TECHDOC_DRIFT`** (FE integration code sinh từ FE tech-design revision cũ — so `fe_tech_doc_revision`).
+
+---
+
+## @trace tags across artifacts
+
+Mọi artifact link với nhau qua `@trace.*` tags.
+
+**`.feature` files:**
+```gherkin
+# @trace.id: FEAT-001-UC1
+# @trace.service: web-admin
+# @trace.module: react
+# @trace.prd_version: 1.2
+# @trace.bdd_version: 3
+# @trace.api_source: existing   # brownfield: API đã tồn tại, contract lấy từ PRD
+```
+Per-scenario trong file: `# @trace.scenario: {UC-ID}-SC{N}`, `# @trace.sc_version: 1.0`, `# @trace.business_rules: ...`.
+
+**Code:**
+```java
+// @trace.implements=FEAT-001-UC1-SC2
+// @trace.prd_version=1.2
+// @trace.bdd_version=3
+// @trace.tech_doc_revision=2
+```
+
+**Dev self-check tests:**
+```java
+// @trace.verifies=FEAT-001-UC1
+// @trace.service=api-backend
+// @trace.test_type=integration
+```
+
+**QC tests** (`qc-playwright`, drive `qc_status`):
+```python
+# @trace.verifies={UC-ID}-SC{N}
+# @trace.source=<official .feature path>
+# @trace.test_type=functional|integration|e2e|non-functional
+```
+
+---
+
+## trace-report.json
+
+`/validate-traces` ghi `{paths.trace_dir}/trace-report.json` — single source of truth cho web dashboards. Cấu trúc rút gọn:
+
+- `generated_at`, `domain`
+- `summary` — aggregates: `total_prds`, `approved_prds`, `total_ucs`, `approved_ucs`, `draft_ucs`, `total_scs`, `coded_scs`, `tested_scs`, `code_coverage_pct`, `test_coverage_pct`, `drift_count`, `gap_count`, `untracked_count`, `dev_selftest_passing/failing/not_run`, `qc_passing/failing/skipped/not_run`, `waiting_dev`, `waiting_po`, `tech_docs_count`
+- `prds[]` → `ucs[]` → `scenarios[]` — mỗi scenario có đầy đủ các trường của TSV row (gồm `dev_selftest`, `dev_selftest_at`, `qc_status`, `qc_run_at`)
+- `issues` — phân loại: `drift`, `gap`, `untracked`, `prd_version_drift`, `techdoc_drift`, `fe_techdoc_drift` (kèm `platform`), mỗi entry kèm `fix` command gợi ý
+
+**TSV `"—"` → JSON mapping:** `implemented_by: "—"` → `null` · `test_count: "—"` → `0` · `test_classes: "—"` → `[]` · `tech_doc_revision: "—"` → `0` · `fe_tech_doc_revision: "—"` → `0` · `dev_selftest: "—"` → `"not_run"` · `dev_selftest_at: "—"` → `null` · `qc_status: "—"` → `"not_run"` · `qc_run_at: "—"` → `null`.
+
+> **Umbrella mode:** khi `spec_source` set, `.trace/*.tsv` authoritative nằm **một chỗ** ở `{spec_source}/.trace/` (committed — PM quản lý tập trung; mỗi scenario mang `@trace.service`). `/validate-traces` (hoặc `/sync`) sinh `trace-report.json` vào `{spec_source}/.living-docs/` + mirror `./.trace/trace-report.json` ở workspace hiện tại — cả hai generated, gitignore. (Không có `spec_source` → `.trace` per-service.)
+
+---
+
+*Xem thêm:* [Command Reference](commands.md) (`/validate-traces`, `/qc-run-test`, `/dev-run-test`) · [03 · Concepts](../03-concepts/) (traceability system).

package/docs/README.md

@@ -0,0 +1,49 @@
+# 📚 Spec-Driven Docs — Documentation
+
+> AI-First Spec-Driven Development for Claude Code: Discovery → PRD → Design-Spec → BDD →
+> Code → Dev self-check → QC automation, with traceability and human review gates.
+
+Tài liệu được chia theo **vai trò** và **chủ đề**. Bắt đầu ở mục phù hợp với bạn:
+
+| Bạn là… | Bắt đầu ở |
+|---------|-----------|
+| Người mới / cài đặt lần đầu | [01 · Getting Started](01-getting-started/) |
+| Product Owner | [Guide · Product Owner](02-guides/product-owner/README.md) |
+| Developer | [Guide · Developer](02-guides/developer/README.md) |
+| QC / Tester (QA) | [Guide · Tester / QA](02-guides/tester/README.md) — gồm cả pipeline QC tự động (`/qc-*`) |
+| Muốn hiểu kiến trúc | [03 · Concepts](03-concepts/) |
+| Vận hành / admin | [04 · Operations](04-operations/) |
+| Tra cứu lệnh | [05 · Reference](05-reference/) |
+
+---
+
+## Mục lục
+
+### 01 · [Getting Started](01-getting-started/)
+- [Installation](01-getting-started/installation.md) — cài framework, prerequisites
+- [Quick Start](01-getting-started/quickstart.md) — chạy feature đầu tiên end-to-end
+- [Core Concepts](01-getting-started/core-concepts.md) — khái niệm trong 5 phút
+
+### 02 · [Guides (theo vai trò)](02-guides/)
+- [Product Owner](02-guides/product-owner/README.md) — define-product, PRD, design-spec, review
+- [Developer](02-guides/developer/README.md) — BDD, tech-docs, code, dev self-check
+- [Tester / QA](02-guides/tester/README.md) — spec-manifest, report-bug, propose-scenario, Living Docs, và **chương [QC Automation](02-guides/tester/qc-automation.md)** (pipeline `/qc-*`, `qc_status`)
+
+### 03 · [Concepts](03-concepts/)
+- [Architecture](03-concepts/architecture.md) — layers, modules, plug-in system
+- [Pipeline](03-concepts/pipeline.md) — các phase Discovery → QC
+- [Traceability & Living Docs](03-concepts/traceability.md) — trace TSV, dev_selftest vs qc_status
+
+### 04 · [Operations](04-operations/)
+- [Sync & Update](04-operations/sync-and-update.md) — `/sync`, `/update-framework`, umbrella
+- [Bug Flow](04-operations/bug-flow.md) — report → fix → verify
+- [Publishing](04-operations/publishing.md) — build + npm publish
+
+### 05 · [Reference](05-reference/)
+- [Commands](05-reference/commands.md) — bảng đầy đủ mọi slash command
+- [Trace Schema](05-reference/trace-schema.md) — cột TSV, trace tags
+- [Modules](05-reference/modules.md) — stack modules (java-spring, react, …, qc-playwright)
+
+---
+
+*Mỗi file có breadcrumb điều hướng ở đầu. Phiên bản framework mới nhất: xem trên [npm](https://www.npmjs.com/package/@edupia-tutor/spec-driven-docs).*

package/hooks/data-guard.js

@@ -0,0 +1,141 @@
+#!/usr/bin/env node
+/**
+ * data-guard.js — Claude Code PreToolUse Hook
+ *
+ * Blocks AI from reading, writing, or executing commands involving
+ * sensitive files (credentials, secrets, private keys, .env, etc.)
+ *
+ * Install: copy to your project and register in .claude/settings.json
+ * (see hooks/settings.json for registration template)
+ *
+ * Exit codes:
+ *   0 = allow the tool call
+ *   2 = block the tool call (Claude Code interprets this as a hard block)
+ */
+
+const readline = require('readline');
+
+// ── Sensitive file patterns ────────────────────────────────────────────────
+
+const SENSITIVE_PATH_PATTERNS = [
+  // Environment files
+  /^\.env$/i,
+  /^\.env\./i,
+  /\.env$/i,
+
+  // Secret/credential files
+  /secret/i,
+  /credential/i,
+  /password/i,
+  /passwd/i,
+  /private[_-]?key/i,
+  /api[_-]?key/i,
+  /access[_-]?token/i,
+  /auth[_-]?token/i,
+
+  // Crypto keys and certificates
+  /\.key$/i,
+  /\.pem$/i,
+  /\.p12$/i,
+  /\.pfx$/i,
+  /\.jks$/i,
+  /\.keystore$/i,
+
+  // Framework-specific prod configs
+  /application-(prod|production|staging)\.(yml|yaml|properties)$/i,
+  /appsettings\.(Production|Staging)\.json$/i,
+  /database\.yml$/i,
+  /config\/master\.key$/i,
+  /storage\/oauth-private\.key$/i,
+
+  // Secret directories
+  /^secrets\//i,
+  /\/secrets\//i,
+  /^\.secrets\//i,
+];
+
+const SENSITIVE_BASH_PATTERNS = [
+  /\bprintenv\b/i,
+  /\benv\b.*\|\s*(grep|awk|sed).*secret/i,
+  /cat\s+\.env/i,
+  /docker\s+inspect/i,
+  /kubectl\s+get\s+secret.*-o\s+yaml/i,
+];
+
+// ── Helpers ────────────────────────────────────────────────────────────────
+
+function isSensitivePath(filePath) {
+  if (!filePath) return false;
+  const normalized = filePath.replace(/\\/g, '/');
+  return SENSITIVE_PATH_PATTERNS.some(pattern => pattern.test(normalized));
+}
+
+function isSensitiveCommand(command) {
+  if (!command) return false;
+  return SENSITIVE_BASH_PATTERNS.some(pattern => pattern.test(command));
+}
+
+function block(reason) {
+  console.error(`\n🔒 DATA GUARD — BLOCKED\n${reason}\n`);
+  console.error('If you need configuration values, describe what you need');
+  console.error('without sharing actual secrets. Use placeholder values in generated code.\n');
+  process.exit(2);
+}
+
+// ── Main ───────────────────────────────────────────────────────────────────
+
+let rawInput = '';
+
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', chunk => { rawInput += chunk; });
+process.stdin.on('end', () => {
+  let input;
+  try {
+    input = JSON.parse(rawInput);
+  } catch {
+    // Cannot parse input — allow (fail open, not fail closed)
+    process.exit(0);
+  }
+
+  const toolName  = input.tool_name  || '';
+  const toolInput = input.tool_input || {};
+
+  // ── Read tool ─────────────────────────────────────────────────────────
+  if (toolName === 'Read') {
+    const filePath = toolInput.file_path || '';
+    if (isSensitivePath(filePath)) {
+      block(`Attempted to READ sensitive file: ${filePath}`);
+    }
+  }
+
+  // ── Write tool ────────────────────────────────────────────────────────
+  if (toolName === 'Write') {
+    const filePath = toolInput.file_path || '';
+    if (isSensitivePath(filePath)) {
+      block(`Attempted to WRITE to sensitive file: ${filePath}`);
+    }
+  }
+
+  // ── Edit tool ─────────────────────────────────────────────────────────
+  if (toolName === 'Edit') {
+    const filePath = toolInput.file_path || '';
+    if (isSensitivePath(filePath)) {
+      block(`Attempted to EDIT sensitive file: ${filePath}`);
+    }
+  }
+
+  // ── Bash tool ─────────────────────────────────────────────────────────
+  if (toolName === 'Bash') {
+    const command = toolInput.command || '';
+    if (isSensitiveCommand(command)) {
+      block(`Attempted to execute sensitive command: ${command}`);
+    }
+    // Also check if the command references a sensitive file path
+    if (isSensitivePath(command)) {
+      block(`Bash command references a sensitive file path: ${command}`);
+    }
+  }
+
+  // Allow all other tool calls
+  process.exit(0);
+});

package/hooks/settings.json

@@ -0,0 +1,18 @@
+{
+  "_comment": "Claude Code hook registration template. Copy this content into your project's .claude/settings.json",
+  "_docs": "https://docs.anthropic.com/claude/claude-code/hooks",
+
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Read|Write|Edit|Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node .claude/hooks/data-guard.js"
+          }
+        ]
+      }
+    ]
+  }
+}

package/modules/android-compose/module.yaml

@@ -0,0 +1,13 @@
+name: "Android (Jetpack Compose)"
+version: "1.0.0"
+description: "Native Android development with Jetpack Compose + Kotlin"
+language: "Kotlin"
+framework: "Jetpack Compose"
+stack_type: "mobile"
+default_layer_order:
+  - Domain models
+  - Repository (data layer)
+  - UseCase (domain logic)
+  - ViewModel (StateFlow<UiState>)
+  - Composable screens (presentation)
+test_framework: "JUnit5 + MockK + Turbine"

package/modules/android-compose/stack-profile.yaml

@@ -0,0 +1,57 @@
+build:
+  compile: "./gradlew assembleRelease"
+  test: "./gradlew test"
+  run: "./gradlew installDebug / Open in Android Studio → Run"
+  lint: "./gradlew lint"
+
+architecture:
+  style: "MVVM + Clean Architecture (Composable → ViewModel → UseCase → Repository)"
+  key_rules:
+    - "Composables are pure UI functions — no business logic, no direct suspend calls"
+    - "ViewModels expose StateFlow<UiState>; Composables collect via collectAsStateWithLifecycle()"
+    - "UseCases are single-responsibility classes injected into ViewModels"
+    - "Repositories are interfaces; implementations live in the data layer"
+    - "Dependency injection via Hilt"
+    - "Never launch coroutines from a Composable directly — use LaunchedEffect or ViewModel"
+  folder_structure: |
+    src/main/java/{package}/
+    ├── core/
+    │   ├── network/      ← Retrofit instance, interceptors
+    │   ├── theme/        ← MaterialTheme, Color, Type, Shape
+    │   └── utils/
+    ├── shared/
+    │   └── components/   ← reusable Composables (AppButton, AppTextField...)
+    ├── features/
+    │   └── {domain}/
+    │       ├── ui/           ← Composable screens + components
+    │       ├── viewmodel/    ← ViewModel + UiState
+    │       ├── domain/       ← UseCases, domain models
+    │       └── data/         ← Repository impl, data sources
+
+coding_standards:
+  naming:
+    composables: "PascalCase (e.g., OrderListScreen, CreateOrderForm)"
+    viewmodels: "PascalCase + ViewModel suffix (e.g., OrderListViewModel)"
+    usecases: "PascalCase + UseCase suffix (e.g., CreateOrderUseCase)"
+    files:
+      screen: "{Feature}Screen.kt"
+      viewmodel: "{Feature}ViewModel.kt"
+      usecase: "{Feature}UseCase.kt"
+  patterns:
+    state_management: "StateFlow<UiState> in ViewModel"
+    navigation: "Jetpack Navigation Compose"
+    networking: "Retrofit + OkHttp"
+    serialization: "Kotlinx Serialization or Gson"
+    di: "Hilt"
+    async: "Kotlin Coroutines + Flow"
+
+testing:
+  unit: "JUnit5 + MockK + Turbine (Flow testing)"
+  ui: "Compose UI Test (composeTestRule)"
+  patterns:
+    - "Test ViewModel with fake repositories and TestCoroutineDispatcher"
+    - "UI tests use semantics matchers — set Modifier.testTag() on Composables"
+
+trace_tags:
+  implements: "// @trace.implements={UC-ID}-SC{N}"
+  source: "// @trace.source=specs/{domain}/{prd-slug}/bdd/{UC-ID}.feature"

package/modules/angular/architecture-snippets/component-patterns.md

@@ -0,0 +1,187 @@
+# Angular — Component Architecture Patterns
+
+## Smart / Container Component Pattern
+
+```typescript
+// order-list.component.ts — Smart component: manages state, injects services
+import { Component, OnInit, inject } from '@angular/core';
+import { CommonModule } from '@angular/common';
+import { OrderService } from '../services/order.service';
+import { OrderListItemComponent } from './order-list-item.component';
+import { Order } from '../models/order.model';
+
+@Component({
+  selector: 'app-order-list',
+  standalone: true,
+  imports: [CommonModule, OrderListItemComponent],
+  template: `
+    <div class="order-list">
+      <app-order-list-item
+        *ngFor="let order of orders"
+        [order]="order"
+        (cancel)="onCancelOrder($event)"
+      />
+    </div>
+  `
+})
+export class OrderListComponent implements OnInit {
+  private orderService = inject(OrderService);
+  orders: Order[] = [];
+
+  ngOnInit(): void {
+    this.orderService.getOrders().subscribe(orders => this.orders = orders);
+  }
+
+  onCancelOrder(orderId: number): void {
+    this.orderService.cancelOrder(orderId).subscribe(() => {
+      this.orders = this.orders.filter(o => o.id !== orderId);
+    });
+  }
+}
+```
+
+## Dumb / Presentational Component Pattern
+
+```typescript
+// order-list-item.component.ts — Dumb component: pure I/O, OnPush, no service injection
+import { Component, Input, Output, EventEmitter, ChangeDetectionStrategy } from '@angular/core';
+import { Order } from '../models/order.model';
+
+@Component({
+  selector: 'app-order-list-item',
+  standalone: true,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  template: `
+    <div class="order-item">
+      <span>{{ order.id }}</span>
+      <span>{{ order.status }}</span>
+      <button (click)="cancel.emit(order.id)" [disabled]="order.status === 'CANCELLED'">
+        Cancel
+      </button>
+    </div>
+  `
+})
+export class OrderListItemComponent {
+  @Input({ required: true }) order!: Order;
+  @Output() cancel = new EventEmitter<number>();
+}
+```
+
+## Service with HttpClient Pattern
+
+```typescript
+// order.service.ts
+import { Injectable, inject } from '@angular/core';
+import { HttpClient, HttpParams } from '@angular/common/http';
+import { Observable } from 'rxjs';
+import { Order, CreateOrderRequest, OrderResponse } from '../models/order.model';
+import { environment } from '@env/environment';
+
+@Injectable({ providedIn: 'root' })
+export class OrderService {
+  private http = inject(HttpClient);
+  private baseUrl = `${environment.apiUrl}/v1/orders`;
+
+  getOrders(customerId?: number): Observable<Order[]> {
+    let params = new HttpParams();
+    if (customerId) params = params.set('customerId', customerId.toString());
+    return this.http.get<Order[]>(this.baseUrl, { params });
+  }
+
+  getOrder(id: number): Observable<Order> {
+    return this.http.get<Order>(`${this.baseUrl}/${id}`);
+  }
+
+  createOrder(request: CreateOrderRequest): Observable<OrderResponse> {
+    return this.http.post<OrderResponse>(this.baseUrl, request);
+  }
+
+  cancelOrder(id: number): Observable<void> {
+    return this.http.patch<void>(`${this.baseUrl}/${id}/cancel`, {});
+  }
+}
+```
+
+## Signal-Based State Pattern (Angular 17+)
+
+```typescript
+// order.store.ts — using Angular Signals for state management
+import { Injectable, signal, computed } from '@angular/core';
+import { Order } from '../models/order.model';
+
+@Injectable({ providedIn: 'root' })
+export class OrderStore {
+  private _orders = signal<Order[]>([]);
+  private _loading = signal(false);
+  private _error = signal<string | null>(null);
+
+  // Public readable signals
+  readonly orders = this._orders.asReadonly();
+  readonly loading = this._loading.asReadonly();
+  readonly error = this._error.asReadonly();
+
+  // Computed signals
+  readonly pendingOrders = computed(() =>
+    this._orders().filter(o => o.status === 'PENDING')
+  );
+  readonly orderCount = computed(() => this._orders().length);
+
+  setOrders(orders: Order[]): void {
+    this._orders.set(orders);
+  }
+
+  setLoading(loading: boolean): void {
+    this._loading.set(loading);
+  }
+
+  setError(error: string | null): void {
+    this._error.set(error);
+  }
+
+  removeOrder(id: number): void {
+    this._orders.update(orders => orders.filter(o => o.id !== id));
+  }
+}
+```
+
+## Route Guard Pattern
+
+```typescript
+// auth.guard.ts
+import { inject } from '@angular/core';
+import { CanActivateFn, Router } from '@angular/router';
+import { AuthService } from '../services/auth.service';
+
+export const authGuard: CanActivateFn = (route, state) => {
+  const auth = inject(AuthService);
+  const router = inject(Router);
+
+  if (auth.isAuthenticated()) {
+    return true;
+  }
+  return router.createUrlTree(['/login'], { queryParams: { returnUrl: state.url } });
+};
+```
+
+## Standalone Component with Lazy Loading
+
+```typescript
+// app.routes.ts
+import { Routes } from '@angular/router';
+import { authGuard } from './guards/auth.guard';
+
+export const APP_ROUTES: Routes = [
+  {
+    path: 'orders',
+    canActivate: [authGuard],
+    loadComponent: () =>
+      import('./features/orders/order-list.component').then(m => m.OrderListComponent)
+  },
+  {
+    path: 'orders/:id',
+    canActivate: [authGuard],
+    loadComponent: () =>
+      import('./features/orders/order-detail.component').then(m => m.OrderDetailComponent)
+  }
+];
+```

package/modules/angular/module.yaml

@@ -0,0 +1,6 @@
+name: "Angular"
+version: "1.0.0"
+description: "Angular 17+ frontend with component-based architecture"
+language: "TypeScript"
+framework: "Angular"
+stack_type: "frontend"

package/modules/angular/stack-profile.yaml

@@ -0,0 +1,38 @@
+build:
+  compile: "ng build"
+  test: "ng test --watch=false"
+  run: "ng serve"
+
+architecture:
+  style: "Component → Service → HTTP Client → Backend API"
+  key_rules:
+    - "Smart (container) components manage state and inject services"
+    - "Dumb (presentational) components receive data via @Input and emit via @Output"
+    - "Business logic lives in services, not in component classes"
+    - "Use OnPush change detection for all pure presentational components"
+    - "HTTP calls must be in services, never in component files"
+
+coding_standards:
+  naming:
+    components: "PascalCase + Component suffix (e.g., OrderListComponent)"
+    services: "PascalCase + Service suffix (e.g., OrderService)"
+    pipes: "PascalCase + Pipe suffix (e.g., CurrencyFormatPipe)"
+    directives: "PascalCase + Directive suffix (e.g., HighlightDirective)"
+    guards: "PascalCase + Guard suffix (e.g., AuthGuard)"
+    files:
+      component: "{feature}.component.ts / .html / .scss"
+      service: "{feature}.service.ts"
+      model: "{feature}.model.ts"
+      store: "{feature}.store.ts"
+  patterns:
+    state_management: "NgRx (complex) or Angular Signals (simple/medium)"
+    http_error_handling: "HttpInterceptor catches 4xx/5xx globally"
+    lazy_loading: "All feature modules must be lazily loaded"
+
+testing:
+  unit: "Jasmine + Karma or Jest"
+  e2e: "Cypress or Playwright"
+  patterns:
+    - "Use TestBed.configureTestingModule for component tests"
+    - "Mock services with jasmine.createSpyObj or jest.fn()"
+    - "Test component DOM via DebugElement and By.css selectors"