Backup: docs: update README and patch 2git.ps1 | 2025-12-06 15:30:17

Merge branch 'main' of github.com:peancharoen/lcbp3
Backup: docs: update README | 2025-12-06 15:21:14
2025-12-06 15:30:17 +07:00 · 2025-12-06 15:26:56 +07:00 · 2025-12-06 15:24:06 +07:00 · 2025-12-06 14:47:36 +07:00 · 2025-12-06 14:42:32 +07:00 · 2025-12-05 23:42:12 +07:00
3231 changed files with 940419 additions and 331948 deletions
@@ -0,0 +1,62 @@
+---
+trigger: always_on
+---
+
+# Project Specifications & Context Protocol
+
+Description: Enforces strict adherence to the project's documentation structure (specs/00-06) for all agent activities.
+Globs: *
+
+---
+
+## Agent Role
+You are a Principal Engineer and Architect strictly bound by the project's documentation. You do not improvise outside of the defined specifications.
+
+## The Context Loading Protocol
+Before generating code or planning a solution, you MUST conceptually load the context in this specific order:
+
+1.  **🎯 ACTIVE TASK (`specs/06-tasks/`)**
+    - Identify the current active task file.
+    - *Action:* Determine the immediate scope. Do NOT implement features not listed here.
+
+2.  **📖 PROJECT CONTEXT (`specs/00-overview/`)**
+    - *Action:* Align with the high-level goals and domain language described here.
+
+3.  **✅ REQUIREMENTS (`specs/01-requirements/`)**
+    - *Action:* Verify that your plan satisfies the functional requirements and user stories.
+    - *Constraint:* If a requirement is ambiguous, stop and ask.
+
+4.  **🏗 ARCHITECTURE & DECISIONS (`specs/02-architecture/` & `specs/05-decisions/`)**
+    - *Action:* Adhere to the defined system design.
+    - *Crucial:* Check `specs/05-decisions/` (ADRs) to ensure you do not violate previously agreed-upon technical decisions.
+
+5.  **💾 DATABASE & SCHEMA (`specs/07-databasee/`)**
+    - *Action:* - **Read `specs/07-database/lcbp3-v1.5.1-schema.sql`** (or relevant `.sql` files) for exact table structures and constraints.
+        - **Consult `specs/database/data-dictionary-v1.5.1.md`** for field meanings and business rules.
+        - **Check `specs/database/lcbp3-v1.5.1-seed.sql`** to understand initial data states.
+    - *Constraint:* NEVER invent table names or columns. Use ONLY what is defined here.
+
+6.  **⚙️ IMPLEMENTATION DETAILS (`specs/03-implementation/`)**
+    - *Action:* Follow Tech Stack, Naming Conventions, and Code Patterns.
+
+7.  **🚀 OPERATIONS (`specs/04-operations/`)**
+    - *Action:* Ensure deployability and configuration compliance.
+
+## Execution Rules
+
+### 1. Citation Requirement
+When proposing a change or writing code, you must explicitly reference the source of truth:
+> "Implementing feature X per `specs/01-requirements/README.md` and `specs/01-requirements/**.md` using pattern defined in `specs/03-implementation/**.md`."
+
+### 2. Conflict Resolution
+- **Spec vs. Training Data:** The `specs/` folder ALWAYS supersedes your general training data.
+- **Spec vs. User Prompt:** If a user prompt contradicts `specs/05-decisions/`, warn the user before proceeding.
+
+### 3. File Generation
+- Do not create new files outside of the structure defined.
+- Keep the code style consistent with `specs/03-implementation/`.
+
+### 4. Data Migration
+- Do not migrate. The schema can be modified directly.
+
+---
@@ -0,0 +1,20 @@
+---
+trigger: always_on
+---
+
+---
+
+description: Control which shell commands the agent may run automatically.
+allowAuto: ["pnpm test:watch", "pnpm test:debug", "pnpm test:e2e", "git status"]
+denyAuto: ["rm -rf", "Remove-Item", "git push --force", "curl | bash"]
+alwaysReview: true
+scopes: ["backend/src/**", "backend/test/**", "frontend/app/**"]
+
+---
+
+# Execution Rules
+
+- Only auto-execute commands that are explicitly listed in `allowAuto`.
+- Commands in denyAuto must always be blocked, even if manually requested.
+- All shell operations that create, modify, or delete files in `backend/src/` or `backend/test/` or `frontend/app/`require human review.
+- Alert if environment variables related to DB connection or secrets would be displayed or logged.
@@ -1,455 +0,0 @@
-# 🚀 Spec-Kit: Antigravity Skills & Workflows
-
-> **The Event Horizon of Software Quality.**
-> _Adapted for Google Antigravity IDE from [github/spec-kit](https://github.com/github/spec-kit)._
-> _Version: 1.8.6 — LCBP3-DMS Edition (v1.8.6 Production Ready)_
-
---
-
-## 🌟 Overview
-
-Welcome to the **Antigravity Edition** of Spec-Kit. This system is architected to empower your AI pair programmer (Antigravity) to drive the entire Software Development Life Cycle (SDLC) using two powerful mechanisms: **Workflows** and **Skills**.
-
-### 🔄 Dual-Mode Intelligence
-
-In this edition, Spec-Kit commands have been split into two interactive layers:
-
-1.  **Workflows (`/command`)**: High-level orchestrations that guide the agent through a series of logical steps. **The easiest way to run a skill is by typing its corresponding workflow command.**
-2.  **Skills (`@speckit-name`)**: Packaged agentic capabilities. Mentions of a skill give the agent immediate context and autonomous "know-how" to execute the specific toolset associated with that phase.
-
-> **To understand the power of Skills in Antigravity, read the docs here:**
-> [https://antigravity.google/docs/skills](https://antigravity.google/docs/skills)
-
---
-
-## 🛠️ Installation
-
-To enable these agent capabilities in your project:
-
-1.  **Add the folder**: Drop the `.agents/` folder into the root of your project workspace.
-2.  **That's it!** Antigravity automatically detects the `.agents/skills` and `.agents/workflows` directories. It will instantly gain the ability to perform Spec-Driven Development.
-
-> **💡 Compatibility Note:** This toolkit is compatible with multiple AI coding agents. To use with Claude Code, rename the `.agents` folder to `.claude`. The skills and workflows will function identically.
-
-### Prerequisites (Optional)
-
-Some skills and scripts reference a `.specify/` directory for templates and project memory. If you want the full Spec-Kit experience (template-driven spec/plan creation), create this structure at repo root:
-
-```text
-.specify/
-├── templates/
-│   ├── spec-template.md          # Template for /speckit-specify
-│   ├── plan-template.md          # Template for /speckit-plan
-│   ├── tasks-template.md         # Template for /speckit-tasks
-│   └── agent-file-template.md    # Template for update-agent-context.sh
-└── memory/
-    └── constitution.md           # Project governance rules (/speckit-constitution)
-```
-
-> **Note:** If `.specify/` is absent, skills will still function — they'll create blank files instead of using templates. The constitution workflow (`/speckit-constitution`) will create this structure for you on first run.
-
---
-
-## 🏗️ The Architecture
-
-The toolkit is organized into modular components that provide both the logic (Scripts) and the structure (Templates) for the agent.
-
-```text
-.agents/                        # Agent Skills & Rules
-├── skills/                        # @ Mentions (Agent Intelligence)
-│   ├── nestjs-best-practices/     # NestJS Architecture Patterns
-│   ├── next-best-practices/       # Next.js App Router Patterns
-│   ├── speckit-analyze/           # Consistency Checker
-│   ├── speckit-checker/           # Static Analysis Aggregator
-│   ├── speckit-checklist/         # Requirements Validator
-│   ├── speckit-clarify/           # Ambiguity Resolver
-│   ├── speckit-constitution/      # Governance Manager
-│   ├── speckit-diff/              # Artifact Comparator
-│   ├── speckit-implement/         # Code Builder (Anti-Regression)
-│   ├── speckit-migrate/           # Legacy Code Migrator
-│   ├── speckit-plan/              # Technical Planner
-│   ├── speckit-quizme/            # Logic Challenger (Red Team)
-│   ├── speckit-reviewer/          # Code Reviewer
-│   ├── speckit-security-audit/    # Security Auditor (OWASP/CASL/ClamAV)
-│   ├── speckit-specify/           # Feature Definer
-│   ├── speckit-status/            # Progress Dashboard
-│   ├── speckit-tasks/             # Task Breaker
-│   ├── speckit-taskstoissues/     # Issue Tracker Syncer (GitHub + Gitea)
-│   ├── speckit-tester/            # Test Runner & Coverage
-│   └── speckit-validate/          # Implementation Validator
-│
-├── rules/                         # Project Context & Validation Rules
-│   ├── 00-project-context.md      # Role, Persona, Rule Tiers
-│   ├── 01-adr-019-uuid.md         # UUID Strategy (Critical)
-│   ├── 02-security.md             # Security Requirements
-│   ├── 03-typescript.md            # TypeScript Standards
-│   ├── 04-domain-terminology.md   # DMS Glossary Compliance
-│   ├── 05-forbidden-actions.md    # Critical Prohibited Patterns
-│   ├── 06-backend-patterns.md     # NestJS Architecture Rules
-│   ├── 07-frontend-patterns.md    # Next.js App Router Rules
-│   ├── 08-development-flow.md      # Development Workflow
-│   ├── 09-commit-checklist.md      # Pre-commit Validation
-│   ├── 10-error-handling.md       # ADR-007 Compliance
-│   └── 11-ai-integration.md       # ADR-018/020 AI Boundaries
-│
-└── scripts/
-    ├── bash/                      # Bash Core (Kinetic logic)
-    ├── powershell/                 # PowerShell Equivalents (Windows-native)
-    ├── fix_links.py               # Spec link fixer
-    ├── verify_links.py            # Spec link verifier
-    └── start-mcp.js               # MCP server launcher
-
-.windsurf/workflows/               # / Slash Commands (Orchestration)
-├── 00-speckit.all.md              # Full Pipeline (10 steps: Specify → Validate)
-├── 01–11-speckit-*.md             # Individual phase workflows
-├── speckit-prepare.md             # Prep Pipeline (5 steps: Specify → Analyze)
-├── schema-change.md               # DB Schema Change (ADR-009)
-├── create-backend-module.md       # NestJS Module Scaffolding
-├── create-frontend-page.md        # Next.js Page Scaffolding
-├── deploy.md                      # Deployment via Gitea CI/CD
-├── review.md                      # Code Review Workflow
-└── util-speckit-*.md              # Utilities (checklist, diff, migrate, etc.)
-```
-
---
-
-## 🗺️ Mapping: Commands to Capabilities
-
-| Phase             | Workflow Trigger              | Antigravity Skill         | Role                                                    |
-| :---------------- | :---------------------------- | :------------------------ | :------------------------------------------------------ |
-| **Full Pipeline** | `/00-speckit-all`             | N/A                       | Runs full SDLC pipeline (10 steps: Specify → Validate). |
-| **Governance**    | `/01-speckit-constitution`    | `@speckit-constitution`   | Establishes project rules & principles.                 |
-| **Definition**    | `/02-speckit-specify`         | `@speckit-specify`        | Drafts structured `spec.md`.                            |
-| **Ambiguity**     | `/03-speckit-clarify`         | `@speckit-clarify`        | Resolves gaps post-spec.                                |
-| **Architecture**  | `/04-speckit-plan`            | `@speckit-plan`           | Generates technical `plan.md`.                          |
-| **Decomposition** | `/05-speckit-tasks`           | `@speckit-tasks`          | Breaks plans into atomic tasks.                         |
-| **Consistency**   | `/06-speckit-analyze`         | `@speckit-analyze`        | Cross-checks Spec vs Plan vs Tasks.                     |
-| **Execution**     | `/07-speckit-implement`       | `@speckit-implement`      | Builds implementation with safety protocols.            |
-| **Quality**       | `/08-speckit-checker`         | `@speckit-checker`        | Runs static analysis (Linting, Security, Types).        |
-| **Testing**       | `/09-speckit-tester`          | `@speckit-tester`         | Runs test suite & reports coverage.                     |
-| **Review**        | `/10-speckit-reviewer`        | `@speckit-reviewer`       | Performs code review (Logic, Perf, Style).              |
-| **Validation**    | `/11-speckit-validate`        | `@speckit-validate`       | Verifies implementation matches Spec requirements.      |
-| **Preparation**   | `/speckit-prepare`            | N/A                       | Runs Specify → Analyze prep sequence (5 steps).         |
-| **Schema**        | `/schema-change`              | N/A                       | DB schema changes per ADR-009 (no migrations).          |
-| **Security**      | N/A                           | `@speckit-security-audit` | OWASP Top 10 + CASL + ClamAV audit.                     |
-| **Checklist**     | `/util-speckit-checklist`     | `@speckit-checklist`      | Generates feature checklists.                           |
-| **Diff**          | `/util-speckit-diff`          | `@speckit-diff`           | Compares artifact versions.                             |
-| **Migration**     | `/util-speckit-migrate`       | `@speckit-migrate`        | Port existing code to Spec-Kit.                         |
-| **Red Team**      | `/util-speckit-quizme`        | `@speckit-quizme`         | Challenges logical flaws.                               |
-| **Status**        | `/util-speckit-status`        | `@speckit-status`         | Shows feature completion status.                        |
-| **Tracking**      | `/util-speckit-taskstoissues` | `@speckit-taskstoissues`  | Syncs tasks to GitHub/Gitea issues.                     |
-
---
-
-## 🛡️ The Quality Assurance Pipeline
-
-The following skills are designed to work together as a comprehensive defense against regression and poor quality. Run them in this order:
-
-| Step            | Skill               | Core Question                     | Focus                                                                                                                                                 |
-| :-------------- | :------------------ | :-------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **1. Checker**  | `@speckit-checker`  | _"Is the code compliant?"_        | **Syntax & Security**. Runs compilation, linting (ESLint/GolangCI), and vulnerability scans (npm audit/govulncheck). Catches low-level errors first.  |
-| **2. Tester**   | `@speckit-tester`   | _"Does it work?"_                 | **Functionality**. Executes your test suite (Jest/Pytest/Go Test) to ensure logic performs as expected and tests pass.                                |
-| **3. Reviewer** | `@speckit-reviewer` | _"Is the code written well?"_     | **Quality & Maintainability**. Analyzes code structure for complexity, performance bottlenecks, and best practices, acting as a senior peer reviewer. |
-| **4. Validate** | `@speckit-validate` | _"Did we build the right thing?"_ | **Requirements**. Semantically compares the implementation against the defined `spec.md` and `plan.md` to ensure all feature requirements are met.    |
-
-> **🤖 Power User Tip:** You can amplify this pipeline by creating a custom **MCP Server** or subagent that delegates heavy reasoning to a dedicated LLM.
->
-> - **Use Case:** Bind the `@speckit-validate` and `@speckit-reviewer` steps to a large-context model.
-> - **Benefit:** Large-context models (1M+ tokens) excel at analyzing the full project context against the Spec, finding subtle logical flaws that smaller models miss.
-> - **How:** Create a wrapper script `scripts/gemini-reviewer.sh` that pipes the `tasks.md` and codebase to an LLM, then expose this as a tool.
-
---
-
-## 🏗️ The Design & Management Pipeline
-
-These workflows function as the "Control Plane" of the project, managing everything from idea inception to status tracking.
-
-| Step               | Workflow                                            | Core Question         | Focus                                                                                                                                                        |
-| :----------------- | :-------------------------------------------------- | :-------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **1. Preparation** | `/speckit-prepare`                                  | _"Are we ready?"_     | **The Macro-Workflow**. Runs Skills 02–06 (Specify $\to$ Clarify $\to$ Plan $\to$ Tasks $\to$ Analyze) in one sequence to go from "Idea" to "Ready to Code". |
-| **2. Migration**   | `/util-speckit-migrate`                             | _"Can we import?"_    | **Onboarding**. Reverse-engineers existing code into `spec.md`, `plan.md`, and `tasks.md`.                                                                   |
-| **3. Red Team**    | `/util-speckit-quizme`                              | _"What did we miss?"_ | **Hardening**. Socratic questioning to find logical gaps in your specification before you plan.                                                              |
-| **4. Export**      | `/util-speckit-taskstoissues`                       | _"Who does what?"_    | **Handoff**. Converts your `tasks.md` into GitHub or Gitea issues with labels and milestones.                                                                |
-| **5. Status**      | `/util-speckit-status`                              | _"Are we there yet?"_ | **Tracking**. Scans all artifacts to report feature completion percentage.                                                                                   |
-| **6. Utilities**   | `/util-speckit-diff` <br> `/util-speckit-checklist` | _"What changed?"_     | **Support**. View artifact diffs or generate quick acceptance checklists.                                                                                    |
-
-### 🔄 The Design Sequence
-
-**Stage 1: Inception**
-
- _Legacy Project?_ $\to$ Run **`/util-speckit-migrate`**.
- _New Feature?_ $\to$ Run **`/speckit-prepare`**.
-
-**Stage 2: Hardening**
-
- Run **`/util-speckit-quizme`** to catch edge cases.
- Run **`/speckit-prepare`** again to regenerate the Plan based on restricted specs.
-
-**Stage 3: Handoff**
-
- Run **`/util-speckit-taskstoissues`** to sync with your board.
-
---
-
-## 🚀 Getting Started in Antigravity
-
-Once the `.agents` folder is present, you can talk to your agent as a partner. You can trigger a full process using a slash command or reference a specific capability using a skill mention.
-
-**Example Conversation:**
-
-> **Developer**: "**/02-speckit-specify** Add a real-time notification system using WebSockets."
->
-> **Antigravity**: "Understood. Executing the **@speckit-specify** skill. Creating feature branch `005-notifications` and drafting the initial specification..."
-> _(Antigravity creates branch, drafts spec.md)_
->
-> **Antigravity**: "Specification ready. I've identified some ambiguity in the reconnection strategy. Should I use **@speckit-clarify** to resolve this?"
->
-> **Developer**: "Yes, use **@speckit-clarify**."
-> _(Antigravity executes the skill logic, interviewing the developer and updating the spec)_
->
-> **Antigravity**: "The spec is now robust. I'm ready to trigger **/04-speckit-plan** and **/05-speckit-tasks** to prepare for implementation."
-
---
-
-## 🏆 Best Practices for Antigravity
-
-To get the most out of this system, follow these **Spec-Driven Development (SDD)** rules:
-
-### 1. The Constitution is King 👑
-
-**Never skip `/01-speckit-constitution`.**
-
- This file is the "Context Window Anchor" for the AI.
- It prevents hallucinations about tech stack (e.g., "Don't use jQuery" or "Always use TypeScript strict mode").
- **Tip:** If Antigravity makes a style mistake, don't just fix the code—update the Constitution so it never happens again.
-
-### 2. The Layered Defense 🛡️
-
-Don't rush to code. The workflow exists to catch errors _cheaply_ before they become expensive bugs.
-
- **Ambiguity Layer**: `/03-speckit-clarify` catches misunderstandings.
- **Logic Layer**: `/util-speckit-quizme` catches edge cases.
- **Consistency Layer**: `/06-speckit-analyze` catches gaps between Spec and Plan.
-
-### 3. The 15-Minute Rule ⏱️
-
-When generating `tasks.md` (Skill 05), ensure tasks are **atomic**.
-
- **Bad Task**: "Implement User Auth" (Too big, AI will get lost).
- **Good Task**: "Create `User` Mongoose schema with email validation" (Perfect).
- **Rule of Thumb**: If a task takes Antigravity more than 3 tool calls to finish, it's too big. Break it down.
-
-### 4. "Refine, Don't Rewind" ⏩
-
-If you change your mind mid-project:
-
-1.  Don't just edit the code.
-2.  Edit the `spec.md` to reflect the new requirement.
-3.  Run `/util-speckit-diff` to see the drift.
-4.  This keeps your documentation alive and truthful.
-
---
-
-## 🧩 Adaptation Notes
-
- **Skill-Based Autonomy**: Mentions like `@speckit-plan` trigger the agent's internalized understanding of how to perform that role.
- **Shared Script Core**: Logic resides in `.agents/scripts/bash` (modular) with PowerShell equivalents in `scripts/powershell/` for Windows-native execution.
- **Agent-Native**: Designed to be invoked via Antigravity tool calls and reasoning rather than just terminal strings.
- **LCBP3-DMS Specific**: Includes project-specific skills (`nestjs-best-practices`, `next-best-practices`, `speckit-security-audit`) and workflows (`/schema-change`, `/create-backend-module`, `/deploy`).
-
---
-
-## 🏗️ LCBP3-DMS Project Notes (v1.8.6)
-
-### 📊 Current Status: Production Ready (2026-04-14)
-
-| Area          | Status                          |
-| ------------- | ------------------------------- |
-| Backend       | ✅ 18 Modules, Production Ready |
-| Frontend      | ✅ 100% Complete                |
-| Database      | ✅ Schema v1.8.6 Stable         |
-| Documentation | ✅ **10/10 Gaps Closed**        |
-| AI Migration  | ✅ Ollama Integration Complete  |
-| UAT           | ✅ Completed Successfully       |
-| Deployment    | ✅ Production Deployed          |
-
-### 📁 Key Spec Files (Always Check Before Writing Code)
-
-| เอกสาร          | Path                                                             | ใช้เมื่อ            |
-| --------------- | ---------------------------------------------------------------- | ------------------- |
-| Schema Tables   | `specs/03-Data-and-Storage/lcbp3-v1.8.0-schema-02-tables.sql`    | ก่อนเขียน Query     |
-| Data Dictionary | `specs/03-Data-and-Storage/03-01-data-dictionary.md`             | ตรวจ Business Rules |
-| Edge Cases      | `specs/01-Requirements/01-06-edge-cases-and-rules.md`            | 37 Rules            |
-| Migration Scope | `specs/03-Data-and-Storage/03-06-migration-business-scope.md`    | Migration Bot       |
-| Release Policy  | `specs/04-Infrastructure-OPS/04-08-release-management-policy.md` | ก่อน Deploy         |
-| UAT Criteria    | `specs/01-Requirements/01-05-acceptance-criteria.md`             | ตรวจ Feature        |
-
-### ⚡ Project-Specific Workflow Cheatsheet
-
-| Task                  | Workflow / Command        | Notes                             |
-| --------------------- | ------------------------- | --------------------------------- |
-| Create Backend Module | `/create-backend-module`  | Scaffolds NestJS module           |
-| Create Frontend Page  | `/create-frontend-page`   | Next.js App Router page           |
-| Schema Change         | `/schema-change`          | ADR-009: No migrations            |
-| Deploy                | `/deploy`                 | Blue-Green via Gitea CI/CD        |
-| UAT Feature Check     | `/11-speckit-validate`    | vs `01-05-acceptance-criteria.md` |
-| Security Audit        | `@speckit-security-audit` | OWASP + CASL + ClamAV             |
-
-### 🚫 Critical Forbidden Actions
-
- ❌ DO NOT bypass Release Gates before deploying — `04-08-release-management-policy.md`
- ❌ DO NOT start Migration without Gate #1 approval — `03-06-migration-business-scope.md`
- ❌ DO NOT use TypeORM Migrations — modify schema SQL directly (ADR-009)
- ❌ DO NOT give Ollama direct DB access — all writes via DMS API (ADR-018)
- ❌ DO NOT use `any` TypeScript type anywhere
-
---
-
-## 🔧 Troubleshooting
-
-### Common Issues & Solutions
-
-#### **Version Inconsistency Errors**
-
-**Problem**: Scripts report version mismatches between files.
-
-**Solution**:
-
-```bash
-# Run version validation
-./scripts/bash/validate-versions.sh
-
-# Fix by updating all files to v1.8.6
-# Then re-run validation to confirm
-```
-
-**Files to check**:
-
- `.agents/README.md`
- `.agents/skills/VERSION`
- `.agents/rules/00-project-context.md`
- `.agents/skills/skills.md`
-
-#### **Missing Workflow Files**
-
-**Problem**: Workflows not found in `.windsurf/workflows/`.
-
-**Solution**:
-
-```bash
-# Sync workflow check
-./scripts/bash/sync-workflows.sh
-
-# Verify all 23 expected workflows are present
-# Create missing ones from templates if needed
-```
-
-#### **Skill Health Issues**
-
-**Problem**: Skills missing SKILL.md or required sections.
-
-**Solution**:
-
-```bash
-# Run comprehensive skill audit
-./scripts/bash/audit-skills.sh
-
-# Check specific skill issues
-# Missing files will be listed with specific errors
-```
-
-**Required SKILL.md sections**:
-
- Front matter: `name`, `description`, `version`
- Content: `## Role`, `## Task`
-
-#### **Script Permission Issues**
-
-**Problem**: Bash scripts not executable.
-
-**Solution**:
-
-```bash
-# Make scripts executable
-chmod +x .agents/scripts/bash/*.sh
-
-# Verify with
-ls -la .agents/scripts/bash/
-```
-
-#### **PowerShell Execution Policy**
-
-**Problem**: PowerShell scripts blocked by execution policy.
-
-**Solution**:
-
-```powershell
-# Check current policy
-Get-ExecutionPolicy
-
-# Allow scripts for current user
-Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
-
-# Or run bypass for single script
-PowerShell -ExecutionPolicy Bypass -File .agents/scripts/powershell/audit-skills.ps1
-```
-
-### Debug Mode
-
-**Enable verbose output**:
-
-```bash
-# Run scripts with debug info
-bash -x .agents/scripts/bash/audit-skills.sh
-
-# PowerShell with verbose output
-$VerbosePreference = "Continue"
-. .agents/scripts/powershell/audit-skills.ps1
-```
-
-### Health Check Commands
-
-**Quick health assessment**:
-
-```bash
-# 1. Check versions
-./scripts/bash/validate-versions.sh
-
-# 2. Audit skills
-./scripts/bash/audit-skills.sh
-
-# 3. Sync workflows
-./scripts/bash/sync-workflows.sh
-
-# 4. Check directory structure
-find .agents -type f -name "*.md" | wc -l
-find .windsurf/workflows -name "*.md" | wc -l
-```
-
-**PowerShell equivalent**:
-
-```powershell
-# 1. Check versions
-. .agents/scripts/powershell/validate-versions.ps1
-
-# 2. Audit skills
-. .agents/scripts/powershell/audit-skills.ps1
-
-# 3. Count files
-(Get-ChildItem -Path .agents -Recurse -Filter "*.md").Count
-(Get-ChildItem -Path .windsurf/workflows -Filter "*.md").Count
-```
-
-### Getting Help
-
-**If issues persist**:
-
-1. Check LCBP3 project version alignment
-2. Verify `.specify/` directory structure (if using templates)
-3. Ensure all dependencies are installed (bash, powershell core)
-4. Review the specific error messages in script output
-5. Check this README for workflow path updates (`.windsurf/workflows`)
-
---
-
-_Built with logic from [Spec-Kit](https://github.com/github/spec-kit). Powered by Antigravity._
@@ -1,571 +0,0 @@
-#!/usr/bin/env node
-
-/**
- * advanced-validator.js - Advanced validation capabilities for .agents
- * Part of LCBP3-DMS Phase 3 enhancements
- */
-
-const fs = require('fs');
-const path = require('path');
-const yaml = require('js-yaml');
-
-// Configuration
-const BASE_DIR = path.resolve(__dirname, '../..');
-const AGENTS_DIR = path.join(BASE_DIR, '.agents');
-const SKILLS_DIR = path.join(AGENTS_DIR, 'skills');
-const WORKFLOWS_DIR = path.join(BASE_DIR, '.windsurf', 'workflows');
-
-// Advanced validation class
-class AdvancedValidator {
-    constructor() {
-        this.validationResults = {
-            timestamp: new Date().toISOString(),
-            validations: {},
-            summary: {
-                total_validations: 0,
-                passed_validations: 0,
-                failed_validations: 0,
-                warnings: 0,
-                critical_issues: 0
-            }
-        };
-        this.criticalIssues = [];
-    }
-
-    log(message, level = 'info') {
-        const colors = {
-            info: '\x1b[36m',    // Cyan
-            pass: '\x1b[32m',    // Green
-            fail: '\x1b[31m',    // Red
-            warn: '\x1b[33m',    // Yellow
-            critical: '\x1b[35m', // Magenta
-            reset: '\x1b[0m'
-        };
-        
-        const color = colors[level] || colors.info;
-        console.log(`${color}[${level.toUpperCase()}] ${message}${colors.reset}`);
-    }
-
-    validateSkillFrontMatter(skillPath, skillName) {
-        const skillMdPath = path.join(skillPath, 'SKILL.md');
-        
-        if (!fs.existsSync(skillMdPath)) {
-            this.addValidationResult(`skill_${skillName}_frontmatter`, 'fail', {
-                message: 'SKILL.md file not found',
-                path: skillMdPath
-            });
-            return false;
-        }
-
-        try {
-            const content = fs.readFileSync(skillMdPath, 'utf8');
-            const frontMatterMatch = content.match(/^---\n([\s\S]*?)\n---/);
-            
-            if (!frontMatterMatch) {
-                this.addValidationResult(`skill_${skillName}_frontmatter`, 'fail', {
-                    message: 'No front matter found',
-                    path: skillMdPath
-                });
-                return false;
-            }
-
-            try {
-                const frontMatter = yaml.load(frontMatterMatch[1]);
-                const requiredFields = ['name', 'description', 'version'];
-                const missingFields = requiredFields.filter(field => !frontMatter[field]);
-                
-                if (missingFields.length > 0) {
-                    this.addValidationResult(`skill_${skillName}_frontmatter`, 'fail', {
-                        message: `Missing required fields: ${missingFields.join(', ')}`,
-                        missing_fields: missingFields,
-                        front_matter: frontMatter,
-                        path: skillMdPath
-                    });
-                    return false;
-                }
-
-                // Validate version format
-                const versionPattern = /^\d+\.\d+\.\d+$/;
-                if (!versionPattern.test(frontMatter.version)) {
-                    this.addValidationResult(`skill_${skillName}_version_format`, 'warn', {
-                        message: 'Version format should be X.Y.Z',
-                        version: frontMatter.version,
-                        path: skillMdPath
-                    });
-                }
-
-                // Validate dependencies if present
-                if (frontMatter['depends-on']) {
-                    const dependencies = Array.isArray(frontMatter['depends-on']) 
-                        ? frontMatter['depends-on'] 
-                        : [frontMatter['depends-on']];
-                    
-                    for (const dep of dependencies) {
-                        const depPath = path.join(SKILLS_DIR, dep);
-                        if (!fs.existsSync(depPath)) {
-                            this.addValidationResult(`skill_${skillName}_dependency_${dep}`, 'critical', {
-                                message: `Dependency not found: ${dep}`,
-                                dependency: dep,
-                                path: skillMdPath
-                            });
-                        }
-                    }
-                }
-
-                this.addValidationResult(`skill_${skillName}_frontmatter`, 'pass', {
-                    message: 'Front matter is valid',
-                    front_matter: frontMatter,
-                    path: skillMdPath
-                });
-                return true;
-
-            } catch (yamlError) {
-                this.addValidationResult(`skill_${skillName}_frontmatter`, 'fail', {
-                    message: `Invalid YAML in front matter: ${yamlError.message}`,
-                    path: skillMdPath
-                });
-                return false;
-            }
-
-        } catch (error) {
-            this.addValidationResult(`skill_${skillName}_frontmatter`, 'fail', {
-                message: `Error reading SKILL.md: ${error.message}`,
-                path: skillMdPath
-            });
-            return false;
-        }
-    }
-
-    validateSkillContent(skillPath, skillName) {
-        const skillMdPath = path.join(skillPath, 'SKILL.md');
-        
-        if (!fs.existsSync(skillMdPath)) {
-            return false;
-        }
-
-        try {
-            const content = fs.readFileSync(skillMdPath, 'utf8');
-            
-            // Check for required sections
-            const requiredSections = ['## Role', '## Task'];
-            const missingSections = requiredSections.filter(section => !content.includes(section));
-            
-            if (missingSections.length > 0) {
-                this.addValidationResult(`skill_${skillName}_content`, 'fail', {
-                    message: `Missing required sections: ${missingSections.join(', ')}`,
-                    missing_sections: missingSections,
-                    path: skillMdPath
-                });
-                return false;
-            }
-
-            // Check for forbidden patterns
-            const forbiddenPatterns = [
-                { pattern: /TODO.*FIX/gi, message: 'TODO items should be resolved' },
-                { pattern: /FIXME/gi, message: 'FIXME items should be addressed' },
-                { pattern: /XXX/gi, message: 'XXX markers should be replaced' }
-            ];
-
-            for (const { pattern, message } of forbiddenPatterns) {
-                if (pattern.test(content)) {
-                    this.addValidationResult(`skill_${skillName}_forbidden_patterns`, 'warn', {
-                        message: `${message} found in content`,
-                        pattern: pattern.toString(),
-                        path: skillMdPath
-                    });
-                }
-            }
-
-            // Validate content length
-            const contentLength = content.length;
-            if (contentLength < 500) {
-                this.addValidationResult(`skill_${skillName}_content_length`, 'warn', {
-                    message: 'Skill content seems too short',
-                    length: contentLength,
-                    path: skillMdPath
-                });
-            }
-
-            this.addValidationResult(`skill_${skillName}_content`, 'pass', {
-                message: 'Skill content is valid',
-                length: contentLength,
-                path: skillMdPath
-            });
-            return true;
-
-        } catch (error) {
-            this.addValidationResult(`skill_${skillName}_content`, 'fail', {
-                message: `Error validating content: ${error.message}`,
-                path: skillMdPath
-            });
-            return false;
-        }
-    }
-
-    validateWorkflowStructure(workflowPath, workflowName) {
-        if (!fs.existsSync(workflowPath)) {
-            this.addValidationResult(`workflow_${workflowName}_exists`, 'fail', {
-                message: 'Workflow file not found',
-                path: workflowPath
-            });
-            return false;
-        }
-
-        try {
-            const content = fs.readFileSync(workflowPath, 'utf8');
-            
-            // Check for markdown headers
-            if (!content.includes('#')) {
-                this.addValidationResult(`workflow_${workflowName}_structure`, 'fail', {
-                    message: 'No markdown headers found',
-                    path: workflowPath
-                });
-                return false;
-            }
-
-            // Check for workflow-specific patterns
-            const hasWorkflowContent = content.length > 200;
-            if (!hasWorkflowContent) {
-                this.addValidationResult(`workflow_${workflowName}_content`, 'warn', {
-                    message: 'Workflow content seems too short',
-                    length: content.length,
-                    path: workflowPath
-                });
-            }
-
-            // Validate skill references
-            const skillReferences = content.match(/@speckit-\w+/g) || [];
-            for (const skillRef of skillReferences) {
-                const skillName = skillRef.replace('@', '');
-                const skillPath = path.join(SKILLS_DIR, skillName);
-                
-                if (!fs.existsSync(skillPath)) {
-                    this.addValidationResult(`workflow_${workflowName}_skill_ref_${skillName}`, 'critical', {
-                        message: `Workflow references non-existent skill: ${skillRef}`,
-                        skill_reference: skillRef,
-                        path: workflowPath
-                    });
-                }
-            }
-
-            this.addValidationResult(`workflow_${workflowName}_structure`, 'pass', {
-                message: 'Workflow structure is valid',
-                skill_references: skillReferences,
-                path: workflowPath
-            });
-            return true;
-
-        } catch (error) {
-            this.addValidationResult(`workflow_${workflowName}_structure`, 'fail', {
-                message: `Error validating workflow: ${error.message}`,
-                path: workflowPath
-            });
-            return false;
-        }
-    }
-
-    validateCrossReferences() {
-        this.log('Validating cross-references...', 'info');
-
-        // Check README.md references
-        const readmePath = path.join(AGENTS_DIR, 'README.md');
-        if (fs.existsSync(readmePath)) {
-            const readmeContent = fs.readFileSync(readmePath, 'utf8');
-            
-            // Check if README references correct workflow path
-            if (readmeContent.includes('.agents/workflows') && !readmeContent.includes('.windsurf/workflows')) {
-                this.addValidationResult('readme_workflow_reference', 'critical', {
-                    message: 'README.md references .agents/workflows instead of .windsurf/workflows',
-                    path: readmePath
-                });
-            }
-
-            // Check version consistency in README
-            const versionMatches = readmeContent.match(/v?(\d+\.\d+\.\d+)/g) || [];
-            const uniqueVersions = [...new Set(versionMatches)];
-            
-            if (uniqueVersions.length > 1) {
-                this.addValidationResult('readme_version_consistency', 'warn', {
-                    message: 'Multiple versions found in README.md',
-                    versions: uniqueVersions,
-                    path: readmePath
-                });
-            }
-        }
-
-        // Check skills.md references
-        const skillsMdPath = path.join(SKILLS_DIR, 'skills.md');
-        if (fs.existsSync(skillsMdPath)) {
-            const skillsContent = fs.readFileSync(skillsMdPath, 'utf8');
-            
-            // Validate skill dependency matrix
-            if (skillsContent.includes('## Skill Dependency Matrix')) {
-                this.addValidationResult('skills_dependency_matrix', 'pass', {
-                    message: 'Skills documentation includes dependency matrix',
-                    path: skillsMdPath
-                });
-            } else {
-                this.addValidationResult('skills_dependency_matrix', 'warn', {
-                    message: 'Skills documentation missing dependency matrix',
-                    path: skillsMdPath
-                });
-            }
-        }
-    }
-
-    validateSecurityCompliance() {
-        this.log('Validating security compliance...', 'info');
-
-        // Check for security patterns in rules
-        const securityRulePath = path.join(AGENTS_DIR, 'rules', '02-security.md');
-        if (fs.existsSync(securityRulePath)) {
-            const securityContent = fs.readFileSync(securityRulePath, 'utf8');
-            
-            const requiredSecurityTopics = [
-                'authentication',
-                'authorization',
-                'rbac',
-                'validation',
-                'audit'
-            ];
-
-            const missingTopics = requiredSecurityTopics.filter(topic => 
-                !securityContent.toLowerCase().includes(topic.toLowerCase())
-            );
-
-            if (missingTopics.length > 0) {
-                this.addValidationResult('security_rules_completeness', 'warn', {
-                    message: `Security rules missing topics: ${missingTopics.join(', ')}`,
-                    missing_topics: missingTopics,
-                    path: securityRulePath
-                });
-            } else {
-                this.addValidationResult('security_rules_completeness', 'pass', {
-                    message: 'Security rules cover all required topics',
-                    path: securityRulePath
-                });
-            }
-        }
-
-        // Check for ADR-019 compliance in rules
-        const uuidRulePath = path.join(AGENTS_DIR, 'rules', '01-adr-019-uuid.md');
-        if (fs.existsSync(uuidRulePath)) {
-            const uuidContent = fs.readFileSync(uuidRulePath, 'utf8');
-            
-            const criticalUuidRules = [
-                'parseInt',
-                'Number(',
-                'publicId',
-                '@Exclude()'
-            ];
-
-            const missingRules = criticalUuidRules.filter(rule => 
-                !uuidContent.includes(rule)
-            );
-
-            if (missingRules.length > 0) {
-                this.addValidationResult('uuid_rules_completeness', 'critical', {
-                    message: `UUID rules missing critical patterns: ${missingRules.join(', ')}`,
-                    missing_patterns: missingRules,
-                    path: uuidRulePath
-                });
-            } else {
-                this.addValidationResult('uuid_rules_completeness', 'pass', {
-                    message: 'UUID rules cover all critical patterns',
-                    path: uuidRulePath
-                });
-            }
-        }
-    }
-
-    validatePerformanceMetrics() {
-        this.log('Validating performance metrics...', 'info');
-
-        // Check file sizes
-        const criticalFiles = [
-            { path: path.join(AGENTS_DIR, 'README.md'), name: 'README.md' },
-            { path: path.join(SKILLS_DIR, 'skills.md'), name: 'skills.md' },
-            { path: path.join(AGENTS_DIR, 'skills', 'VERSION'), name: 'VERSION' }
-        ];
-
-        for (const file of criticalFiles) {
-            if (fs.existsSync(file.path)) {
-                const stats = fs.statSync(file.path);
-                const sizeKB = stats.size / 1024;
-                
-                if (sizeKB > 100) {
-                    this.addValidationResult(`file_size_${file.name}`, 'warn', {
-                        message: `File ${file.name} is large (${sizeKB.toFixed(1)}KB)`,
-                        size_kb: sizeKB,
-                        path: file.path
-                    });
-                } else {
-                    this.addValidationResult(`file_size_${file.name}`, 'pass', {
-                        message: `File ${file.name} size is acceptable`,
-                        size_kb: sizeKB,
-                        path: file.path
-                    });
-                }
-            }
-        }
-
-        // Check directory structure depth
-        function getDirectoryDepth(dirPath, currentDepth = 0) {
-            let maxDepth = currentDepth;
-            
-            if (fs.existsSync(dirPath)) {
-                const items = fs.readdirSync(dirPath);
-                for (const item of items) {
-                    const itemPath = path.join(dirPath, item);
-                    if (fs.statSync(itemPath).isDirectory()) {
-                        const depth = getDirectoryDepth(itemPath, currentDepth + 1);
-                        maxDepth = Math.max(maxDepth, depth);
-                    }
-                }
-            }
-            
-            return maxDepth;
-        }
-
-        const agentsDepth = getDirectoryDepth(AGENTS_DIR);
-        if (agentsDepth > 5) {
-            this.addValidationResult('directory_depth', 'warn', {
-                message: `.agents directory structure is deep (${agentsDepth} levels)`,
-                depth: agentsDepth,
-                path: AGENTS_DIR
-            });
-        } else {
-            this.addValidationResult('directory_depth', 'pass', {
-                message: `.agents directory structure depth is acceptable`,
-                depth: agentsDepth,
-                path: AGENTS_DIR
-            });
-        }
-    }
-
-    addValidationResult(name, status, details) {
-        this.validationResults.validations[name] = {
-            status,
-            timestamp: new Date().toISOString(),
-            ...details
-        };
-
-        this.validationResults.summary.total_validations++;
-
-        switch (status) {
-            case 'pass':
-                this.validationResults.summary.passed_validations++;
-                this.log(`${name}: PASS - ${details.message}`, 'pass');
-                break;
-            case 'fail':
-                this.validationResults.summary.failed_validations++;
-                this.log(`${name}: FAIL - ${details.message}`, 'fail');
-                break;
-            case 'warn':
-                this.validationResults.summary.warnings++;
-                this.log(`${name}: WARN - ${details.message}`, 'warn');
-                break;
-            case 'critical':
-                this.validationResults.summary.critical_issues++;
-                this.criticalIssues.push({ name, ...details });
-                this.log(`${name}: CRITICAL - ${details.message}`, 'critical');
-                break;
-        }
-    }
-
-    async runAdvancedValidation() {
-        this.log('Starting advanced validation...', 'info');
-        this.log(`Base directory: ${BASE_DIR}`, 'info');
-
-        // Validate all skills
-        this.log('Validating skills...', 'info');
-        if (fs.existsSync(SKILLS_DIR)) {
-            const skillDirs = fs.readdirSync(SKILLS_DIR).filter(item => {
-                const itemPath = path.join(SKILLS_DIR, item);
-                return fs.statSync(itemPath).isDirectory();
-            });
-
-            for (const skillDir of skillDirs) {
-                const skillPath = path.join(SKILLS_DIR, skillDir);
-                this.validateSkillFrontMatter(skillPath, skillDir);
-                this.validateSkillContent(skillPath, skillDir);
-            }
-        }
-
-        // Validate all workflows
-        this.log('Validating workflows...', 'info');
-        if (fs.existsSync(WORKFLOWS_DIR)) {
-            const workflowFiles = fs.readdirSync(WORKFLOWS_DIR).filter(file => file.endsWith('.md'));
-            
-            for (const workflowFile of workflowFiles) {
-                const workflowPath = path.join(WORKFLOWS_DIR, workflowFile);
-                const workflowName = workflowFile.replace('.md', '');
-                this.validateWorkflowStructure(workflowPath, workflowName);
-            }
-        }
-
-        // Cross-reference validation
-        this.validateCrossReferences();
-
-        // Security compliance validation
-        this.validateSecurityCompliance();
-
-        // Performance metrics validation
-        this.validatePerformanceMetrics();
-
-        // Generate summary
-        this.generateSummary();
-
-        return this.validationResults;
-    }
-
-    generateSummary() {
-        const { summary, critical_issues } = this.validationResults;
-        
-        this.log('=== Advanced Validation Summary ===', 'info');
-        this.log(`Total validations: ${summary.total_validations}`, 'info');
-        this.log(`Passed: ${summary.passed_validations}`, 'pass');
-        this.log(`Failed: ${summary.failed_validations}`, summary.failed_validations > 0 ? 'fail' : 'info');
-        this.log(`Warnings: ${summary.warnings}`, 'warn');
-        this.log(`Critical issues: ${summary.critical_issues}`, 'critical');
-
-        if (critical_issues.length > 0) {
-            this.log('Critical Issues:', 'critical');
-            critical_issues.forEach(issue => {
-                this.log(`  - ${issue.name}: ${issue.message}`, 'critical');
-            });
-        }
-
-        // Save validation results
-        const validationReportPath = path.join(AGENTS_DIR, 'reports', 'advanced-validation.json');
-        const reportsDir = path.dirname(validationReportPath);
-        
-        if (!fs.existsSync(reportsDir)) {
-            fs.mkdirSync(reportsDir, { recursive: true });
-        }
-
-        fs.writeFileSync(validationReportPath, JSON.stringify(this.validationResults, null, 2));
-        this.log(`Advanced validation report saved to: ${validationReportPath}`, 'info');
-    }
-}
-
-// CLI interface
-async function main() {
-    const validator = new AdvancedValidator();
-    
-    try {
-        const results = await validator.runAdvancedValidation();
-        process.exit(results.summary.critical_issues > 0 ? 1 : 0);
-    } catch (error) {
-        console.error('Advanced validation failed:', error);
-        process.exit(1);
-    }
-}
-
-// Export for use in other modules
-module.exports = { AdvancedValidator };
-
-// Run if called directly
-if (require.main === module) {
-    main();
-}
@@ -1,95 +0,0 @@
-#!/usr/bin/env bash
-# Agent registry — maps agent types to file paths and display names
-# Extracted from update-agent-context.sh for modularity
-#
-# Usage:
-#   source agent-registry.sh
-#   init_agent_registry "$REPO_ROOT"
-#   get_agent_file "claude"    # → /path/to/CLAUDE.md
-#   get_agent_name "claude"    # → "Claude Code"
-
-# Initialize agent file paths (call after REPO_ROOT is set)
-init_agent_registry() {
-    local repo_root="$1"
-
-    # Agent type → file path mapping
-    declare -gA AGENT_FILES=(
-        [claude]="$repo_root/CLAUDE.md"
-        [gemini]="$repo_root/GEMINI.md"
-        [copilot]="$repo_root/.github/agents/copilot-instructions.md"
-        [cursor-agent]="$repo_root/.cursor/rules/specify-rules.mdc"
-        [qwen]="$repo_root/QWEN.md"
-        [opencode]="$repo_root/AGENTS.md"
-        [codex]="$repo_root/AGENTS.md"
-        [windsurf]="$repo_root/.windsurf/rules/specify-rules.md"
-        [kilocode]="$repo_root/.kilocode/rules/specify-rules.md"
-        [auggie]="$repo_root/.augment/rules/specify-rules.md"
-        [roo]="$repo_root/.roo/rules/specify-rules.md"
-        [codebuddy]="$repo_root/CODEBUDDY.md"
-        [qoder]="$repo_root/QODER.md"
-        [amp]="$repo_root/AGENTS.md"
-        [shai]="$repo_root/SHAI.md"
-        [q]="$repo_root/AGENTS.md"
-        [bob]="$repo_root/AGENTS.md"
-    )
-
-    # Agent type → display name mapping
-    declare -gA AGENT_NAMES=(
-        [claude]="Claude Code"
-        [gemini]="Gemini CLI"
-        [copilot]="GitHub Copilot"
-        [cursor-agent]="Cursor IDE"
-        [qwen]="Qwen Code"
-        [opencode]="opencode"
-        [codex]="Codex CLI"
-        [windsurf]="Windsurf"
-        [kilocode]="Kilo Code"
-        [auggie]="Auggie CLI"
-        [roo]="Roo Code"
-        [codebuddy]="CodeBuddy CLI"
-        [qoder]="Qoder CLI"
-        [amp]="Amp"
-        [shai]="SHAI"
-        [q]="Amazon Q Developer CLI"
-        [bob]="IBM Bob"
-    )
-
-    # Template file path
-    TEMPLATE_FILE="$repo_root/.specify/templates/agent-file-template.md"
-}
-
-# Get file path for an agent type
-get_agent_file() {
-    local agent_type="$1"
-    echo "${AGENT_FILES[$agent_type]:-}"
-}
-
-# Get display name for an agent type
-get_agent_name() {
-    local agent_type="$1"
-    echo "${AGENT_NAMES[$agent_type]:-}"
-}
-
-# Get all registered agent types
-get_all_agent_types() {
-    echo "${!AGENT_FILES[@]}"
-}
-
-# Check if an agent type is valid
-is_valid_agent() {
-    local agent_type="$1"
-    [[ -n "${AGENT_FILES[$agent_type]:-}" ]]
-}
-
-# Get supported agent types as a pipe-separated string (for error messages)
-get_supported_agents_string() {
-    local result=""
-    for key in "${!AGENT_FILES[@]}"; do
-        if [[ -n "$result" ]]; then
-            result="$result|$key"
-        else
-            result="$key"
-        fi
-    done
-    echo "$result"
-}
@@ -1,195 +0,0 @@
-#!/bin/bash
-
-# audit-skills.sh - Verify skill completeness and health
-# Part of LCBP3-DMS Phase 2 improvements
-
-set -uo pipefail
-# Note: no -e — we let per-skill checks accumulate issues without terminating
-
-# Colors for output
-RED='\033[0;31m'
-GREEN='\033[0;32m'
-YELLOW='\033[1;33m'
-BLUE='\033[0;34m'
-NC='\033[0m' # No Color
-
-# Base directory
-BASE_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/../../.." && pwd)"
-AGENTS_DIR="$BASE_DIR/.agents"
-SKILLS_DIR="$AGENTS_DIR/skills"
-
-echo "=== Skills Health Audit ==="
-echo "Base directory: $BASE_DIR"
-echo
-
-# Function to check if skill has required files
-check_skill_health() {
-    local skill_dir="$1"
-    local skill_name="$(basename "$skill_dir")"
-
-    local issues=0
-
-    # Check for SKILL.md
-    if [[ -f "$skill_dir/SKILL.md" ]]; then
-        echo -e "${GREEN}  OK${NC}: $skill_name/SKILL.md"
-    else
-        echo -e "${RED}  MISSING${NC}: $skill_name/SKILL.md"
-        ((issues++))
-    fi
-
-    # Check for templates directory (optional)
-    if [[ -d "$skill_dir/templates" ]]; then
-        template_count=$(find "$skill_dir/templates" -name "*.md" -type f | wc -l)
-        if [[ $template_count -gt 0 ]]; then
-            echo -e "${GREEN}  OK${NC}: $skill_name/templates ($template_count files)"
-        else
-            echo -e "${YELLOW}  EMPTY${NC}: $skill_name/templates (no files)"
-        fi
-    fi
-
-    # Check SKILL.md content if exists
-    local skill_file="$skill_dir/SKILL.md"
-    if [[ -f "$skill_file" ]]; then
-        # Check for required front matter fields
-        local required_fields=("name" "description" "version")
-        for field in "${required_fields[@]}"; do
-            if grep -q "^$field:" "$skill_file"; then
-                echo -e "    ${GREEN}  FIELD${NC}: $field"
-            else
-                echo -e "    ${RED}  MISSING FIELD${NC}: $field"
-                ((issues++)) || true
-            fi
-        done
-
-        # Check for LCBP3 context reference (speckit-* skills only)
-        if [[ "$skill_name" == speckit-* ]]; then
-            if grep -q '_LCBP3-CONTEXT\.md' "$skill_file"; then
-                echo -e "    ${GREEN}  CONTEXT${NC}: LCBP3 appendix referenced"
-            else
-                echo -e "    ${YELLOW}  MISSING${NC}: LCBP3 context reference"
-                ((issues++)) || true
-            fi
-        fi
-    fi
-
-    return $issues
-}
-
-# Function to get skill version from SKILL.md
-get_skill_version() {
-    local skill_file="$1"
-    if [[ -f "$skill_file" ]]; then
-        # Match 'version: X.Y.Z' (or quoted) at a LINE START only; ignore nested `  version:` fields.
-        # Output: bare X.Y.Z with no quotes/whitespace.
-        local raw
-        raw=$(grep -E "^version:[[:space:]]*['\"]?[0-9]+\.[0-9]+\.[0-9]+" "$skill_file" | head -1 || true)
-        if [[ -n "$raw" ]]; then
-            printf '%s' "$raw" | sed -E "s/^version:[[:space:]]*['\"]?([0-9]+\.[0-9]+\.[0-9]+).*/\1/"
-        else
-            echo "unknown"
-        fi
-    else
-        echo "no_file"
-    fi
-}
-
-# Check skills directory
-if [[ ! -d "$SKILLS_DIR" ]]; then
-    echo -e "${RED}ERROR: Skills directory not found${NC}"
-    exit 1
-fi
-
-echo "Scanning skills directory: $SKILLS_DIR"
-echo
-
-# Get all skill directories
-SKILL_DIRS=()
-while IFS= read -r -d '' dir; do
-    SKILL_DIRS+=("$dir")
-done < <(find "$SKILLS_DIR" -maxdepth 1 -type d -not -path "$SKILLS_DIR" -print0 | sort -z)
-
-echo "Found ${#SKILL_DIRS[@]} skill directories"
-echo
-
-# Audit each skill
-TOTAL_ISSUES=0
-SKILL_SUMMARY=()
-
-for skill_dir in "${SKILL_DIRS[@]}"; do
-    skill_name="$(basename "$skill_dir")"
-    # Skip non-skill entries (e.g. _LCBP3-CONTEXT.md would not match here; safe)
-    [[ "$skill_name" == _* ]] && continue
-    echo "Auditing: $skill_name"
-    echo "------------------------"
-
-    set +e
-    check_skill_health "$skill_dir"
-    issues=$?
-    set -u
-
-    skill_version=$(get_skill_version "$skill_dir/SKILL.md")
-    SKILL_SUMMARY+=("$skill_name:$issues:$skill_version")
-
-    TOTAL_ISSUES=$((TOTAL_ISSUES + issues))
-    echo
-done
-
-# Summary report
-echo "=== Skills Audit Summary ==="
-echo
-
-echo "Skill Status:"
-echo "-----------"
-for summary in "${SKILL_SUMMARY[@]}"; do
-    IFS=':' read -r name issues version <<< "$summary"
-    if [[ $issues -eq 0 ]]; then
-        echo -e "${GREEN}  HEALTHY${NC}: $name (v$version)"
-    else
-        echo -e "${RED}  ISSUES${NC}: $name (v$version) - $issues issues"
-    fi
-done
-
-echo
-
-# Check skills.md version consistency
-SKILLS_VERSION_FILE="$SKILLS_DIR/VERSION"
-if [[ -f "$SKILLS_VERSION_FILE" ]]; then
-    global_version=$(grep "^version:" "$SKILLS_VERSION_FILE" | sed 's/version: *//' | tr -d '\r\n ')
-    echo "Global skills version: v$global_version"
-    echo
-
-    # Check for version mismatches
-    echo "Version Consistency Check:"
-    echo "------------------------"
-    VERSION_MISMATCHES=0
-
-    for summary in "${SKILL_SUMMARY[@]}"; do
-        IFS=':' read -r name issues version <<< "$summary"
-        if [[ "$version" != "unknown" && "$version" != "no_file" && "$version" != "$global_version" ]]; then
-            echo -e "${YELLOW}  MISMATCH${NC}: $name is v$version, global is v$global_version"
-            ((VERSION_MISMATCHES++))
-        fi
-    done
-
-    if [[ $VERSION_MISMATCHES -eq 0 ]]; then
-        echo -e "${GREEN}  All skills match global version${NC}"
-    fi
-fi
-
-echo
-
-# Overall health
-if [[ $TOTAL_ISSUES -eq 0 ]]; then
-    echo -e "${GREEN}=== SUCCESS: All skills healthy ===${NC}"
-    echo "Total skills: ${#SKILL_DIRS[@]}"
-    exit 0
-else
-    echo -e "${RED}=== ISSUES FOUND: $TOTAL_ISSUES total issues ===${NC}"
-    echo
-    echo "Recommendations:"
-    echo "1. Fix missing SKILL.md files"
-    echo "2. Add required front matter fields"
-    echo "3. Ensure Role and Task sections exist"
-    echo "4. Align skill versions with global version"
-    exit 1
-fi
@@ -1,166 +0,0 @@
-#!/usr/bin/env bash
-
-# Consolidated prerequisite checking script
-#
-# This script provides unified prerequisite checking for Spec-Driven Development workflow.
-# It replaces the functionality previously spread across multiple scripts.
-#
-# Usage: ./check-prerequisites.sh [OPTIONS]
-#
-# OPTIONS:
-#   --json              Output in JSON format
-#   --require-tasks     Require tasks.md to exist (for implementation phase)
-#   --include-tasks     Include tasks.md in AVAILABLE_DOCS list
-#   --paths-only        Only output path variables (no validation)
-#   --help, -h          Show help message
-#
-# OUTPUTS:
-#   JSON mode: {"FEATURE_DIR":"...", "AVAILABLE_DOCS":["..."]}
-#   Text mode: FEATURE_DIR:... \n AVAILABLE_DOCS: \n ✓/✗ file.md
-#   Paths only: REPO_ROOT: ... \n BRANCH: ... \n FEATURE_DIR: ... etc.
-
-set -e
-
-# Parse command line arguments
-JSON_MODE=false
-REQUIRE_TASKS=false
-INCLUDE_TASKS=false
-PATHS_ONLY=false
-
-for arg in "$@"; do
-    case "$arg" in
-        --json)
-            JSON_MODE=true
-            ;;
-        --require-tasks)
-            REQUIRE_TASKS=true
-            ;;
-        --include-tasks)
-            INCLUDE_TASKS=true
-            ;;
-        --paths-only)
-            PATHS_ONLY=true
-            ;;
-        --help|-h)
-            cat << 'EOF'
-Usage: check-prerequisites.sh [OPTIONS]
-
-Consolidated prerequisite checking for Spec-Driven Development workflow.
-
-OPTIONS:
-  --json              Output in JSON format
-  --require-tasks     Require tasks.md to exist (for implementation phase)
-  --include-tasks     Include tasks.md in AVAILABLE_DOCS list
-  --paths-only        Only output path variables (no prerequisite validation)
-  --help, -h          Show this help message
-
-EXAMPLES:
-  # Check task prerequisites (plan.md required)
-  ./check-prerequisites.sh --json
-  
-  # Check implementation prerequisites (plan.md + tasks.md required)
-  ./check-prerequisites.sh --json --require-tasks --include-tasks
-  
-  # Get feature paths only (no validation)
-  ./check-prerequisites.sh --paths-only
-  
-EOF
-            exit 0
-            ;;
-        *)
-            echo "ERROR: Unknown option '$arg'. Use --help for usage information." >&2
-            exit 1
-            ;;
-    esac
-done
-
-# Source common functions
-SCRIPT_DIR="$(CDPATH="" cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-source "$SCRIPT_DIR/common.sh"
-
-# Get feature paths and validate branch
-eval $(get_feature_paths)
-check_feature_branch "$CURRENT_BRANCH" "$HAS_GIT" || exit 1
-
-# If paths-only mode, output paths and exit (support JSON + paths-only combined)
-if $PATHS_ONLY; then
-    if $JSON_MODE; then
-        # Minimal JSON paths payload (no validation performed)
-        printf '{"REPO_ROOT":"%s","BRANCH":"%s","FEATURE_DIR":"%s","FEATURE_SPEC":"%s","IMPL_PLAN":"%s","TASKS":"%s"}\n' \
-            "$REPO_ROOT" "$CURRENT_BRANCH" "$FEATURE_DIR" "$FEATURE_SPEC" "$IMPL_PLAN" "$TASKS"
-    else
-        echo "REPO_ROOT: $REPO_ROOT"
-        echo "BRANCH: $CURRENT_BRANCH"
-        echo "FEATURE_DIR: $FEATURE_DIR"
-        echo "FEATURE_SPEC: $FEATURE_SPEC"
-        echo "IMPL_PLAN: $IMPL_PLAN"
-        echo "TASKS: $TASKS"
-    fi
-    exit 0
-fi
-
-# Validate required directories and files
-if [[ ! -d "$FEATURE_DIR" ]]; then
-    echo "ERROR: Feature directory not found: $FEATURE_DIR" >&2
-    echo "Run /speckit.specify first to create the feature structure." >&2
-    exit 1
-fi
-
-if [[ ! -f "$IMPL_PLAN" ]]; then
-    echo "ERROR: plan.md not found in $FEATURE_DIR" >&2
-    echo "Run /speckit.plan first to create the implementation plan." >&2
-    exit 1
-fi
-
-# Check for tasks.md if required
-if $REQUIRE_TASKS && [[ ! -f "$TASKS" ]]; then
-    echo "ERROR: tasks.md not found in $FEATURE_DIR" >&2
-    echo "Run /speckit.tasks first to create the task list." >&2
-    exit 1
-fi
-
-# Build list of available documents
-docs=()
-
-# Always check these optional docs
-[[ -f "$RESEARCH" ]] && docs+=("research.md")
-[[ -f "$DATA_MODEL" ]] && docs+=("data-model.md")
-
-# Check contracts directory (only if it exists and has files)
-if [[ -d "$CONTRACTS_DIR" ]] && [[ -n "$(ls -A "$CONTRACTS_DIR" 2>/dev/null)" ]]; then
-    docs+=("contracts/")
-fi
-
-[[ -f "$QUICKSTART" ]] && docs+=("quickstart.md")
-
-# Include tasks.md if requested and it exists
-if $INCLUDE_TASKS && [[ -f "$TASKS" ]]; then
-    docs+=("tasks.md")
-fi
-
-# Output results
-if $JSON_MODE; then
-    # Build JSON array of documents
-    if [[ ${#docs[@]} -eq 0 ]]; then
-        json_docs="[]"
-    else
-        json_docs=$(printf '"%s",' "${docs[@]}")
-        json_docs="[${json_docs%,}]"
-    fi
-    
-    printf '{"FEATURE_DIR":"%s","AVAILABLE_DOCS":%s}\n' "$FEATURE_DIR" "$json_docs"
-else
-    # Text output
-    echo "FEATURE_DIR:$FEATURE_DIR"
-    echo "AVAILABLE_DOCS:"
-    
-    # Show status of each potential document
-    check_file "$RESEARCH" "research.md"
-    check_file "$DATA_MODEL" "data-model.md"
-    check_dir "$CONTRACTS_DIR" "contracts/"
-    check_file "$QUICKSTART" "quickstart.md"
-    
-    if $INCLUDE_TASKS; then
-        check_file "$TASKS" "tasks.md"
-    fi
-fi
@@ -1,156 +0,0 @@
-#!/usr/bin/env bash
-# Common functions and variables for all scripts
-
-# Get repository root, with fallback for non-git repositories
-get_repo_root() {
-    if git rev-parse --show-toplevel >/dev/null 2>&1; then
-        git rev-parse --show-toplevel
-    else
-        # Fall back to script location for non-git repos
-        local script_dir="$(CDPATH="" cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-        (cd "$script_dir/../../.." && pwd)
-    fi
-}
-
-# Get current branch, with fallback for non-git repositories
-get_current_branch() {
-    # First check if SPECIFY_FEATURE environment variable is set
-    if [[ -n "${SPECIFY_FEATURE:-}" ]]; then
-        echo "$SPECIFY_FEATURE"
-        return
-    fi
-
-    # Then check git if available
-    if git rev-parse --abbrev-ref HEAD >/dev/null 2>&1; then
-        git rev-parse --abbrev-ref HEAD
-        return
-    fi
-
-    # For non-git repos, try to find the latest feature directory
-    local repo_root=$(get_repo_root)
-    local specs_dir="$repo_root/specs"
-
-    if [[ -d "$specs_dir" ]]; then
-        local latest_feature=""
-        local highest=0
-
-        for dir in "$specs_dir"/*; do
-            if [[ -d "$dir" ]]; then
-                local dirname=$(basename "$dir")
-                if [[ "$dirname" =~ ^([0-9]{3})- ]]; then
-                    local number=${BASH_REMATCH[1]}
-                    number=$((10#$number))
-                    if [[ "$number" -gt "$highest" ]]; then
-                        highest=$number
-                        latest_feature=$dirname
-                    fi
-                fi
-            fi
-        done
-
-        if [[ -n "$latest_feature" ]]; then
-            echo "$latest_feature"
-            return
-        fi
-    fi
-
-    echo "main"  # Final fallback
-}
-
-# Check if we have git available
-has_git() {
-    git rev-parse --show-toplevel >/dev/null 2>&1
-}
-
-check_feature_branch() {
-    local branch="$1"
-    local has_git_repo="$2"
-
-    # For non-git repos, we can't enforce branch naming but still provide output
-    if [[ "$has_git_repo" != "true" ]]; then
-        echo "[specify] Warning: Git repository not detected; skipped branch validation" >&2
-        return 0
-    fi
-
-    if [[ ! "$branch" =~ ^[0-9]{3}- ]]; then
-        echo "ERROR: Not on a feature branch. Current branch: $branch" >&2
-        echo "Feature branches should be named like: 001-feature-name" >&2
-        return 1
-    fi
-
-    return 0
-}
-
-get_feature_dir() { echo "$1/specs/$2"; }
-
-# Find feature directory by numeric prefix instead of exact branch match
-# This allows multiple branches to work on the same spec (e.g., 004-fix-bug, 004-add-feature)
-find_feature_dir_by_prefix() {
-    local repo_root="$1"
-    local branch_name="$2"
-    local specs_dir="$repo_root/specs"
-
-    # Extract numeric prefix from branch (e.g., "004" from "004-whatever")
-    if [[ ! "$branch_name" =~ ^([0-9]{3})- ]]; then
-        # If branch doesn't have numeric prefix, fall back to exact match
-        echo "$specs_dir/$branch_name"
-        return
-    fi
-
-    local prefix="${BASH_REMATCH[1]}"
-
-    # Search for directories in specs/ that start with this prefix
-    local matches=()
-    if [[ -d "$specs_dir" ]]; then
-        for dir in "$specs_dir"/"$prefix"-*; do
-            if [[ -d "$dir" ]]; then
-                matches+=("$(basename "$dir")")
-            fi
-        done
-    fi
-
-    # Handle results
-    if [[ ${#matches[@]} -eq 0 ]]; then
-        # No match found - return the branch name path (will fail later with clear error)
-        echo "$specs_dir/$branch_name"
-    elif [[ ${#matches[@]} -eq 1 ]]; then
-        # Exactly one match - perfect!
-        echo "$specs_dir/${matches[0]}"
-    else
-        # Multiple matches - this shouldn't happen with proper naming convention
-        echo "ERROR: Multiple spec directories found with prefix '$prefix': ${matches[*]}" >&2
-        echo "Please ensure only one spec directory exists per numeric prefix." >&2
-        echo "$specs_dir/$branch_name"  # Return something to avoid breaking the script
-    fi
-}
-
-get_feature_paths() {
-    local repo_root=$(get_repo_root)
-    local current_branch=$(get_current_branch)
-    local has_git_repo="false"
-
-    if has_git; then
-        has_git_repo="true"
-    fi
-
-    # Use prefix-based lookup to support multiple branches per spec
-    local feature_dir=$(find_feature_dir_by_prefix "$repo_root" "$current_branch")
-
-    cat <<EOF
-REPO_ROOT='$repo_root'
-CURRENT_BRANCH='$current_branch'
-HAS_GIT='$has_git_repo'
-FEATURE_DIR='$feature_dir'
-FEATURE_SPEC='$feature_dir/spec.md'
-IMPL_PLAN='$feature_dir/plan.md'
-TASKS='$feature_dir/tasks.md'
-RESEARCH='$feature_dir/research.md'
-DATA_MODEL='$feature_dir/data-model.md'
-QUICKSTART='$feature_dir/quickstart.md'
-CONTRACTS_DIR='$feature_dir/contracts'
-EOF
-}
-
-check_file() { [[ -f "$1" ]] && echo "  ✓ $2" || echo "  ✗ $2"; }
-check_dir() { [[ -d "$1" && -n $(ls -A "$1" 2>/dev/null) ]] && echo "  ✓ $2" || echo "  ✗ $2"; }
-
@@ -1,40 +0,0 @@
-#!/usr/bin/env bash
-# Content generation functions for update-agent-context
-# Extracted from update-agent-context.sh for modularity
-
-# Get project directory structure based on project type
-get_project_structure() {
-    local project_type="$1"
-
-    if [[ "$project_type" == *"web"* ]]; then
-        echo "backend/\\nfrontend/\\ntests/"
-    else
-        echo "src/\\ntests/"
-    fi
-}
-
-# Get build/test commands for a given language
-get_commands_for_language() {
-    local lang="$1"
-
-    case "$lang" in
-        *"Python"*)
-            echo "cd src && pytest && ruff check ."
-            ;;
-        *"Rust"*)
-            echo "cargo test && cargo clippy"
-            ;;
-        *"JavaScript"*|*"TypeScript"*)
-            echo "npm test \\&\\& npm run lint"
-            ;;
-        *)
-            echo "# Add commands for $lang"
-            ;;
-    esac
-}
-
-# Get language-specific conventions string
-get_language_conventions() {
-    local lang="$1"
-    echo "$lang: Follow standard conventions"
-}
@@ -1,297 +0,0 @@
-#!/usr/bin/env bash
-
-set -e
-
-JSON_MODE=false
-SHORT_NAME=""
-BRANCH_NUMBER=""
-ARGS=()
-i=1
-while [ $i -le $# ]; do
-    arg="${!i}"
-    case "$arg" in
-        --json) 
-            JSON_MODE=true 
-            ;;
-        --short-name)
-            if [ $((i + 1)) -gt $# ]; then
-                echo 'Error: --short-name requires a value' >&2
-                exit 1
-            fi
-            i=$((i + 1))
-            next_arg="${!i}"
-            # Check if the next argument is another option (starts with --)
-            if [[ "$next_arg" == --* ]]; then
-                echo 'Error: --short-name requires a value' >&2
-                exit 1
-            fi
-            SHORT_NAME="$next_arg"
-            ;;
-        --number)
-            if [ $((i + 1)) -gt $# ]; then
-                echo 'Error: --number requires a value' >&2
-                exit 1
-            fi
-            i=$((i + 1))
-            next_arg="${!i}"
-            if [[ "$next_arg" == --* ]]; then
-                echo 'Error: --number requires a value' >&2
-                exit 1
-            fi
-            BRANCH_NUMBER="$next_arg"
-            ;;
-        --help|-h) 
-            echo "Usage: $0 [--json] [--short-name <name>] [--number N] <feature_description>"
-            echo ""
-            echo "Options:"
-            echo "  --json              Output in JSON format"
-            echo "  --short-name <name> Provide a custom short name (2-4 words) for the branch"
-            echo "  --number N          Specify branch number manually (overrides auto-detection)"
-            echo "  --help, -h          Show this help message"
-            echo ""
-            echo "Examples:"
-            echo "  $0 'Add user authentication system' --short-name 'user-auth'"
-            echo "  $0 'Implement OAuth2 integration for API' --number 5"
-            exit 0
-            ;;
-        *) 
-            ARGS+=("$arg") 
-            ;;
-    esac
-    i=$((i + 1))
-done
-
-FEATURE_DESCRIPTION="${ARGS[*]}"
-if [ -z "$FEATURE_DESCRIPTION" ]; then
-    echo "Usage: $0 [--json] [--short-name <name>] [--number N] <feature_description>" >&2
-    exit 1
-fi
-
-# Function to find the repository root by searching for existing project markers
-find_repo_root() {
-    local dir="$1"
-    while [ "$dir" != "/" ]; do
-        if [ -d "$dir/.git" ] || [ -d "$dir/.specify" ]; then
-            echo "$dir"
-            return 0
-        fi
-        dir="$(dirname "$dir")"
-    done
-    return 1
-}
-
-# Function to get highest number from specs directory
-get_highest_from_specs() {
-    local specs_dir="$1"
-    local highest=0
-    
-    if [ -d "$specs_dir" ]; then
-        for dir in "$specs_dir"/*; do
-            [ -d "$dir" ] || continue
-            dirname=$(basename "$dir")
-            number=$(echo "$dirname" | grep -o '^[0-9]\+' || echo "0")
-            number=$((10#$number))
-            if [ "$number" -gt "$highest" ]; then
-                highest=$number
-            fi
-        done
-    fi
-    
-    echo "$highest"
-}
-
-# Function to get highest number from git branches
-get_highest_from_branches() {
-    local highest=0
-    
-    # Get all branches (local and remote)
-    branches=$(git branch -a 2>/dev/null || echo "")
-    
-    if [ -n "$branches" ]; then
-        while IFS= read -r branch; do
-            # Clean branch name: remove leading markers and remote prefixes
-            clean_branch=$(echo "$branch" | sed 's/^[* ]*//; s|^remotes/[^/]*/||')
-            
-            # Extract feature number if branch matches pattern ###-*
-            if echo "$clean_branch" | grep -q '^[0-9]\{3\}-'; then
-                number=$(echo "$clean_branch" | grep -o '^[0-9]\{3\}' || echo "0")
-                number=$((10#$number))
-                if [ "$number" -gt "$highest" ]; then
-                    highest=$number
-                fi
-            fi
-        done <<< "$branches"
-    fi
-    
-    echo "$highest"
-}
-
-# Function to check existing branches (local and remote) and return next available number
-check_existing_branches() {
-    local specs_dir="$1"
-
-    # Fetch all remotes to get latest branch info (suppress errors if no remotes)
-    git fetch --all --prune 2>/dev/null || true
-
-    # Get highest number from ALL branches (not just matching short name)
-    local highest_branch=$(get_highest_from_branches)
-
-    # Get highest number from ALL specs (not just matching short name)
-    local highest_spec=$(get_highest_from_specs "$specs_dir")
-
-    # Take the maximum of both
-    local max_num=$highest_branch
-    if [ "$highest_spec" -gt "$max_num" ]; then
-        max_num=$highest_spec
-    fi
-
-    # Return next number
-    echo $((max_num + 1))
-}
-
-# Function to clean and format a branch name
-clean_branch_name() {
-    local name="$1"
-    echo "$name" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g' | sed 's/-\+/-/g' | sed 's/^-//' | sed 's/-$//'
-}
-
-# Resolve repository root. Prefer git information when available, but fall back
-# to searching for repository markers so the workflow still functions in repositories that
-# were initialised with --no-git.
-SCRIPT_DIR="$(CDPATH="" cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-
-if git rev-parse --show-toplevel >/dev/null 2>&1; then
-    REPO_ROOT=$(git rev-parse --show-toplevel)
-    HAS_GIT=true
-else
-    REPO_ROOT="$(find_repo_root "$SCRIPT_DIR")"
-    if [ -z "$REPO_ROOT" ]; then
-        echo "Error: Could not determine repository root. Please run this script from within the repository." >&2
-        exit 1
-    fi
-    HAS_GIT=false
-fi
-
-cd "$REPO_ROOT"
-
-SPECS_DIR="$REPO_ROOT/specs"
-mkdir -p "$SPECS_DIR"
-
-# Function to generate branch name with stop word filtering and length filtering
-generate_branch_name() {
-    local description="$1"
-    
-    # Common stop words to filter out
-    local stop_words="^(i|a|an|the|to|for|of|in|on|at|by|with|from|is|are|was|were|be|been|being|have|has|had|do|does|did|will|would|should|could|can|may|might|must|shall|this|that|these|those|my|your|our|their|want|need|add|get|set)$"
-    
-    # Convert to lowercase and split into words
-    local clean_name=$(echo "$description" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/ /g')
-    
-    # Filter words: remove stop words and words shorter than 3 chars (unless they're uppercase acronyms in original)
-    local meaningful_words=()
-    for word in $clean_name; do
-        # Skip empty words
-        [ -z "$word" ] && continue
-        
-        # Keep words that are NOT stop words AND (length >= 3 OR are potential acronyms)
-        if ! echo "$word" | grep -qiE "$stop_words"; then
-            if [ ${#word} -ge 3 ]; then
-                meaningful_words+=("$word")
-            elif echo "$description" | grep -q "\b${word^^}\b"; then
-                # Keep short words if they appear as uppercase in original (likely acronyms)
-                meaningful_words+=("$word")
-            fi
-        fi
-    done
-    
-    # If we have meaningful words, use first 3-4 of them
-    if [ ${#meaningful_words[@]} -gt 0 ]; then
-        local max_words=3
-        if [ ${#meaningful_words[@]} -eq 4 ]; then max_words=4; fi
-        
-        local result=""
-        local count=0
-        for word in "${meaningful_words[@]}"; do
-            if [ $count -ge $max_words ]; then break; fi
-            if [ -n "$result" ]; then result="$result-"; fi
-            result="$result$word"
-            count=$((count + 1))
-        done
-        echo "$result"
-    else
-        # Fallback to original logic if no meaningful words found
-        local cleaned=$(clean_branch_name "$description")
-        echo "$cleaned" | tr '-' '\n' | grep -v '^$' | head -3 | tr '\n' '-' | sed 's/-$//'
-    fi
-}
-
-# Generate branch name
-if [ -n "$SHORT_NAME" ]; then
-    # Use provided short name, just clean it up
-    BRANCH_SUFFIX=$(clean_branch_name "$SHORT_NAME")
-else
-    # Generate from description with smart filtering
-    BRANCH_SUFFIX=$(generate_branch_name "$FEATURE_DESCRIPTION")
-fi
-
-# Determine branch number
-if [ -z "$BRANCH_NUMBER" ]; then
-    if [ "$HAS_GIT" = true ]; then
-        # Check existing branches on remotes
-        BRANCH_NUMBER=$(check_existing_branches "$SPECS_DIR")
-    else
-        # Fall back to local directory check
-        HIGHEST=$(get_highest_from_specs "$SPECS_DIR")
-        BRANCH_NUMBER=$((HIGHEST + 1))
-    fi
-fi
-
-# Force base-10 interpretation to prevent octal conversion (e.g., 010 → 8 in octal, but should be 10 in decimal)
-FEATURE_NUM=$(printf "%03d" "$((10#$BRANCH_NUMBER))")
-BRANCH_NAME="${FEATURE_NUM}-${BRANCH_SUFFIX}"
-
-# GitHub enforces a 244-byte limit on branch names
-# Validate and truncate if necessary
-MAX_BRANCH_LENGTH=244
-if [ ${#BRANCH_NAME} -gt $MAX_BRANCH_LENGTH ]; then
-    # Calculate how much we need to trim from suffix
-    # Account for: feature number (3) + hyphen (1) = 4 chars
-    MAX_SUFFIX_LENGTH=$((MAX_BRANCH_LENGTH - 4))
-    
-    # Truncate suffix at word boundary if possible
-    TRUNCATED_SUFFIX=$(echo "$BRANCH_SUFFIX" | cut -c1-$MAX_SUFFIX_LENGTH)
-    # Remove trailing hyphen if truncation created one
-    TRUNCATED_SUFFIX=$(echo "$TRUNCATED_SUFFIX" | sed 's/-$//')
-    
-    ORIGINAL_BRANCH_NAME="$BRANCH_NAME"
-    BRANCH_NAME="${FEATURE_NUM}-${TRUNCATED_SUFFIX}"
-    
-    >&2 echo "[specify] Warning: Branch name exceeded GitHub's 244-byte limit"
-    >&2 echo "[specify] Original: $ORIGINAL_BRANCH_NAME (${#ORIGINAL_BRANCH_NAME} bytes)"
-    >&2 echo "[specify] Truncated to: $BRANCH_NAME (${#BRANCH_NAME} bytes)"
-fi
-
-if [ "$HAS_GIT" = true ]; then
-    git checkout -b "$BRANCH_NAME"
-else
-    >&2 echo "[specify] Warning: Git repository not detected; skipped branch creation for $BRANCH_NAME"
-fi
-
-FEATURE_DIR="$SPECS_DIR/$BRANCH_NAME"
-mkdir -p "$FEATURE_DIR"
-
-TEMPLATE="$REPO_ROOT/.specify/templates/spec-template.md"
-SPEC_FILE="$FEATURE_DIR/spec.md"
-if [ -f "$TEMPLATE" ]; then cp "$TEMPLATE" "$SPEC_FILE"; else touch "$SPEC_FILE"; fi
-
-# Set the SPECIFY_FEATURE environment variable for the current session
-export SPECIFY_FEATURE="$BRANCH_NAME"
-
-if $JSON_MODE; then
-    printf '{"BRANCH_NAME":"%s","SPEC_FILE":"%s","FEATURE_NUM":"%s"}\n' "$BRANCH_NAME" "$SPEC_FILE" "$FEATURE_NUM"
-else
-    echo "BRANCH_NAME: $BRANCH_NAME"
-    echo "SPEC_FILE: $SPEC_FILE"
-    echo "FEATURE_NUM: $FEATURE_NUM"
-    echo "SPECIFY_FEATURE environment variable set to: $BRANCH_NAME"
-fi
@@ -1,72 +0,0 @@
-#!/usr/bin/env bash
-# Plan parsing functions for update-agent-context
-# Extracted from update-agent-context.sh for modularity
-
-# Extract a field value from plan.md by pattern
-# Usage: extract_plan_field "Language/Version" "/path/to/plan.md"
-extract_plan_field() {
-    local field_pattern="$1"
-    local plan_file="$2"
-
-    grep "^\*\*${field_pattern}\*\*: " "$plan_file" 2>/dev/null | \
-        head -1 | \
-        sed "s|^\*\*${field_pattern}\*\*: ||" | \
-        sed 's/^[ \t]*//;s/[ \t]*$//' | \
-        grep -v "NEEDS CLARIFICATION" | \
-        grep -v "^N/A$" || echo ""
-}
-
-# Parse plan.md and set global variables: NEW_LANG, NEW_FRAMEWORK, NEW_DB, NEW_PROJECT_TYPE
-parse_plan_data() {
-    local plan_file="$1"
-
-    if [[ ! -f "$plan_file" ]]; then
-        log_error "Plan file not found: $plan_file"
-        return 1
-    fi
-
-    if [[ ! -r "$plan_file" ]]; then
-        log_error "Plan file is not readable: $plan_file"
-        return 1
-    fi
-
-    log_info "Parsing plan data from $plan_file"
-
-    NEW_LANG=$(extract_plan_field "Language/Version" "$plan_file")
-    NEW_FRAMEWORK=$(extract_plan_field "Primary Dependencies" "$plan_file")
-    NEW_DB=$(extract_plan_field "Storage" "$plan_file")
-    NEW_PROJECT_TYPE=$(extract_plan_field "Project Type" "$plan_file")
-
-    # Log what we found
-    if [[ -n "$NEW_LANG" ]]; then
-        log_info "Found language: $NEW_LANG"
-    else
-        log_warning "No language information found in plan"
-    fi
-
-    [[ -n "$NEW_FRAMEWORK" ]] && log_info "Found framework: $NEW_FRAMEWORK"
-    [[ -n "$NEW_DB" && "$NEW_DB" != "N/A" ]] && log_info "Found database: $NEW_DB"
-    [[ -n "$NEW_PROJECT_TYPE" ]] && log_info "Found project type: $NEW_PROJECT_TYPE"
-}
-
-# Format technology stack string from language and framework
-format_technology_stack() {
-    local lang="$1"
-    local framework="$2"
-    local parts=()
-
-    [[ -n "$lang" && "$lang" != "NEEDS CLARIFICATION" ]] && parts+=("$lang")
-    [[ -n "$framework" && "$framework" != "NEEDS CLARIFICATION" && "$framework" != "N/A" ]] && parts+=("$framework")
-
-    if [[ ${#parts[@]} -eq 0 ]]; then
-        echo ""
-    elif [[ ${#parts[@]} -eq 1 ]]; then
-        echo "${parts[0]}"
-    else
-        local result="${parts[0]}"
-        for ((i=1; i<${#parts[@]}; i++)); do
-            result="$result + ${parts[i]}"
-        done
-        echo "$result"
-    fi
-}
@@ -1,61 +0,0 @@
-#!/usr/bin/env bash
-
-set -e
-
-# Parse command line arguments
-JSON_MODE=false
-ARGS=()
-
-for arg in "$@"; do
-    case "$arg" in
-        --json) 
-            JSON_MODE=true 
-            ;;
-        --help|-h) 
-            echo "Usage: $0 [--json]"
-            echo "  --json    Output results in JSON format"
-            echo "  --help    Show this help message"
-            exit 0 
-            ;;
-        *) 
-            ARGS+=("$arg") 
-            ;;
-    esac
-done
-
-# Get script directory and load common functions
-SCRIPT_DIR="$(CDPATH="" cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-source "$SCRIPT_DIR/common.sh"
-
-# Get all paths and variables from common functions
-eval $(get_feature_paths)
-
-# Check if we're on a proper feature branch (only for git repos)
-check_feature_branch "$CURRENT_BRANCH" "$HAS_GIT" || exit 1
-
-# Ensure the feature directory exists
-mkdir -p "$FEATURE_DIR"
-
-# Copy plan template if it exists
-TEMPLATE="$REPO_ROOT/.specify/templates/plan-template.md"
-if [[ -f "$TEMPLATE" ]]; then
-    cp "$TEMPLATE" "$IMPL_PLAN"
-    echo "Copied plan template to $IMPL_PLAN"
-else
-    echo "Warning: Plan template not found at $TEMPLATE"
-    # Create a basic plan file if template doesn't exist
-    touch "$IMPL_PLAN"
-fi
-
-# Output results
-if $JSON_MODE; then
-    printf '{"FEATURE_SPEC":"%s","IMPL_PLAN":"%s","SPECS_DIR":"%s","BRANCH":"%s","HAS_GIT":"%s"}\n' \
-        "$FEATURE_SPEC" "$IMPL_PLAN" "$FEATURE_DIR" "$CURRENT_BRANCH" "$HAS_GIT"
-else
-    echo "FEATURE_SPEC: $FEATURE_SPEC"
-    echo "IMPL_PLAN: $IMPL_PLAN" 
-    echo "SPECS_DIR: $FEATURE_DIR"
-    echo "BRANCH: $CURRENT_BRANCH"
-    echo "HAS_GIT: $HAS_GIT"
-fi
-
@@ -1,149 +0,0 @@
-#!/bin/bash
-
-# sync-workflows.sh - Sync workflow references between .agents and .windsurf
-# Part of LCBP3-DMS Phase 2 improvements
-
-set -euo pipefail
-
-# Colors for output
-RED='\033[0;31m'
-GREEN='\033[0;32m'
-YELLOW='\033[1;33m'
-BLUE='\033[0;34m'
-NC='\033[0m' # No Color
-
-# Base directory
-BASE_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
-AGENTS_DIR="$BASE_DIR/.agents"
-WINDSURF_DIR="$BASE_DIR/.windsurf"
-WORKFLOWS_DIR="$WINDSURF_DIR/workflows"
-
-echo "=== Workflow Synchronization Check ==="
-echo "Base directory: $BASE_DIR"
-echo
-
-# Function to check if workflow exists
-check_workflow() {
-    local workflow_name="$1"
-    local workflow_file="$WORKFLOWS_DIR/$workflow_name"
-    
-    if [[ -f "$workflow_file" ]]; then
-        echo -e "${GREEN}  EXISTS${NC}: $workflow_name"
-        return 0
-    else
-        echo -e "${RED}  MISSING${NC}: $workflow_name"
-        return 1
-    fi
-}
-
-# Function to list all workflows
-list_workflows() {
-    if [[ -d "$WORKFLOWS_DIR" ]]; then
-        find "$WORKFLOWS_DIR" -name "*.md" -type f | sort
-    else
-        echo "No workflows directory found"
-    fi
-}
-
-# Check directories
-echo "Checking directory structure..."
-if [[ -d "$AGENTS_DIR" ]]; then
-    echo -e "${GREEN}  OK${NC}: .agents directory exists"
-else
-    echo -e "${RED}  ERROR${NC}: .agents directory not found"
-    exit 1
-fi
-
-if [[ -d "$WINDSURF_DIR" ]]; then
-    echo -e "${GREEN}  OK${NC}: .windsurf directory exists"
-else
-    echo -e "${RED}  ERROR${NC}: .windsurf directory not found"
-    exit 1
-fi
-
-if [[ -d "$WORKFLOWS_DIR" ]]; then
-    echo -e "${GREEN}  OK${NC}: workflows directory exists"
-else
-    echo -e "${RED}  ERROR${NC}: workflows directory not found"
-    exit 1
-fi
-
-echo
-
-# Expected workflows based on README documentation
-echo "Checking expected workflows..."
-EXPECTED_WORKFLOWS=(
-    "00-speckit.all.md"
-    "01-speckit.constitution.md"
-    "02-speckit.specify.md"
-    "03-speckit.clarify.md"
-    "04-speckit.plan.md"
-    "05-speckit.tasks.md"
-    "06-speckit.analyze.md"
-    "07-speckit.implement.md"
-    "08-speckit.checker.md"
-    "09-speckit.tester.md"
-    "10-speckit.reviewer.md"
-    "11-speckit.validate.md"
-    "speckit.prepare.md"
-    "schema-change.md"
-    "create-backend-module.md"
-    "create-frontend-page.md"
-    "deploy.md"
-    "review.md"
-    "util-speckit.checklist.md"
-    "util-speckit.diff.md"
-    "util-speckit.migrate.md"
-    "util-speckit.quizme.md"
-    "util-speckit.status.md"
-    "util-speckit.taskstoissues.md"
-)
-
-MISSING_WORKFLOWS=0
-
-for workflow in "${EXPECTED_WORKFLOWS[@]}"; do
-    if ! check_workflow "$workflow"; then
-        ((MISSING_WORKFLOWS++))
-    fi
-done
-
-echo
-
-# List all actual workflows
-echo "All workflows in $WORKFLOWS_DIR:"
-echo "--------------------------------"
-while IFS= read -r workflow; do
-    echo "  $(basename "$workflow")"
-done < <(list_workflows)
-
-echo
-
-# Check for orphaned workflows (unexpected ones)
-echo "Checking for unexpected workflows..."
-ACTUAL_WORKFLOWS=()
-while IFS= read -r workflow; do
-    ACTUAL_WORKFLOWS+=("$(basename "$workflow")")
-done < <(list_workflows)
-
-for actual_workflow in "${ACTUAL_WORKFLOWS[@]}"; do
-    if [[ ! " ${EXPECTED_WORKFLOWS[*]} " =~ " ${actual_workflow} " ]]; then
-        echo -e "${YELLOW}  UNEXPECTED${NC}: $actual_workflow"
-    fi
-done
-
-echo
-
-# Summary
-if [[ $MISSING_WORKFLOWS -eq 0 ]]; then
-    echo -e "${GREEN}=== SUCCESS: All expected workflows present ===${NC}"
-    echo "Total workflows: ${#ACTUAL_WORKFLOWS[@]}"
-    exit 0
-else
-    echo -e "${RED}=== FAILED: $MISSING_WORKFLOWS workflows missing ===${NC}"
-    echo
-    echo "To fix missing workflows:"
-    echo "1. Create missing workflow files in $WORKFLOWS_DIR"
-    echo "2. Use existing workflows as templates"
-    echo "3. Run this script again to verify"
-    exit 1
-fi
@@ -1,805 +0,0 @@
-#!/usr/bin/env bash
-
-# Update agent context files with information from plan.md
-#
-# This script maintains AI agent context files by parsing feature specifications
-# and updating agent-specific configuration files with project information.
-#
-# MAIN FUNCTIONS:
-# 1. Environment Validation
-#    - Verifies git repository structure and branch information
-#    - Checks for required plan.md files and templates
-#    - Validates file permissions and accessibility
-#
-# 2. Plan Data Extraction
-#    - Parses plan.md files to extract project metadata
-#    - Identifies language/version, frameworks, databases, and project types
-#    - Handles missing or incomplete specification data gracefully
-#
-# 3. Agent File Management
-#    - Creates new agent context files from templates when needed
-#    - Updates existing agent files with new project information
-#    - Preserves manual additions and custom configurations
-#    - Supports multiple AI agent formats and directory structures
-#
-# 4. Content Generation
-#    - Generates language-specific build/test commands
-#    - Creates appropriate project directory structures
-#    - Updates technology stacks and recent changes sections
-#    - Maintains consistent formatting and timestamps
-#
-# 5. Multi-Agent Support
-#    - Handles agent-specific file paths and naming conventions
-#    - Supports: Claude, Gemini, Copilot, Cursor, Qwen, opencode, Codex, Windsurf, Kilo Code, Auggie CLI, Roo Code, CodeBuddy CLI, Qoder CLI, Amp, SHAI, or Amazon Q Developer CLI
-#    - Can update single agents or all existing agent files
-#    - Creates default Claude file if no agent files exist
-#
-# Usage: ./update-agent-context.sh [agent_type]
-# Agent types: claude|gemini|copilot|cursor-agent|qwen|opencode|codex|windsurf|kilocode|auggie|shai|q|bob|qoder
-# Leave empty to update all existing agent files
-
-set -e
-
-# Enable strict error handling
-set -u
-set -o pipefail
-
-#==============================================================================
-# Configuration and Global Variables
-#==============================================================================
-
-# Get script directory and load common functions
-SCRIPT_DIR="$(CDPATH="" cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-source "$SCRIPT_DIR/common.sh"
-
-# Load modular components (extracted for maintainability)
-# See each file for documentation of the functions it provides
-source "$SCRIPT_DIR/plan-parser.sh"        # extract_plan_field, parse_plan_data, format_technology_stack
-source "$SCRIPT_DIR/content-generator.sh"  # get_project_structure, get_commands_for_language, get_language_conventions
-source "$SCRIPT_DIR/agent-registry.sh"     # init_agent_registry, get_agent_file, get_agent_name, etc.
-
-# Get all paths and variables from common functions
-eval $(get_feature_paths)
-
-NEW_PLAN="$IMPL_PLAN"  # Alias for compatibility with existing code
-AGENT_TYPE="${1:-}"
-
-# Agent-specific file paths
-CLAUDE_FILE="$REPO_ROOT/CLAUDE.md"
-GEMINI_FILE="$REPO_ROOT/GEMINI.md"
-COPILOT_FILE="$REPO_ROOT/.github/agents/copilot-instructions.md"
-CURSOR_FILE="$REPO_ROOT/.cursor/rules/specify-rules.mdc"
-QWEN_FILE="$REPO_ROOT/QWEN.md"
-AGENTS_FILE="$REPO_ROOT/AGENTS.md"
-WINDSURF_FILE="$REPO_ROOT/.windsurf/rules/specify-rules.md"
-KILOCODE_FILE="$REPO_ROOT/.kilocode/rules/specify-rules.md"
-AUGGIE_FILE="$REPO_ROOT/.augment/rules/specify-rules.md"
-ROO_FILE="$REPO_ROOT/.roo/rules/specify-rules.md"
-CODEBUDDY_FILE="$REPO_ROOT/CODEBUDDY.md"
-QODER_FILE="$REPO_ROOT/QODER.md"
-AMP_FILE="$REPO_ROOT/AGENTS.md"
-SHAI_FILE="$REPO_ROOT/SHAI.md"
-Q_FILE="$REPO_ROOT/AGENTS.md"
-BOB_FILE="$REPO_ROOT/AGENTS.md"
-
-# Template file
-TEMPLATE_FILE="$REPO_ROOT/.specify/templates/agent-file-template.md"
-
-# Global variables for parsed plan data
-NEW_LANG=""
-NEW_FRAMEWORK=""
-NEW_DB=""
-NEW_PROJECT_TYPE=""
-
-#==============================================================================
-# Utility Functions
-#==============================================================================
-
-log_info() {
-    echo "INFO: $1"
-}
-
-log_success() {
-    echo "✓ $1"
-}
-
-log_error() {
-    echo "ERROR: $1" >&2
-}
-
-log_warning() {
-    echo "WARNING: $1" >&2
-}
-
-# Cleanup function for temporary files
-cleanup() {
-    local exit_code=$?
-    rm -f /tmp/agent_update_*_$$
-    rm -f /tmp/manual_additions_$$
-    exit $exit_code
-}
-
-# Set up cleanup trap
-trap cleanup EXIT INT TERM
-
-#==============================================================================
-# Validation Functions
-#==============================================================================
-
-validate_environment() {
-    # Check if we have a current branch/feature (git or non-git)
-    if [[ -z "$CURRENT_BRANCH" ]]; then
-        log_error "Unable to determine current feature"
-        if [[ "$HAS_GIT" == "true" ]]; then
-            log_info "Make sure you're on a feature branch"
-        else
-            log_info "Set SPECIFY_FEATURE environment variable or create a feature first"
-        fi
-        exit 1
-    fi
-
-    # Check if plan.md exists
-    if [[ ! -f "$NEW_PLAN" ]]; then
-        log_error "No plan.md found at $NEW_PLAN"
-        log_info "Make sure you're working on a feature with a corresponding spec directory"
-        if [[ "$HAS_GIT" != "true" ]]; then
-            log_info "Use: export SPECIFY_FEATURE=your-feature-name or create a new feature first"
-        fi
-        exit 1
-    fi
-
-    # Check if template exists (needed for new files)
-    if [[ ! -f "$TEMPLATE_FILE" ]]; then
-        log_warning "Template file not found at $TEMPLATE_FILE"
-        log_warning "Creating new agent files will fail"
-    fi
-}
-
-#==============================================================================
-# Plan Parsing Functions
-#==============================================================================
-
-extract_plan_field() {
-    local field_pattern="$1"
-    local plan_file="$2"
-
-    grep "^\*\*${field_pattern}\*\*: " "$plan_file" 2>/dev/null | \
-        head -1 | \
-        sed "s|^\*\*${field_pattern}\*\*: ||" | \
-        sed 's/^[ \t]*//;s/[ \t]*$//' | \
-        grep -v "NEEDS CLARIFICATION" | \
-        grep -v "^N/A$" || echo ""
-}
-
-parse_plan_data() {
-    local plan_file="$1"
-
-    if [[ ! -f "$plan_file" ]]; then
-        log_error "Plan file not found: $plan_file"
-        return 1
-    fi
-
-    if [[ ! -r "$plan_file" ]]; then
-        log_error "Plan file is not readable: $plan_file"
-        return 1
-    fi
-
-    log_info "Parsing plan data from $plan_file"
-
-    NEW_LANG=$(extract_plan_field "Language/Version" "$plan_file")
-    NEW_FRAMEWORK=$(extract_plan_field "Primary Dependencies" "$plan_file")
-    NEW_DB=$(extract_plan_field "Storage" "$plan_file")
-    NEW_PROJECT_TYPE=$(extract_plan_field "Project Type" "$plan_file")
-
-    # Log what we found
-    if [[ -n "$NEW_LANG" ]]; then
-        log_info "Found language: $NEW_LANG"
-    else
-        log_warning "No language information found in plan"
-    fi
-
-    if [[ -n "$NEW_FRAMEWORK" ]]; then
-        log_info "Found framework: $NEW_FRAMEWORK"
-    fi
-
-    if [[ -n "$NEW_DB" ]] && [[ "$NEW_DB" != "N/A" ]]; then
-        log_info "Found database: $NEW_DB"
-    fi
-
-    if [[ -n "$NEW_PROJECT_TYPE" ]]; then
-        log_info "Found project type: $NEW_PROJECT_TYPE"
-    fi
-}
-
-format_technology_stack() {
-    local lang="$1"
-    local framework="$2"
-    local parts=()
-
-    # Add non-empty parts
-    [[ -n "$lang" && "$lang" != "NEEDS CLARIFICATION" ]] && parts+=("$lang")
-    [[ -n "$framework" && "$framework" != "NEEDS CLARIFICATION" && "$framework" != "N/A" ]] && parts+=("$framework")
-
-    # Join with proper formatting
-    if [[ ${#parts[@]} -eq 0 ]]; then
-        echo ""
-    elif [[ ${#parts[@]} -eq 1 ]]; then
-        echo "${parts[0]}"
-    else
-        # Join multiple parts with " + "
-        local result="${parts[0]}"
-        for ((i=1; i<${#parts[@]}; i++)); do
-            result="$result + ${parts[i]}"
-        done
-        echo "$result"
-    fi
-}
-
-#==============================================================================
-# Template and Content Generation Functions
-#==============================================================================
-
-get_project_structure() {
-    local project_type="$1"
-
-    if [[ "$project_type" == *"web"* ]]; then
-        echo "backend/\\nfrontend/\\ntests/"
-    else
-        echo "src/\\ntests/"
-    fi
-}
-
-get_commands_for_language() {
-    local lang="$1"
-
-    case "$lang" in
-        *"Python"*)
-            echo "cd src && pytest && ruff check ."
-            ;;
-        *"Rust"*)
-            echo "cargo test && cargo clippy"
-            ;;
-        *"JavaScript"*|*"TypeScript"*)
-            echo "npm test \\&\\& npm run lint"
-            ;;
-        *)
-            echo "# Add commands for $lang"
-            ;;
-    esac
-}
-
-get_language_conventions() {
-    local lang="$1"
-    echo "$lang: Follow standard conventions"
-}
-
-create_new_agent_file() {
-    local target_file="$1"
-    local temp_file="$2"
-    local project_name="$3"
-    local current_date="$4"
-
-    if [[ ! -f "$TEMPLATE_FILE" ]]; then
-        log_error "Template not found at $TEMPLATE_FILE"
-        return 1
-    fi
-
-    if [[ ! -r "$TEMPLATE_FILE" ]]; then
-        log_error "Template file is not readable: $TEMPLATE_FILE"
-        return 1
-    fi
-
-    log_info "Creating new agent context file from template..."
-
-    if ! cp "$TEMPLATE_FILE" "$temp_file"; then
-        log_error "Failed to copy template file"
-        return 1
-    fi
-
-    # Replace template placeholders
-    local project_structure
-    project_structure=$(get_project_structure "$NEW_PROJECT_TYPE")
-
-    local commands
-    commands=$(get_commands_for_language "$NEW_LANG")
-
-    local language_conventions
-    language_conventions=$(get_language_conventions "$NEW_LANG")
-
-    # Perform substitutions with error checking using safer approach
-    # Escape special characters for sed by using a different delimiter or escaping
-    local escaped_lang=$(printf '%s\n' "$NEW_LANG" | sed 's/[\[\.*^$()+{}|]/\\&/g')
-    local escaped_framework=$(printf '%s\n' "$NEW_FRAMEWORK" | sed 's/[\[\.*^$()+{}|]/\\&/g')
-    local escaped_branch=$(printf '%s\n' "$CURRENT_BRANCH" | sed 's/[\[\.*^$()+{}|]/\\&/g')
-
-    # Build technology stack and recent change strings conditionally
-    local tech_stack
-    if [[ -n "$escaped_lang" && -n "$escaped_framework" ]]; then
-        tech_stack="- $escaped_lang + $escaped_framework ($escaped_branch)"
-    elif [[ -n "$escaped_lang" ]]; then
-        tech_stack="- $escaped_lang ($escaped_branch)"
-    elif [[ -n "$escaped_framework" ]]; then
-        tech_stack="- $escaped_framework ($escaped_branch)"
-    else
-        tech_stack="- ($escaped_branch)"
-    fi
-
-    local recent_change
-    if [[ -n "$escaped_lang" && -n "$escaped_framework" ]]; then
-        recent_change="- $escaped_branch: Added $escaped_lang + $escaped_framework"
-    elif [[ -n "$escaped_lang" ]]; then
-        recent_change="- $escaped_branch: Added $escaped_lang"
-    elif [[ -n "$escaped_framework" ]]; then
-        recent_change="- $escaped_branch: Added $escaped_framework"
-    else
-        recent_change="- $escaped_branch: Added"
-    fi
-
-    local substitutions=(
-        "s|\[PROJECT NAME\]|$project_name|"
-        "s|\[DATE\]|$current_date|"
-        "s|\[EXTRACTED FROM ALL PLAN.MD FILES\]|$tech_stack|"
-        "s|\[ACTUAL STRUCTURE FROM PLANS\]|$project_structure|g"
-        "s|\[ONLY COMMANDS FOR ACTIVE TECHNOLOGIES\]|$commands|"
-        "s|\[LANGUAGE-SPECIFIC, ONLY FOR LANGUAGES IN USE\]|$language_conventions|"
-        "s|\[LAST 3 FEATURES AND WHAT THEY ADDED\]|$recent_change|"
-    )
-
-    for substitution in "${substitutions[@]}"; do
-        if ! sed -i.bak -e "$substitution" "$temp_file"; then
-            log_error "Failed to perform substitution: $substitution"
-            rm -f "$temp_file" "$temp_file.bak"
-            return 1
-        fi
-    done
-
-    # Convert \n sequences to actual newlines
-    newline=$(printf '\n')
-    sed -i.bak2 "s/\\\\n/${newline}/g" "$temp_file"
-
-    # Clean up backup files
-    rm -f "$temp_file.bak" "$temp_file.bak2"
-
-    return 0
-}
-
-
-
-
-update_existing_agent_file() {
-    local target_file="$1"
-    local current_date="$2"
-
-    log_info "Updating existing agent context file..."
-
-    # Use a single temporary file for atomic update
-    local temp_file
-    temp_file=$(mktemp) || {
-        log_error "Failed to create temporary file"
-        return 1
-    }
-
-    # Process the file in one pass
-    local tech_stack=$(format_technology_stack "$NEW_LANG" "$NEW_FRAMEWORK")
-    local new_tech_entries=()
-    local new_change_entry=""
-
-    # Prepare new technology entries
-    if [[ -n "$tech_stack" ]] && ! grep -q "$tech_stack" "$target_file"; then
-        new_tech_entries+=("- $tech_stack ($CURRENT_BRANCH)")
-    fi
-
-    if [[ -n "$NEW_DB" ]] && [[ "$NEW_DB" != "N/A" ]] && [[ "$NEW_DB" != "NEEDS CLARIFICATION" ]] && ! grep -q "$NEW_DB" "$target_file"; then
-        new_tech_entries+=("- $NEW_DB ($CURRENT_BRANCH)")
-    fi
-
-    # Prepare new change entry
-    if [[ -n "$tech_stack" ]]; then
-        new_change_entry="- $CURRENT_BRANCH: Added $tech_stack"
-    elif [[ -n "$NEW_DB" ]] && [[ "$NEW_DB" != "N/A" ]] && [[ "$NEW_DB" != "NEEDS CLARIFICATION" ]]; then
-        new_change_entry="- $CURRENT_BRANCH: Added $NEW_DB"
-    fi
-
-    # Check if sections exist in the file
-    local has_active_technologies=0
-    local has_recent_changes=0
-
-    if grep -q "^## Active Technologies" "$target_file" 2>/dev/null; then
-        has_active_technologies=1
-    fi
-
-    if grep -q "^## Recent Changes" "$target_file" 2>/dev/null; then
-        has_recent_changes=1
-    fi
-
-    # Process file line by line
-    local in_tech_section=false
-    local in_changes_section=false
-    local tech_entries_added=false
-    local changes_entries_added=false
-    local existing_changes_count=0
-    local file_ended=false
-
-    while IFS= read -r line || [[ -n "$line" ]]; do
-        # Handle Active Technologies section
-        if [[ "$line" == "## Active Technologies" ]]; then
-            echo "$line" >> "$temp_file"
-            in_tech_section=true
-            continue
-        elif [[ $in_tech_section == true ]] && [[ "$line" =~ ^##[[:space:]] ]]; then
-            # Add new tech entries before closing the section
-            if [[ $tech_entries_added == false ]] && [[ ${#new_tech_entries[@]} -gt 0 ]]; then
-                printf '%s\n' "${new_tech_entries[@]}" >> "$temp_file"
-                tech_entries_added=true
-            fi
-            echo "$line" >> "$temp_file"
-            in_tech_section=false
-            continue
-        elif [[ $in_tech_section == true ]] && [[ -z "$line" ]]; then
-            # Add new tech entries before empty line in tech section
-            if [[ $tech_entries_added == false ]] && [[ ${#new_tech_entries[@]} -gt 0 ]]; then
-                printf '%s\n' "${new_tech_entries[@]}" >> "$temp_file"
-                tech_entries_added=true
-            fi
-            echo "$line" >> "$temp_file"
-            continue
-        fi
-
-        # Handle Recent Changes section
-        if [[ "$line" == "## Recent Changes" ]]; then
-            echo "$line" >> "$temp_file"
-            # Add new change entry right after the heading
-            if [[ -n "$new_change_entry" ]]; then
-                echo "$new_change_entry" >> "$temp_file"
-            fi
-            in_changes_section=true
-            changes_entries_added=true
-            continue
-        elif [[ $in_changes_section == true ]] && [[ "$line" =~ ^##[[:space:]] ]]; then
-            echo "$line" >> "$temp_file"
-            in_changes_section=false
-            continue
-        elif [[ $in_changes_section == true ]] && [[ "$line" == "- "* ]]; then
-            # Keep only first 2 existing changes
-            if [[ $existing_changes_count -lt 2 ]]; then
-                echo "$line" >> "$temp_file"
-                ((existing_changes_count++))
-            fi
-            continue
-        fi
-
-        # Update timestamp
-        if [[ "$line" =~ \*\*Last\ updated\*\*:.*[0-9][0-9][0-9][0-9]-[0-9][0-9]-[0-9][0-9] ]]; then
-            echo "$line" | sed "s/[0-9][0-9][0-9][0-9]-[0-9][0-9]-[0-9][0-9]/$current_date/" >> "$temp_file"
-        else
-            echo "$line" >> "$temp_file"
-        fi
-    done < "$target_file"
-
-    # Post-loop check: if we're still in the Active Technologies section and haven't added new entries
-    if [[ $in_tech_section == true ]] && [[ $tech_entries_added == false ]] && [[ ${#new_tech_entries[@]} -gt 0 ]]; then
-        printf '%s\n' "${new_tech_entries[@]}" >> "$temp_file"
-        tech_entries_added=true
-    fi
-
-    # If sections don't exist, add them at the end of the file
-    if [[ $has_active_technologies -eq 0 ]] && [[ ${#new_tech_entries[@]} -gt 0 ]]; then
-        echo "" >> "$temp_file"
-        echo "## Active Technologies" >> "$temp_file"
-        printf '%s\n' "${new_tech_entries[@]}" >> "$temp_file"
-        tech_entries_added=true
-    fi
-
-    if [[ $has_recent_changes -eq 0 ]] && [[ -n "$new_change_entry" ]]; then
-        echo "" >> "$temp_file"
-        echo "## Recent Changes" >> "$temp_file"
-        echo "$new_change_entry" >> "$temp_file"
-        changes_entries_added=true
-    fi
-
-    # Move temp file to target atomically
-    if ! mv "$temp_file" "$target_file"; then
-        log_error "Failed to update target file"
-        rm -f "$temp_file"
-        return 1
-    fi
-
-    return 0
-}
-#==============================================================================
-# Main Agent File Update Function
-#==============================================================================
-
-update_agent_file() {
-    local target_file="$1"
-    local agent_name="$2"
-
-    if [[ -z "$target_file" ]] || [[ -z "$agent_name" ]]; then
-        log_error "update_agent_file requires target_file and agent_name parameters"
-        return 1
-    fi
-
-    log_info "Updating $agent_name context file: $target_file"
-
-    local project_name
-    project_name=$(basename "$REPO_ROOT")
-    local current_date
-    current_date=$(date +%Y-%m-%d)
-
-    # Create directory if it doesn't exist
-    local target_dir
-    target_dir=$(dirname "$target_file")
-    if [[ ! -d "$target_dir" ]]; then
-        if ! mkdir -p "$target_dir"; then
-            log_error "Failed to create directory: $target_dir"
-            return 1
-        fi
-    fi
-
-    if [[ ! -f "$target_file" ]]; then
-        # Create new file from template
-        local temp_file
-        temp_file=$(mktemp) || {
-            log_error "Failed to create temporary file"
-            return 1
-        }
-
-        if create_new_agent_file "$target_file" "$temp_file" "$project_name" "$current_date"; then
-            if mv "$temp_file" "$target_file"; then
-                log_success "Created new $agent_name context file"
-            else
-                log_error "Failed to move temporary file to $target_file"
-                rm -f "$temp_file"
-                return 1
-            fi
-        else
-            log_error "Failed to create new agent file"
-            rm -f "$temp_file"
-            return 1
-        fi
-    else
-        # Update existing file
-        if [[ ! -r "$target_file" ]]; then
-            log_error "Cannot read existing file: $target_file"
-            return 1
-        fi
-
-        if [[ ! -w "$target_file" ]]; then
-            log_error "Cannot write to existing file: $target_file"
-            return 1
-        fi
-
-        if update_existing_agent_file "$target_file" "$current_date"; then
-            log_success "Updated existing $agent_name context file"
-        else
-            log_error "Failed to update existing agent file"
-            return 1
-        fi
-    fi
-
-    return 0
-}
-
-#==============================================================================
-# Agent Selection and Processing
-#==============================================================================
-
-update_specific_agent() {
-    local agent_type="$1"
-
-    case "$agent_type" in
-        claude)
-            update_agent_file "$CLAUDE_FILE" "Claude Code"
-            ;;
-        gemini)
-            update_agent_file "$GEMINI_FILE" "Gemini CLI"
-            ;;
-        copilot)
-            update_agent_file "$COPILOT_FILE" "GitHub Copilot"
-            ;;
-        cursor-agent)
-            update_agent_file "$CURSOR_FILE" "Cursor IDE"
-            ;;
-        qwen)
-            update_agent_file "$QWEN_FILE" "Qwen Code"
-            ;;
-        opencode)
-            update_agent_file "$AGENTS_FILE" "opencode"
-            ;;
-        codex)
-            update_agent_file "$AGENTS_FILE" "Codex CLI"
-            ;;
-        windsurf)
-            update_agent_file "$WINDSURF_FILE" "Windsurf"
-            ;;
-        kilocode)
-            update_agent_file "$KILOCODE_FILE" "Kilo Code"
-            ;;
-        auggie)
-            update_agent_file "$AUGGIE_FILE" "Auggie CLI"
-            ;;
-        roo)
-            update_agent_file "$ROO_FILE" "Roo Code"
-            ;;
-        codebuddy)
-            update_agent_file "$CODEBUDDY_FILE" "CodeBuddy CLI"
-            ;;
-        qoder)
-            update_agent_file "$QODER_FILE" "Qoder CLI"
-            ;;
-        amp)
-            update_agent_file "$AMP_FILE" "Amp"
-            ;;
-        shai)
-            update_agent_file "$SHAI_FILE" "SHAI"
-            ;;
-        q)
-            update_agent_file "$Q_FILE" "Amazon Q Developer CLI"
-            ;;
-        bob)
-            update_agent_file "$BOB_FILE" "IBM Bob"
-            ;;
-        *)
-            log_error "Unknown agent type '$agent_type'"
-            log_error "Expected: claude|gemini|copilot|cursor-agent|qwen|opencode|codex|windsurf|kilocode|auggie|roo|amp|shai|q|bob|qoder"
-            exit 1
-            ;;
-    esac
-}
-
-update_all_existing_agents() {
-    local found_agent=false
-
-    # Check each possible agent file and update if it exists
-    if [[ -f "$CLAUDE_FILE" ]]; then
-        update_agent_file "$CLAUDE_FILE" "Claude Code"
-        found_agent=true
-    fi
-
-    if [[ -f "$GEMINI_FILE" ]]; then
-        update_agent_file "$GEMINI_FILE" "Gemini CLI"
-        found_agent=true
-    fi
-
-    if [[ -f "$COPILOT_FILE" ]]; then
-        update_agent_file "$COPILOT_FILE" "GitHub Copilot"
-        found_agent=true
-    fi
-
-    if [[ -f "$CURSOR_FILE" ]]; then
-        update_agent_file "$CURSOR_FILE" "Cursor IDE"
-        found_agent=true
-    fi
-
-    if [[ -f "$QWEN_FILE" ]]; then
-        update_agent_file "$QWEN_FILE" "Qwen Code"
-        found_agent=true
-    fi
-
-    if [[ -f "$AGENTS_FILE" ]]; then
-        update_agent_file "$AGENTS_FILE" "Codex/opencode"
-        found_agent=true
-    fi
-
-    if [[ -f "$WINDSURF_FILE" ]]; then
-        update_agent_file "$WINDSURF_FILE" "Windsurf"
-        found_agent=true
-    fi
-
-    if [[ -f "$KILOCODE_FILE" ]]; then
-        update_agent_file "$KILOCODE_FILE" "Kilo Code"
-        found_agent=true
-    fi
-
-    if [[ -f "$AUGGIE_FILE" ]]; then
-        update_agent_file "$AUGGIE_FILE" "Auggie CLI"
-        found_agent=true
-    fi
-
-    if [[ -f "$ROO_FILE" ]]; then
-        update_agent_file "$ROO_FILE" "Roo Code"
-        found_agent=true
-    fi
-
-    if [[ -f "$CODEBUDDY_FILE" ]]; then
-        update_agent_file "$CODEBUDDY_FILE" "CodeBuddy CLI"
-        found_agent=true
-    fi
-
-    if [[ -f "$SHAI_FILE" ]]; then
-        update_agent_file "$SHAI_FILE" "SHAI"
-        found_agent=true
-    fi
-
-    if [[ -f "$QODER_FILE" ]]; then
-        update_agent_file "$QODER_FILE" "Qoder CLI"
-        found_agent=true
-    fi
-
-    if [[ -f "$Q_FILE" ]]; then
-        update_agent_file "$Q_FILE" "Amazon Q Developer CLI"
-        found_agent=true
-    fi
-
-    if [[ -f "$BOB_FILE" ]]; then
-        update_agent_file "$BOB_FILE" "IBM Bob"
-        found_agent=true
-    fi
-
-    # If no agent files exist, create a default Claude file
-    if [[ "$found_agent" == false ]]; then
-        log_info "No existing agent files found, creating default Claude file..."
-        update_agent_file "$CLAUDE_FILE" "Claude Code"
-    fi
-}
-print_summary() {
-    echo
-    log_info "Summary of changes:"
-
-    if [[ -n "$NEW_LANG" ]]; then
-        echo "  - Added language: $NEW_LANG"
-    fi
-
-    if [[ -n "$NEW_FRAMEWORK" ]]; then
-        echo "  - Added framework: $NEW_FRAMEWORK"
-    fi
-
-    if [[ -n "$NEW_DB" ]] && [[ "$NEW_DB" != "N/A" ]]; then
-        echo "  - Added database: $NEW_DB"
-    fi
-
-    echo
-
-    log_info "Usage: $0 [claude|gemini|copilot|cursor-agent|qwen|opencode|codex|windsurf|kilocode|auggie|codebuddy|shai|q|bob|qoder]"
-}
-
-#==============================================================================
-# Main Execution
-#==============================================================================
-
-main() {
-    # Validate environment before proceeding
-    validate_environment
-
-    log_info "=== Updating agent context files for feature $CURRENT_BRANCH ==="
-
-    # Parse the plan file to extract project information
-    if ! parse_plan_data "$NEW_PLAN"; then
-        log_error "Failed to parse plan data"
-        exit 1
-    fi
-
-    # Process based on agent type argument
-    local success=true
-
-    if [[ -z "$AGENT_TYPE" ]]; then
-        # No specific agent provided - update all existing agent files
-        log_info "No agent specified, updating all existing agent files..."
-        if ! update_all_existing_agents; then
-            success=false
-        fi
-    else
-        # Specific agent provided - update only that agent
-        log_info "Updating specific agent: $AGENT_TYPE"
-        if ! update_specific_agent "$AGENT_TYPE"; then
-            success=false
-        fi
-    fi
-
-    # Print summary
-    print_summary
-
-    if [[ "$success" == true ]]; then
-        log_success "Agent context update completed successfully"
-        exit 0
-    else
-        log_error "Agent context update completed with errors"
-        exit 1
-    fi
-}
-
-# Execute main function if script is run directly
-if [[ "${BASH_SOURCE[0]}" == "${0}" ]]; then
-    main "$@"
-fi
-
@@ -1,106 +0,0 @@
-#!/bin/bash
-
-# validate-versions.sh - Check version consistency across .agents files
-# Part of LCBP3-DMS Phase 2 improvements
-
-set -euo pipefail
-
-# Colors for output
-RED='\033[0;31m'
-GREEN='\033[0;32m'
-YELLOW='\033[1;33m'
-NC='\033[0m' # No Color
-
-# Base directory
-BASE_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/../../.." && pwd)"
-AGENTS_DIR="$BASE_DIR/.agents"
-
-# Expected version (should match LCBP3 version)
-EXPECTED_VERSION="1.8.9"
-
-echo "=== .agents Version Validation ==="
-echo "Base directory: $BASE_DIR"
-echo "Expected version: $EXPECTED_VERSION"
-echo
-
-# Function to extract version from file
-extract_version() {
-    local file="$1"
-    local pattern="$2"
-
-    if [[ -f "$file" ]]; then
-        grep -o "$pattern" "$file" | head -1 | sed 's/.*\([0-9]\+\.[0-9]\+\.[0-9]\+\).*/\1/' || echo "NOT_FOUND"
-    else
-        echo "FILE_NOT_FOUND"
-    fi
-}
-
-# Files to check
-declare -A FILES_TO_CHECK=(
-    ["$AGENTS_DIR/skills/VERSION"]="version: \([0-9]\+\.[0-9]\+\.[0-9]\+\)"
-    ["$AGENTS_DIR/skills/skills.md"]="[Vv]\([0-9]\+\.[0-9]\+\.[0-9]\+\)"
-)
-
-# Track issues
-ISSUES=0
-
-echo "Checking version consistency..."
-echo
-
-for file in "${!FILES_TO_CHECK[@]}"; do
-    pattern="${FILES_TO_CHECK[$file]}"
-    relative_path="${file#$BASE_DIR/}"
-
-    version=$(extract_version "$file" "$pattern")
-
-    if [[ "$version" == "NOT_FOUND" ]] || [[ "$version" == "FILE_NOT_FOUND" ]]; then
-        echo -e "${RED}  ERROR${NC}: $relative_path - Version not found"
-        ((ISSUES++))
-    elif [[ "$version" != "$EXPECTED_VERSION" ]]; then
-        echo -e "${RED}  ERROR${NC}: $relative_path - Found v$version, expected v$EXPECTED_VERSION"
-        ((ISSUES++))
-    else
-        echo -e "${GREEN}  OK${NC}: $relative_path - v$version"
-    fi
-done
-
-echo
-
-# Check for version mismatches in skill files
-echo "Checking skill file versions..."
-SKILL_VERSIONS_FILE="$AGENTS_DIR/skills/VERSION"
-if [[ -f "$SKILL_VERSIONS_FILE" ]]; then
-    skills_version=$(extract_version "$SKILL_VERSIONS_FILE" "version: \([0-9]\+\.[0-9]\+\.[0-9]\+\)")
-    echo "Skills version file: v$skills_version"
-fi
-
-# Check workflow versions (in .windsurf/workflows)
-WORKFLOWS_DIR="$BASE_DIR/.windsurf/workflows"
-if [[ -d "$WORKFLOWS_DIR" ]]; then
-    echo "Checking workflow files..."
-    workflow_count=0
-    for workflow in "$WORKFLOWS_DIR"/*.md; do
-        if [[ -f "$workflow" ]]; then
-            workflow_count=$((workflow_count + 1))
-        fi
-    done
-    echo -e "${GREEN}  OK${NC}: Found $workflow_count workflow files"
-else
-    echo -e "${YELLOW}  WARNING${NC}: Workflows directory not found at $WORKFLOWS_DIR"
-fi
-
-echo
-
-# Summary
-if [[ $ISSUES -eq 0 ]]; then
-    echo -e "${GREEN}=== SUCCESS: All versions consistent ===${NC}"
-    exit 0
-else
-    echo -e "${RED}=== FAILED: $ISSUES version issues found ===${NC}"
-    echo
-    echo "To fix version issues:"
-    echo "1. Update files to use v$EXPECTED_VERSION"
-    echo "2. Ensure LCBP3 project version matches"
-    echo "3. Run this script again to verify"
-    exit 1
-fi
@@ -1,516 +0,0 @@
-# ci-hooks.ps1 - Continuous integration hooks for .agents (PowerShell version)
-# Part of LCBP3-DMS Phase 3 enhancements
-
-param(
-    [Parameter(Mandatory=$false)]
-    [ValidateSet("pre-commit", "pre-push", "ci-pipeline", "install-hooks", "help")]
-    [string]$Command = "help"
-)
-
-# Configuration
-$BaseDir = Split-Path -Parent (Split-Path -Parent $PSScriptRoot)
-$AgentsDir = Join-Path $BaseDir ".agents"
-$CILogDir = Join-Path $AgentsDir "logs\ci"
-$CIReportDir = Join-Path $AgentsDir "reports\ci"
-
-# Ensure directories exist
-if (-not (Test-Path $CILogDir)) { New-Item -ItemType Directory -Path $CILogDir -Force | Out-Null }
-if (-not (Test-Path $CIReportDir)) { New-Item -ItemType Directory -Path $CIReportDir -Force | Out-Null }
-
-# Colors for output
-$Colors = @{
-    Red = "`e[0;31m"
-    Green = "`e[0;32m"
-    Yellow = "`e[1;33m"
-    Blue = "`e[0;34m"
-    NoColor = "`e[0m"
-}
-
-# Logging function
-function Write-CILog {
-    param(
-        [string]$Level,
-        [string]$Message
-    )
-    
-    $timestamp = Get-Date -Format "yyyy-MM-dd HH:mm:ss"
-    $logFile = Join-Path $CILogDir "ci-$(Get-Date -Format 'yyyy-MM-dd').log"
-    "$timestamp [$Level] $Message" | Out-File -FilePath $logFile -Append
-    
-    # Console output with colors
-    switch ($Level) {
-        "INFO"  { Write-Host $Message -ForegroundColor $Colors.Blue }
-        "PASS"  { Write-Host $Message -ForegroundColor $Colors.Green }
-        "WARN"  { Write-Host $Message -ForegroundColor $Colors.Yellow }
-        "FAIL"  { Write-Host $Message -ForegroundColor $Colors.Red }
-        default { Write-Host $Message }
-    }
-}
-
-# Pre-commit hook
-function Invoke-PreCommitHook {
-    Write-CILog "INFO" "Running pre-commit validation..."
-    
-    $exitCode = 0
-    
-    # 1. Run version validation
-    Write-CILog "INFO" "Checking version consistency..."
-    $versionScript = Join-Path $AgentsDir "scripts\powershell\validate-versions.ps1"
-    if (Test-Path $versionScript) {
-        try {
-            & $versionScript | Out-File -FilePath (Join-Path $CILogDir "pre-commit-versions.log") -Append
-            Write-CILog "PASS" "Version validation passed"
-        } catch {
-            Write-CILog "FAIL" "Version validation failed"
-            $exitCode = 1
-        }
-    } else {
-        Write-CILog "WARN" "Version validation script not found"
-    }
-    
-    # 2. Run skill audit
-    Write-CILog "INFO" "Auditing skills..."
-    $auditScript = Join-Path $AgentsDir "scripts\powershell\audit-skills.ps1"
-    if (Test-Path $auditScript) {
-        try {
-            & $auditScript | Out-File -FilePath (Join-Path $CILogDir "pre-commit-skills.log") -Append
-            Write-CILog "PASS" "Skill audit passed"
-        } catch {
-            Write-CILog "FAIL" "Skill audit failed"
-            $exitCode = 1
-        }
-    } else {
-        Write-CILog "WARN" "Skill audit script not found"
-    }
-    
-    # 3. Run integration tests (if Node.js available)
-    if (Get-Command node -ErrorAction SilentlyContinue) {
-        Write-CILog "INFO" "Running integration tests..."
-        $testScript = Join-Path $AgentsDir "tests\skill-integration.test.js"
-        if (Test-Path $testScript) {
-            try {
-                node $testScript | Out-File -FilePath (Join-Path $CILogDir "pre-commit-tests.log") -Append
-                Write-CILog "PASS" "Integration tests passed"
-            } catch {
-                Write-CILog "WARN" "Integration tests failed (non-blocking)"
-            }
-        } else {
-            Write-CILog "WARN" "Integration test script not found"
-        }
-    } else {
-        Write-CILog "WARN" "Node.js not available, skipping integration tests"
-    }
-    
-    # 4. Check for forbidden patterns
-    Write-CILog "INFO" "Checking for forbidden patterns..."
-    $forbiddenPatterns = @("TODO", "FIXME", "XXX", "HACK")
-    $foundForbidden = $false
-    
-    foreach ($pattern in $forbiddenPatterns) {
-        $skillsDir = Join-Path $AgentsDir "skills"
-        if (Test-Path $skillsDir) {
-            $matches = Select-String -Path $skillsDir\*.md -Pattern $pattern -Recurse
-            if ($matches) {
-                Write-CILog "WARN" "Found forbidden pattern: $pattern"
-                $foundForbidden = $true
-            }
-        }
-    }
-    
-    if (-not $foundForbidden) {
-        Write-CILog "PASS" "No forbidden patterns found"
-    }
-    
-    # Generate pre-commit report
-    $reportFile = Join-Path $CIReportDir "pre-commit-$(Get-Date -Format 'yyyyMMdd-HHmmss').json"
-    $report = @{
-        timestamp = (Get-Date -Format "yyyy-MM-ddTHH:mm:sszzz")
-        hook_type = "pre-commit"
-        exit_code = $exitCode
-        checks_performed = @(
-            "version_validation",
-            "skill_audit", 
-            "integration_tests",
-            "forbidden_patterns"
-        )
-        log_files = @(
-            "pre-commit-versions.log",
-            "pre-commit-skills.log",
-            "pre-commit-tests.log"
-        )
-    }
-    $report | ConvertTo-Json -Depth 10 | Out-File -FilePath $reportFile
-    
-    Write-CILog "INFO" "Pre-commit report saved to: $reportFile"
-    
-    if ($exitCode -eq 0) {
-        Write-CILog "PASS" "Pre-commit validation completed successfully"
-    } else {
-        Write-CILog "FAIL" "Pre-commit validation failed"
-    }
-    
-    return $exitCode
-}
-
-# Pre-push hook
-function Invoke-PrePushHook {
-    Write-CILog "INFO" "Running pre-push validation..."
-    
-    $exitCode = 0
-    
-    # 1. Full health check
-    Write-CILog "INFO" "Running full health check..."
-    if (Get-Command node -ErrorAction SilentlyContinue) {
-        $healthScript = Join-Path $AgentsDir "scripts\health-monitor.js"
-        if (Test-Path $healthScript) {
-            try {
-                node $healthScript | Out-File -FilePath (Join-Path $CILogDir "pre-push-health.log") -Append
-                Write-CILog "PASS" "Health check passed"
-            } catch {
-                Write-CILog "FAIL" "Health check failed"
-                $exitCode = 1
-            }
-        } else {
-            Write-CILog "WARN" "Health monitor script not found"
-        }
-    } else {
-        Write-CILog "WARN" "Node.js not available, using basic health check"
-        $auditScript = Join-Path $AgentsDir "scripts\powershell\audit-skills.ps1"
-        if (Test-Path $auditScript) {
-            try {
-                & $auditScript | Out-File -FilePath (Join-Path $CILogDir "pre-push-basic.log") -Append
-                Write-CILog "PASS" "Basic health check passed"
-            } catch {
-                Write-CILog "FAIL" "Basic health check failed"
-                $exitCode = 1
-            }
-        }
-    }
-    
-    # 2. Advanced validation (if available)
-    if (Get-Command node -ErrorAction SilentlyContinue) {
-        $advancedScript = Join-Path $AgentsDir "scripts\advanced-validator.js"
-        if (Test-Path $advancedScript) {
-            Write-CILog "INFO" "Running advanced validation..."
-            try {
-                node $advancedScript | Out-File -FilePath (Join-Path $CILogDir "pre-push-advanced.log") -Append
-                Write-CILog "PASS" "Advanced validation passed"
-            } catch {
-                Write-CILog "WARN" "Advanced validation found issues (non-blocking)"
-            }
-        }
-    }
-    
-    # 3. Dependency validation
-    if (Get-Command node -ErrorAction SilentlyContinue) {
-        $dependencyScript = Join-Path $AgentsDir "scripts\dependency-validator.js"
-        if (Test-Path $dependencyScript) {
-            Write-CILog "INFO" "Running dependency validation..."
-            try {
-                node $dependencyScript | Out-File -FilePath (Join-Path $CILogDir "pre-push-dependencies.log") -Append
-                Write-CILog "PASS" "Dependency validation passed"
-            } catch {
-                Write-CILog "WARN" "Dependency validation found issues (non-blocking)"
-            }
-        }
-    }
-    
-    # 4. Performance monitoring
-    if (Get-Command node -ErrorAction SilentlyContinue) {
-        $performanceScript = Join-Path $AgentsDir "scripts\performance-monitor.js"
-        if (Test-Path $performanceScript) {
-            Write-CILog "INFO" "Running performance monitoring..."
-            try {
-                node $performanceScript | Out-File -FilePath (Join-Path $CILogDir "pre-push-performance.log") -Append
-                Write-CILog "PASS" "Performance monitoring passed"
-            } catch {
-                Write-CILog "WARN" "Performance monitoring found issues (non-blocking)"
-            }
-        }
-    }
-    
-    # Generate pre-push report
-    $reportFile = Join-Path $CIReportDir "pre-push-$(Get-Date -Format 'yyyyMMdd-HHmmss').json"
-    $report = @{
-        timestamp = (Get-Date -Format "yyyy-MM-ddTHH:mm:sszzz")
-        hook_type = "pre-push"
-        exit_code = $exitCode
-        checks_performed = @(
-            "health_check",
-            "advanced_validation",
-            "dependency_validation",
-            "performance_monitoring"
-        )
-        log_files = @(
-            "pre-push-health.log",
-            "pre-push-advanced.log",
-            "pre-push-dependencies.log",
-            "pre-push-performance.log"
-        )
-    }
-    $report | ConvertTo-Json -Depth 10 | Out-File -FilePath $reportFile
-    
-    Write-CILog "INFO" "Pre-push report saved to: $reportFile"
-    
-    if ($exitCode -eq 0) {
-        Write-CILog "PASS" "Pre-push validation completed successfully"
-    } else {
-        Write-CILog "FAIL" "Pre-push validation failed"
-    }
-    
-    return $exitCode
-}
-
-# CI pipeline hook
-function Invoke-CIPipelineHook {
-    Write-CILog "INFO" "Running CI pipeline validation..."
-    
-    $exitCode = 0
-    $pipelineStart = Get-Date
-    
-    # Create pipeline workspace
-    $workspace = Join-Path $CIReportDir "pipeline-$(Get-Date -Format 'yyyyMMdd-HHmmss')"
-    New-Item -ItemType Directory -Path $workspace -Force | Out-Null
-    
-    # 1. Environment validation
-    Write-CILog "INFO" "Validating CI environment..."
-    
-    # Check required tools
-    $requiredTools = @("node", "npm")
-    foreach ($tool in $requiredTools) {
-        if (Get-Command $tool -ErrorAction SilentlyContinue) {
-            Write-CILog "PASS" "Tool available: $tool"
-        } else {
-            Write-CILog "FAIL" "Tool missing: $tool"
-            $exitCode = 1
-        }
-    }
-    
-    # Check Node.js modules
-    $packageJson = Join-Path $AgentsDir "package.json"
-    if (Test-Path $packageJson) {
-        Push-Location $AgentsDir
-        try {
-            npm list --depth=0 | Out-Null
-            Write-CILog "PASS" "Node.js dependencies installed"
-        } catch {
-            Write-CILog "WARN" "Installing Node.js dependencies..."
-            npm install | Out-File -FilePath (Join-Path $workspace "npm-install.log")
-            if ($LASTEXITCODE -ne 0) {
-                Write-CILog "FAIL" "Failed to install Node.js dependencies"
-                $exitCode = 1
-            }
-        }
-        Pop-Location
-    }
-    
-    # 2. Full test suite
-    Write-CILog "INFO" "Running full test suite..."
-    
-    # Integration tests
-    $integrationTest = Join-Path $AgentsDir "tests\skill-integration.test.js"
-    if (Test-Path $integrationTest) {
-        try {
-            node $integrationTest | Out-File -FilePath (Join-Path $workspace "integration-tests.log")
-            Write-CILog "PASS" "Integration tests passed"
-        } catch {
-            Write-CILog "FAIL" "Integration tests failed"
-            $exitCode = 1
-        }
-    }
-    
-    # Workflow validation tests
-    $workflowTest = Join-Path $AgentsDir "tests\workflow-validation.test.js"
-    if (Test-Path $workflowTest) {
-        try {
-            node $workflowTest | Out-File -FilePath (Join-Path $workspace "workflow-tests.log")
-            Write-CILog "PASS" "Workflow validation tests passed"
-        } catch {
-            Write-CILog "FAIL" "Workflow validation tests failed"
-            $exitCode = 1
-        }
-    }
-    
-    # 3. Comprehensive validation
-    Write-CILog "INFO" "Running comprehensive validation..."
-    
-    # Health monitoring
-    $healthScript = Join-Path $AgentsDir "scripts\health-monitor.js"
-    if (Test-Path $healthScript) {
-        try {
-            node $healthScript | Out-File -FilePath (Join-Path $workspace "health-check.log")
-            Write-CILog "PASS" "Health monitoring passed"
-        } catch {
-            Write-CILog "FAIL" "Health monitoring failed"
-            $exitCode = 1
-        }
-    }
-    
-    # Advanced validation
-    $advancedScript = Join-Path $AgentsDir "scripts\advanced-validator.js"
-    if (Test-Path $advancedScript) {
-        try {
-            node $advancedScript | Out-File -FilePath (Join-Path $workspace "advanced-validation.log")
-            Write-CILog "PASS" "Advanced validation passed"
-        } catch {
-            Write-CILog "WARN" "Advanced validation found issues"
-        }
-    }
-    
-    # Dependency validation
-    $dependencyScript = Join-Path $AgentsDir "scripts\dependency-validator.js"
-    if (Test-Path $dependencyScript) {
-        try {
-            node $dependencyScript | Out-File -FilePath (Join-Path $workspace "dependency-validation.log")
-            Write-CILog "PASS" "Dependency validation passed"
-        } catch {
-            Write-CILog "WARN" "Dependency validation found issues"
-        }
-    }
-    
-    # Performance monitoring
-    $performanceScript = Join-Path $AgentsDir "scripts\performance-monitor.js"
-    if (Test-Path $performanceScript) {
-        try {
-            node $performanceScript | Out-File -FilePath (Join-Path $workspace "performance-monitor.log")
-            Write-CILog "PASS" "Performance monitoring passed"
-        } catch {
-            Write-CILog "WARN" "Performance monitoring found issues"
-        }
-    }
-    
-    # 4. Generate artifacts
-    Write-CILog "INFO" "Generating CI artifacts..."
-    
-    $pipelineEnd = Get-Date
-    $duration = ($pipelineEnd - $pipelineStart).TotalSeconds
-    
-    # Consolidated report
-    $reportFile = Join-Path $workspace "ci-pipeline-report.json"
-    $report = @{
-        timestamp = (Get-Date -Format "yyyy-MM-ddTHH:mm:sszzz")
-        pipeline_type = "full_ci"
-        duration_seconds = [int]$duration
-        exit_code = $exitCode
-        environment = @{
-            node_version = (node --version)
-            platform = $env:OS
-            working_directory = $BaseDir
-        }
-        checks_performed = @(
-            "environment_validation",
-            "integration_tests",
-            "workflow_validation_tests",
-            "health_monitoring",
-            "advanced_validation",
-            "dependency_validation",
-            "performance_monitoring"
-        )
-        artifacts = @(
-            "integration-tests.log",
-            "workflow-tests.log",
-            "health-check.log",
-            "advanced-validation.log",
-            "dependency-validation.log",
-            "performance-monitor.log",
-            "npm-install.log"
-        )
-        workspace = $workspace
-    }
-    $report | ConvertTo-Json -Depth 10 | Out-File -FilePath $reportFile
-    
-    Write-CILog "INFO" "CI pipeline report saved to: $reportFile"
-    Write-CILog "INFO" "CI artifacts saved to: $workspace"
-    Write-CILog "INFO" "Pipeline duration: $([int]$duration)s"
-    
-    if ($exitCode -eq 0) {
-        Write-CILog "PASS" "CI pipeline completed successfully"
-    } else {
-        Write-CILog "FAIL" "CI pipeline failed"
-    }
-    
-    return $exitCode
-}
-
-# Install Git hooks
-function Install-GitHooks {
-    Write-CILog "INFO" "Installing Git hooks..."
-    
-    $hooksDir = Join-Path $BaseDir ".git\hooks"
-    $agentsHooksDir = Join-Path $AgentsDir "scripts\git-hooks"
-    
-    # Create git-hooks directory
-    if (-not (Test-Path $agentsHooksDir)) {
-        New-Item -ItemType Directory -Path $agentsHooksDir -Force | Out-Null
-    }
-    
-    # Create pre-commit hook
-    $preCommitContent = @'
-#!/bin/bash
-# Pre-commit hook for .agents validation
-echo "Running .agents pre-commit validation..."
-if bash .agents/scripts/ci-hooks.sh pre-commit; then
-    echo "Pre-commit validation passed"
-    exit 0
-else
-    echo "Pre-commit validation failed"
-    exit 1
-fi
-'@
-    $preCommitContent | Out-File -FilePath (Join-Path $agentsHooksDir "pre-commit") -Encoding UTF8
-    
-    # Create pre-push hook
-    $prePushContent = @'
-#!/bin/bash
-# Pre-push hook for .agents validation
-echo "Running .agents pre-push validation..."
-if bash .agents/scripts/ci-hooks.sh pre-push; then
-    echo "Pre-push validation passed"
-    exit 0
-else
-    echo "Pre-push validation failed"
-    exit 1
-fi
-'@
-    $prePushContent | Out-File -FilePath (Join-Path $agentsHooksDir "pre-push") -Encoding UTF8
-    
-    # Install hooks if .git directory exists
-    if (Test-Path $hooksDir) {
-        Copy-Item (Join-Path $agentsHooksDir "pre-commit") $hooksDir -Force
-        Copy-Item (Join-Path $agentsHooksDir "pre-push") $hooksDir -Force
-        Write-CILog "PASS" "Git hooks installed successfully"
-    } else {
-        Write-CILog "WARN" "Git repository not found, hooks copied to .agents\scripts\git-hooks"
-    }
-}
-
-# Main execution
-switch ($Command) {
-    "pre-commit" {
-        exit (Invoke-PreCommitHook)
-    }
-    "pre-push" {
-        exit (Invoke-PrePushHook)
-    }
-    "ci-pipeline" {
-        exit (Invoke-CIPipelineHook)
-    }
-    "install-hooks" {
-        Install-GitHooks
-    }
-    "help" {
-        Write-Host "Usage: .\ci-hooks.ps1 -Command {pre-commit|pre-push|ci-pipeline|install-hooks|help}"
-        Write-Host ""
-        Write-Host "Commands:"
-        Write-Host "  pre-commit    - Run pre-commit validation"
-        Write-Host "  pre-push      - Run pre-push validation"
-        Write-Host "  ci-pipeline   - Run full CI pipeline"
-        Write-Host "  install-hooks - Install Git hooks"
-        Write-Host "  help          - Show this help"
-    }
-    default {
-        Write-Host "Unknown command: $Command"
-        Write-Host "Use 'help' to see available commands"
-        exit 1
-    }
-}
@@ -1,445 +0,0 @@
-#!/bin/bash
-
-# ci-hooks.sh - Continuous integration hooks for .agents
-# Part of LCBP3-DMS Phase 3 enhancements
-
-set -euo pipefail
-
-# Colors for output
-RED='\033[0;31m'
-GREEN='\033[0;32m'
-YELLOW='\033[1;33m'
-BLUE='\033[0;34m'
-NC='\033[0m' # No Color
-
-# Base directory
-BASE_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
-AGENTS_DIR="$BASE_DIR/.agents"
-
-# CI configuration
-CI_LOG_DIR="$AGENTS_DIR/logs/ci"
-CI_REPORT_DIR="$AGENTS_DIR/reports/ci"
-
-# Ensure directories exist
-mkdir -p "$CI_LOG_DIR" "$CI_REPORT_DIR"
-
-# Logging function
-ci_log() {
-    local level="$1"
-    local message="$2"
-    local timestamp=$(date '+%Y-%m-%d %H:%M:%S')
-    local log_file="$CI_LOG_DIR/ci-$(date '+%Y-%m-%d').log"
-    
-    echo "[$timestamp] [$level] $message" | tee -a "$log_file"
-    
-    # Console output with colors
-    case "$level" in
-        "INFO")  echo -e "${BLUE}$message${NC}" ;;
-        "PASS")  echo -e "${GREEN}$message${NC}" ;;
-        "WARN")  echo -e "${YELLOW}$message${NC}" ;;
-        "FAIL")  echo -e "${RED}$message${NC}" ;;
-        *) echo "$message" ;;
-    esac
-}
-
-# Pre-commit hook
-pre_commit_hook() {
-    ci_log "INFO" "Running pre-commit validation..."
-    
-    local exit_code=0
-    
-    # 1. Run version validation
-    ci_log "INFO" "Checking version consistency..."
-    if "$AGENTS_DIR/scripts/bash/validate-versions.sh" >> "$CI_LOG_DIR/pre-commit-versions.log" 2>&1; then
-        ci_log "PASS" "Version validation passed"
-    else
-        ci_log "FAIL" "Version validation failed"
-        exit_code=1
-    fi
-    
-    # 2. Run skill audit
-    ci_log "INFO" "Auditing skills..."
-    if "$AGENTS_DIR/scripts/bash/audit-skills.sh" >> "$CI_LOG_DIR/pre-commit-skills.log" 2>&1; then
-        ci_log "PASS" "Skill audit passed"
-    else
-        ci_log "FAIL" "Skill audit failed"
-        exit_code=1
-    fi
-    
-    # 3. Run integration tests (if Node.js available)
-    if command -v node >/dev/null 2>&1; then
-        ci_log "INFO" "Running integration tests..."
-        if node "$AGENTS_DIR/tests/skill-integration.test.js" >> "$CI_LOG_DIR/pre-commit-tests.log" 2>&1; then
-            ci_log "PASS" "Integration tests passed"
-        else
-            ci_log "WARN" "Integration tests failed (non-blocking)"
-        fi
-    else
-        ci_log "WARN" "Node.js not available, skipping integration tests"
-    fi
-    
-    # 4. Check for forbidden patterns
-    ci_log "INFO" "Checking for forbidden patterns..."
-    local forbidden_patterns=("TODO" "FIXME" "XXX" "HACK")
-    local found_forbidden=false
-    
-    for pattern in "${forbidden_patterns[@]}"; do
-        if grep -r "$pattern" "$AGENTS_DIR/skills" --include="*.md" >/dev/null 2>&1; then
-            ci_log "WARN" "Found forbidden pattern: $pattern"
-            found_forbidden=true
-        fi
-    done
-    
-    if [ "$found_forbidden" = false ]; then
-        ci_log "PASS" "No forbidden patterns found"
-    fi
-    
-    # Generate pre-commit report
-    local report_file="$CI_REPORT_DIR/pre-commit-$(date '+%Y%m%d-%H%M%S').json"
-    cat > "$report_file" << EOF
-{
-    "timestamp": "$(date -Iseconds)",
-    "hook_type": "pre-commit",
-    "exit_code": $exit_code,
-    "checks_performed": [
-        "version_validation",
-        "skill_audit", 
-        "integration_tests",
-        "forbidden_patterns"
-    ],
-    "log_files": [
-        "pre-commit-versions.log",
-        "pre-commit-skills.log",
-        "pre-commit-tests.log"
-    ]
-}
-EOF
-    
-    ci_log "INFO" "Pre-commit report saved to: $report_file"
-    
-    if [ $exit_code -eq 0 ]; then
-        ci_log "PASS" "Pre-commit validation completed successfully"
-    else
-        ci_log "FAIL" "Pre-commit validation failed"
-    fi
-    
-    return $exit_code
-}
-
-# Pre-push hook
-pre_push_hook() {
-    ci_log "INFO" "Running pre-push validation..."
-    
-    local exit_code=0
-    
-    # 1. Full health check
-    ci_log "INFO" "Running full health check..."
-    if command -v node >/dev/null 2>&1; then
-        if node "$AGENTS_DIR/scripts/health-monitor.js" >> "$CI_LOG_DIR/pre-push-health.log" 2>&1; then
-            ci_log "PASS" "Health check passed"
-        else
-            ci_log "FAIL" "Health check failed"
-            exit_code=1
-        fi
-    else
-        ci_log "WARN" "Node.js not available, using basic health check"
-        if "$AGENTS_DIR/scripts/bash/audit-skills.sh" >> "$CI_LOG_DIR/pre-push-basic.log" 2>&1; then
-            ci_log "PASS" "Basic health check passed"
-        else
-            ci_log "FAIL" "Basic health check failed"
-            exit_code=1
-        fi
-    fi
-    
-    # 2. Advanced validation (if available)
-    if command -v node >/dev/null 2>&1 && [ -f "$AGENTS_DIR/scripts/advanced-validator.js" ]; then
-        ci_log "INFO" "Running advanced validation..."
-        if node "$AGENTS_DIR/scripts/advanced-validator.js" >> "$CI_LOG_DIR/pre-push-advanced.log" 2>&1; then
-            ci_log "PASS" "Advanced validation passed"
-        else
-            ci_log "WARN" "Advanced validation found issues (non-blocking)"
-        fi
-    fi
-    
-    # 3. Dependency validation
-    if command -v node >/dev/null 2>&1 && [ -f "$AGENTS_DIR/scripts/dependency-validator.js" ]; then
-        ci_log "INFO" "Running dependency validation..."
-        if node "$AGENTS_DIR/scripts/dependency-validator.js" >> "$CI_LOG_DIR/pre-push-dependencies.log" 2>&1; then
-            ci_log "PASS" "Dependency validation passed"
-        else
-            ci_log "WARN" "Dependency validation found issues (non-blocking)"
-        fi
-    fi
-    
-    # 4. Performance monitoring
-    if command -v node >/dev/null 2>&1 && [ -f "$AGENTS_DIR/scripts/performance-monitor.js" ]; then
-        ci_log "INFO" "Running performance monitoring..."
-        if node "$AGENTS_DIR/scripts/performance-monitor.js" >> "$CI_LOG_DIR/pre-push-performance.log" 2>&1; then
-            ci_log "PASS" "Performance monitoring passed"
-        else
-            ci_log "WARN" "Performance monitoring found issues (non-blocking)"
-        fi
-    fi
-    
-    # Generate pre-push report
-    local report_file="$CI_REPORT_DIR/pre-push-$(date '+%Y%m%d-%H%M%S').json"
-    cat > "$report_file" << EOF
-{
-    "timestamp": "$(date -Iseconds)",
-    "hook_type": "pre-push",
-    "exit_code": $exit_code,
-    "checks_performed": [
-        "health_check",
-        "advanced_validation",
-        "dependency_validation",
-        "performance_monitoring"
-    ],
-    "log_files": [
-        "pre-push-health.log",
-        "pre-push-advanced.log",
-        "pre-push-dependencies.log",
-        "pre-push-performance.log"
-    ]
-}
-EOF
-    
-    ci_log "INFO" "Pre-push report saved to: $report_file"
-    
-    if [ $exit_code -eq 0 ]; then
-        ci_log "PASS" "Pre-push validation completed successfully"
-    else
-        ci_log "FAIL" "Pre-push validation failed"
-    fi
-    
-    return $exit_code
-}
-
-# CI pipeline hook
-ci_pipeline_hook() {
-    ci_log "INFO" "Running CI pipeline validation..."
-    
-    local exit_code=0
-    local pipeline_start=$(date +%s)
-    
-    # Create pipeline workspace
-    local workspace="$CI_REPORT_DIR/pipeline-$(date '+%Y%m%d-%H%M%S')"
-    mkdir -p "$workspace"
-    
-    # 1. Environment validation
-    ci_log "INFO" "Validating CI environment..."
-    
-    # Check required tools
-    local required_tools=("node" "npm")
-    for tool in "${required_tools[@]}"; do
-        if command -v "$tool" >/dev/null 2>&1; then
-            ci_log "PASS" "Tool available: $tool"
-        else
-            ci_log "FAIL" "Tool missing: $tool"
-            exit_code=1
-        fi
-    done
-    
-    # Check Node.js modules
-    if [ -f "$AGENTS_DIR/package.json" ]; then
-        cd "$AGENTS_DIR"
-        if npm list --depth=0 >/dev/null 2>&1; then
-            ci_log "PASS" "Node.js dependencies installed"
-        else
-            ci_log "WARN" "Installing Node.js dependencies..."
-            npm install >> "$workspace/npm-install.log" 2>&1 || {
-                ci_log "FAIL" "Failed to install Node.js dependencies"
-                exit_code=1
-            }
-        fi
-        cd "$BASE_DIR"
-    fi
-    
-    # 2. Full test suite
-    ci_log "INFO" "Running full test suite..."
-    
-    # Integration tests
-    if node "$AGENTS_DIR/tests/skill-integration.test.js" >> "$workspace/integration-tests.log" 2>&1; then
-        ci_log "PASS" "Integration tests passed"
-    else
-        ci_log "FAIL" "Integration tests failed"
-        exit_code=1
-    fi
-    
-    # Workflow validation tests
-    if node "$AGENTS_DIR/tests/workflow-validation.test.js" >> "$workspace/workflow-tests.log" 2>&1; then
-        ci_log "PASS" "Workflow validation tests passed"
-    else
-        ci_log "FAIL" "Workflow validation tests failed"
-        exit_code=1
-    fi
-    
-    # 3. Comprehensive validation
-    ci_log "INFO" "Running comprehensive validation..."
-    
-    # Health monitoring
-    if node "$AGENTS_DIR/scripts/health-monitor.js" >> "$workspace/health-check.log" 2>&1; then
-        ci_log "PASS" "Health monitoring passed"
-    else
-        ci_log "FAIL" "Health monitoring failed"
-        exit_code=1
-    fi
-    
-    # Advanced validation
-    if node "$AGENTS_DIR/scripts/advanced-validator.js" >> "$workspace/advanced-validation.log" 2>&1; then
-        ci_log "PASS" "Advanced validation passed"
-    else
-        ci_log "WARN" "Advanced validation found issues"
-    fi
-    
-    # Dependency validation
-    if node "$AGENTS_DIR/scripts/dependency-validator.js" >> "$workspace/dependency-validation.log" 2>&1; then
-        ci_log "PASS" "Dependency validation passed"
-    else
-        ci_log "WARN" "Dependency validation found issues"
-    fi
-    
-    # Performance monitoring
-    if node "$AGENTS_DIR/scripts/performance-monitor.js" >> "$workspace/performance-monitor.log" 2>&1; then
-        ci_log "PASS" "Performance monitoring passed"
-    else
-        ci_log "WARN" "Performance monitoring found issues"
-    fi
-    
-    # 4. Generate artifacts
-    ci_log "INFO" "Generating CI artifacts..."
-    
-    local pipeline_end=$(date +%s)
-    local duration=$((pipeline_end - pipeline_start))
-    
-    # Consolidated report
-    local report_file="$workspace/ci-pipeline-report.json"
-    cat > "$report_file" << EOF
-{
-    "timestamp": "$(date -Iseconds)",
-    "pipeline_type": "full_ci",
-    "duration_seconds": $duration,
-    "exit_code": $exit_code,
-    "environment": {
-        "node_version": "$(node --version)",
-        "platform": "$(uname -s)",
-        "working_directory": "$BASE_DIR"
-    },
-    "checks_performed": [
-        "environment_validation",
-        "integration_tests",
-        "workflow_validation_tests",
-        "health_monitoring",
-        "advanced_validation",
-        "dependency_validation",
-        "performance_monitoring"
-    ],
-    "artifacts": [
-        "integration-tests.log",
-        "workflow-tests.log",
-        "health-check.log",
-        "advanced-validation.log",
-        "dependency-validation.log",
-        "performance-monitor.log",
-        "npm-install.log"
-    ],
-    "workspace": "$workspace"
-}
-EOF
-    
-    ci_log "INFO" "CI pipeline report saved to: $report_file"
-    ci_log "INFO" "CI artifacts saved to: $workspace"
-    ci_log "INFO" "Pipeline duration: ${duration}s"
-    
-    if [ $exit_code -eq 0 ]; then
-        ci_log "PASS" "CI pipeline completed successfully"
-    else
-        ci_log "FAIL" "CI pipeline failed"
-    fi
-    
-    return $exit_code
-}
-
-# Install Git hooks
-install_git_hooks() {
-    ci_log "INFO" "Installing Git hooks..."
-    
-    local hooks_dir="$BASE_DIR/.git/hooks"
-    local agents_hooks_dir="$AGENTS_DIR/scripts/git-hooks"
-    
-    # Create git-hooks directory
-    mkdir -p "$agents_hooks_dir"
-    
-    # Create pre-commit hook
-    cat > "$agents_hooks_dir/pre-commit" << 'EOF'
-#!/bin/bash
-# Pre-commit hook for .agents validation
-echo "Running .agents pre-commit validation..."
-if bash .agents/scripts/ci-hooks.sh pre-commit; then
-    echo "Pre-commit validation passed"
-    exit 0
-else
-    echo "Pre-commit validation failed"
-    exit 1
-fi
-EOF
-    
-    # Create pre-push hook
-    cat > "$agents_hooks_dir/pre-push" << 'EOF'
-#!/bin/bash
-# Pre-push hook for .agents validation
-echo "Running .agents pre-push validation..."
-if bash .agents/scripts/ci-hooks.sh pre-push; then
-    echo "Pre-push validation passed"
-    exit 0
-else
-    echo "Pre-push validation failed"
-    exit 1
-fi
-EOF
-    
-    # Make hooks executable
-    chmod +x "$agents_hooks_dir/pre-commit"
-    chmod +x "$agents_hooks_dir/pre-push"
-    
-    # Install hooks if .git directory exists
-    if [ -d "$hooks_dir" ]; then
-        cp "$agents_hooks_dir/pre-commit" "$hooks_dir/"
-        cp "$agents_hooks_dir/pre-push" "$hooks_dir/"
-        ci_log "PASS" "Git hooks installed successfully"
-    else
-        ci_log "WARN" "Git repository not found, hooks copied to .agents/scripts/git-hooks"
-    fi
-}
-
-# Main function
-main() {
-    local command="${1:-help}"
-    
-    case "$command" in
-        "pre-commit")
-            pre_commit_hook
-            ;;
-        "pre-push")
-            pre_push_hook
-            ;;
-        "ci-pipeline")
-            ci_pipeline_hook
-            ;;
-        "install-hooks")
-            install_git_hooks
-            ;;
-        "help"|*)
-            echo "Usage: $0 {pre-commit|pre-push|ci-pipeline|install-hooks|help}"
-            echo ""
-            echo "Commands:"
-            echo "  pre-commit    - Run pre-commit validation"
-            echo "  pre-push      - Run pre-push validation"
-            echo "  ci-pipeline   - Run full CI pipeline"
-            echo "  install-hooks - Install Git hooks"
-            echo "  help          - Show this help"
-            ;;
-    esac
-}
-
-# Run main function with all arguments
-main "$@"
@@ -1,457 +0,0 @@
-#!/usr/bin/env node
-
-/**
- * dependency-validator.js - Skill dependency validation system
- * Part of LCBP3-DMS Phase 3 enhancements
- */
-
-const fs = require('fs');
-const path = require('path');
-const yaml = require('js-yaml');
-
-// Configuration
-const BASE_DIR = path.resolve(__dirname, '../..');
-const AGENTS_DIR = path.join(BASE_DIR, '.agents');
-const SKILLS_DIR = path.join(AGENTS_DIR, 'skills');
-const WORKFLOWS_DIR = path.join(BASE_DIR, '.windsurf', 'workflows');
-
-// Dependency validation class
-class DependencyValidator {
-    constructor() {
-        this.validationResults = {
-            timestamp: new Date().toISOString(),
-            dependency_graph: {},
-            circular_dependencies: [],
-            missing_dependencies: [],
-            orphaned_skills: [],
-            dependency_chains: {},
-            validation_summary: {
-                total_skills: 0,
-                skills_with_dependencies: 0,
-                circular_dependencies_found: 0,
-                missing_dependencies_found: 0,
-                orphaned_skills_found: 0,
-                max_dependency_depth: 0,
-                validation_status: 'unknown'
-            }
-        };
-    }
-
-    log(message, level = 'info') {
-        const colors = {
-            info: '\x1b[36m',    // Cyan
-            pass: '\x1b[32m',    // Green
-            fail: '\x1b[31m',    // Red
-            warn: '\x1b[33m',    // Yellow
-            critical: '\x1b[35m', // Magenta
-            reset: '\x1b[0m'
-        };
-        
-        const color = colors[level] || colors.info;
-        console.log(`${color}[${level.toUpperCase()}] ${message}${colors.reset}`);
-    }
-
-    extractSkillDependencies(skillPath, skillName) {
-        const skillMdPath = path.join(skillPath, 'SKILL.md');
-        
-        if (!fs.existsSync(skillMdPath)) {
-            this.log(`No SKILL.md found for ${skillName}`, 'warn');
-            return { dependencies: [], handoffs: [], error: 'SKILL.md not found' };
-        }
-
-        try {
-            const content = fs.readFileSync(skillMdPath, 'utf8');
-            
-            // Extract dependencies from front matter
-            let dependencies = [];
-            let handoffs = [];
-            
-            const frontMatterMatch = content.match(/^---\n([\s\S]*?)\n---/);
-            if (frontMatterMatch) {
-                try {
-                    const frontMatter = yaml.load(frontMatterMatch[1]);
-                    
-                    // Handle depends-on field
-                    if (frontMatter['depends-on']) {
-                        if (Array.isArray(frontMatter['depends-on'])) {
-                            dependencies = frontMatter['depends-on'];
-                        } else {
-                            dependencies = [frontMatter['depends-on']];
-                        }
-                    }
-                    
-                    // Handle handoffs field
-                    if (frontMatter.handoffs && Array.isArray(frontMatter.handoffs)) {
-                        handoffs = frontMatter.handoffs.map(h => h.agent);
-                    }
-                    
-                } catch (yamlError) {
-                    this.log(`Invalid YAML in ${skillName} front matter: ${yamlError.message}`, 'warn');
-                }
-            }
-
-            // Also extract skill references from content
-            const contentSkillRefs = content.match(/@speckit-\w+/g) || [];
-            const contentDependencies = contentSkillRefs.map(ref => ref.replace('@', ''));
-            
-            // Merge dependencies (avoid duplicates)
-            const allDependencies = [...new Set([...dependencies, ...contentDependencies])];
-            
-            return { 
-                dependencies: allDependencies, 
-                handoffs: handoffs,
-                content_references: contentSkillRefs,
-                front_matter_dependencies: dependencies,
-                error: null 
-            };
-
-        } catch (error) {
-            this.log(`Error reading ${skillName}: ${error.message}`, 'warn');
-            return { dependencies: [], handoffs: [], error: error.message };
-        }
-    }
-
-    buildDependencyGraph() {
-        this.log('Building dependency graph...', 'info');
-        
-        if (!fs.existsSync(SKILLS_DIR)) {
-            this.log('Skills directory not found', 'fail');
-            return;
-        }
-
-        const skillDirs = fs.readdirSync(SKILLS_DIR).filter(item => {
-            const itemPath = path.join(SKILLS_DIR, item);
-            return fs.statSync(itemPath).isDirectory();
-        });
-
-        this.validationResults.validation_summary.total_skills = skillDirs.length;
-
-        // Extract dependencies for each skill
-        for (const skillDir of skillDirs) {
-            const skillPath = path.join(SKILLS_DIR, skillDir);
-            const dependencyInfo = this.extractSkillDependencies(skillPath, skillDir);
-            
-            this.validationResults.dependency_graph[skillDir] = dependencyInfo;
-            
-            if (dependencyInfo.dependencies.length > 0 || dependencyInfo.handoffs.length > 0) {
-                this.validationResults.validation_summary.skills_with_dependencies++;
-            }
-        }
-
-        this.log(`Analyzed ${skillDirs.length} skills`, 'info');
-        this.log(`Skills with dependencies: ${this.validationResults.validation_summary.skills_with_dependencies}`, 'info');
-    }
-
-    validateDependencies() {
-        this.log('Validating dependencies...', 'info');
-        
-        const { dependency_graph } = this.validationResults;
-        const allSkills = Object.keys(dependency_graph);
-        
-        // Check for missing dependencies
-        for (const [skillName, dependencyInfo] of Object.entries(dependency_graph)) {
-            for (const dependency of dependencyInfo.dependencies) {
-                if (!allSkills.includes(dependency)) {
-                    this.validationResults.missing_dependencies.push({
-                        skill: skillName,
-                        missing_dependency: dependency,
-                        dependency_type: 'depends-on'
-                    });
-                    this.validationResults.validation_summary.missing_dependencies_found++;
-                    this.log(`Missing dependency: ${skillName} depends on ${dependency}`, 'fail');
-                }
-            }
-            
-            for (const handoff of dependencyInfo.handoffs) {
-                if (!allSkills.includes(handoff)) {
-                    this.validationResults.missing_dependencies.push({
-                        skill: skillName,
-                        missing_dependency: handoff,
-                        dependency_type: 'handoff'
-                    });
-                    this.validationResults.validation_summary.missing_dependencies_found++;
-                    this.log(`Missing handoff: ${skillName} hands off to ${handoff}`, 'fail');
-                }
-            }
-        }
-
-        // Check for orphaned skills (no one depends on them)
-        const dependedOnSkills = new Set();
-        for (const dependencyInfo of Object.values(dependency_graph)) {
-            dependencyInfo.dependencies.forEach(dep => dependedOnSkills.add(dep));
-            dependencyInfo.handoffs.forEach(handoff => dependedOnSkills.add(handoff));
-        }
-
-        for (const skill of allSkills) {
-            if (!dependedOnSkills.has(skill) && skill !== 'speckit-constitution') {
-                // Constitution is allowed to be orphaned (it's a starting point)
-                this.validationResults.orphaned_skills.push(skill);
-                this.validationResults.validation_summary.orphaned_skills_found++;
-                this.log(`Orphaned skill: ${skill} (no dependencies on it)`, 'warn');
-            }
-        }
-    }
-
-    detectCircularDependencies() {
-        this.log('Detecting circular dependencies...', 'info');
-        
-        const { dependency_graph } = this.validationResults;
-        const visited = new Set();
-        const recursionStack = new Set();
-        const circularDeps = [];
-
-        function dfs(skillName, path = []) {
-            if (recursionStack.has(skillName)) {
-                // Found circular dependency
-                const cycleStart = path.indexOf(skillName);
-                const cycle = path.slice(cycleStart).concat(skillName);
-                circularDeps.push(cycle);
-                return;
-            }
-
-            if (visited.has(skillName)) {
-                return;
-            }
-
-            visited.add(skillName);
-            recursionStack.add(skillName);
-            path.push(skillName);
-
-            const dependencyInfo = dependency_graph[skillName];
-            if (dependencyInfo) {
-                for (const dependency of dependencyInfo.dependencies) {
-                    dfs(dependency, [...path]);
-                }
-            }
-
-            recursionStack.delete(skillName);
-        }
-
-        // Run DFS from each skill
-        for (const skillName of Object.keys(dependency_graph)) {
-            if (!visited.has(skillName)) {
-                dfs(skillName);
-            }
-        }
-
-        this.validationResults.circular_dependencies = circularDeps;
-        this.validationResults.validation_summary.circular_dependencies_found = circularDeps.length;
-
-        if (circularDeps.length > 0) {
-            this.log(`Found ${circularDeps.length} circular dependencies:`, 'critical');
-            circularDeps.forEach((cycle, index) => {
-                this.log(`  ${index + 1}. ${cycle.join(' -> ')}`, 'critical');
-            });
-        } else {
-            this.log('No circular dependencies found', 'pass');
-        }
-    }
-
-    calculateDependencyChains() {
-        this.log('Calculating dependency chains...', 'info');
-        
-        const { dependency_graph } = this.validationResults;
-        const chains = {};
-
-        function calculateDepth(skillName, visited = new Set()) {
-            if (visited.has(skillName)) {
-                return 0; // Circular dependency protection
-            }
-
-            visited.add(skillName);
-            
-            const dependencyInfo = dependency_graph[skillName];
-            if (!dependencyInfo || dependencyInfo.dependencies.length === 0) {
-                return 1;
-            }
-
-            let maxDepth = 0;
-            for (const dependency of dependencyInfo.dependencies) {
-                const depth = calculateDepth(dependency, new Set(visited));
-                maxDepth = Math.max(maxDepth, depth);
-            }
-
-            return maxDepth + 1;
-        }
-
-        function getDependencyChain(skillName) {
-            const dependencyInfo = dependency_graph[skillName];
-            if (!dependencyInfo || dependencyInfo.dependencies.length === 0) {
-                return [skillName];
-            }
-
-            const chains = [];
-            for (const dependency of dependencyInfo.dependencies) {
-                const depChain = getDependencyChain(dependency);
-                chains.push(depChain.concat(skillName));
-            }
-
-            // Return the longest chain
-            return chains.reduce((longest, current) => 
-                current.length > longest.length ? current : longest, [skillName]
-            );
-        }
-
-        for (const skillName of Object.keys(dependency_graph)) {
-            const depth = calculateDepth(skillName);
-            const chain = getDependencyChain(skillName);
-            
-            chains[skillName] = {
-                depth: depth,
-                chain: chain,
-                chain_length: chain.length
-            };
-        }
-
-        this.validationResults.dependency_chains = chains;
-        
-        const maxDepth = Math.max(...Object.values(chains).map(c => c.depth));
-        this.validationResults.validation_summary.max_dependency_depth = maxDepth;
-        
-        this.log(`Maximum dependency depth: ${maxDepth}`, 'info');
-    }
-
-    validateWorkflowDependencies() {
-        this.log('Validating workflow dependencies...', 'info');
-        
-        if (!fs.existsSync(WORKFLOWS_DIR)) {
-            this.log('Workflows directory not found', 'warn');
-            return;
-        }
-
-        const workflowFiles = fs.readdirSync(WORKFLOWS_DIR).filter(file => file.endsWith('.md'));
-        const allSkills = Object.keys(this.validationResults.dependency_graph);
-
-        for (const workflowFile of workflowFiles) {
-            const workflowPath = path.join(WORKFLOWS_DIR, workflowFile);
-            
-            try {
-                const content = fs.readFileSync(workflowPath, 'utf8');
-                const skillReferences = content.match(/@speckit-\w+/g) || [];
-                
-                for (const skillRef of skillReferences) {
-                    const skillName = skillRef.replace('@', '');
-                    
-                    if (!allSkills.includes(skillName)) {
-                        this.validationResults.missing_dependencies.push({
-                            workflow: workflowFile,
-                            missing_dependency: skillName,
-                            dependency_type: 'workflow-reference'
-                        });
-                        this.validationResults.validation_summary.missing_dependencies_found++;
-                        this.log(`Workflow ${workflowFile} references missing skill: ${skillRef}`, 'fail');
-                    }
-                }
-                
-            } catch (error) {
-                this.log(`Error reading workflow ${workflowFile}: ${error.message}`, 'warn');
-            }
-        }
-    }
-
-    generateDependencyReport() {
-        this.log('Generating dependency report...', 'info');
-        
-        // Determine overall validation status
-        const summary = this.validationResults.validation_summary;
-        
-        if (summary.circular_dependencies_found > 0) {
-            summary.validation_status = 'critical';
-        } else if (summary.missing_dependencies_found > 0) {
-            summary.validation_status = 'failed';
-        } else if (summary.orphaned_skills_found > 0) {
-            summary.validation_status = 'warning';
-        } else {
-            summary.validation_status = 'passed';
-        }
-
-        // Save report
-        const reportPath = path.join(AGENTS_DIR, 'reports', 'dependency-validation.json');
-        const reportsDir = path.dirname(reportPath);
-        
-        if (!fs.existsSync(reportsDir)) {
-            fs.mkdirSync(reportsDir, { recursive: true });
-        }
-
-        fs.writeFileSync(reportPath, JSON.stringify(this.validationResults, null, 2));
-        this.log(`Dependency validation report saved to: ${reportPath}`, 'info');
-    }
-
-    printSummary() {
-        const summary = this.validationResults.validation_summary;
-        
-        this.log('=== Dependency Validation Summary ===', 'info');
-        this.log(`Total skills: ${summary.total_skills}`, 'info');
-        this.log(`Skills with dependencies: ${summary.skills_with_dependencies}`, 'info');
-        this.log(`Circular dependencies: ${summary.circular_dependencies_found}`, summary.circular_dependencies_found > 0 ? 'critical' : 'pass');
-        this.log(`Missing dependencies: ${summary.missing_dependencies_found}`, summary.missing_dependencies_found > 0 ? 'fail' : 'pass');
-        this.log(`Orphaned skills: ${summary.orphaned_skills_found}`, summary.orphaned_skills_found > 0 ? 'warn' : 'info');
-        this.log(`Max dependency depth: ${summary.max_dependency_depth}`, 'info');
-        this.log(`Validation status: ${summary.validation_status.toUpperCase()}`, 
-            summary.validation_status === 'passed' ? 'pass' : 
-            summary.validation_status === 'warning' ? 'warn' : 'fail');
-
-        // Show longest dependency chains
-        const chains = this.validationResults.dependency_chains;
-        const sortedChains = Object.entries(chains)
-            .sort(([,a], [,b]) => b.depth - a.depth)
-            .slice(0, 3);
-
-        if (sortedChains.length > 0) {
-            this.log('Top 3 longest dependency chains:', 'info');
-            sortedChains.forEach(([skillName, chainInfo], index) => {
-                this.log(`  ${index + 1}. ${chainInfo.chain.join(' -> ')} (depth: ${chainInfo.depth})`, 'info');
-            });
-        }
-    }
-
-    async runDependencyValidation() {
-        this.log('Starting dependency validation...', 'info');
-        this.log(`Base directory: ${BASE_DIR}`, 'info');
-        
-        // Build dependency graph
-        this.buildDependencyGraph();
-        
-        // Validate dependencies
-        this.validateDependencies();
-        
-        // Detect circular dependencies
-        this.detectCircularDependencies();
-        
-        // Calculate dependency chains
-        this.calculateDependencyChains();
-        
-        // Validate workflow dependencies
-        this.validateWorkflowDependencies();
-        
-        // Generate report
-        this.generateDependencyReport();
-        
-        // Print summary
-        this.printSummary();
-        
-        return this.validationResults;
-    }
-}
-
-// CLI interface
-async function main() {
-    const validator = new DependencyValidator();
-    
-    try {
-        const results = await validator.runDependencyValidation();
-        const status = results.validation_summary.validation_status;
-        process.exit(status === 'passed' || status === 'warning' ? 0 : 1);
-    } catch (error) {
-        console.error('Dependency validation failed:', error);
-        process.exit(1);
-    }
-}
-
-// Export for use in other modules
-module.exports = { DependencyValidator };
-
-// Run if called directly
-if (require.main === module) {
-    main();
-}
@@ -1,135 +0,0 @@
-import os
-import re
-import sys
-from pathlib import Path
-
-# Configuration - default base directory, can be overridden via CLI argument
-DEFAULT_BASE_DIR = Path(__file__).resolve().parent.parent.parent / "specs"
-
-DIRECTORIES = [
-    "00-Overview",
-    "01-Requirements",
-    "02-Architecture",
-    "03-Data-and-Storage",
-    "04-Infrastructure-OPS",
-    "05-Engineering-Guidelines",
-    "06-Decision-Records"
-]
-
-LINK_PATTERN = re.compile(r'(\[([^\]]+)\]\(([^)]+)\))')
-
-def get_file_map(base_dir: Path):
-    """Builds a map of {basename}.md -> {prefixed_name}.md across all dirs."""
-    file_map = {}
-    for dir_name in DIRECTORIES:
-        directory = base_dir / dir_name
-        if not directory.exists():
-            continue
-        for file_path in directory.glob("*.md"):
-            actual_name = file_path.name
-            low_name = actual_name.lower()
-
-            # 1. Map actual name
-            file_map[low_name] = f"{dir_name}/{actual_name}"
-
-            # 2. Try to strip prefixes to find base names
-            strip_patterns = [
-                r'^\d+-\d+\.?\d*-?(.*)', # 01-03.1- or 01-01-
-                r'^\d+-(.*)',           # 04-
-                r'^ADR-\d+-(.*)',       # ADR-001-
-            ]
-
-            for pattern in strip_patterns:
-                match = re.match(pattern, actual_name)
-                if match:
-                    base_name = match.group(1).lower()
-                    if base_name:
-                        file_map[base_name] = f"{dir_name}/{actual_name}"
-
-                    # Also map partials like "03.1-project-management.md"
-                    # if the original was "01-03.1-project-management.md"
-                    if pattern == r'^\d+-\d+\.?\d*-?(.*)':
-                        secondary_match = re.match(r'^\d+-(.*)', actual_name)
-                        if secondary_match:
-                            secondary_base = secondary_match.group(1).lower()
-                            if secondary_base:
-                                file_map[secondary_base] = f"{dir_name}/{actual_name}"
-
-    return file_map
-
-def fix_links(base_dir: Path):
-    file_map = get_file_map(base_dir)
-    changes_made = 0
-
-    for dir_name in DIRECTORIES:
-        directory = base_dir / dir_name
-        if not directory.exists():
-            continue
-
-        for file_path in directory.glob("*.md"):
-            with open(file_path, "r", encoding="utf-8") as f:
-                content = f.read()
-
-            new_content = content
-            original_links = LINK_PATTERN.findall(content)
-
-            for full_match, label, target in original_links:
-                if target.startswith("http") or target.startswith("#"):
-                    continue
-
-                # Check if broken
-                target_path = target.split("#")[0]
-                if not target_path:
-                    continue
-
-                # Special case: file:/// absolute paths
-                clean_target_path = re.sub(
-                    r'^file:///[a-zA-Z]:[/\\].*?specs[/\\]',
-                    '',
-                    target_path
-                )
-
-                resolved_locally = (file_path.parent / target_path).resolve()
-                if resolved_locally.exists() and resolved_locally.is_file():
-                    continue # Not broken
-
-                # It's broken, try to fix it
-                target_filename = Path(clean_target_path).name.lower()
-                if target_filename in file_map:
-                    correct_relative_to_specs = file_map[target_filename]
-                    # Calculate relative path from current file's parent to the correct file
-                    correct_abs = (base_dir / correct_relative_to_specs).resolve()
-
-                    try:
-                        new_relative_path = os.path.relpath(correct_abs, file_path.parent).replace(os.sep, "/")
-                        # Re-add anchor if it was there
-                        anchor = target.split("#")[1] if "#" in target else ""
-                        new_target = new_relative_path + (f"#{anchor}" if anchor else "")
-
-                        # Replace in content
-                        old_link = f"({target})"
-                        new_link = f"({new_target})"
-                        new_content = new_content.replace(old_link, new_link)
-                        print(f"Fixed in {file_path.name}: {target} -> {new_target}")
-                    except ValueError:
-                        print(f"Error calculating relpath for {correct_abs} from {file_path.parent}")
-
-            if new_content != content:
-                with open(file_path, "w", encoding="utf-8") as f:
-                    f.write(new_content)
-                changes_made += 1
-
-    print(f"\nTotal files updated: {changes_made}")
-
-if __name__ == "__main__":
-    if len(sys.argv) > 1:
-        base_dir = Path(sys.argv[1])
-    else:
-        base_dir = DEFAULT_BASE_DIR
-
-    if not base_dir.exists():
-        print(f"Error: Directory not found: {base_dir}", file=sys.stderr)
-        sys.exit(1)
-
-    print(f"Scanning specs directory: {base_dir}")
-    fix_links(base_dir)
@@ -1,369 +0,0 @@
-#!/usr/bin/env node
-
-/**
- * health-monitor.js - Automated health monitoring system for .agents
- * Part of LCBP3-DMS Phase 3 enhancements
- */
-
-const fs = require('fs');
-const path = require('path');
-const { execSync } = require('child_process');
-
-// Configuration
-const BASE_DIR = path.resolve(__dirname, '../..');
-const AGENTS_DIR = path.join(BASE_DIR, '.agents');
-const HEALTH_LOG_PATH = path.join(AGENTS_DIR, 'logs', 'health.log');
-const HEALTH_REPORT_PATH = path.join(AGENTS_DIR, 'reports', 'health-report.json');
-
-// Ensure directories exist
-[ path.dirname(HEALTH_LOG_PATH), path.dirname(HEALTH_REPORT_PATH) ].forEach(dir => {
-    if (!fs.existsSync(dir)) {
-        fs.mkdirSync(dir, { recursive: true });
-    }
-});
-
-// Health monitoring class
-class HealthMonitor {
-    constructor() {
-        this.startTime = new Date();
-        this.metrics = {
-            timestamp: this.startTime.toISOString(),
-            version: '1.8.6',
-            checks: {},
-            summary: {
-                total_checks: 0,
-                passed_checks: 0,
-                failed_checks: 0,
-                warnings: 0,
-                overall_health: 'unknown'
-            }
-        };
-    }
-
-    log(message, level = 'info') {
-        const timestamp = new Date().toISOString();
-        const logEntry = `[${timestamp}] [${level.toUpperCase()}] ${message}\n`;
-        
-        // Console output with colors
-        const colors = {
-            info: '\x1b[36m',    // Cyan
-            pass: '\x1b[32m',    // Green
-            fail: '\x1b[31m',    // Red
-            warn: '\x1b[33m',    // Yellow
-            reset: '\x1b[0m'
-        };
-        
-        const color = colors[level] || colors.info;
-        console.log(`${color}${logEntry.trim()}${colors.reset}`);
-        
-        // File logging
-        fs.appendFileSync(HEALTH_LOG_PATH, logEntry);
-    }
-
-    checkDirectoryExists(dirPath, checkName) {
-        this.metrics.summary.total_checks++;
-        const exists = fs.existsSync(dirPath);
-        
-        this.metrics.checks[checkName] = {
-            type: 'directory_exists',
-            status: exists ? 'pass' : 'fail',
-            path: dirPath,
-            message: exists ? 'Directory exists' : 'Directory missing'
-        };
-        
-        if (exists) {
-            this.metrics.summary.passed_checks++;
-            this.log(`${checkName}: PASS - Directory exists`, 'pass');
-        } else {
-            this.metrics.summary.failed_checks++;
-            this.log(`${checkName}: FAIL - Directory missing: ${dirPath}`, 'fail');
-        }
-        
-        return exists;
-    }
-
-    checkFileExists(filePath, checkName) {
-        this.metrics.summary.total_checks++;
-        const exists = fs.existsSync(filePath);
-        
-        this.metrics.checks[checkName] = {
-            type: 'file_exists',
-            status: exists ? 'pass' : 'fail',
-            path: filePath,
-            message: exists ? 'File exists' : 'File missing'
-        };
-        
-        if (exists) {
-            this.metrics.summary.passed_checks++;
-            this.log(`${checkName}: PASS - File exists`, 'pass');
-        } else {
-            this.metrics.summary.failed_checks++;
-            this.log(`${checkName}: FAIL - File missing: ${filePath}`, 'fail');
-        }
-        
-        return exists;
-    }
-
-    checkFileVersion(filePath, expectedVersion, checkName) {
-        this.metrics.summary.total_checks++;
-        
-        if (!fs.existsSync(filePath)) {
-            this.metrics.summary.failed_checks++;
-            this.metrics.checks[checkName] = {
-                type: 'version_check',
-                status: 'fail',
-                path: filePath,
-                message: 'File does not exist'
-            };
-            this.log(`${checkName}: FAIL - File not found: ${filePath}`, 'fail');
-            return false;
-        }
-        
-        try {
-            const content = fs.readFileSync(filePath, 'utf8');
-            const versionMatch = content.match(/v?(\d+\.\d+\.\d+)/);
-            const actualVersion = versionMatch ? versionMatch[1] : 'not_found';
-            const versionMatches = actualVersion === expectedVersion;
-            
-            this.metrics.checks[checkName] = {
-                type: 'version_check',
-                status: versionMatches ? 'pass' : 'fail',
-                path: filePath,
-                expected_version: expectedVersion,
-                actual_version: actualVersion,
-                message: versionMatches ? 'Version matches' : `Version mismatch (expected ${expectedVersion}, found ${actualVersion})`
-            };
-            
-            if (versionMatches) {
-                this.metrics.summary.passed_checks++;
-                this.log(`${checkName}: PASS - Version ${actualVersion}`, 'pass');
-            } else {
-                this.metrics.summary.failed_checks++;
-                this.log(`${checkName}: FAIL - Version mismatch (expected ${expectedVersion}, found ${actualVersion})`, 'fail');
-            }
-            
-            return versionMatches;
-        } catch (error) {
-            this.metrics.summary.failed_checks++;
-            this.metrics.checks[checkName] = {
-                type: 'version_check',
-                status: 'fail',
-                path: filePath,
-                message: `Error reading file: ${error.message}`
-            };
-            this.log(`${checkName}: FAIL - Error reading file: ${error.message}`, 'fail');
-            return false;
-        }
-    }
-
-    checkSkillHealth() {
-        this.log('Checking skill health...', 'info');
-        const skillsDir = path.join(AGENTS_DIR, 'skills');
-        
-        if (!fs.existsSync(skillsDir)) {
-            this.log('Skills directory not found', 'fail');
-            return;
-        }
-        
-        const skillDirs = fs.readdirSync(skillsDir).filter(item => {
-            const itemPath = path.join(skillsDir, item);
-            return fs.statSync(itemPath).isDirectory();
-        });
-        
-        this.metrics.checks['skill_count'] = {
-            type: 'skill_count',
-            status: skillDirs.length >= 20 ? 'pass' : 'warn',
-            count: skillDirs.length,
-            expected: 20,
-            message: `Found ${skillDirs.length} skills (expected at least 20)`
-        };
-        
-        if (skillDirs.length >= 20) {
-            this.metrics.summary.passed_checks++;
-            this.log(`Skill count: PASS - Found ${skillDirs.length} skills`, 'pass');
-        } else {
-            this.metrics.summary.warnings++;
-            this.log(`Skill count: WARN - Only ${skillDirs.length} skills found (expected at least 20)`, 'warn');
-        }
-        
-        // Check individual skills
-        let healthySkills = 0;
-        skillDirs.forEach(skillDir => {
-            const skillPath = path.join(skillsDir, skillDir);
-            const skillMdPath = path.join(skillPath, 'SKILL.md');
-            
-            if (fs.existsSync(skillMdPath)) {
-                try {
-                    const content = fs.readFileSync(skillMdPath, 'utf8');
-                    const hasName = content.includes('name:');
-                    const hasDescription = content.includes('description:');
-                    const hasVersion = content.includes('version:');
-                    const hasRole = content.includes('## Role');
-                    const hasTask = content.includes('## Task');
-                    
-                    const isHealthy = hasName && hasDescription && hasVersion && hasRole && hasTask;
-                    if (isHealthy) healthySkills++;
-                    
-                    this.metrics.checks[`skill_${skillDir}_health`] = {
-                        type: 'skill_health',
-                        status: isHealthy ? 'pass' : 'fail',
-                        skill: skillDir,
-                        has_name: hasName,
-                        has_description: hasDescription,
-                        has_version: hasVersion,
-                        has_role: hasRole,
-                        has_task: hasTask,
-                        message: isHealthy ? 'Skill is healthy' : 'Skill has missing sections'
-                    };
-                } catch (error) {
-                    this.metrics.checks[`skill_${skillDir}_health`] = {
-                        type: 'skill_health',
-                        status: 'fail',
-                        skill: skillDir,
-                        message: `Error reading skill: ${error.message}`
-                    };
-                }
-            }
-        });
-        
-        this.metrics.summary.total_checks++;
-        if (healthySkills === skillDirs.length) {
-            this.metrics.summary.passed_checks++;
-            this.log(`Individual skills: PASS - All ${healthySkills} skills are healthy`, 'pass');
-        } else {
-            this.metrics.summary.failed_checks++;
-            this.log(`Individual skills: FAIL - Only ${healthySkills}/${skillDirs.length} skills are healthy`, 'fail');
-        }
-    }
-
-    checkWorkflowHealth() {
-        this.log('Checking workflow health...', 'info');
-        const workflowsDir = path.join(BASE_DIR, '.windsurf', 'workflows');
-        
-        if (!fs.existsSync(workflowsDir)) {
-            this.log('Workflows directory not found', 'fail');
-            return;
-        }
-        
-        const workflowFiles = fs.readdirSync(workflowsDir).filter(file => file.endsWith('.md'));
-        
-        this.metrics.checks['workflow_count'] = {
-            type: 'workflow_count',
-            status: workflowFiles.length >= 20 ? 'pass' : 'warn',
-            count: workflowFiles.length,
-            expected: 20,
-            message: `Found ${workflowFiles.length} workflows (expected at least 20)`
-        };
-        
-        if (workflowFiles.length >= 20) {
-            this.metrics.summary.passed_checks++;
-            this.log(`Workflow count: PASS - Found ${workflowFiles.length} workflows`, 'pass');
-        } else {
-            this.metrics.summary.warnings++;
-            this.log(`Workflow count: WARN - Only ${workflowFiles.length} workflows found (expected at least 20)`, 'warn');
-        }
-    }
-
-    calculateOverallHealth() {
-        const { total_checks, passed_checks, failed_checks, warnings } = this.metrics.summary;
-        
-        if (failed_checks === 0) {
-            this.metrics.summary.overall_health = warnings === 0 ? 'excellent' : 'good';
-        } else if (failed_checks <= total_checks * 0.1) {
-            this.metrics.summary.overall_health = 'fair';
-        } else {
-            this.metrics.summary.overall_health = 'poor';
-        }
-        
-        this.log(`Overall health: ${this.metrics.summary.overall_health}`, 'info');
-    }
-
-    generateReport() {
-        const report = {
-            ...this.metrics,
-            duration: new Date() - this.startTime,
-            environment: {
-                node_version: process.version,
-                platform: process.platform,
-                agents_dir: AGENTS_DIR
-            }
-        };
-        
-        fs.writeFileSync(HEALTH_REPORT_PATH, JSON.stringify(report, null, 2));
-        this.log(`Health report saved to: ${HEALTH_REPORT_PATH}`, 'info');
-        
-        return report;
-    }
-
-    async runFullHealthCheck() {
-        this.log('Starting comprehensive health check...', 'info');
-        this.log(`Base directory: ${BASE_DIR}`, 'info');
-        
-        // Core directory checks
-        this.checkDirectoryExists(AGENTS_DIR, 'agents_directory');
-        this.checkDirectoryExists(path.join(AGENTS_DIR, 'skills'), 'skills_directory');
-        this.checkDirectoryExists(path.join(AGENTS_DIR, 'scripts'), 'scripts_directory');
-        this.checkDirectoryExists(path.join(AGENTS_DIR, 'rules'), 'rules_directory');
-        this.checkDirectoryExists(path.join(BASE_DIR, '.windsurf', 'workflows'), 'workflows_directory');
-        
-        // Core file checks
-        this.checkFileExists(path.join(AGENTS_DIR, 'README.md'), 'readme_file');
-        this.checkFileExists(path.join(AGENTS_DIR, 'skills', 'VERSION'), 'skills_version_file');
-        this.checkFileExists(path.join(AGENTS_DIR, 'skills', 'skills.md'), 'skills_documentation');
-        
-        // Version consistency checks
-        this.checkFileVersion(path.join(AGENTS_DIR, 'README.md'), '1.8.6', 'readme_version');
-        this.checkFileVersion(path.join(AGENTS_DIR, 'skills', 'VERSION'), '1.8.6', 'skills_version_file_version');
-        this.checkFileVersion(path.join(AGENTS_DIR, 'skills', 'skills.md'), '1.8.6', 'skills_documentation_version');
-        this.checkFileVersion(path.join(AGENTS_DIR, 'rules', '00-project-context.md'), '1.8.6', 'project_context_version');
-        
-        // Script availability checks
-        this.checkFileExists(path.join(AGENTS_DIR, 'scripts', 'bash', 'validate-versions.sh'), 'bash_version_script');
-        this.checkFileExists(path.join(AGENTS_DIR, 'scripts', 'bash', 'audit-skills.sh'), 'bash_audit_script');
-        this.checkFileExists(path.join(AGENTS_DIR, 'scripts', 'bash', 'sync-workflows.sh'), 'bash_sync_script');
-        this.checkFileExists(path.join(AGENTS_DIR, 'scripts', 'powershell', 'validate-versions.ps1'), 'powershell_version_script');
-        this.checkFileExists(path.join(AGENTS_DIR, 'scripts', 'powershell', 'audit-skills.ps1'), 'powershell_audit_script');
-        
-        // Detailed health checks
-        this.checkSkillHealth();
-        this.checkWorkflowHealth();
-        
-        // Calculate overall health
-        this.calculateOverallHealth();
-        
-        // Generate report
-        const report = this.generateReport();
-        
-        // Summary
-        this.log('=== Health Check Summary ===', 'info');
-        this.log(`Total checks: ${this.metrics.summary.total_checks}`, 'info');
-        this.log(`Passed: ${this.metrics.summary.passed_checks}`, 'pass');
-        this.log(`Failed: ${this.metrics.summary.failed_checks}`, this.metrics.summary.failed_checks > 0 ? 'fail' : 'info');
-        this.log(`Warnings: ${this.metrics.summary.warnings}`, 'warn');
-        this.log(`Overall health: ${this.metrics.summary.overall_health}`, 'info');
-        this.log(`Duration: ${new Date() - this.startTime}ms`, 'info');
-        
-        return report;
-    }
-}
-
-// CLI interface
-async function main() {
-    const monitor = new HealthMonitor();
-    
-    try {
-        const report = await monitor.runFullHealthCheck();
-        process.exit(report.summary.failed_checks > 0 ? 1 : 0);
-    } catch (error) {
-        console.error('Health check failed:', error);
-        process.exit(1);
-    }
-}
-
-// Export for use in other modules
-module.exports = { HealthMonitor };
-
-// Run if called directly
-if (require.main === module) {
-    main();
-}
@@ -1,494 +0,0 @@
-#!/usr/bin/env node
-
-/**
- * performance-monitor.js - Performance monitoring for .agents skills
- * Part of LCBP3-DMS Phase 3 enhancements
- */
-
-const fs = require('fs');
-const path = require('path');
-const { performance } = require('perf_hooks');
-
-// Configuration
-const BASE_DIR = path.resolve(__dirname, '../..');
-const AGENTS_DIR = path.join(BASE_DIR, '.agents');
-const SKILLS_DIR = path.join(AGENTS_DIR, 'skills');
-const PERFORMANCE_LOG_PATH = path.join(AGENTS_DIR, 'logs', 'performance.log');
-const PERFORMANCE_REPORT_PATH = path.join(AGENTS_DIR, 'reports', 'performance-report.json');
-
-// Ensure directories exist
-[ path.dirname(PERFORMANCE_LOG_PATH), path.dirname(PERFORMANCE_REPORT_PATH) ].forEach(dir => {
-    if (!fs.existsSync(dir)) {
-        fs.mkdirSync(dir, { recursive: true });
-    }
-});
-
-// Performance monitoring class
-class PerformanceMonitor {
-    constructor() {
-        this.startTime = performance.now();
-        this.metrics = {
-            timestamp: new Date().toISOString(),
-            duration: 0,
-            skill_metrics: {},
-            workflow_metrics: {},
-            system_metrics: {},
-            summary: {
-                total_skills_analyzed: 0,
-                total_workflows_analyzed: 0,
-                average_skill_size: 0,
-                average_workflow_size: 0,
-                performance_score: 0,
-                recommendations: []
-            }
-        };
-    }
-
-    log(message, level = 'info') {
-        const timestamp = new Date().toISOString();
-        const logEntry = `[${timestamp}] [${level.toUpperCase()}] ${message}\n`;
-        
-        // Console output with colors
-        const colors = {
-            info: '\x1b[36m',    // Cyan
-            good: '\x1b[32m',    // Green
-            warn: '\x1b[33m',    // Yellow
-            poor: '\x1b[31m',    // Red
-            reset: '\x1b[0m'
-        };
-        
-        const color = colors[level] || colors.info;
-        console.log(`${color}${logEntry.trim()}${colors.reset}`);
-        
-        // File logging
-        fs.appendFileSync(PERFORMANCE_LOG_PATH, logEntry);
-    }
-
-    analyzeSkillPerformance(skillPath, skillName) {
-        const skillMdPath = path.join(skillPath, 'SKILL.md');
-        
-        if (!fs.existsSync(skillMdPath)) {
-            this.log(`Skipping ${skillName} - SKILL.md not found`, 'warn');
-            return null;
-        }
-
-        const startTime = performance.now();
-        
-        try {
-            const stats = fs.statSync(skillMdPath);
-            const content = fs.readFileSync(skillMdPath, 'utf8');
-            
-            // Basic metrics
-            const fileSizeKB = stats.size / 1024;
-            const lineCount = content.split('\n').length;
-            const wordCount = content.split(/\s+/).filter(word => word.length > 0).length;
-            const charCount = content.length;
-            
-            // Content complexity metrics
-            const sectionCount = (content.match(/^#+\s/gm) || []).length;
-            const codeBlockCount = (content.match(/```[\s\S]*?```/g) || []).length;
-            const listCount = (content.match(/^[-*+]\s/gm) || []).length;
-            
-            // Front matter analysis
-            const frontMatterMatch = content.match(/^---\n([\s\S]*?)\n---/);
-            const frontMatterSize = frontMatterMatch ? frontMatterMatch[1].length : 0;
-            const hasFrontMatter = frontMatterMatch !== null;
-            
-            // Readability metrics
-            const sentences = content.split(/[.!?]+/).filter(s => s.trim().length > 0);
-            const avgWordsPerSentence = sentences.length > 0 ? wordCount / sentences.length : 0;
-            const avgCharsPerWord = wordCount > 0 ? charCount / wordCount : 0;
-            
-            // Performance score calculation
-            let performanceScore = 100;
-            
-            // Size penalties
-            if (fileSizeKB > 50) performanceScore -= 10;
-            if (fileSizeKB > 100) performanceScore -= 20;
-            
-            // Content quality bonuses
-            if (hasFrontMatter) performanceScore += 5;
-            if (sectionCount >= 3) performanceScore += 5;
-            if (codeBlockCount > 0) performanceScore += 5;
-            
-            // Readability penalties
-            if (avgWordsPerSentence > 25) performanceScore -= 5;
-            if (avgWordsPerSentence > 35) performanceScore -= 10;
-            
-            const analysisTime = performance.now() - startTime;
-            
-            const skillMetrics = {
-                skill_name: skillName,
-                file_path: skillMdPath,
-                file_size_kb: Math.round(fileSizeKB * 100) / 100,
-                line_count: lineCount,
-                word_count: wordCount,
-                char_count: charCount,
-                section_count: sectionCount,
-                code_block_count: codeBlockCount,
-                list_count: listCount,
-                front_matter_size: frontMatterSize,
-                has_front_matter: hasFrontMatter,
-                avg_words_per_sentence: Math.round(avgWordsPerSentence * 100) / 100,
-                avg_chars_per_word: Math.round(avgCharsPerWord * 100) / 100,
-                performance_score: Math.max(0, Math.min(100, performanceScore)),
-                analysis_time_ms: Math.round(analysisTime * 100) / 100,
-                last_modified: stats.mtime.toISOString()
-            };
-
-            this.metrics.skill_metrics[skillName] = skillMetrics;
-            
-            // Log performance assessment
-            if (performanceScore >= 80) {
-                this.log(`${skillName}: GOOD performance (score: ${performanceScore})`, 'good');
-            } else if (performanceScore >= 60) {
-                this.log(`${skillName}: OK performance (score: ${performanceScore})`, 'info');
-            } else {
-                this.log(`${skillName}: POOR performance (score: ${performanceScore})`, 'poor');
-            }
-
-            return skillMetrics;
-
-        } catch (error) {
-            this.log(`Error analyzing ${skillName}: ${error.message}`, 'warn');
-            return null;
-        }
-    }
-
-    analyzeWorkflowPerformance(workflowPath, workflowName) {
-        const startTime = performance.now();
-        
-        if (!fs.existsSync(workflowPath)) {
-            this.log(`Skipping workflow ${workflowName} - file not found`, 'warn');
-            return null;
-        }
-
-        try {
-            const stats = fs.statSync(workflowPath);
-            const content = fs.readFileSync(workflowPath, 'utf8');
-            
-            // Basic metrics
-            const fileSizeKB = stats.size / 1024;
-            const lineCount = content.split('\n').length;
-            const wordCount = content.split(/\s+/).filter(word => word.length > 0).length;
-            
-            // Workflow-specific metrics
-            const stepCount = (content.match(/^\d+\./gm) || []).length;
-            const codeBlockCount = (content.match(/```[\s\S]*?```/g) || []).length;
-            const skillReferences = (content.match(/@speckit-\w+/g) || []).length;
-            
-            // Performance score calculation
-            let performanceScore = 100;
-            
-            // Size penalties
-            if (fileSizeKB > 20) performanceScore -= 10;
-            if (fileSizeKB > 50) performanceScore -= 20;
-            
-            // Content quality bonuses
-            if (stepCount > 0) performanceScore += 10;
-            if (codeBlockCount > 0) performanceScore += 5;
-            if (skillReferences > 0) performanceScore += 5;
-            
-            const analysisTime = performance.now() - startTime;
-            
-            const workflowMetrics = {
-                workflow_name: workflowName,
-                file_path: workflowPath,
-                file_size_kb: Math.round(fileSizeKB * 100) / 100,
-                line_count: lineCount,
-                word_count: wordCount,
-                step_count: stepCount,
-                code_block_count: codeBlockCount,
-                skill_references: skillReferences,
-                performance_score: Math.max(0, Math.min(100, performanceScore)),
-                analysis_time_ms: Math.round(analysisTime * 100) / 100,
-                last_modified: stats.mtime.toISOString()
-            };
-
-            this.metrics.workflow_metrics[workflowName] = workflowMetrics;
-            
-            // Log performance assessment
-            if (performanceScore >= 80) {
-                this.log(`${workflowName}: GOOD performance (score: ${performanceScore})`, 'good');
-            } else if (performanceScore >= 60) {
-                this.log(`${workflowName}: OK performance (score: ${performanceScore})`, 'info');
-            } else {
-                this.log(`${workflowName}: POOR performance (score: ${performanceScore})`, 'poor');
-            }
-
-            return workflowMetrics;
-
-        } catch (error) {
-            this.log(`Error analyzing workflow ${workflowName}: ${error.message}`, 'warn');
-            return null;
-        }
-    }
-
-    analyzeSystemMetrics() {
-        this.log('Analyzing system metrics...', 'info');
-        
-        // Directory sizes
-        const agentsSize = this.getDirectorySize(AGENTS_DIR);
-        const skillsSize = this.getDirectorySize(SKILLS_DIR);
-        const workflowsDir = path.join(BASE_DIR, '.windsurf', 'workflows');
-        const workflowsSize = fs.existsSync(workflowsDir) ? this.getDirectorySize(workflowsDir) : 0;
-        
-        // File counts
-        const totalFiles = this.countFiles(AGENTS_DIR);
-        const skillFiles = this.countFiles(SKILLS_DIR);
-        const workflowFiles = fs.existsSync(workflowsDir) ? this.countFiles(workflowsDir) : 0;
-        
-        this.metrics.system_metrics = {
-            agents_directory_size_kb: Math.round(agentsSize / 1024),
-            skills_directory_size_kb: Math.round(skillsSize / 1024),
-            workflows_directory_size_kb: Math.round(workflowsSize / 1024),
-            total_files: totalFiles,
-            skill_files: skillFiles,
-            workflow_files: workflowFiles,
-            analysis_timestamp: new Date().toISOString()
-        };
-        
-        this.log(`System: ${totalFiles} files, ${Math.round(agentsSize / 1024)}KB total`, 'info');
-    }
-
-    getDirectorySize(dirPath) {
-        let totalSize = 0;
-        
-        if (!fs.existsSync(dirPath)) {
-            return 0;
-        }
-        
-        const items = fs.readdirSync(dirPath);
-        
-        for (const item of items) {
-            const itemPath = path.join(dirPath, item);
-            const stats = fs.statSync(itemPath);
-            
-            if (stats.isDirectory()) {
-                totalSize += this.getDirectorySize(itemPath);
-            } else {
-                totalSize += stats.size;
-            }
-        }
-        
-        return totalSize;
-    }
-
-    countFiles(dirPath) {
-        let fileCount = 0;
-        
-        if (!fs.existsSync(dirPath)) {
-            return 0;
-        }
-        
-        const items = fs.readdirSync(dirPath);
-        
-        for (const item of items) {
-            const itemPath = path.join(dirPath, item);
-            const stats = fs.statSync(itemPath);
-            
-            if (stats.isDirectory()) {
-                fileCount += this.countFiles(itemPath);
-            } else {
-                fileCount++;
-            }
-        }
-        
-        return fileCount;
-    }
-
-    generateRecommendations() {
-        const recommendations = [];
-        const { skill_metrics, workflow_metrics, system_metrics } = this.metrics;
-        
-        // Analyze skill performance
-        const skillScores = Object.values(skill_metrics).map(m => m.performance_score);
-        const avgSkillScore = skillScores.length > 0 ? skillScores.reduce((a, b) => a + b, 0) / skillScores.length : 0;
-        
-        if (avgSkillScore < 70) {
-            recommendations.push({
-                type: 'performance',
-                priority: 'high',
-                message: 'Average skill performance is below optimal. Consider optimizing skill documentation.',
-                details: `Average score: ${Math.round(avgSkillScore)}`
-            });
-        }
-        
-        // Check for oversized files
-        const largeSkills = Object.values(skill_metrics).filter(m => m.file_size_kb > 50);
-        if (largeSkills.length > 0) {
-            recommendations.push({
-                type: 'size',
-                priority: 'medium',
-                message: `${largeSkills.length} skills have large file sizes (>50KB). Consider breaking down complex skills.`,
-                details: largeSkills.map(s => `${s.skill_name} (${s.file_size_kb}KB)`).join(', ')
-            });
-        }
-        
-        // Check for missing front matter
-        const skillsWithoutFrontMatter = Object.values(skill_metrics).filter(m => !m.has_front_matter);
-        if (skillsWithoutFrontMatter.length > 0) {
-            recommendations.push({
-                type: 'structure',
-                priority: 'high',
-                message: `${skillsWithoutFrontMatter.length} skills missing front matter. Add proper YAML front matter.`,
-                details: skillsWithoutFrontMatter.map(s => s.skill_name).join(', ')
-            });
-        }
-        
-        // Analyze workflow performance
-        const workflowScores = Object.values(workflow_metrics).map(m => m.performance_score);
-        const avgWorkflowScore = workflowScores.length > 0 ? workflowScores.reduce((a, b) => a + b, 0) / workflowScores.length : 0;
-        
-        if (avgWorkflowScore < 70) {
-            recommendations.push({
-                type: 'performance',
-                priority: 'medium',
-                message: 'Average workflow performance could be improved. Add more detailed steps and examples.',
-                details: `Average score: ${Math.round(avgWorkflowScore)}`
-            });
-        }
-        
-        // System recommendations
-        if (system_metrics.agents_directory_size_kb > 1000) {
-            recommendations.push({
-                type: 'maintenance',
-                priority: 'low',
-                message: '.agents directory is growing large. Consider archiving old logs and reports.',
-                details: `Current size: ${system_metrics.agents_directory_size_kb}KB`
-            });
-        }
-        
-        this.metrics.summary.recommendations = recommendations;
-        
-        // Log recommendations
-        if (recommendations.length > 0) {
-            this.log('Performance Recommendations:', 'info');
-            recommendations.forEach((rec, index) => {
-                const priority = rec.priority === 'high' ? 'HIGH' : rec.priority === 'medium' ? 'MED' : 'LOW';
-                this.log(`  ${index + 1}. [${priority}] ${rec.message}`, 'warn');
-            });
-        } else {
-            this.log('No performance issues detected - system is optimized!', 'good');
-        }
-    }
-
-    calculateOverallPerformance() {
-        const { skill_metrics, workflow_metrics } = this.metrics;
-        
-        const skillScores = Object.values(skill_metrics).map(m => m.performance_score);
-        const workflowScores = Object.values(workflow_metrics).map(m => m.performance_score);
-        
-        const avgSkillScore = skillScores.length > 0 ? skillScores.reduce((a, b) => a + b, 0) / skillScores.length : 100;
-        const avgWorkflowScore = workflowScores.length > 0 ? workflowScores.reduce((a, b) => a + b, 0) / workflowScores.length : 100;
-        
-        // Weight skills more heavily than workflows
-        const overallScore = (avgSkillScore * 0.7) + (avgWorkflowScore * 0.3);
-        
-        this.metrics.summary.performance_score = Math.round(overallScore);
-        this.metrics.summary.average_skill_size = skillScores.length > 0 
-            ? Math.round(Object.values(skill_metrics).reduce((sum, m) => sum + m.file_size_kb, 0) / skillScores.length * 100) / 100
-            : 0;
-        this.metrics.summary.average_workflow_size = workflowScores.length > 0
-            ? Math.round(Object.values(workflow_metrics).reduce((sum, m) => sum + m.file_size_kb, 0) / workflowScores.length * 100) / 100
-            : 0;
-        this.metrics.summary.total_skills_analyzed = skillScores.length;
-        this.metrics.summary.total_workflows_analyzed = workflowScores.length;
-    }
-
-    generateReport() {
-        this.metrics.duration = performance.now() - this.startTime;
-        
-        const report = {
-            ...this.metrics,
-            generated_at: new Date().toISOString(),
-            environment: {
-                node_version: process.version,
-                platform: process.platform,
-                memory_usage: process.memoryUsage()
-            }
-        };
-        
-        fs.writeFileSync(PERFORMANCE_REPORT_PATH, JSON.stringify(report, null, 2));
-        this.log(`Performance report saved to: ${PERFORMANCE_REPORT_PATH}`, 'info');
-        
-        return report;
-    }
-
-    async runPerformanceAnalysis() {
-        this.log('Starting performance analysis...', 'info');
-        this.log(`Base directory: ${BASE_DIR}`, 'info');
-        
-        // Analyze skills
-        this.log('Analyzing skill performance...', 'info');
-        if (fs.existsSync(SKILLS_DIR)) {
-            const skillDirs = fs.readdirSync(SKILLS_DIR).filter(item => {
-                const itemPath = path.join(SKILLS_DIR, item);
-                return fs.statSync(itemPath).isDirectory();
-            });
-
-            for (const skillDir of skillDirs) {
-                const skillPath = path.join(SKILLS_DIR, skillDir);
-                this.analyzeSkillPerformance(skillPath, skillDir);
-            }
-        }
-
-        // Analyze workflows
-        this.log('Analyzing workflow performance...', 'info');
-        const workflowsDir = path.join(BASE_DIR, '.windsurf', 'workflows');
-        if (fs.existsSync(workflowsDir)) {
-            const workflowFiles = fs.readdirSync(workflowsDir).filter(file => file.endsWith('.md'));
-            
-            for (const workflowFile of workflowFiles) {
-                const workflowPath = path.join(workflowsDir, workflowFile);
-                const workflowName = workflowFile.replace('.md', '');
-                this.analyzeWorkflowPerformance(workflowPath, workflowName);
-            }
-        }
-
-        // System metrics
-        this.analyzeSystemMetrics();
-
-        // Calculate overall performance
-        this.calculateOverallPerformance();
-
-        // Generate recommendations
-        this.generateRecommendations();
-
-        // Generate report
-        const report = this.generateReport();
-
-        // Summary
-        this.log('=== Performance Analysis Summary ===', 'info');
-        this.log(`Overall performance score: ${this.metrics.summary.performance_score}/100`, 'info');
-        this.log(`Skills analyzed: ${this.metrics.summary.total_skills_analyzed}`, 'info');
-        this.log(`Workflows analyzed: ${this.metrics.summary.total_workflows_analyzed}`, 'info');
-        this.log(`Average skill size: ${this.metrics.summary.average_skill_size}KB`, 'info');
-        this.log(`Average workflow size: ${this.metrics.summary.average_workflow_size}KB`, 'info');
-        this.log(`Analysis duration: ${Math.round(this.metrics.duration)}ms`, 'info');
-        this.log(`Recommendations: ${this.metrics.summary.recommendations.length}`, 'info');
-
-        return report;
-    }
-}
-
-// CLI interface
-async function main() {
-    const monitor = new PerformanceMonitor();
-    
-    try {
-        const report = await monitor.runPerformanceAnalysis();
-        process.exit(report.summary.performance_score < 60 ? 1 : 0);
-    } catch (error) {
-        console.error('Performance analysis failed:', error);
-        process.exit(1);
-    }
-}
-
-// Export for use in other modules
-module.exports = { PerformanceMonitor };
-
-// Run if called directly
-if (require.main === module) {
-    main();
-}
@@ -1,198 +0,0 @@
-# audit-skills.ps1 - Verify skill completeness and health
-# Part of LCBP3-DMS Phase 2 improvements
-
-param(
-    [string]$BaseDir = (Split-Path -Parent (Split-Path -Parent (Split-Path -Parent $PSScriptRoot)))
-)
-
-# Map to ConsoleColor enum (Write-Host expects enum, not ANSI strings)
-$Colors = @{
-    Red = 'Red'
-    Green = 'Green'
-    Yellow = 'Yellow'
-    Blue = 'Blue'
-    NoColor = 'Gray'
-}
-
-$AgentsDir = Join-Path $BaseDir ".agents"
-$SkillsDir = Join-Path $AgentsDir "skills"
-
-Write-Host "=== Skills Health Audit ===" -ForegroundColor Cyan
-Write-Host "Base directory: $BaseDir"
-Write-Host ""
-
-# Function to check if skill has required files
-function Test-SkillHealth {
-    param(
-        [string]$SkillDir
-    )
-
-    $skillName = Split-Path $SkillDir -Leaf
-    $issues = 0
-
-    # Check for SKILL.md
-    $skillFile = Join-Path $SkillDir "SKILL.md"
-    if (Test-Path $skillFile) {
-        Write-Host "  OK: $skillName/SKILL.md" -ForegroundColor $Colors.Green
-    } else {
-        Write-Host "  MISSING: $skillName/SKILL.md" -ForegroundColor $Colors.Red
-        $issues++
-    }
-
-    # Check for templates directory (optional)
-    $templatesDir = Join-Path $SkillDir "templates"
-    if (Test-Path $templatesDir) {
-        $templateCount = (Get-ChildItem -Path $templatesDir -Filter "*.md" -File | Measure-Object).Count
-        if ($templateCount -gt 0) {
-            Write-Host "  OK: $skillName/templates ($templateCount files)" -ForegroundColor $Colors.Green
-        } else {
-            Write-Host "  EMPTY: $skillName/templates (no files)" -ForegroundColor $Colors.Yellow
-        }
-    }
-
-    # Check SKILL.md content if exists
-    if (Test-Path $skillFile) {
-        $content = Get-Content $skillFile -Raw
-
-        # Check for required front matter fields
-        $requiredFields = @('name', 'description', 'version')
-        foreach ($field in $requiredFields) {
-            $pattern = "(?m)^${field}:"
-            if ($content -match $pattern) {
-                Write-Host "    FIELD: $field" -ForegroundColor $Colors.Green
-            } else {
-                Write-Host "    MISSING FIELD: $field" -ForegroundColor $Colors.Red
-                $issues++
-            }
-        }
-
-        # Check for LCBP3 context reference (speckit-* skills)
-        if ($skillName -like 'speckit-*') {
-            if ($content -match '_LCBP3-CONTEXT\.md') {
-                Write-Host "    CONTEXT: LCBP3 appendix referenced" -ForegroundColor $Colors.Green
-            } else {
-                Write-Host "    MISSING: LCBP3 context reference" -ForegroundColor $Colors.Yellow
-                $issues++
-            }
-        }
-    }
-
-    return $issues
-}
-
-# Function to get skill version from SKILL.md
-function Get-SkillVersion {
-    param(
-        [string]$SkillFile
-    )
-
-    if (Test-Path $SkillFile) {
-        try {
-            $content = Get-Content $SkillFile -Raw
-            if ($content -match "(?m)^version:\s*['""]?([0-9]+\.[0-9]+\.[0-9]+)['""]?") {
-                return $matches[1].Trim()
-            }
-        } catch {
-            return "error"
-        }
-    }
-    return "no_file"
-}
-
-# Check skills directory
-if (-not (Test-Path $SkillsDir)) {
-    Write-Host "ERROR: Skills directory not found" -ForegroundColor $Colors.Red
-    exit 1
-}
-
-Write-Host "Scanning skills directory: $SkillsDir"
-Write-Host ""
-
-# Get all skill directories
-$skillDirs = Get-ChildItem -Path $SkillsDir -Directory | Sort-Object Name
-
-Write-Host "Found $($skillDirs.Count) skill directories"
-Write-Host ""
-
-# Audit each skill
-$totalIssues = 0
-$skillSummary = @()
-
-foreach ($skillDir in $skillDirs) {
-    $skillName = $skillDir.Name
-    Write-Host "Auditing: $skillName"
-    Write-Host "------------------------"
-
-    $issues = Test-SkillHealth -SkillDir $skillDir.FullName
-
-    $skillVersion = Get-SkillVersion -SkillFile (Join-Path $skillDir.FullName "SKILL.md")
-    $skillSummary += @{
-        Name = $skillName
-        Issues = $issues
-        Version = $skillVersion
-    }
-
-    $totalIssues += $issues
-    Write-Host ""
-}
-
-# Summary report
-Write-Host "=== Skills Audit Summary ===" -ForegroundColor Cyan
-Write-Host ""
-
-Write-Host "Skill Status:"
-Write-Host "-----------"
-foreach ($summary in $skillSummary) {
-    if ($summary.Issues -eq 0) {
-        Write-Host "  HEALTHY: $($summary.Name) (v$($summary.Version))" -ForegroundColor $Colors.Green
-    } else {
-        Write-Host "  ISSUES: $($summary.Name) (v$($summary.Version)) - $($summary.Issues) issues" -ForegroundColor $Colors.Red
-    }
-}
-
-Write-Host ""
-
-# Check skills.md version consistency
-$skillsVersionFile = Join-Path $SkillsDir "VERSION"
-if (Test-Path $skillsVersionFile) {
-    $content = Get-Content $skillsVersionFile -Raw
-    if ($content -match "^version:\s*(.+)") {
-        $globalVersion = $matches[1].Trim()
-        Write-Host "Global skills version: v$globalVersion"
-        Write-Host ""
-
-        # Check for version mismatches
-        Write-Host "Version Consistency Check:"
-        Write-Host "------------------------"
-        $versionMismatches = 0
-
-        foreach ($summary in $skillSummary) {
-            if ($summary.Version -ne "unknown" -and $summary.Version -ne "no_file" -and $summary.Version -ne $globalVersion) {
-                Write-Host "  MISMATCH: $($summary.Name) is v$($summary.Version), global is v$globalVersion" -ForegroundColor $Colors.Yellow
-                $versionMismatches++
-            }
-        }
-
-        if ($versionMismatches -eq 0) {
-            Write-Host "  All skills match global version" -ForegroundColor $Colors.Green
-        }
-    }
-}
-
-Write-Host ""
-
-# Overall health
-if ($totalIssues -eq 0) {
-    Write-Host "=== SUCCESS: All skills healthy ===" -ForegroundColor $Colors.Green
-    Write-Host "Total skills: $($skillDirs.Count)"
-    exit 0
-} else {
-    Write-Host "=== ISSUES FOUND: $totalIssues total issues ===" -ForegroundColor $Colors.Red
-    Write-Host ""
-    Write-Host "Recommendations:"
-    Write-Host "1. Fix missing SKILL.md files"
-    Write-Host "2. Add required front matter fields"
-    Write-Host "3. Ensure Role and Task sections exist"
-    Write-Host "4. Align skill versions with global version"
-    exit 1
-}
@@ -1,157 +0,0 @@
-# PowerShell equivalents for key .agents bash scripts
-# These provide Windows-native alternatives for the most commonly used functions
-
-<#
-.SYNOPSIS
-    Common utility functions for Spec-Kit PowerShell scripts.
-.DESCRIPTION
-    PowerShell equivalent of .agents/scripts/bash/common.sh
-    Provides repository root detection, branch identification, and feature path resolution.
-#>
-
-function Get-RepoRoot {
-    try {
-        $root = git rev-parse --show-toplevel 2>$null
-        if ($LASTEXITCODE -eq 0) { return $root.Trim() }
-    } catch {}
-    # Fallback: navigate up from script location
-    return (Resolve-Path "$PSScriptRoot\..\..\..").Path
-}
-
-function Get-CurrentBranch {
-    # Check environment variable first
-    if ($env:SPECIFY_FEATURE) { return $env:SPECIFY_FEATURE }
-
-    try {
-        $branch = git rev-parse --abbrev-ref HEAD 2>$null
-        if ($LASTEXITCODE -eq 0) { return $branch.Trim() }
-    } catch {}
-
-    # Fallback: find latest feature directory
-    $repoRoot = Get-RepoRoot
-    $specsDir = Join-Path $repoRoot "specs"
-    if (Test-Path $specsDir) {
-        $latest = Get-ChildItem -Path $specsDir -Directory |
-            Where-Object { $_.Name -match '^\d{3}-' } |
-            Sort-Object Name -Descending |
-            Select-Object -First 1
-        if ($latest) { return $latest.Name }
-    }
-    return "main"
-}
-
-function Test-HasGit {
-    try {
-        git rev-parse --show-toplevel 2>$null | Out-Null
-        return $LASTEXITCODE -eq 0
-    } catch { return $false }
-}
-
-function Test-FeatureBranch {
-    param([string]$Branch, [bool]$HasGit)
-    if (-not $HasGit) {
-        Write-Warning "[specify] Git repository not detected; skipped branch validation"
-        return $true
-    }
-    if ($Branch -notmatch '^\d{3}-') {
-        Write-Error "Not on a feature branch. Current branch: $Branch"
-        Write-Error "Feature branches should be named like: 001-feature-name"
-        return $false
-    }
-    return $true
-}
-
-function Find-FeatureDir {
-    param([string]$RepoRoot, [string]$BranchName)
-    $specsDir = Join-Path $RepoRoot "specs"
-
-    if ($BranchName -match '^(\d{3})-') {
-        $prefix = $Matches[1]
-        $matches = Get-ChildItem -Path $specsDir -Directory -Filter "$prefix-*" -ErrorAction SilentlyContinue
-        if ($matches.Count -eq 1) { return $matches[0].FullName }
-        if ($matches.Count -gt 1) {
-            Write-Warning "Multiple spec dirs with prefix '$prefix': $($matches.Name -join ', ')"
-        }
-    }
-    return Join-Path $specsDir $BranchName
-}
-
-function Get-FeaturePaths {
-    $repoRoot = Get-RepoRoot
-    $branch = Get-CurrentBranch
-    $hasGit = Test-HasGit
-    $featureDir = Find-FeatureDir -RepoRoot $repoRoot -BranchName $branch
-
-    return [PSCustomObject]@{
-        RepoRoot     = $repoRoot
-        Branch       = $branch
-        HasGit       = $hasGit
-        FeatureDir   = $featureDir
-        FeatureSpec  = Join-Path $featureDir "spec.md"
-        ImplPlan     = Join-Path $featureDir "plan.md"
-        Tasks        = Join-Path $featureDir "tasks.md"
-        Research     = Join-Path $featureDir "research.md"
-        DataModel    = Join-Path $featureDir "data-model.md"
-        Quickstart   = Join-Path $featureDir "quickstart.md"
-        ContractsDir = Join-Path $featureDir "contracts"
-    }
-}
-
-<#
-.SYNOPSIS
-    Check prerequisites for Spec-Kit workflows.
-.DESCRIPTION
-    PowerShell equivalent of .agents/scripts/bash/check-prerequisites.sh
-.PARAMETER RequireTasks
-    Require tasks.md to exist (for implementation phase)
-.PARAMETER IncludeTasks
-    Include tasks.md in available docs list
-.PARAMETER PathsOnly
-    Only output paths, no validation
-.EXAMPLE
-    .\common.ps1
-    $result = Check-Prerequisites -RequireTasks
-#>
-function Check-Prerequisites {
-    param(
-        [switch]$RequireTasks,
-        [switch]$IncludeTasks,
-        [switch]$PathsOnly
-    )
-
-    $paths = Get-FeaturePaths
-    $valid = Test-FeatureBranch -Branch $paths.Branch -HasGit $paths.HasGit
-    if (-not $valid) { throw "Not on a feature branch" }
-
-    if ($PathsOnly) { return $paths }
-
-    # Validate required files
-    if (-not (Test-Path $paths.FeatureDir)) {
-        throw "Feature directory not found: $($paths.FeatureDir). Run /speckit.specify first."
-    }
-    if (-not (Test-Path $paths.ImplPlan)) {
-        throw "plan.md not found. Run /speckit.plan first."
-    }
-    if ($RequireTasks -and -not (Test-Path $paths.Tasks)) {
-        throw "tasks.md not found. Run /speckit.tasks first."
-    }
-
-    # Build available docs list
-    $docs = @()
-    if (Test-Path $paths.Research)  { $docs += "research.md" }
-    if (Test-Path $paths.DataModel) { $docs += "data-model.md" }
-    if ((Test-Path $paths.ContractsDir) -and (Get-ChildItem $paths.ContractsDir -ErrorAction SilentlyContinue)) {
-        $docs += "contracts/"
-    }
-    if (Test-Path $paths.Quickstart) { $docs += "quickstart.md" }
-    if ($IncludeTasks -and (Test-Path $paths.Tasks)) { $docs += "tasks.md" }
-
-    return [PSCustomObject]@{
-        FeatureDir    = $paths.FeatureDir
-        AvailableDocs = $docs
-        Paths         = $paths
-    }
-}
-
-# Export functions when dot-sourced
-Export-ModuleMember -Function * -ErrorAction SilentlyContinue 2>$null
@@ -1,138 +0,0 @@
-<#
-.SYNOPSIS
-    Create a new feature branch and spec directory.
-.DESCRIPTION
-    PowerShell equivalent of .agents/scripts/bash/create-new-feature.sh
-    Creates a numbered feature branch and initializes the spec directory.
-.PARAMETER Description
-    Natural language description of the feature.
-.PARAMETER ShortName
-    Optional custom short name for the branch (2-4 words).
-.PARAMETER Number
-    Optional manual branch number (overrides auto-detection).
-.EXAMPLE
-    .\create-new-feature.ps1 -Description "Add user authentication" -ShortName "user-auth"
-#>
-param(
-    [Parameter(Mandatory = $true, Position = 0)]
-    [string]$Description,
-
-    [string]$ShortName,
-    [int]$Number = 0
-)
-
-$ErrorActionPreference = "Stop"
-
-# Load common functions
-. "$PSScriptRoot\common.ps1"
-
-$repoRoot = Get-RepoRoot
-$hasGit = Test-HasGit
-$specsDir = Join-Path $repoRoot "specs"
-if (-not (Test-Path $specsDir)) { New-Item -ItemType Directory -Path $specsDir | Out-Null }
-
-# Stop words for smart branch name generation
-$stopWords = @('i','a','an','the','to','for','of','in','on','at','by','with','from',
-               'is','are','was','were','be','been','being','have','has','had',
-               'do','does','did','will','would','should','could','can','may','might',
-               'must','shall','this','that','these','those','my','your','our','their',
-               'want','need','add','get','set')
-
-function ConvertTo-BranchName {
-    param([string]$Text)
-    $Text.ToLower() -replace '[^a-z0-9]', '-' -replace '-+', '-' -replace '^-|-$', ''
-}
-
-function Get-SmartBranchName {
-    param([string]$Desc)
-    $words = ($Desc.ToLower() -replace '[^a-z0-9]', ' ').Split(' ', [StringSplitOptions]::RemoveEmptyEntries)
-    $meaningful = $words | Where-Object { $_ -notin $stopWords -and $_.Length -ge 3 } | Select-Object -First 3
-    if ($meaningful.Count -gt 0) { return ($meaningful -join '-') }
-    return ConvertTo-BranchName $Desc
-}
-
-function Get-HighestNumber {
-    param([string]$Dir)
-    $highest = 0
-    if (Test-Path $Dir) {
-        Get-ChildItem -Path $Dir -Directory | ForEach-Object {
-            if ($_.Name -match '^(\d+)-') {
-                $num = [int]$Matches[1]
-                if ($num -gt $highest) { $highest = $num }
-            }
-        }
-    }
-    return $highest
-}
-
-# Generate branch suffix
-if ($ShortName) {
-    $branchSuffix = ConvertTo-BranchName $ShortName
-} else {
-    $branchSuffix = Get-SmartBranchName $Description
-}
-
-# Determine branch number
-if ($Number -gt 0) {
-    $branchNumber = $Number
-} else {
-    $highestSpec = Get-HighestNumber $specsDir
-    $highestBranch = 0
-    if ($hasGit) {
-        try {
-            git fetch --all --prune 2>$null | Out-Null
-            $branches = git branch -a 2>$null
-            foreach ($b in $branches) {
-                $clean = $b.Trim('* ') -replace '^remotes/[^/]+/', ''
-                if ($clean -match '^(\d{3})-') {
-                    $num = [int]$Matches[1]
-                    if ($num -gt $highestBranch) { $highestBranch = $num }
-                }
-            }
-        } catch {}
-    }
-    $branchNumber = [Math]::Max($highestSpec, $highestBranch) + 1
-}
-
-$featureNum = "{0:D3}" -f $branchNumber
-$branchName = "$featureNum-$branchSuffix"
-
-# Truncate if exceeding GitHub's 244-byte limit
-if ($branchName.Length -gt 244) {
-    $maxSuffix = 244 - 4  # 3 digits + 1 hyphen
-    $branchSuffix = $branchSuffix.Substring(0, $maxSuffix).TrimEnd('-')
-    Write-Warning "Branch name truncated to 244 bytes"
-    $branchName = "$featureNum-$branchSuffix"
-}
-
-# Create git branch
-if ($hasGit) {
-    git checkout -b $branchName
-} else {
-    Write-Warning "Git not detected; skipped branch creation for $branchName"
-}
-
-# Create feature directory and spec file
-$featureDir = Join-Path $specsDir $branchName
-New-Item -ItemType Directory -Path $featureDir -Force | Out-Null
-
-$templateFile = Join-Path $repoRoot ".specify" "templates" "spec-template.md"
-$specFile = Join-Path $featureDir "spec.md"
-if (Test-Path $templateFile) {
-    Copy-Item $templateFile $specFile
-} else {
-    New-Item -ItemType File -Path $specFile -Force | Out-Null
-}
-
-$env:SPECIFY_FEATURE = $branchName
-
-# Output
-[PSCustomObject]@{
-    BranchName = $branchName
-    SpecFile   = $specFile
-    FeatureNum = $featureNum
-}
-
-Write-Host "BRANCH_NAME: $branchName"
-Write-Host "SPEC_FILE: $specFile"
-Write-Host "FEATURE_NUM: $featureNum"
@@ -1,110 +0,0 @@
-# validate-versions.ps1 - Check version consistency across .agents files
-# Part of LCBP3-DMS Phase 2 improvements
-
-param(
-    [string]$BaseDir = (Split-Path -Parent (Split-Path -Parent (Split-Path -Parent $PSScriptRoot))),
-    [string]$ExpectedVersion = "1.8.9"
-)
-
-# Map to ConsoleColor enum (Write-Host expects enum, not ANSI)
-$Colors = @{
-    Red = 'Red'
-    Green = 'Green'
-    Yellow = 'Yellow'
-    NoColor = 'Gray'
-}
-
-$AgentsDir = Join-Path $BaseDir ".agents"
-
-Write-Host "=== .agents Version Validation ===" -ForegroundColor Cyan
-Write-Host "Base directory: $BaseDir"
-Write-Host "Expected version: $ExpectedVersion"
-Write-Host ""
-
-# Function to extract version from file
-function Get-VersionFromFile {
-    param(
-        [string]$FilePath,
-        [string]$Pattern
-    )
-
-    if (Test-Path $FilePath) {
-        try {
-            $content = Get-Content $FilePath -Raw
-            if ($content -match $Pattern) {
-                return $matches[1]
-            } else {
-                return "NOT_FOUND"
-            }
-        } catch {
-            return "ERROR"
-        }
-    } else {
-        return "FILE_NOT_FOUND"
-    }
-}
-
-# Files to check
-$FilesToCheck = @{
-    (Join-Path $AgentsDir "skills\VERSION") = "version: ([0-9]+\.[0-9]+\.[0-9]+)"
-    (Join-Path $AgentsDir "skills\skills.md") = "V([0-9]+\.[0-9]+\.[0-9]+)"
-}
-
-# Track issues
-$Issues = 0
-
-Write-Host "Checking version consistency..."
-Write-Host ""
-
-foreach ($file in $FilesToCheck.Keys) {
-    $pattern = $FilesToCheck[$file]
-    $relativePath = $file.Replace($BaseDir + "\", "")
-
-    $version = Get-VersionFromFile -FilePath $file -Pattern $pattern
-
-    if ($version -eq "NOT_FOUND" -or $version -eq "FILE_NOT_FOUND") {
-        Write-Host "  ERROR: $relativePath - Version not found" -ForegroundColor $Colors.Red
-        $Issues++
-    } elseif ($version -ne $ExpectedVersion) {
-        Write-Host "  ERROR: $relativePath - Found v$version, expected v$ExpectedVersion" -ForegroundColor $Colors.Red
-        $Issues++
-    } else {
-        Write-Host "  OK: $relativePath - v$version" -ForegroundColor $Colors.Green
-    }
-}
-
-Write-Host ""
-
-# Check for version mismatches in skill files
-Write-Host "Checking skill file versions..."
-$SkillsVersionFile = Join-Path $AgentsDir "skills\VERSION"
-if (Test-Path $SkillsVersionFile) {
-    $skillsVersion = Get-VersionFromFile -FilePath $SkillsVersionFile -Pattern "version: ([0-9]+\.[0-9]+\.[0-9]+)"
-    Write-Host "Skills version file: v$skillsVersion"
-}
-
-# Check workflow versions (in .windsurf\workflows)
-$WorkflowsDir = Join-Path $BaseDir ".windsurf\workflows"
-if (Test-Path $WorkflowsDir) {
-    Write-Host "Checking workflow files..."
-    $workflowCount = (Get-ChildItem -Path $WorkflowsDir -Filter "*.md" -File | Measure-Object).Count
-    Write-Host "  OK: Found $workflowCount workflow files" -ForegroundColor $Colors.Green
-} else {
-    Write-Host "  WARNING: Workflows directory not found at $WorkflowsDir" -ForegroundColor $Colors.Yellow
-}
-
-Write-Host ""
-
-# Summary
-if ($Issues -eq 0) {
-    Write-Host "=== SUCCESS: All versions consistent ===" -ForegroundColor $Colors.Green
-    exit 0
-} else {
-    Write-Host "=== FAILED: $Issues version issues found ===" -ForegroundColor $Colors.Red
-    Write-Host ""
-    Write-Host "To fix version issues:"
-    Write-Host "1. Update files to use v$ExpectedVersion"
-    Write-Host "2. Ensure LCBP3 project version matches"
-    Write-Host "3. Run this script again to verify"
-    exit 1
-}
@@ -1,32 +0,0 @@
-// scripts/start-mcp.js
-const { spawn } = require('child_process');
-const path = require('path');
-const os = require('os');
-
-// Resolve the external config file (outside the repo)
-const configPath = path.resolve(os.homedir(), '.gemini', 'antigravity', 'mcp_config.json');
-
-// Load the JSON config (will throw if invalid)
-const config = require(configPath);
-
-function runServer(name, command, args, env = {}) {
-  console.log(`▶️ Starting ${name}…`);
-  const fullCmd = process.platform === 'win32' ? `${command}.cmd` : command;
-  const proc = spawn(fullCmd, args, {
-    stdio: 'inherit',
-    env: { ...process.env, ...env },
-    cwd: process.cwd(),
-    shell: true,
-  });
-  proc.on('close', (code) => {
-    if (code !== 0) {
-      console.error(`❌ ${name} exited with code ${code}`);
-    } else {
-      console.log(`✅ ${name} finished`);
-    }
-  });
-}
-
-Object.entries(config.mcpServers).forEach(([name, srv]) => {
-  runServer(name, srv.command, srv.args, srv.env);
-});
@@ -1,101 +0,0 @@
-import os
-import re
-import sys
-from pathlib import Path
-
-# Configuration - default base directory, can be overridden via CLI argument
-DEFAULT_BASE_DIR = Path(__file__).resolve().parent.parent.parent / "specs"
-
-DIRECTORIES = [
-    "00-Overview",
-    "01-Requirements",
-    "02-Architecture",
-    "03-Data-and-Storage",
-    "04-Infrastructure-OPS",
-    "05-Engineering-Guidelines",
-    "06-Decision-Records"
-]
-
-# Regex for Markdown links: [label](path)
-# Handles relative paths, absolute file paths, and anchors
-LINK_PATTERN = re.compile(r'\[([^\]]+)\]\(([^)]+)\)')
-
-def verify_links(base_dir: Path):
-    results = {
-        "total_links": 0,
-        "broken_links": []
-    }
-
-    for dir_name in DIRECTORIES:
-        directory = base_dir / dir_name
-        if not directory.exists():
-            print(f"Directory not found: {directory}")
-            continue
-
-        for file_path in directory.glob("*.md"):
-            with open(file_path, "r", encoding="utf-8") as f:
-                content = f.read()
-                links = LINK_PATTERN.findall(content)
-
-                for label, target in links:
-                    # Ignore external links (http/https)
-                    if target.startswith("http"):
-                        continue
-
-                    # Ignore anchors within the same file
-                    if target.startswith("#"):
-                        continue
-
-                    results["total_links"] += 1
-
-                    # Process target path
-                    # 1. Handle file:/// Absolute paths if any
-                    if target.startswith("file:///"):
-                        clean_target = Path(target.replace("file:///", "").replace("/", os.sep))
-                    else:
-                        # 2. Handle relative paths
-                        # Remove anchor if present
-                        clean_target_str = target.split("#")[0]
-                        if not clean_target_str:
-                            continue
-
-                        # Resolve path relative to current file
-                        clean_target = (file_path.parent / clean_target_str).resolve()
-
-                    # Verify existence
-                    if not clean_target.exists():
-                        results["broken_links"].append({
-                            "source": str(file_path),
-                            "label": label,
-                            "target": target,
-                            "resolved": str(clean_target)
-                        })
-
-    return results
-
-if __name__ == "__main__":
-    if len(sys.argv) > 1:
-        base_dir = Path(sys.argv[1])
-    else:
-        base_dir = DEFAULT_BASE_DIR
-
-    if not base_dir.exists():
-        print(f"Error: Directory not found: {base_dir}", file=sys.stderr)
-        sys.exit(1)
-
-    print(f"Starting link verification in {base_dir}...")
-    audit_results = verify_links(base_dir)
-
-    print(f"\nAudit Summary:")
-    print(f"Total Internal Links Scanned: {audit_results['total_links']}")
-    print(f"Total Broken Links Found: {len(audit_results['broken_links'])}")
-
-    if audit_results['broken_links']:
-        print("\nBroken Links Detail:")
-        for idx, link in enumerate(audit_results['broken_links'], 1):
-            print(f"{idx}. Source: {link['source']}")
-            print(f"   Link: [{link['label']}]({link['target']})")
-            print(f"   Resolved Path: {link['resolved']}")
-            print("-" * 20)
-    else:
-        print("\nNo broken links found! 🎉")
@@ -1,109 +0,0 @@
-# `.agents/skills/` — LCBP3 Agent Skill Pack
-
-**Version:** 1.8.9 | **Last Updated:** 2026-04-22 | **Total Skills:** 20
-
-Agent skills for AI-assisted development in **Windsurf IDE** (and compatible agents: Codex CLI, opencode, Amp, Antigravity, AGENTS.md-aware tools).
-
---
-
-## 📂 Layout
-
-```
-.agents/skills/
-├── VERSION                      # Single source of truth for skill-pack version
-├── skills.md                    # Overview + dependency matrix + health monitoring
-├── _LCBP3-CONTEXT.md            # Shared LCBP3 context injected into every speckit-* skill
-├── README.md                    # (this file)
-├── nestjs-best-practices/       # Backend rules (40 rules across 10 categories)
-├── next-best-practices/         # Frontend rules (Next.js 15+)
-└── speckit-*/                   # 18 workflow skills (spec → plan → tasks → implement → …)
-```
-
-Each skill directory contains:
-
- `SKILL.md` — frontmatter (`name`, `description`, `version: 1.8.9`, `scope`, `depends-on`, `handoffs`) + instructions
- `templates/` _(optional)_ — artifact templates (spec/plan/tasks/checklist)
- `rules/` _(nestjs only)_ — individual rule files grouped by prefix (`arch-`, `security-`, `db-`, etc.)
-
---
-
-## 🚀 How Windsurf Invokes These Skills
-
-Windsurf exposes two entry points:
-
-1. **Skill tool** — Windsurf discovers skills by scanning `.agents/skills/*/SKILL.md` frontmatter. Skills marked `user-invocable: false` are used silently by Cascade.
-2. **Slash commands** — `.windsurf/workflows/*.md` wraps each skill as a slash command (e.g. `/04-speckit.plan`). The workflow file is short; the heavy lifting is delegated to the skill via `skill` tool.
-
-Both paths end up executing the same `SKILL.md` instructions.
-
---
-
-## 🧭 Typical Flow
-
-```
-/01-speckit.constitution   → AGENTS.md / product vision
-/02-speckit.specify        → specs/feat-XXX/spec.md
-/03-speckit.clarify        → updates spec.md (up to 5 targeted questions)
-/04-speckit.plan           → specs/feat-XXX/plan.md + data-model.md + contracts/
-/05-speckit.tasks          → specs/feat-XXX/tasks.md
-/06-speckit.analyze        → cross-artifact consistency report (read-only)
-/07-speckit.implement      → executes tasks with Ironclad Protocols (Blast Radius + Strangler + TDD)
-/08-speckit.checker        → pnpm lint / typecheck / markdown-lint
-/09-speckit.tester         → pnpm test + coverage gates (Backend 70%+, Business Logic 80%+)
-/10-speckit.reviewer       → code review with Tier 1/2/3 classification
-/11-speckit.validate       → UAT / acceptance-criteria.md
-```
-
-Use `/00-speckit.all` to run specify → clarify → plan → tasks → analyze in one go.
-
---
-
-## 🛠️ Helper Scripts
-
-From repo root:
-
-| Script | Purpose |
-| --- | --- |
-| `./.agents/scripts/bash/check-prerequisites.sh --json` | Emit `FEATURE_DIR` + `AVAILABLE_DOCS` for a feature branch |
-| `./.agents/scripts/bash/setup-plan.sh --json` | Emit `FEATURE_SPEC`, `IMPL_PLAN`, `SPECS_DIR`, `BRANCH` |
-| `./.agents/scripts/bash/update-agent-context.sh windsurf` | Append tech entries to `AGENTS.md` |
-| `./.agents/scripts/bash/audit-skills.sh` | Validate all `SKILL.md` frontmatter + presence |
-| `./.agents/scripts/bash/validate-versions.sh` | Version consistency check |
-| `./.agents/scripts/bash/sync-workflows.sh` | Verify every skill has a `.windsurf/workflows/*.md` wrapper |
-
-All scripts mirror to `.agents/scripts/powershell/*.ps1` for Windows.
-
---
-
-## ⚠️ Tier 1 Non-Negotiables (auto-enforced)
-
- ADR-019 — `publicId` exposed directly; no `parseInt` / `Number` / `+` on UUID; no `id ?? ''` fallback
- ADR-009 — edit SQL schema directly, no TypeORM migrations
- ADR-016 — JWT + CASL on every mutation; `Idempotency-Key` required; ClamAV two-phase upload
- ADR-018 — AI via DMS API only (Ollama on Admin Desktop; no direct DB/storage)
- ADR-007 — layered error classification (Validation / Business / System)
- Zero `any`, zero `console.log` (use `Logger`)
-
-See [`_LCBP3-CONTEXT.md`](./_LCBP3-CONTEXT.md) for the complete list.
-
---
-
-## 🤝 Extending
-
-To add a new skill:
-
-1. Create `NAME/SKILL.md` with frontmatter: `name`, `description`, `version: 1.8.9`, `scope`, `depends-on`.
-2. Append an LCBP3 context reference pointing to `_LCBP3-CONTEXT.md`.
-3. Wrap with `.windsurf/workflows/NAME.md` so it becomes a slash command.
-4. Update [`skills.md`](./skills.md) dependency matrix.
-5. Run `./.agents/scripts/bash/audit-skills.sh` → must pass.
-
---
-
-## 📚 References
-
- **Canonical rules:** `AGENTS.md` (repo root)
- **Product vision:** `specs/00-Overview/00-03-product-vision.md`
- **ADRs:** `specs/06-Decision-Records/`
- **Engineering guidelines:** `specs/05-Engineering-Guidelines/`
- **Contributing:** `CONTRIBUTING.md`
@@ -1,33 +0,0 @@
-# Speckit Skills Version
-
-version: 1.8.9
-release_date: 2026-04-22
-
-## Changelog
-
-### 1.8.9 (2026-04-22)
- Full LCBP3-native rebuild of `.agents/skills/`
- Fixed ADR-019 drift (removed `@Expose({ name: 'id' })` and `id ?? ''` fallback patterns)
- Replaced all dead references (`GEMINI.md` → `AGENTS.md`, v1.7.0 → v1.8.0 schema, `.specify/memory/` → `AGENTS.md`)
- Added real helper scripts under `.agents/scripts/bash/` and `.agents/scripts/powershell/`
- Added ADR-007/008/020/021 coverage
- New rules: workflow-engine, file-two-phase-upload, ai-boundary, i18n, file-upload, workflow-banner
- Standardized frontmatter across all 20 skills (`version: 1.8.9`)
-
-### 1.8.6 (2026-04-14)
- Version alignment with LCBP3-DMS v1.8.6
- Complete skill implementations for all 20 skills
- Enhanced security and audit capabilities
- Production-ready deployment status
-
-### 1.1.0 (2026-01-24)
- New QA skills: tester, reviewer, checker
- tester: Execute tests, measure coverage, report results
- reviewer: Code review with severity levels and suggestions
- checker: Static analysis aggregation (lint, types, security)
-
-### 1.0.0 (2026-01-24)
- Initial versioned release
- Core skills: specify, clarify, plan, tasks, implement, analyze, checklist, constitution, quizme, taskstoissues
- New skills: diff, validate, migrate, status
- All workflows enhanced with error handling and relative paths
@@ -1,91 +0,0 @@
-# 🧭 LCBP3-DMS Context Appendix (Shared)
-
-> This file is included/referenced by every Speckit skill as the authoritative project context.
-> Skills **must** load it (or the files it links to) before generating any artifact.
-
-**Project:** NAP-DMS (LCBP3) — Laem Chabang Port Phase 3 Document Management System
-**Stack:** NestJS 11 + Next.js 16 + TypeScript + MariaDB 11.8 + Redis + BullMQ + Elasticsearch + Ollama (on-prem AI)
-**Version:** 1.8.9 (2026-04-18)
-
---
-
-## 📌 Canonical Rule Sources (read in this order)
-
-1. **`AGENTS.md`** (repo root) — primary rule file for AI agents; supersedes legacy `GEMINI.md`.
-2. **`specs/06-Decision-Records/`** — architectural decisions (22 ADRs); ADR priority > Engineering Guidelines.
-3. **`specs/05-Engineering-Guidelines/`** — backend/frontend/testing/i18n/git patterns.
-4. **`specs/00-Overview/00-02-glossary.md`** — domain terminology (Correspondence / RFA / Transmittal / Circulation).
-5. **`specs/00-Overview/00-03-product-vision.md`** — project constitution (Vision, Strategic Pillars, Guardrails).
-6. **`CONTRIBUTING.md`** — spec writing standards, PR template, review levels.
-7. **`README.md`** — technology stack + getting started.
-
---
-
-## 🔴 Tier 1 Non-Negotiables
-
- **ADR-019 UUID:** `publicId: string` exposed directly — **no** `@Expose({ name: 'id' })` rename; **no** `parseInt`/`Number`/`+` on UUID; **no** `id ?? ''` fallback in frontend.
- **ADR-009:** No TypeORM migrations — edit `specs/03-Data-and-Storage/lcbp3-v1.8.0-schema-02-tables.sql` or add a `deltas/*.sql` file.
- **ADR-016 Security:** JWT + CASL 4-Level RBAC; `@UseGuards(JwtAuthGuard, CaslAbilityGuard)` on every mutation controller; `ThrottlerGuard` on auth; bcrypt 12 rounds; `Idempotency-Key` required on POST/PUT/PATCH.
- **ADR-002 Document Numbering:** Redis Redlock + TypeORM `@VersionColumn` (double-lock). Never use application-side counter alone.
- **ADR-008 Notifications:** BullMQ queue — never inline email/notification in a request thread.
- **ADR-018 AI Boundary:** Ollama on Admin Desktop only; AI → DMS API → DB (never direct DB/storage). Human-in-the-loop validation required.
- **ADR-007 Error Handling:** Layered (Validation / Business / System); `BusinessException` hierarchy; user-friendly `userMessage` + `recoveryAction`; technical stack only in logs.
- **TypeScript Strict:** Zero `any`, zero `console.log` (use NestJS `Logger`).
- **i18n:** No hardcoded Thai/English strings in components — use i18n keys (see `05-08-i18n-guidelines.md`).
- **File Upload:** Two-phase (Temp → ClamAV → Permanent), whitelist `PDF/DWG/DOCX/XLSX/ZIP`, max 50MB, `StorageService` only.
-
---
-
-## 🏷️ Domain Glossary (reject generic terms)
-
-| ✅ Use | ❌ Don't Use |
-| --- | --- |
-| Correspondence | Letter, Communication, Document |
-| RFA | Approval Request, Submit for Approval |
-| Transmittal | Delivery Note, Cover Letter |
-| Circulation | Distribution, Routing |
-| Shop Drawing | Construction Drawing |
-| Contract Drawing | Design Drawing, Blueprint |
-| Workflow Engine | Approval Flow, Process Engine |
-| Document Numbering | Document ID, Auto Number |
-
---
-
-## 📁 Key Files for Generating / Validating Artifacts
-
-| When you need... | Read |
-| --- | --- |
-| A new feature spec | `.agents/skills/speckit-specify/templates/spec-template.md` + `specs/01-Requirements/01-06-edge-cases-and-rules.md` |
-| A plan | `.agents/skills/speckit-plan/templates/plan-template.md` + relevant ADRs |
-| Task breakdown | `.agents/skills/speckit-tasks/templates/tasks-template.md` + existing patterns in `specs/08-Tasks/` |
-| Acceptance criteria / UAT | `specs/01-Requirements/01-05-acceptance-criteria.md` |
-| Schema / table definition | `specs/03-Data-and-Storage/lcbp3-v1.8.0-schema-02-tables.sql` + `03-01-data-dictionary.md` |
-| RBAC / permissions | `specs/03-Data-and-Storage/lcbp3-v1.8.0-seed-permissions.sql` + `01-02-01-rbac-matrix.md` |
-| Release / hotfix | `specs/04-Infrastructure-OPS/04-08-release-management-policy.md` |
-
---
-
-## 🛠️ Helper Scripts (real paths in this repo)
-
- `./.agents/scripts/bash/check-prerequisites.sh` / `powershell/*.ps1`
- `./.agents/scripts/bash/setup-plan.sh`
- `./.agents/scripts/bash/update-agent-context.sh windsurf`
- `./.agents/scripts/bash/audit-skills.sh`
- `./.agents/scripts/bash/validate-versions.sh`
- `./.agents/scripts/bash/sync-workflows.sh`
-
---
-
-## ✅ Commit Checklist (applied automatically by speckit-implement)
-
- [ ] UUID pattern verified (no `parseInt` / `Number` / `+` on UUID, no `id ?? ''` fallback)
- [ ] No `any`, no `console.log` in committed code
- [ ] Business comments in Thai, code identifiers in English
- [ ] Schema changes via SQL directly (not migration)
- [ ] Test coverage meets targets (Backend 70%+, Business Logic 80%+)
- [ ] Relevant ADRs referenced (007/008/009/016/018/019/020/021)
- [ ] Domain glossary terms used correctly
- [ ] Error handling: `Logger` + `HttpException` / `BusinessException`
- [ ] i18n keys used (no hardcode text)
- [ ] Cache invalidation when data mutated
- [ ] OWASP Top 10 review passed
@@ -1,24 +0,0 @@
-name: Branch Protection
-
-on:
-  pull_request:
-    branches: [main]
-
-jobs:
-  check-branch:
-    runs-on: ubuntu-latest
-    steps:
-      - name: Block docs branch merge to main
-        if: github.head_ref == 'docs'
-        run: |
-          echo "::error::Merging 'docs' branch into 'main' is not allowed."
-          echo ""
-          echo "The 'docs' branch contains the documentation website which should"
-          echo "remain separate from the main skill files to keep installations lightweight."
-          echo ""
-          echo "If you need to sync changes, cherry-pick specific commits instead."
-          exit 1
-
-      - name: Branch check passed
-        if: github.head_ref != 'docs'
-        run: echo "Branch check passed - not merging from docs branch"
@@ -1,61 +0,0 @@
-name: Deploy to GitHub Pages
-
-on:
-  push:
-    branches: [docs]
-    paths:
-      - 'website/**'
-  workflow_dispatch:
-
-permissions:
-  contents: read
-  pages: write
-  id-token: write
-
-concurrency:
-  group: pages
-  cancel-in-progress: false
-
-jobs:
-  build:
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-
-      - name: Setup Node
-        uses: actions/setup-node@v4
-        with:
-          node-version: 20
-          cache: npm
-          cache-dependency-path: website/package-lock.json
-
-      - name: Setup Pages
-        uses: actions/configure-pages@v4
-
-      - name: Install dependencies
-        run: npm ci
-        working-directory: website
-
-      - name: Build
-        run: npm run build
-        working-directory: website
-
-      - name: Copy index.html to 404.html for SPA routing
-        run: cp website/dist/index.html website/dist/404.html
-
-      - name: Upload artifact
-        uses: actions/upload-pages-artifact@v3
-        with:
-          path: website/dist
-
-  deploy:
-    environment:
-      name: github-pages
-      url: ${{ steps.deployment.outputs.page_url }}
-    runs-on: ubuntu-latest
-    needs: build
-    steps:
-      - name: Deploy to GitHub Pages
-        id: deployment
-        uses: actions/deploy-pages@v4
@@ -1,29 +0,0 @@
-# Dependencies
-node_modules/
-
-# Website (lives on docs branch)
-website/
-
-# Build outputs
-dist/
-*.js
-*.d.ts
-*.js.map
-
-# IDE
-.idea/
-.vscode/
-*.swp
-*.swo
-
-# OS
-.DS_Store
-Thumbs.db
-
-# Logs
-*.log
-npm-debug.log*
-
-# Environment
-.env
-.env.local
@@ -1,163 +0,0 @@
-# NestJS Best Practices
-
-📖 [For Humans <3](https://kadajett.github.io/agent-nestjs-skills/)
-
-A structured repository for creating and maintaining NestJS Best Practices optimized for agents and LLMs.
-
-## Installation
-
-Install this skill using [skills](https://github.com/vercel-labs/skills):
-
-```bash
-# GitHub shorthand
-npx skills add Kadajett/agent-nestjs-skills
-
-# Install globally (available across all projects)
-npx skills add Kadajett/agent-nestjs-skills --global
-
-# Install for specific agents
-npx skills add Kadajett/agent-nestjs-skills -a claude-code -a cursor
-```
-
-### Supported Agents
-
- Claude Code
- OpenCode
- Codex
- Cursor
- Antigravity
- Roo Code
-
-## Structure
-
- `rules/` - Individual rule files (one per rule)
-  - `_sections.md` - Section metadata (titles, impacts, descriptions)
-  - `_template.md` - Template for creating new rules
-  - `area-description.md` - Individual rule files
- `scripts/` - Build scripts and utilities
- `metadata.json` - Document metadata (version, organization, abstract)
- **`AGENTS.md`** - Compiled output (generated)
-
-## Getting Started
-
-1. Install dependencies:
-
-   ```bash
-   cd scripts && npm install
-   ```
-
-2. Build AGENTS.md from rules:
-   ```bash
-   npm run build
-   # or
-   ./scripts/build.sh
-   ```
-
-## Creating a New Rule
-
-1. Copy `rules/_template.md` to `rules/area-description.md`
-2. Choose the appropriate area prefix:
-   - `arch-` for Architecture (Section 1)
-   - `di-` for Dependency Injection (Section 2)
-   - `error-` for Error Handling (Section 3)
-   - `security-` for Security (Section 4)
-   - `perf-` for Performance (Section 5)
-   - `test-` for Testing (Section 6)
-   - `db-` for Database & ORM (Section 7)
-   - `api-` for API Design (Section 8)
-   - `micro-` for Microservices (Section 9)
-   - `devops-` for DevOps & Deployment (Section 10)
-3. Fill in the frontmatter and content
-4. Ensure you have clear examples with explanations
-5. Run the build script to regenerate AGENTS.md
-
-## Rule File Structure
-
-Each rule file should follow this structure:
-
-````markdown
---
-title: Rule Title Here
-impact: MEDIUM
-impactDescription: Optional description
-tags: tag1, tag2, tag3
---
-
-## Rule Title Here
-
-Brief explanation of the rule and why it matters.
-
-**Incorrect (description of what's wrong):**
-
-```typescript
-// Bad code example
-```
-````
-
-**Correct (description of what's right):**
-
-```typescript
-// Good code example
-```
-
-Optional explanatory text after examples.
-
-Reference: [NestJS Documentation](https://docs.nestjs.com)
-
-## File Naming Convention
-
- Files starting with `_` are special (excluded from build)
- Rule files: `area-description.md` (e.g., `arch-avoid-circular-deps.md`)
- Section is automatically inferred from filename prefix
- Rules are sorted alphabetically by title within each section
- IDs (e.g., 1.1, 1.2) are auto-generated during build
-
-## Impact Levels
-
-| Level       | Description                                                                           |
-| ----------- | ------------------------------------------------------------------------------------- |
-| CRITICAL    | Violations cause runtime errors, security vulnerabilities, or architectural breakdown |
-| HIGH        | Significant impact on reliability, security, or maintainability                       |
-| MEDIUM-HIGH | Notable impact on quality and developer experience                                    |
-| MEDIUM      | Moderate impact on code quality and best practices                                    |
-| LOW-MEDIUM  | Minor improvements for consistency and maintainability                                |
-
-## Scripts
-
- `npm run build` (in scripts/) - Compile rules into AGENTS.md
-
-## Contributing
-
-When adding or modifying rules:
-
-1. Use the correct filename prefix for your section
-2. Follow the `_template.md` structure
-3. Include clear bad/good examples with explanations
-4. Add appropriate tags
-5. Run the build script to regenerate AGENTS.md
-6. Rules are automatically sorted by title - no need to manage numbers!
-
-## Documentation Website
-
-The documentation website source code lives on the [`docs` branch](https://github.com/Kadajett/agent-nestjs-skills/tree/docs/website). This separation keeps the skill installation lightweight while maintaining the full documentation site.
-
-To contribute to the website:
-
-```bash
-git checkout docs
-cd website
-npm install
-npm run dev
-```
-
-## Acknowledgments
-
- Inspired by the [Vercel React Best Practices](https://github.com/vercel-labs/agent-skills) skill structure
- Compatible with [skills](https://github.com/vercel-labs/skills) for easy installation across coding agents
-
-## Compatible Agents
-
-These NestJS skills work with:
-
- [Claude Code](https://claude.ai/code) - Anthropic's official CLI
- [AdaL](https://sylph.ai/adal) - Self-evolving AI coding agent with MCP support
@@ -1,261 +0,0 @@
---
-name: nestjs-best-practices
-description: NestJS best practices and architecture patterns for building production-ready LCBP3-DMS backend code. Enforces ADR-009 (no TypeORM migrations), ADR-019 (hybrid UUID), ADR-016 (security), ADR-007 (error handling), ADR-008 (BullMQ), ADR-001/002 (workflow + numbering), ADR-018/020 (AI boundary), and ADR-021 (workflow context).
-version: 1.8.9
-scope: backend
-user-invocable: false
-license: MIT
-metadata:
-  upstream: 'Kadajett/nestjs-best-practices v1.1.0 (forked + LCBP3-aligned)'
---
-
-# NestJS Best Practices
-
-Comprehensive best practices guide for NestJS applications. Contains 40 rules across 10 categories, prioritized by impact to guide automated refactoring and code generation.
-
-## When to Apply
-
-Reference these guidelines when:
-
- Writing new NestJS modules, controllers, or services
- Implementing authentication and authorization
- Reviewing code for architecture and security issues
- Refactoring existing NestJS codebases
- Optimizing performance or database queries
- Building microservices architectures
-
-## Rule Categories by Priority
-
-| Priority | Category             | Impact      | Prefix      |
-| -------- | -------------------- | ----------- | ----------- |
-| 1        | Architecture         | CRITICAL    | `arch-`     |
-| 2        | Dependency Injection | CRITICAL    | `di-`       |
-| 3        | Error Handling       | HIGH        | `error-`    |
-| 4        | Security             | HIGH        | `security-` |
-| 5        | Performance          | HIGH        | `perf-`     |
-| 6        | Testing              | MEDIUM-HIGH | `test-`     |
-| 7        | Database & ORM       | MEDIUM-HIGH | `db-`       |
-| 8        | API Design           | MEDIUM      | `api-`      |
-| 9        | Microservices        | MEDIUM      | `micro-`    |
-| 10       | DevOps & Deployment  | LOW-MEDIUM  | `devops-`   |
-
-## Quick Reference
-
-### 1. Architecture (CRITICAL)
-
- `arch-avoid-circular-deps` - Avoid circular module dependencies
- `arch-feature-modules` - Organize by feature, not technical layer
- `arch-module-sharing` - Proper module exports/imports, avoid duplicate providers
- `arch-single-responsibility` - Focused services over "god services"
- `arch-use-repository-pattern` - Abstract database logic for testability
- `arch-use-events` - Event-driven architecture for decoupling
-
-### 2. Dependency Injection (CRITICAL)
-
- `di-avoid-service-locator` - Avoid service locator anti-pattern
- `di-interface-segregation` - Interface Segregation Principle (ISP)
- `di-liskov-substitution` - Liskov Substitution Principle (LSP)
- `di-prefer-constructor-injection` - Constructor over property injection
- `di-scope-awareness` - Understand singleton/request/transient scopes
- `di-use-interfaces-tokens` - Use injection tokens for interfaces
-
-### 3. Error Handling (HIGH)
-
- `error-use-exception-filters` - Centralized exception handling
- `error-throw-http-exceptions` - Use NestJS HTTP exceptions
- `error-handle-async-errors` - Handle async errors properly
-
-### 4. Security (HIGH)
-
- `security-auth-jwt` - Secure JWT authentication
- `security-validate-all-input` - Validate with class-validator
- `security-use-guards` - Authentication and authorization guards
- `security-sanitize-output` - Prevent XSS attacks
- `security-rate-limiting` - Implement rate limiting
-
-### 5. Performance (HIGH)
-
- `perf-async-hooks` - Proper async lifecycle hooks
- `perf-use-caching` - Implement caching strategies
- `perf-optimize-database` - Optimize database queries
- `perf-lazy-loading` - Lazy load modules for faster startup
-
-### 6. Testing (MEDIUM-HIGH)
-
- `test-use-testing-module` - Use NestJS testing utilities
- `test-e2e-supertest` - E2E testing with Supertest
- `test-mock-external-services` - Mock external dependencies
-
-### 7. Database & ORM (MEDIUM-HIGH)
-
- `db-hybrid-identifier` - **CRITICAL** ADR-019: INT PK + UUID public API
- `db-avoid-n-plus-one` - HIGH N+1 query prevention
- `db-use-transactions` - HIGH Transaction management
- `db-no-typeorm-migrations` - **CRITICAL** ADR-009: No TypeORM migrations - use SQL files
-
-### 8. API Design (MEDIUM)
-
- `api-use-dto-serialization` - DTO and response serialization
- `api-use-interceptors` - Cross-cutting concerns
- `api-versioning` - API versioning strategies
- `api-use-pipes` - Input transformation with pipes
-
-### 9. Microservices (MEDIUM)
-
- `micro-use-patterns` - Message and event patterns
- `micro-use-health-checks` - Health checks for orchestration
- `micro-use-queues` - Background job processing
-
-### 10. DevOps & Deployment (LOW-MEDIUM)
-
- `devops-use-config-module` - Environment configuration
- `devops-use-logging` - Structured logging
- `devops-graceful-shutdown` - Zero-downtime deployments
-
-### 11. LCBP3-Specific (CRITICAL — Project Overrides)
-
- `db-no-typeorm-migrations` — **CRITICAL** ADR-009: edit SQL directly
- `lcbp3-workflow-engine` — **CRITICAL** ADR-001/002/021: DSL state machine + double-lock numbering + workflow context
- `security-file-two-phase-upload` — **CRITICAL** ADR-016: Upload → Temp → ClamAV → Commit
- `lcbp3-ai-boundary` — **CRITICAL** ADR-018/020: Ollama on-prem only, human-in-the-loop
-
-## NAP-DMS Project-Specific Rules (MUST FOLLOW)
-
-These rules override general NestJS best practices for the NAP-DMS project:
-
-### ADR-009: No TypeORM Migrations
-
- **ห้ามสร้างไฟล์ migration ของ TypeORM**
- แก้ไข schema โดยตรงที่: `specs/03-Data-and-Storage/lcbp3-v1.8.0-schema-02-tables.sql`
- ใช้ n8n workflow สำหรับ data migration ถ้าจำเป็น
-
-### ADR-019: Hybrid Identifier Strategy (CRITICAL — March 2026 Pattern)
-
-> **Updated pattern:** `UuidBaseEntity` exposes `publicId` **directly**. ห้ามใช้ `@Expose({ name: 'id' })` — API จะคืน `publicId` เป็น field name ตรงๆ.
-
-```typescript
-// ✅ CORRECT — ใช้ UuidBaseEntity
-@Entity()
-export class Project extends UuidBaseEntity {
-  // publicId (string UUIDv7) + id (INT, @Exclude) สืบทอดจาก UuidBaseEntity
-  // API response → { publicId: "019505a1-7c3e-7000-8000-abc123..." }
-
-  @Column()
-  projectCode: string;
-
-  @Column()
-  projectName: string;
-}
-```
-
-```typescript
-// ❌ WRONG — pattern เก่า ห้ามใช้
-@Entity()
-export class OldProject {
-  @PrimaryGeneratedColumn()
-  @Exclude()
-  id: number;
-
-  @Column({ type: 'uuid' })
-  @Expose({ name: 'id' }) // ❌ อย่า rename publicId เป็น 'id'
-  publicId: string;
-}
-```
-
-**DTO Input (รับ UUID จาก Frontend):**
-
-```typescript
-export class CreateContractDto {
-  @IsUUID('7')
-  projectUuid: string; // รับ UUID string จาก client
-}
-
-// Controller resolves UUID → INT internally
-@Post()
-async create(@Body() dto: CreateContractDto) {
-  const projectId = await this.projectService.resolveInternalId(dto.projectUuid);
-  return this.contractService.create({ ...dto, projectId });
-}
-```
-
-**ห้ามเด็ดขาด (CI Blocker):**
-
- ❌ `parseInt(projectPublicId)` — "019505…" → 19 (silently wrong)
- ❌ `Number(publicId)` / `+publicId` — NaN
- ❌ `@Expose({ name: 'id' })` บน `publicId` (pattern เก่า)
- ❌ Expose INT `id` ใน API response (ต้อง `@Exclude()` เสมอ)
-
-### Two-Phase File Upload
-
-```typescript
-// Phase 1: Upload to temp
-@Post('upload')
-async uploadFile(@UploadedFile() file: Express.Multer.File) {
-  await this.virusScan(file);
-  const tempId = await this.fileStorage.saveToTemp(file);
-  return { temp_id: tempId, expires_at: addHours(new Date(), 24) };
-}
-
-// Phase 2: Commit in transaction
-async createEntity(dto: CreateDto, tempIds: string[]) {
-  return this.dataSource.transaction(async (manager) => {
-    const entity = await manager.save(Entity, dto);
-    await this.fileStorage.commitFiles(tempIds, entity.id, manager);
-    return entity;
-  });
-}
-```
-
-### Idempotency Requirement
-
- ทุก POST/PUT/PATCH ที่สำคัญต้องมี `Idempotency-Key` header
- ใช้ `IdempotencyInterceptor` ที่มีอยู่แล้ว
-
-### Document Numbering (Double-Lock)
-
-```typescript
-async generateNextNumber(context: NumberingContext): Promise<string> {
-  const lockKey = `doc_num:${context.projectId}:${context.typeId}`;
-  const lock = await this.redisLock.acquire(lockKey, 3000);
-
-  try {
-    const counter = await this.counterRepo.findOne({
-      where: context,
-      lock: { mode: 'optimistic' },
-    });
-    counter.last_number++;
-    return this.formatNumber(await this.counterRepo.save(counter));
-  } finally {
-    await lock.release();
-  }
-}
-```
-
-### Anti-Patterns (ห้ามทำ)
-
- ❌ ใช้ SQL Triggers สำหรับ business logic
- ❌ ใช้ `.env` ใน production (ใช้ Docker ENV)
- ❌ ใช้ `any` type (strict mode enforced)
- ❌ ใช้ `console.log` (ใช้ NestJS Logger)
- ❌ สร้างตาราง routing แยก (ใช้ Workflow Engine)
-
---
-
-Read individual rule files for detailed explanations and code examples:
-
-```
-rules/arch-avoid-circular-deps.md
-rules/security-validate-all-input.md
-rules/_sections.md
-```
-
-Each rule file contains:
-
- Brief explanation of why it matters
- Incorrect code example with explanation
- Correct code example with explanation
- Additional context and references
-
-## Full Compiled Document
-
-For the complete guide with all rules expanded: `AGENTS.md`
@@ -1,24 +0,0 @@
-{
-  "version": "1.8.9",
-  "organization": "**NAP-DMS / LCBP3** — Laem Chabang Port Phase 3 Document Management System",
-  "date": "2026-04-22",
-  "abstract": "Comprehensive NestJS best-practices guide compiled for the LCBP3-DMS backend. Contains 40+ rules across 11 categories (10 general + 1 project-specific), prioritized by impact. Forked from Kadajett/nestjs-best-practices (v1.1.0) and aligned to LCBP3 ADRs: ADR-001 (workflow engine), ADR-002 (document numbering), ADR-007 (error handling), ADR-008 (notifications/BullMQ), ADR-009 (no TypeORM migrations), ADR-016 (security), ADR-018/020 (AI boundary), ADR-019 (hybrid UUID identifier — March 2026 pattern), and ADR-021 (workflow context).\n\nThis document is the single, consolidated reference used by Cascade and other AI coding agents when writing, reviewing, or refactoring backend code in this repository. All LCBP3-specific overrides live in section 11.",
-  "references": [
-    "[AGENTS.md (root)](../../../AGENTS.md) — canonical AI agent rules",
-    "[CONTRIBUTING.md](../../../CONTRIBUTING.md) — spec authoring + PR process",
-    "[ADR-001 Unified Workflow Engine](../../../specs/06-Decision-Records/ADR-001-unified-workflow-engine.md)",
-    "[ADR-002 Document Numbering Strategy](../../../specs/06-Decision-Records/ADR-002-document-numbering-strategy.md)",
-    "[ADR-007 Error Handling Strategy](../../../specs/06-Decision-Records/ADR-007-error-handling-strategy.md)",
-    "[ADR-008 Email/Notification Strategy](../../../specs/06-Decision-Records/ADR-008-email-notification-strategy.md)",
-    "[ADR-009 Database Migration Strategy](../../../specs/06-Decision-Records/ADR-009-database-migration-strategy.md)",
-    "[ADR-016 Security & Authentication](../../../specs/06-Decision-Records/ADR-016-security-authentication.md)",
-    "[ADR-018 AI Boundary](../../../specs/06-Decision-Records/ADR-018-ai-boundary.md)",
-    "[ADR-019 Hybrid Identifier Strategy](../../../specs/06-Decision-Records/ADR-019-hybrid-identifier-strategy.md)",
-    "[ADR-020 AI Intelligence Integration](../../../specs/06-Decision-Records/ADR-020-ai-intelligence-integration.md)",
-    "[ADR-021 Workflow Context](../../../specs/06-Decision-Records/ADR-021-workflow-context.md)",
-    "[Backend Engineering Guidelines](../../../specs/05-Engineering-Guidelines/05-02-backend-guidelines.md)",
-    "[Schema — v1.8.0 Tables](../../../specs/03-Data-and-Storage/lcbp3-v1.8.0-schema-02-tables.sql)",
-    "[Data Dictionary](../../../specs/03-Data-and-Storage/03-01-data-dictionary.md)",
-    "Upstream: [Kadajett/nestjs-best-practices](https://github.com/Kadajett/nestjs-best-practices) v1.1.0"
-  ]
-}
@@ -1,182 +0,0 @@
---
-title: Use DTOs and Serialization for API Responses
-impact: MEDIUM
-impactDescription: Response DTOs prevent accidental data exposure and ensure consistency
-tags: api, dto, serialization, class-transformer
---
-
-## Use DTOs and Serialization for API Responses
-
-Never return entity objects directly from controllers. Use response DTOs with class-transformer's `@Exclude()` and `@Expose()` decorators to control exactly what data is sent to clients. This prevents accidental exposure of sensitive fields and provides a stable API contract.
-
-**Incorrect (returning entities directly or manual spreading):**
-
-```typescript
-// Return entities directly
-@Controller('users')
-export class UsersController {
-  @Get(':id')
-  async findOne(@Param('id') id: string): Promise<User> {
-    return this.usersService.findById(id);
-    // Returns: { id, email, passwordHash, ssn, internalNotes, ... }
-    // Exposes sensitive data!
-  }
-}
-
-// Manual object spreading (error-prone)
-@Get(':id')
-async findOne(@Param('id') id: string) {
-  const user = await this.usersService.findById(id);
-  return {
-    id: user.id,
-    email: user.email,
-    name: user.name,
-    // Easy to forget to exclude sensitive fields
-    // Hard to maintain across endpoints
-  };
-}
-```
-
-**Correct (use class-transformer with @Exclude and response DTOs):**
-
-```typescript
-// Enable class-transformer globally
-async function bootstrap() {
-  const app = await NestFactory.create(AppModule);
-  app.useGlobalInterceptors(new ClassSerializerInterceptor(app.get(Reflector)));
-  await app.listen(3000);
-}
-
-// Entity with serialization control
-@Entity()
-export class User {
-  @PrimaryGeneratedColumn('uuid')
-  id: string;
-
-  @Column()
-  email: string;
-
-  @Column()
-  name: string;
-
-  @Column()
-  @Exclude() // Never include in responses
-  passwordHash: string;
-
-  @Column({ nullable: true })
-  @Exclude()
-  ssn: string;
-
-  @Column({ default: false })
-  @Exclude({ toPlainOnly: true }) // Exclude from response, allow in requests
-  isAdmin: boolean;
-
-  @CreateDateColumn()
-  createdAt: Date;
-
-  @Column()
-  @Exclude()
-  internalNotes: string;
-}
-
-// Now returning entity is safe
-@Controller('users')
-export class UsersController {
-  @Get(':id')
-  async findOne(@Param('id') id: string): Promise<User> {
-    return this.usersService.findById(id);
-    // Returns: { id, email, name, createdAt }
-    // Sensitive fields excluded automatically
-  }
-}
-
-// For different response shapes, use explicit DTOs
-export class UserResponseDto {
-  @Expose()
-  id: string;
-
-  @Expose()
-  email: string;
-
-  @Expose()
-  name: string;
-
-  @Expose()
-  @Transform(({ obj }) => obj.posts?.length || 0)
-  postCount: number;
-
-  constructor(partial: Partial<User>) {
-    Object.assign(this, partial);
-  }
-}
-
-export class UserDetailResponseDto extends UserResponseDto {
-  @Expose()
-  createdAt: Date;
-
-  @Expose()
-  @Type(() => PostResponseDto)
-  posts: PostResponseDto[];
-}
-
-// Controller with explicit DTOs
-@Controller('users')
-export class UsersController {
-  @Get()
-  @SerializeOptions({ type: UserResponseDto })
-  async findAll(): Promise<UserResponseDto[]> {
-    const users = await this.usersService.findAll();
-    return users.map((u) => plainToInstance(UserResponseDto, u));
-  }
-
-  @Get(':id')
-  async findOne(@Param('id') id: string): Promise<UserDetailResponseDto> {
-    const user = await this.usersService.findByIdWithPosts(id);
-    return plainToInstance(UserDetailResponseDto, user, {
-      excludeExtraneousValues: true,
-    });
-  }
-}
-
-// Groups for conditional serialization
-export class UserDto {
-  @Expose()
-  id: string;
-
-  @Expose()
-  name: string;
-
-  @Expose({ groups: ['admin'] })
-  email: string;
-
-  @Expose({ groups: ['admin'] })
-  createdAt: Date;
-
-  @Expose({ groups: ['admin', 'owner'] })
-  settings: UserSettings;
-}
-
-@Controller('users')
-export class UsersController {
-  @Get()
-  @SerializeOptions({ groups: ['public'] })
-  async findAllPublic(): Promise<UserDto[]> {
-    // Returns: { id, name }
-  }
-
-  @Get('admin')
-  @UseGuards(AdminGuard)
-  @SerializeOptions({ groups: ['admin'] })
-  async findAllAdmin(): Promise<UserDto[]> {
-    // Returns: { id, name, email, createdAt }
-  }
-
-  @Get('me')
-  @SerializeOptions({ groups: ['owner'] })
-  async getProfile(@CurrentUser() user: User): Promise<UserDto> {
-    // Returns: { id, name, settings }
-  }
-}
-```
-
-Reference: [NestJS Serialization](https://docs.nestjs.com/techniques/serialization)
@@ -1,202 +0,0 @@
---
-title: Use Interceptors for Cross-Cutting Concerns
-impact: MEDIUM-HIGH
-impactDescription: Interceptors provide clean separation for cross-cutting logic
-tags: api, interceptors, logging, caching
---
-
-## Use Interceptors for Cross-Cutting Concerns
-
-Interceptors can transform responses, add logging, handle caching, and measure performance without polluting your business logic. They wrap the route handler execution, giving you access to both the request and response streams.
-
-**Incorrect (logging and transformation in every method):**
-
-```typescript
-// Logging in every controller method
-@Controller('users')
-export class UsersController {
-  @Get()
-  async findAll(): Promise<User[]> {
-    const start = Date.now();
-    this.logger.log('findAll called');
-
-    const users = await this.usersService.findAll();
-
-    this.logger.log(`findAll completed in ${Date.now() - start}ms`);
-    return users;
-  }
-
-  @Get(':id')
-  async findOne(@Param('id') id: string): Promise<User> {
-    const start = Date.now();
-    this.logger.log(`findOne called with id: ${id}`);
-
-    const user = await this.usersService.findOne(id);
-
-    this.logger.log(`findOne completed in ${Date.now() - start}ms`);
-    return user;
-  }
-  // Repeated in every method!
-}
-
-// Manual response wrapping
-@Get()
-async findAll(): Promise<{ data: User[]; meta: Meta }> {
-  const users = await this.usersService.findAll();
-  return {
-    data: users,
-    meta: { timestamp: new Date(), count: users.length },
-  };
-}
-```
-
-**Correct (use interceptors for cross-cutting concerns):**
-
-```typescript
-// Logging interceptor
-@Injectable()
-export class LoggingInterceptor implements NestInterceptor {
-  private readonly logger = new Logger('HTTP');
-
-  intercept(context: ExecutionContext, next: CallHandler): Observable<any> {
-    const request = context.switchToHttp().getRequest();
-    const { method, url, body } = request;
-    const now = Date.now();
-
-    return next.handle().pipe(
-      tap({
-        next: (data) => {
-          const response = context.switchToHttp().getResponse();
-          this.logger.log(
-            `${method} ${url} ${response.statusCode} - ${Date.now() - now}ms`,
-          );
-        },
-        error: (error) => {
-          this.logger.error(
-            `${method} ${url} ${error.status || 500} - ${Date.now() - now}ms`,
-            error.stack,
-          );
-        },
-      }),
-    );
-  }
-}
-
-// Response transformation interceptor
-@Injectable()
-export class TransformInterceptor<T> implements NestInterceptor<T, Response<T>> {
-  intercept(context: ExecutionContext, next: CallHandler): Observable<Response<T>> {
-    return next.handle().pipe(
-      map((data) => ({
-        data,
-        meta: {
-          timestamp: new Date().toISOString(),
-          path: context.switchToHttp().getRequest().url,
-        },
-      })),
-    );
-  }
-}
-
-// Timeout interceptor
-@Injectable()
-export class TimeoutInterceptor implements NestInterceptor {
-  intercept(context: ExecutionContext, next: CallHandler): Observable<any> {
-    return next.handle().pipe(
-      timeout(5000),
-      catchError((err) => {
-        if (err instanceof TimeoutError) {
-          throw new RequestTimeoutException('Request timed out');
-        }
-        throw err;
-      }),
-    );
-  }
-}
-
-// Apply globally or per-controller
-@Module({
-  providers: [
-    { provide: APP_INTERCEPTOR, useClass: LoggingInterceptor },
-    { provide: APP_INTERCEPTOR, useClass: TransformInterceptor },
-  ],
-})
-export class AppModule {}
-
-// Or per-controller
-@Controller('users')
-@UseInterceptors(LoggingInterceptor)
-export class UsersController {
-  @Get()
-  async findAll(): Promise<User[]> {
-    // Clean business logic only
-    return this.usersService.findAll();
-  }
-}
-
-// Custom cache interceptor with TTL
-@Injectable()
-export class HttpCacheInterceptor implements NestInterceptor {
-  constructor(
-    private cacheManager: Cache,
-    private reflector: Reflector,
-  ) {}
-
-  async intercept(context: ExecutionContext, next: CallHandler): Promise<Observable<any>> {
-    const request = context.switchToHttp().getRequest();
-
-    // Only cache GET requests
-    if (request.method !== 'GET') {
-      return next.handle();
-    }
-
-    const cacheKey = this.generateKey(request);
-    const ttl = this.reflector.get<number>('cacheTTL', context.getHandler()) || 300;
-
-    const cached = await this.cacheManager.get(cacheKey);
-    if (cached) {
-      return of(cached);
-    }
-
-    return next.handle().pipe(
-      tap((response) => {
-        this.cacheManager.set(cacheKey, response, ttl);
-      }),
-    );
-  }
-
-  private generateKey(request: Request): string {
-    return `cache:${request.url}:${JSON.stringify(request.query)}`;
-  }
-}
-
-// Usage with custom TTL
-@Get()
-@SetMetadata('cacheTTL', 600)
-@UseInterceptors(HttpCacheInterceptor)
-async findAll(): Promise<User[]> {
-  return this.usersService.findAll();
-}
-
-// Error mapping interceptor
-@Injectable()
-export class ErrorMappingInterceptor implements NestInterceptor {
-  intercept(context: ExecutionContext, next: CallHandler): Observable<any> {
-    return next.handle().pipe(
-      catchError((error) => {
-        if (error instanceof EntityNotFoundError) {
-          throw new NotFoundException(error.message);
-        }
-        if (error instanceof QueryFailedError) {
-          if (error.message.includes('duplicate')) {
-            throw new ConflictException('Resource already exists');
-          }
-        }
-        throw error;
-      }),
-    );
-  }
-}
-```
-
-Reference: [NestJS Interceptors](https://docs.nestjs.com/interceptors)
@@ -1,205 +0,0 @@
---
-title: Use Pipes for Input Transformation
-impact: MEDIUM
-impactDescription: Pipes ensure clean, validated data reaches your handlers
-tags: api, pipes, validation, transformation
---
-
-## Use Pipes for Input Transformation
-
-Use built-in pipes like `ParseIntPipe`, `ParseUUIDPipe`, and `DefaultValuePipe` for common transformations. Create custom pipes for business-specific transformations. Pipes separate validation/transformation logic from controllers.
-
-**Incorrect (manual type parsing in handlers):**
-
-```typescript
-// Manual type parsing in handlers
-@Controller('users')
-export class UsersController {
-  @Get(':id')
-  async findOne(@Param('id') id: string): Promise<User> {
-    // Manual validation in every handler
-    const uuid = id.trim();
-    if (!isUUID(uuid)) {
-      throw new BadRequestException('Invalid UUID');
-    }
-    return this.usersService.findOne(uuid);
-  }
-
-  @Get()
-  async findAll(
-    @Query('page') page: string,
-    @Query('limit') limit: string,
-  ): Promise<User[]> {
-    // Manual parsing and defaults
-    const pageNum = parseInt(page) || 1;
-    const limitNum = parseInt(limit) || 10;
-    return this.usersService.findAll(pageNum, limitNum);
-  }
-}
-
-// Type coercion without validation
-@Get()
-async search(@Query('price') price: string): Promise<Product[]> {
-  const priceNum = +price; // NaN if invalid, no error
-  return this.productsService.findByPrice(priceNum);
-}
-```
-
-**Correct (use built-in and custom pipes):**
-
-```typescript
-// Use built-in pipes for common transformations
-@Controller('users')
-export class UsersController {
-  @Get(':id')
-  async findOne(@Param('id', ParseUUIDPipe) id: string): Promise<User> {
-    // id is guaranteed to be a valid UUID
-    return this.usersService.findOne(id);
-  }
-
-  @Get()
-  async findAll(
-    @Query('page', new DefaultValuePipe(1), ParseIntPipe) page: number,
-    @Query('limit', new DefaultValuePipe(10), ParseIntPipe) limit: number,
-  ): Promise<User[]> {
-    // Automatic defaults and type conversion
-    return this.usersService.findAll(page, limit);
-  }
-
-  @Get('by-status/:status')
-  async findByStatus(
-    @Param('status', new ParseEnumPipe(UserStatus)) status: UserStatus,
-  ): Promise<User[]> {
-    return this.usersService.findByStatus(status);
-  }
-}
-
-// Custom pipe for business logic
-@Injectable()
-export class ParseDatePipe implements PipeTransform<string, Date> {
-  transform(value: string): Date {
-    const date = new Date(value);
-    if (isNaN(date.getTime())) {
-      throw new BadRequestException('Invalid date format');
-    }
-    return date;
-  }
-}
-
-@Get('reports')
-async getReports(
-  @Query('from', ParseDatePipe) from: Date,
-  @Query('to', ParseDatePipe) to: Date,
-): Promise<Report[]> {
-  return this.reportsService.findBetween(from, to);
-}
-
-// Custom transformation pipes
-@Injectable()
-export class NormalizeEmailPipe implements PipeTransform<string, string> {
-  transform(value: string): string {
-    if (!value) return value;
-    return value.trim().toLowerCase();
-  }
-}
-
-// Parse comma-separated values
-@Injectable()
-export class ParseArrayPipe implements PipeTransform<string, string[]> {
-  transform(value: string): string[] {
-    if (!value) return [];
-    return value.split(',').map((v) => v.trim()).filter(Boolean);
-  }
-}
-
-@Get('products')
-async findProducts(
-  @Query('ids', ParseArrayPipe) ids: string[],
-  @Query('email', NormalizeEmailPipe) email: string,
-): Promise<Product[]> {
-  // ids is already an array, email is normalized
-  return this.productsService.findByIds(ids);
-}
-
-// Sanitize HTML input
-@Injectable()
-export class SanitizeHtmlPipe implements PipeTransform<string, string> {
-  transform(value: string): string {
-    if (!value) return value;
-    return sanitizeHtml(value, { allowedTags: [] });
-  }
-}
-
-// Global validation pipe with transformation
-app.useGlobalPipes(
-  new ValidationPipe({
-    whitelist: true, // Strip non-DTO properties
-    transform: true, // Auto-transform to DTO types
-    transformOptions: {
-      enableImplicitConversion: true, // Convert query strings to numbers
-    },
-    forbidNonWhitelisted: true, // Throw on extra properties
-  }),
-);
-
-// DTO with transformation decorators
-export class FindProductsDto {
-  @IsOptional()
-  @Type(() => Number)
-  @IsInt()
-  @Min(1)
-  page?: number = 1;
-
-  @IsOptional()
-  @Type(() => Number)
-  @IsInt()
-  @Min(1)
-  @Max(100)
-  limit?: number = 10;
-
-  @IsOptional()
-  @Transform(({ value }) => value?.toLowerCase())
-  @IsString()
-  search?: string;
-
-  @IsOptional()
-  @Transform(({ value }) => value?.split(','))
-  @IsArray()
-  @IsString({ each: true })
-  categories?: string[];
-}
-
-@Get()
-async findAll(@Query() dto: FindProductsDto): Promise<Product[]> {
-  // dto is already transformed and validated
-  return this.productsService.findAll(dto);
-}
-
-// Pipe error customization
-@Injectable()
-export class CustomParseIntPipe extends ParseIntPipe {
-  constructor() {
-    super({
-      exceptionFactory: (error) =>
-        new BadRequestException(`${error} must be a valid integer`),
-    });
-  }
-}
-
-// Or use options on built-in pipes
-@Get(':id')
-async findOne(
-  @Param(
-    'id',
-    new ParseIntPipe({
-      errorHttpStatusCode: HttpStatus.NOT_ACCEPTABLE,
-      exceptionFactory: () => new NotAcceptableException('ID must be numeric'),
-    }),
-  )
-  id: number,
-): Promise<Item> {
-  return this.itemsService.findOne(id);
-}
-```
-
-Reference: [NestJS Pipes](https://docs.nestjs.com/pipes)
@@ -1,188 +0,0 @@
---
-title: Use API Versioning for Breaking Changes
-impact: MEDIUM
-impactDescription: Versioning allows you to evolve APIs without breaking existing clients
-tags: api, versioning, breaking-changes, compatibility
---
-
-## Use API Versioning for Breaking Changes
-
-Use NestJS built-in versioning when making breaking changes to your API. Choose a versioning strategy (URI, header, or media type) and apply it consistently. This allows old clients to continue working while new clients use updated endpoints.
-
-**Incorrect (breaking changes without versioning):**
-
-```typescript
-// Breaking changes without versioning
-@Controller('users')
-export class UsersController {
-  @Get(':id')
-  async findOne(@Param('id') id: string): Promise<User> {
-    // Original response: { id, name, email }
-    // Later changed to: { id, firstName, lastName, emailAddress }
-    // Old clients break!
-    return this.usersService.findOne(id);
-  }
-}
-
-// Manual versioning in routes
-@Controller('v1/users')
-export class UsersV1Controller {}
-
-@Controller('v2/users')
-export class UsersV2Controller {}
-// Inconsistent, error-prone, hard to maintain
-```
-
-**Correct (use NestJS built-in versioning):**
-
-```typescript
-// Enable versioning in main.ts
-async function bootstrap() {
-  const app = await NestFactory.create(AppModule);
-
-  // URI versioning: /v1/users, /v2/users
-  app.enableVersioning({
-    type: VersioningType.URI,
-    defaultVersion: '1',
-  });
-
-  // Or header versioning: X-API-Version: 1
-  app.enableVersioning({
-    type: VersioningType.HEADER,
-    header: 'X-API-Version',
-    defaultVersion: '1',
-  });
-
-  // Or media type: Accept: application/json;v=1
-  app.enableVersioning({
-    type: VersioningType.MEDIA_TYPE,
-    key: 'v=',
-    defaultVersion: '1',
-  });
-
-  await app.listen(3000);
-}
-
-// Version-specific controllers
-@Controller('users')
-@Version('1')
-export class UsersV1Controller {
-  @Get(':id')
-  async findOne(@Param('id') id: string): Promise<UserV1Response> {
-    const user = await this.usersService.findOne(id);
-    // V1 response format
-    return {
-      id: user.id,
-      name: user.name,
-      email: user.email,
-    };
-  }
-}
-
-@Controller('users')
-@Version('2')
-export class UsersV2Controller {
-  @Get(':id')
-  async findOne(@Param('id') id: string): Promise<UserV2Response> {
-    const user = await this.usersService.findOne(id);
-    // V2 response format with breaking changes
-    return {
-      id: user.id,
-      firstName: user.firstName,
-      lastName: user.lastName,
-      emailAddress: user.email,
-      createdAt: user.createdAt,
-    };
-  }
-}
-
-// Per-route versioning - different versions for different routes
-@Controller('users')
-export class UsersController {
-  @Get()
-  @Version('1')
-  findAllV1(): Promise<UserV1Response[]> {
-    return this.usersService.findAllV1();
-  }
-
-  @Get()
-  @Version('2')
-  findAllV2(): Promise<UserV2Response[]> {
-    return this.usersService.findAllV2();
-  }
-
-  @Get(':id')
-  @Version(['1', '2']) // Same handler for multiple versions
-  findOne(@Param('id') id: string): Promise<User> {
-    return this.usersService.findOne(id);
-  }
-
-  @Post()
-  @Version(VERSION_NEUTRAL) // Available in all versions
-  create(@Body() dto: CreateUserDto): Promise<User> {
-    return this.usersService.create(dto);
-  }
-}
-
-// Shared service with version-specific logic
-@Injectable()
-export class UsersService {
-  async findOne(id: string, version: string): Promise<any> {
-    const user = await this.repo.findOne({ where: { id } });
-
-    if (version === '1') {
-      return this.toV1Response(user);
-    }
-    return this.toV2Response(user);
-  }
-
-  private toV1Response(user: User): UserV1Response {
-    return {
-      id: user.id,
-      name: `${user.firstName} ${user.lastName}`,
-      email: user.email,
-    };
-  }
-
-  private toV2Response(user: User): UserV2Response {
-    return {
-      id: user.id,
-      firstName: user.firstName,
-      lastName: user.lastName,
-      emailAddress: user.email,
-      createdAt: user.createdAt,
-    };
-  }
-}
-
-// Controller extracts version
-@Controller('users')
-export class UsersController {
-  @Get(':id')
-  async findOne(@Param('id') id: string, @Headers('X-API-Version') version: string = '1'): Promise<any> {
-    return this.usersService.findOne(id, version);
-  }
-}
-
-// Deprecation strategy - mark old versions as deprecated
-@Controller('users')
-@Version('1')
-@UseInterceptors(DeprecationInterceptor)
-export class UsersV1Controller {
-  // All V1 routes will include deprecation warning
-}
-
-@Injectable()
-export class DeprecationInterceptor implements NestInterceptor {
-  intercept(context: ExecutionContext, next: CallHandler): Observable<any> {
-    const response = context.switchToHttp().getResponse();
-    response.setHeader('Deprecation', 'true');
-    response.setHeader('Sunset', 'Sat, 1 Jan 2025 00:00:00 GMT');
-    response.setHeader('Link', '</v2/users>; rel="successor-version"');
-
-    return next.handle();
-  }
-}
-```
-
-Reference: [NestJS Versioning](https://docs.nestjs.com/techniques/versioning)
@@ -1,80 +0,0 @@
---
-title: Avoid Circular Dependencies
-impact: CRITICAL
-impactDescription: '#1 cause of runtime crashes'
-tags: architecture, modules, dependencies
---
-
-## Avoid Circular Dependencies
-
-Circular dependencies occur when Module A imports Module B, and Module B imports Module A (directly or transitively). NestJS can sometimes resolve these through forward references, but they indicate architectural problems and should be avoided. This is the #1 cause of runtime crashes in NestJS applications.
-
-**Incorrect (circular module imports):**
-
-```typescript
-// users.module.ts
-@Module({
-  imports: [OrdersModule], // Orders needs Users, Users needs Orders = circular
-  providers: [UsersService],
-  exports: [UsersService],
-})
-export class UsersModule {}
-
-// orders.module.ts
-@Module({
-  imports: [UsersModule], // Circular dependency!
-  providers: [OrdersService],
-  exports: [OrdersService],
-})
-export class OrdersModule {}
-```
-
-**Correct (extract shared logic or use events):**
-
-```typescript
-// Option 1: Extract shared logic to a third module
-// shared.module.ts
-@Module({
-  providers: [SharedService],
-  exports: [SharedService],
-})
-export class SharedModule {}
-
-// users.module.ts
-@Module({
-  imports: [SharedModule],
-  providers: [UsersService],
-})
-export class UsersModule {}
-
-// orders.module.ts
-@Module({
-  imports: [SharedModule],
-  providers: [OrdersService],
-})
-export class OrdersModule {}
-
-// Option 2: Use events for decoupled communication
-// users.service.ts
-@Injectable()
-export class UsersService {
-  constructor(private eventEmitter: EventEmitter2) {}
-
-  async createUser(data: CreateUserDto) {
-    const user = await this.userRepo.save(data);
-    this.eventEmitter.emit('user.created', user);
-    return user;
-  }
-}
-
-// orders.service.ts
-@Injectable()
-export class OrdersService {
-  @OnEvent('user.created')
-  handleUserCreated(user: User) {
-    // React to user creation without direct dependency
-  }
-}
-```
-
-Reference: [NestJS Circular Dependency](https://docs.nestjs.com/fundamentals/circular-dependency)
@@ -1,82 +0,0 @@
---
-title: Organize by Feature Modules
-impact: CRITICAL
-impactDescription: '3-5x faster onboarding and development'
-tags: architecture, modules, organization
---
-
-## Organize by Feature Modules
-
-Organize your application into feature modules that encapsulate related functionality. Each feature module should be self-contained with its own controllers, services, entities, and DTOs. Avoid organizing by technical layer (all controllers together, all services together). This enables 3-5x faster onboarding and feature development.
-
-**Incorrect (technical layer organization):**
-
-```typescript
-// Technical layer organization (anti-pattern)
-src/
-├── controllers/
-│   ├── users.controller.ts
-│   ├── orders.controller.ts
-│   └── products.controller.ts
-├── services/
-│   ├── users.service.ts
-│   ├── orders.service.ts
-│   └── products.service.ts
-├── entities/
-│   ├── user.entity.ts
-│   ├── order.entity.ts
-│   └── product.entity.ts
-└── app.module.ts  // Imports everything directly
-```
-
-**Correct (feature module organization):**
-
-```typescript
-// Feature module organization
-src/
-├── users/
-│   ├── dto/
-│   │   ├── create-user.dto.ts
-│   │   └── update-user.dto.ts
-│   ├── entities/
-│   │   └── user.entity.ts
-│   ├── users.controller.ts
-│   ├── users.service.ts
-│   ├── users.repository.ts
-│   └── users.module.ts
-├── orders/
-│   ├── dto/
-│   ├── entities/
-│   ├── orders.controller.ts
-│   ├── orders.service.ts
-│   └── orders.module.ts
-├── shared/
-│   ├── guards/
-│   ├── interceptors/
-│   ├── filters/
-│   └── shared.module.ts
-└── app.module.ts
-
-// users.module.ts
-@Module({
-  imports: [TypeOrmModule.forFeature([User])],
-  controllers: [UsersController],
-  providers: [UsersService, UsersRepository],
-  exports: [UsersService], // Only export what others need
-})
-export class UsersModule {}
-
-// app.module.ts
-@Module({
-  imports: [
-    ConfigModule.forRoot(),
-    TypeOrmModule.forRoot(),
-    UsersModule,
-    OrdersModule,
-    SharedModule,
-  ],
-})
-export class AppModule {}
-```
-
-Reference: [NestJS Modules](https://docs.nestjs.com/modules)
@@ -1,141 +0,0 @@
---
-title: Use Proper Module Sharing Patterns
-impact: CRITICAL
-impactDescription: Prevents duplicate instances, memory leaks, and state inconsistency
-tags: architecture, modules, sharing, exports
---
-
-## Use Proper Module Sharing Patterns
-
-NestJS modules are singletons by default. When a service is properly exported from a module and that module is imported elsewhere, the same instance is shared. However, providing a service in multiple modules creates separate instances, leading to memory waste, state inconsistency, and confusing behavior. Always encapsulate services in dedicated modules, export them explicitly, and import the module where needed.
-
-**Incorrect (service provided in multiple modules):**
-
-```typescript
-// StorageService provided directly in multiple modules - WRONG
-// storage.service.ts
-@Injectable()
-export class StorageService {
-  private cache = new Map(); // Each instance has separate state!
-
-  store(key: string, value: any) {
-    this.cache.set(key, value);
-  }
-}
-
-// app.module.ts
-@Module({
-  providers: [StorageService], // Instance #1
-  controllers: [AppController],
-})
-export class AppModule {}
-
-// videos.module.ts
-@Module({
-  providers: [StorageService], // Instance #2 - different from AppModule!
-  controllers: [VideosController],
-})
-export class VideosModule {}
-
-// Problems:
-// 1. Two separate StorageService instances exist
-// 2. cache.set() in VideosModule doesn't affect AppModule's cache
-// 3. Memory wasted on duplicate instances
-// 4. Debugging nightmares when state doesn't sync
-```
-
-**Correct (dedicated module with exports):**
-
-```typescript
-// storage/storage.module.ts
-@Module({
-  providers: [StorageService],
-  exports: [StorageService], // Make available to importers
-})
-export class StorageModule {}
-
-// videos/videos.module.ts
-@Module({
-  imports: [StorageModule], // Import the module, not the service
-  controllers: [VideosController],
-  providers: [VideosService],
-})
-export class VideosModule {}
-
-// channels/channels.module.ts
-@Module({
-  imports: [StorageModule], // Same instance shared
-  controllers: [ChannelsController],
-  providers: [ChannelsService],
-})
-export class ChannelsModule {}
-
-// app.module.ts
-@Module({
-  imports: [
-    StorageModule, // Only if AppModule itself needs StorageService
-    VideosModule,
-    ChannelsModule,
-  ],
-})
-export class AppModule {}
-
-// Now all modules share the SAME StorageService instance
-```
-
-**When to use @Global() (sparingly):**
-
-```typescript
-// ONLY for truly cross-cutting concerns
-@Global()
-@Module({
-  providers: [ConfigService, LoggerService],
-  exports: [ConfigService, LoggerService],
-})
-export class CoreModule {}
-
-// Import once in AppModule
-@Module({
-  imports: [CoreModule], // Registered globally, available everywhere
-})
-export class AppModule {}
-
-// Other modules don't need to import CoreModule
-@Module({
-  controllers: [UsersController],
-  providers: [UsersService], // Can inject ConfigService without importing
-})
-export class UsersModule {}
-
-// WARNING: Don't make everything global!
-// - Hides dependencies (can't see what a module needs from imports)
-// - Makes testing harder
-// - Reserve for: config, logging, database connections
-```
-
-**Module re-exporting pattern:**
-
-```typescript
-// common.module.ts - shared utilities
-@Module({
-  providers: [DateService, ValidationService],
-  exports: [DateService, ValidationService],
-})
-export class CommonModule {}
-
-// core.module.ts - re-exports common for convenience
-@Module({
-  imports: [CommonModule, DatabaseModule],
-  exports: [CommonModule, DatabaseModule], // Re-export for consumers
-})
-export class CoreModule {}
-
-// feature.module.ts - imports CoreModule, gets both
-@Module({
-  imports: [CoreModule], // Gets CommonModule + DatabaseModule
-  controllers: [FeatureController],
-})
-export class FeatureModule {}
-```
-
-Reference: [NestJS Modules](https://docs.nestjs.com/modules#shared-modules)
@@ -1,106 +0,0 @@
---
-title: Single Responsibility for Services
-impact: CRITICAL
-impactDescription: '40%+ improvement in testability'
-tags: architecture, services, single-responsibility
---
-
-## Single Responsibility for Services
-
-Each service should have a single, well-defined responsibility. Avoid "god services" that handle multiple unrelated concerns. If a service name includes "And" or handles more than one domain concept, it likely violates single responsibility. This reduces complexity and improves testability by 40%+.
-
-**Incorrect (god service anti-pattern):**
-
-```typescript
-// God service anti-pattern
-@Injectable()
-export class UserAndOrderService {
-  constructor(
-    private userRepo: UserRepository,
-    private orderRepo: OrderRepository,
-    private mailer: MailService,
-    private payment: PaymentService
-  ) {}
-
-  async createUser(dto: CreateUserDto) {
-    const user = await this.userRepo.save(dto);
-    await this.mailer.sendWelcome(user);
-    return user;
-  }
-
-  async createOrder(userId: string, dto: CreateOrderDto) {
-    const order = await this.orderRepo.save({ userId, ...dto });
-    await this.payment.charge(order);
-    await this.mailer.sendOrderConfirmation(order);
-    return order;
-  }
-
-  async calculateOrderStats(userId: string) {
-    // Stats logic mixed in
-  }
-
-  async validatePayment(orderId: string) {
-    // Payment logic mixed in
-  }
-}
-```
-
-**Correct (focused services with single responsibility):**
-
-```typescript
-// Focused services with single responsibility
-@Injectable()
-export class UsersService {
-  constructor(private userRepo: UserRepository) {}
-
-  async create(dto: CreateUserDto): Promise<User> {
-    return this.userRepo.save(dto);
-  }
-
-  async findById(id: string): Promise<User> {
-    return this.userRepo.findOneOrFail({ where: { id } });
-  }
-}
-
-@Injectable()
-export class OrdersService {
-  constructor(private orderRepo: OrderRepository) {}
-
-  async create(userId: string, dto: CreateOrderDto): Promise<Order> {
-    return this.orderRepo.save({ userId, ...dto });
-  }
-
-  async findByUser(userId: string): Promise<Order[]> {
-    return this.orderRepo.find({ where: { userId } });
-  }
-}
-
-@Injectable()
-export class OrderStatsService {
-  constructor(private orderRepo: OrderRepository) {}
-
-  async calculateForUser(userId: string): Promise<OrderStats> {
-    // Focused stats calculation
-  }
-}
-
-// Orchestration in controller or dedicated orchestrator
-@Controller('orders')
-export class OrdersController {
-  constructor(
-    private orders: OrdersService,
-    private payment: PaymentService,
-    private notifications: NotificationService
-  ) {}
-
-  @Post()
-  async create(@CurrentUser() user: User, @Body() dto: CreateOrderDto) {
-    const order = await this.orders.create(user.id, dto);
-    await this.payment.charge(order);
-    await this.notifications.sendOrderConfirmation(order);
-    return order;
-  }
-}
-```
-
-Reference: [NestJS Providers](https://docs.nestjs.com/providers)
@@ -1,105 +0,0 @@
---
-title: Use Event-Driven Architecture for Decoupling
-impact: MEDIUM-HIGH
-impactDescription: Enables async processing and modularity
-tags: architecture, events, decoupling
---
-
-## Use Event-Driven Architecture for Decoupling
-
-Use `@nestjs/event-emitter` for intra-service events and message brokers for inter-service communication. Events allow modules to react to changes without direct dependencies, improving modularity and enabling async processing.
-
-**Incorrect (direct service coupling):**
-
-```typescript
-// Direct service coupling
-@Injectable()
-export class OrdersService {
-  constructor(
-    private inventoryService: InventoryService,
-    private emailService: EmailService,
-    private analyticsService: AnalyticsService,
-    private notificationService: NotificationService,
-    private loyaltyService: LoyaltyService
-  ) {}
-
-  async createOrder(dto: CreateOrderDto): Promise<Order> {
-    const order = await this.repo.save(dto);
-
-    // Tight coupling - OrdersService knows about all consumers
-    await this.inventoryService.reserve(order.items);
-    await this.emailService.sendConfirmation(order);
-    await this.analyticsService.track('order_created', order);
-    await this.notificationService.push(order.userId, 'Order placed');
-    await this.loyaltyService.addPoints(order.userId, order.total);
-
-    // Adding new behavior requires modifying this service
-    return order;
-  }
-}
-```
-
-**Correct (event-driven decoupling):**
-
-```typescript
-// Use EventEmitter for decoupling
-import { EventEmitter2 } from '@nestjs/event-emitter';
-
-// Define event
-export class OrderCreatedEvent {
-  constructor(
-    public readonly orderId: string,
-    public readonly userId: string,
-    public readonly items: OrderItem[],
-    public readonly total: number
-  ) {}
-}
-
-// Service emits events
-@Injectable()
-export class OrdersService {
-  constructor(
-    private eventEmitter: EventEmitter2,
-    private repo: Repository<Order>
-  ) {}
-
-  async createOrder(dto: CreateOrderDto): Promise<Order> {
-    const order = await this.repo.save(dto);
-
-    // Emit event - no knowledge of consumers
-    this.eventEmitter.emit('order.created', new OrderCreatedEvent(order.id, order.userId, order.items, order.total));
-
-    return order;
-  }
-}
-
-// Listeners in separate modules
-@Injectable()
-export class InventoryListener {
-  @OnEvent('order.created')
-  async handleOrderCreated(event: OrderCreatedEvent): Promise<void> {
-    await this.inventoryService.reserve(event.items);
-  }
-}
-
-@Injectable()
-export class EmailListener {
-  @OnEvent('order.created')
-  async handleOrderCreated(event: OrderCreatedEvent): Promise<void> {
-    await this.emailService.sendConfirmation(event.orderId);
-  }
-}
-
-@Injectable()
-export class AnalyticsListener {
-  @OnEvent('order.created')
-  async handleOrderCreated(event: OrderCreatedEvent): Promise<void> {
-    await this.analyticsService.track('order_created', {
-      orderId: event.orderId,
-      total: event.total,
-    });
-  }
-}
-```
-
-Reference: [NestJS Events](https://docs.nestjs.com/techniques/events)
@@ -1,93 +0,0 @@
---
-title: Use Repository Pattern for Data Access
-impact: HIGH
-impactDescription: Decouples business logic from database
-tags: architecture, repository, data-access
---
-
-## Use Repository Pattern for Data Access
-
-Create custom repositories to encapsulate complex queries and database logic. This keeps services focused on business logic, makes testing easier with mock repositories, and allows changing database implementations without affecting business code.
-
-**Incorrect (complex queries in services):**
-
-```typescript
-// Complex queries in services
-@Injectable()
-export class UsersService {
-  constructor(@InjectRepository(User) private repo: Repository<User>) {}
-
-  async findActiveWithOrders(minOrders: number): Promise<User[]> {
-    // Complex query logic mixed with business logic
-    return this.repo
-      .createQueryBuilder('user')
-      .leftJoinAndSelect('user.orders', 'order')
-      .where('user.isActive = :active', { active: true })
-      .andWhere('user.deletedAt IS NULL')
-      .groupBy('user.id')
-      .having('COUNT(order.id) >= :min', { min: minOrders })
-      .orderBy('user.createdAt', 'DESC')
-      .getMany();
-  }
-
-  // Service becomes bloated with query logic
-}
-```
-
-**Correct (custom repository with encapsulated queries):**
-
-```typescript
-// Custom repository with encapsulated queries
-@Injectable()
-export class UsersRepository {
-  constructor(@InjectRepository(User) private repo: Repository<User>) {}
-
-  async findById(id: string): Promise<User | null> {
-    return this.repo.findOne({ where: { id } });
-  }
-
-  async findByEmail(email: string): Promise<User | null> {
-    return this.repo.findOne({ where: { email } });
-  }
-
-  async findActiveWithMinOrders(minOrders: number): Promise<User[]> {
-    return this.repo
-      .createQueryBuilder('user')
-      .leftJoinAndSelect('user.orders', 'order')
-      .where('user.isActive = :active', { active: true })
-      .andWhere('user.deletedAt IS NULL')
-      .groupBy('user.id')
-      .having('COUNT(order.id) >= :min', { min: minOrders })
-      .orderBy('user.createdAt', 'DESC')
-      .getMany();
-  }
-
-  async save(user: User): Promise<User> {
-    return this.repo.save(user);
-  }
-}
-
-// Clean service with business logic only
-@Injectable()
-export class UsersService {
-  constructor(private usersRepo: UsersRepository) {}
-
-  async getActiveUsersWithOrders(): Promise<User[]> {
-    return this.usersRepo.findActiveWithMinOrders(1);
-  }
-
-  async create(dto: CreateUserDto): Promise<User> {
-    const existing = await this.usersRepo.findByEmail(dto.email);
-    if (existing) {
-      throw new ConflictException('Email already registered');
-    }
-
-    const user = new User();
-    user.email = dto.email;
-    user.name = dto.name;
-    return this.usersRepo.save(user);
-  }
-}
-```
-
-Reference: [Repository Pattern](https://martinfowler.com/eaaCatalog/repository.html)
@@ -1,139 +0,0 @@
---
-title: Avoid N+1 Query Problems
-impact: HIGH
-impactDescription: N+1 queries are one of the most common performance killers
-tags: database, n-plus-one, queries, performance
---
-
-## Avoid N+1 Query Problems
-
-N+1 queries occur when you fetch a list of entities, then make an additional query for each entity to load related data. Use eager loading with `relations`, query builder joins, or DataLoader to batch queries efficiently.
-
-**Incorrect (lazy loading in loops causes N+1):**
-
-```typescript
-// Lazy loading in loops causes N+1
-@Injectable()
-export class OrdersService {
-  async getOrdersWithItems(userId: string): Promise<Order[]> {
-    const orders = await this.orderRepo.find({ where: { userId } });
-    // 1 query for orders
-
-    for (const order of orders) {
-      // N additional queries - one per order!
-      order.items = await this.itemRepo.find({ where: { orderId: order.id } });
-    }
-
-    return orders;
-  }
-}
-
-// Accessing lazy relations without loading
-@Controller('users')
-export class UsersController {
-  @Get()
-  async findAll(): Promise<User[]> {
-    const users = await this.userRepo.find();
-    // If User.posts is lazy-loaded, serializing triggers N queries
-    return users; // Each user.posts access = 1 query
-  }
-}
-```
-
-**Correct (use relations for eager loading):**
-
-```typescript
-// Use relations option for eager loading
-@Injectable()
-export class OrdersService {
-  async getOrdersWithItems(userId: string): Promise<Order[]> {
-    // Single query with JOIN
-    return this.orderRepo.find({
-      where: { userId },
-      relations: ['items', 'items.product'],
-    });
-  }
-}
-
-// Use QueryBuilder for complex joins
-@Injectable()
-export class UsersService {
-  async getUsersWithPostCounts(): Promise<UserWithPostCount[]> {
-    return this.userRepo
-      .createQueryBuilder('user')
-      .leftJoin('user.posts', 'post')
-      .select('user.id', 'id')
-      .addSelect('user.name', 'name')
-      .addSelect('COUNT(post.id)', 'postCount')
-      .groupBy('user.id')
-      .getRawMany();
-  }
-
-  async getActiveUsersWithPosts(): Promise<User[]> {
-    return this.userRepo
-      .createQueryBuilder('user')
-      .leftJoinAndSelect('user.posts', 'post')
-      .leftJoinAndSelect('post.comments', 'comment')
-      .where('user.isActive = :active', { active: true })
-      .andWhere('post.status = :status', { status: 'published' })
-      .getMany();
-  }
-}
-
-// Use find options for specific fields
-async getOrderSummaries(userId: string): Promise<OrderSummary[]> {
-  return this.orderRepo.find({
-    where: { userId },
-    relations: ['items'],
-    select: {
-      id: true,
-      total: true,
-      status: true,
-      items: {
-        id: true,
-        quantity: true,
-        price: true,
-      },
-    },
-  });
-}
-
-// Use DataLoader for GraphQL to batch and cache queries
-import DataLoader from 'dataloader';
-
-@Injectable({ scope: Scope.REQUEST })
-export class PostsLoader {
-  constructor(private postsService: PostsService) {}
-
-  readonly batchPosts = new DataLoader<string, Post[]>(async (userIds) => {
-    // Single query for all users' posts
-    const posts = await this.postsService.findByUserIds([...userIds]);
-
-    // Group by userId
-    const postsMap = new Map<string, Post[]>();
-    for (const post of posts) {
-      const userPosts = postsMap.get(post.userId) || [];
-      userPosts.push(post);
-      postsMap.set(post.userId, userPosts);
-    }
-
-    // Return in same order as input
-    return userIds.map((id) => postsMap.get(id) || []);
-  });
-}
-
-// In resolver
-@ResolveField()
-async posts(@Parent() user: User): Promise<Post[]> {
-  // DataLoader batches multiple calls into single query
-  return this.postsLoader.batchPosts.load(user.id);
-}
-
-// Enable query logging in development to detect N+1
-TypeOrmModule.forRoot({
-  logging: ['query', 'error'],
-  logger: 'advanced-console',
-});
-```
-
-Reference: [TypeORM Relations](https://typeorm.io/relations)
@@ -1,229 +0,0 @@
---
-title: Hybrid Identifier Strategy (ADR-019)
-impact: CRITICAL
-impactDescription: Use INT PK internally + UUID for public API per project ADR-019
-tags: database, uuid, identifier, adr-019, api-design, typeorm
---
-
-## Hybrid Identifier Strategy (ADR-019) — March 2026 Pattern
-
-**This project follows ADR-019: INT Primary Key (internal) + UUIDv7 (public API)**
-
-Unlike standard practices that use UUID as the primary key, this project uses a **hybrid approach** optimized for MariaDB performance and API consistency.
-
-> **Updated pattern (March 2026):** Entities extend `UuidBaseEntity`. The `publicId` column is exposed **directly** in API responses — ห้ามใช้ `@Expose({ name: 'id' })` เพื่อ rename.
-
-### The Strategy
-
-| Layer           | Field      | Type                                | Usage                                             |
-| --------------- | ---------- | ----------------------------------- | ------------------------------------------------- |
-| **Database PK** | `id`       | `INT AUTO_INCREMENT`                | Internal foreign keys only (marked `@Exclude()`)  |
-| **Public API**  | `publicId` | `MariaDB UUID` (native, BINARY(16)) | External references, URLs — exposed as-is         |
-| **DTO Input**   | `xxxUuid`  | `string` (UUIDv7)                   | Accept UUID in create/update DTOs                 |
-| **DTO Output**  | `publicId` | `string` (UUIDv7)                   | API returns `publicId` field directly (no rename) |
-
-### Why Hybrid IDs?
-
- **Performance**: INT PK is faster for joins and indexing than UUID
- **Security**: Internal IDs never exposed in API (enumerable IDs are a risk)
- **Compatibility**: UUID works well with distributed systems and external integrations
- **MariaDB Native**: Uses MariaDB's native UUID type (stored as BINARY(16), auto-converts to string)
-
-### Entity Definition (Current Pattern)
-
-```typescript
-import { Entity, Column } from 'typeorm';
-import { UuidBaseEntity } from '@/common/entities/uuid-base.entity';
-
-@Entity('contracts')
-export class Contract extends UuidBaseEntity {
-  // publicId (string UUIDv7) + id (INT, @Exclude) สืบทอดจาก UuidBaseEntity
-  // API response → { publicId: "019505a1-7c3e-7000-8000-abc123...", contractCode: ..., ... }
-
-  @Column()
-  contractCode: string;
-
-  @Column()
-  contractName: string;
-
-  @Column({ name: 'project_id' })
-  projectId: number; // INT FK — internal, not exposed if marked @Exclude in UuidBaseEntity
-}
-```
-
-**`UuidBaseEntity` (shared base):**
-
-```typescript
-import { PrimaryGeneratedColumn, Column, CreateDateColumn, UpdateDateColumn } from 'typeorm';
-import { Exclude } from 'class-transformer';
-
-export abstract class UuidBaseEntity {
-  @PrimaryGeneratedColumn()
-  @Exclude() // ❗ CRITICAL: INT id must never leak to API
-  id: number;
-
-  @Column({ type: 'uuid', unique: true, generated: 'uuid' })
-  publicId: string; // UUIDv7, exposed as-is
-
-  @CreateDateColumn()
-  createdAt: Date;
-
-  @UpdateDateColumn()
-  updatedAt: Date;
-}
-```
-
-### DTO Pattern (Accept UUID, Resolve to INT Internally)
-
-```typescript
-// dto/create-contract.dto.ts
-import { IsUUID, IsNotEmpty } from 'class-validator';
-
-export class CreateContractDto {
-  @IsNotEmpty()
-  @IsUUID('7') // UUIDv7 (MariaDB native)
-  projectUuid: string; // Accept UUID from client
-
-  @IsNotEmpty()
-  contractCode: string;
-
-  @IsNotEmpty()
-  contractName: string;
-}
-
-// ❌ NO Response DTO with @Expose rename needed.
-// Entity class_transformer via TransformInterceptor will serialize publicId directly.
-```
-
-### Service/Controller Pattern
-
-```typescript
-@Controller('contracts')
-@UseGuards(JwtAuthGuard, CaslAbilityGuard)
-export class ContractsController {
-  constructor(
-    private contractsService: ContractsService,
-    private uuidResolver: UuidResolver
-  ) {}
-
-  @Post()
-  async create(@Body() dto: CreateContractDto) {
-    // Resolve UUID → INT PK for FK relationship
-    const projectId = await this.uuidResolver.resolveProject(dto.projectUuid);
-
-    const contract = await this.contractsService.create({
-      ...dto,
-      projectId,
-    });
-
-    // Response: TransformInterceptor + @Exclude on id → publicId exposed directly
-    return contract;
-  }
-
-  @Get(':publicId')
-  async findOne(@Param('publicId', ParseUuidPipe) publicId: string) {
-    return this.contractsService.findOneByPublicId(publicId);
-  }
-}
-```
-
-### UUID Resolver Helper
-
-```typescript
-@Injectable()
-export class UuidResolver {
-  constructor(
-    @InjectRepository(Project)
-    private projectRepo: Repository<Project>,
-    @InjectRepository(Contract)
-    private contractRepo: Repository<Contract>
-  ) {}
-
-  async resolveProject(publicId: string): Promise<number> {
-    const project = await this.projectRepo.findOne({
-      where: { publicId },
-      select: ['id'], // Only INT PK for FK
-    });
-    if (!project) throw new NotFoundException('Project not found');
-    return project.id;
-  }
-
-  async resolveContract(publicId: string): Promise<number> {
-    const contract = await this.contractRepo.findOne({
-      where: { publicId },
-      select: ['id'],
-    });
-    if (!contract) throw new NotFoundException('Contract not found');
-    return contract.id;
-  }
-}
-```
-
-### TransformInterceptor (Required — register ONCE)
-
-```typescript
-// Register via APP_INTERCEPTOR in CommonModule — ห้ามซ้ำใน main.ts
-@Injectable()
-export class TransformInterceptor implements NestInterceptor {
-  intercept(context: ExecutionContext, next: CallHandler): Observable<any> {
-    return next.handle().pipe(
-      map((data) => instanceToPlain(data)) // Applies @Exclude / @Expose
-    );
-  }
-}
-
-// common.module.ts
-@Module({
-  providers: [
-    {
-      provide: APP_INTERCEPTOR,
-      useClass: TransformInterceptor,
-    },
-  ],
-})
-export class CommonModule {}
-```
-
-> **Warning:** ห้ามเรียก `app.useGlobalInterceptors(new TransformInterceptor())` ใน `main.ts` ซ้ำ — จะทำให้ response double-wrap `{ data: { data: ... } }`.
-
-### Critical: NEVER ParseInt on UUID
-
-```typescript
-// ❌ WRONG - parseInt on UUID gives garbage value
-const id = parseInt(projectPublicId); // "0195a1b2-..." → 195 (wrong!)
-
-// ❌ WRONG - Number() on UUID
-const id = Number(projectPublicId); // NaN
-
-// ❌ WRONG - Unary plus on UUID
-const id = +projectPublicId; // NaN
-
-// ✅ CORRECT - Resolve via database lookup
-const projectId = await uuidResolver.resolveProject(projectPublicId);
-
-// ✅ CORRECT - Use TypeORM find with publicId column
-const project = await projectRepo.findOne({ where: { publicId: projectPublicId } });
-const id = project.id; // Get INT PK from entity
-```
-
-### Query with publicId (No Resolution Needed)
-
-```typescript
-// Direct UUID lookup in TypeORM
-const project = await this.projectRepo.findOne({
-  where: { publicId: projectPublicId },
-});
-
-// Relations use INT FK internally
-const contracts = await this.contractRepo.find({
-  where: { projectId: project.id }, // INT for FK query
-});
-```
-
-### Reference
-
- [ADR-019 Hybrid Identifier Strategy](../../../../specs/06-Decision-Records/ADR-019-hybrid-identifier-strategy.md)
- [UUID Implementation Plan](../../../../specs/05-Engineering-Guidelines/05-07-hybrid-uuid-implementation-plan.md)
- [Data Dictionary](../../../../specs/03-Data-and-Storage/03-01-data-dictionary.md)
-
-> **Warning**: Using `parseInt()`, `Number()`, or unary `+` on UUID values violates ADR-019 and will cause data corruption. Always resolve UUIDs via database lookup.
@@ -1,100 +0,0 @@
---
-title: No TypeORM Migrations (ADR-009)
-impact: CRITICAL
-impactDescription: Edit SQL schema files directly; n8n handles data migration. Do not generate TypeORM migration files.
-tags: database, schema, migration, adr-009, sql, n8n
---
-
-## No TypeORM Migrations (ADR-009)
-
-**This project does NOT use TypeORM migration files.**
-
-All schema changes must be made **directly** in the canonical SQL file:
-
- `specs/03-Data-and-Storage/lcbp3-v1.8.0-schema-02-tables.sql`
-
-Delta scripts (for incremental rollout to existing environments) go under:
-
- `specs/03-Data-and-Storage/deltas/YYYY-MM-DD-descriptive-name.sql`
-
-Data migration (e.g., backfilling a new column) is handled by **n8n workflows**, not TypeORM's `QueryRunner`.
-
---
-
-## Why No Migrations?
-
-1. **Single source of truth** — The full SQL schema is always readable as one file. No need to replay a migration chain to understand current state.
-2. **Review friendly** — Schema diff = git diff on the SQL file. Reviewers see the complete picture.
-3. **Ops alignment** — DBAs and operators work in SQL, not TypeScript.
-4. **n8n for data** — Business-meaningful data transforms live in n8n where they can be versioned, retried, and orchestrated with monitoring.
-
---
-
-## ✅ Workflow for a Schema Change
-
-1. **Update Data Dictionary** first:
-   - `specs/03-Data-and-Storage/03-01-data-dictionary.md` — add field meaning + business rules.
-2. **Update the canonical schema**:
-   - Edit `lcbp3-v1.8.0-schema-02-tables.sql` — add/alter column, constraint, index.
-3. **Add a delta script** (if deploying to existing env):
-   - `specs/03-Data-and-Storage/deltas/2026-04-22-add-rfa-revision-column.sql`
-
-   ```sql
-   -- Delta: Add revision column to rfa table
-   ALTER TABLE rfa
-     ADD COLUMN revision INT NOT NULL DEFAULT 1 AFTER status;
-
-   CREATE INDEX idx_rfa_revision ON rfa(revision);
-   ```
-4. **Update the Entity** (`backend/src/.../entities/rfa.entity.ts`):
-
-   ```typescript
-   @Column({ type: 'int', default: 1 })
-   revision: number;
-   ```
-5. **If data backfill needed** → create n8n workflow, not TypeScript migration.
-
---
-
-## ❌ Forbidden
-
-```bash
-# ❌ DO NOT generate migrations
-pnpm typeorm migration:generate ./src/migrations/AddRevision
-
-# ❌ DO NOT run migrations
-pnpm typeorm migration:run
-```
-
-```typescript
-// ❌ DO NOT write migration classes
-export class AddRevision1730000000000 implements MigrationInterface {
-  async up(queryRunner: QueryRunner): Promise<void> { /* ... */ }
-  async down(queryRunner: QueryRunner): Promise<void> { /* ... */ }
-}
-```
-
---
-
-## ✅ TypeORM Config (runtime only)
-
-```typescript
-// ormconfig.ts
-export default {
-  type: 'mariadb',
-  // ...
-  synchronize: false,      // ❗ NEVER true (would auto-sync entity ↔ schema)
-  migrationsRun: false,    // ❗ NEVER true
-  // ❌ Do NOT specify `migrations:` entries
-};
-```
-
-`synchronize: false` is mandatory because the canonical SQL file is authoritative — TypeORM should never mutate the schema.
-
---
-
-## Reference
-
- [ADR-009 Database Migration Strategy](../../../../specs/06-Decision-Records/ADR-009-database-migration-strategy.md)
- [Data Dictionary](../../../../specs/03-Data-and-Storage/03-01-data-dictionary.md)
- [Schema Tables](../../../../specs/03-Data-and-Storage/lcbp3-v1.8.0-schema-02-tables.sql)
@@ -1,128 +0,0 @@
---
-title: No TypeORM Migrations (ADR-009)
-impact: HIGH
-impactDescription: Use direct SQL schema files instead of TypeORM migrations per project ADR
-tags: database, schema, typeorm, migrations, adr-009
---
-
-## No TypeORM Migrations (ADR-009)
-
-**This project follows ADR-009: Direct SQL Schema Management**
-
-Unlike standard NestJS/TypeORM practices, this project does **NOT** use TypeORM migrations. Instead, we manage database schema through direct SQL files.
-
-### Why No Migrations?
-
- **ADR-009 Decision**: Explicit schema control over auto-generated migrations
- **MariaDB-specific features**: Native UUID type, virtual columns, custom indexing
- **Team workflow**: Schema changes reviewed as SQL, not TypeORM migration classes
- **Audit trail**: Single source of truth in `specs/03-Data-and-Storage/`
-
-### Schema File Locations
-
-```
-specs/03-Data-and-Storage/
-├── lcbp3-v1.8.0-schema-01-drop.sql      # Drop statements (dev only)
-├── lcbp3-v1.8.0-schema-02-tables.sql   # CREATE TABLE statements
-├── lcbp3-v1.8.0-schema-03-views-indexes.sql  # Views, indexes, constraints
-└── deltas/                              # Incremental changes
-    ├── 01-add-reference-date.sql
-    ├── 02-add-rbac-bulk-permission.sql
-    └── 03-fix-numbering-enums.sql
-```
-
-### Correct: Using SQL Schema Files
-
-```typescript
-// TypeORM configuration - NO migrationsRun
-TypeOrmModule.forRootAsync({
-  inject: [ConfigService],
-  useFactory: (config: ConfigService) => ({
-    type: 'mariadb',
-    host: config.get('DB_HOST'),
-    port: config.get('DB_PORT'),
-    username: config.get('DB_USERNAME'),
-    password: config.get('DB_PASSWORD'),
-    database: config.get('DB_NAME'),
-    entities: ['dist/**/*.entity.js'],
-    synchronize: false, // NEVER true, even in development
-    migrationsRun: false, // Disabled per ADR-009
-    // Migrations are managed via SQL files, not TypeORM
-  }),
-});
-```
-
-### Schema Change Process (ADR-009)
-
-1. **Modify SQL file directly**:
-
-   ```sql
-   -- specs/03-Data-and-Storage/lcbp3-v1.8.0-schema-02-tables.sql
-   ALTER TABLE correspondences
-   ADD COLUMN priority VARCHAR(20) DEFAULT 'normal';
-   ```
-
-2. **Create delta for existing databases**:
-
-   ```sql
-   -- specs/03-Data-and-Storage/deltas/04-add-priority-column.sql
-   ALTER TABLE correspondences
-   ADD COLUMN priority VARCHAR(20) DEFAULT 'normal';
-   ```
-
-3. **Apply to database manually or via deployment script**:
-   ```bash
-   mysql -u root -p lcbp3 < specs/03-Data-and-Storage/deltas/04-add-priority-column.sql
-   ```
-
-### Entity Definition (No Migration Needed)
-
-```typescript
-@Entity('correspondences')
-export class Correspondence {
-  @PrimaryGeneratedColumn()
-  id: number; // Internal INT PK
-
-  @Column({ type: 'uuid' })
-  uuid: string; // Public UUID
-
-  @Column({ name: 'priority', default: 'normal' })
-  priority: string;
-
-  // No migration class needed - schema managed via SQL
-}
-```
-
-### Anti-Pattern: TypeORM Migrations (Do NOT Use)
-
-```typescript
-// ❌ WRONG - Do not create migration files
-// migrations/1705312800000-AddUserAge.ts
-export class AddUserAge1705312800000 implements MigrationInterface {
-  public async up(queryRunner: QueryRunner): Promise<void> {
-    await queryRunner.query(`ALTER TABLE "users" ADD "age" integer`);
-  }
-}
-
-// ❌ WRONG - Do not enable migrationsRun
-TypeOrmModule.forRoot({
-  migrationsRun: true, // Disabled per ADR-009
-  migrations: ['dist/migrations/*.js'],
-});
-```
-
-### When You Need Schema Changes
-
-1. Check `specs/03-Data-and-Storage/lcbp3-v1.8.0-schema-02-tables.sql`
-2. Add your DDL to the appropriate SQL file
-3. Create delta file in `deltas/` directory
-4. Apply SQL to your database
-5. Update corresponding Entity class
-
-### Reference
-
- [ADR-009 Database Strategy](../../../../specs/06-Decision-Records/ADR-009-db-strategy.md)
- [Schema SQL Files](../../../../specs/03-Data-and-Storage/)
- [Data Dictionary](../../../../specs/03-Data-and-Storage/03-01-data-dictionary.md)
-
-> **Warning**: Attempting to use TypeORM migrations in this project violates ADR-009 and will be rejected in code review.
@@ -1,122 +0,0 @@
---
-title: Use Transactions for Multi-Step Operations
-impact: HIGH
-impactDescription: Ensures data consistency in multi-step operations
-tags: database, transactions, typeorm, consistency
---
-
-## Use Transactions for Multi-Step Operations
-
-When multiple database operations must succeed or fail together, wrap them in a transaction. This prevents partial updates that leave your data in an inconsistent state. Use TypeORM's transaction APIs or the DataSource query runner for complex scenarios.
-
-**Incorrect (multiple saves without transaction):**
-
-```typescript
-// Multiple saves without transaction
-@Injectable()
-export class OrdersService {
-  async createOrder(userId: string, items: OrderItem[]): Promise<Order> {
-    // If any step fails, data is inconsistent
-    const order = await this.orderRepo.save({ userId, status: 'pending' });
-
-    for (const item of items) {
-      await this.orderItemRepo.save({ orderId: order.id, ...item });
-      await this.inventoryRepo.decrement({ productId: item.productId }, 'stock', item.quantity);
-    }
-
-    await this.paymentService.charge(order.id);
-    // If payment fails, order and inventory are already modified!
-
-    return order;
-  }
-}
-```
-
-**Correct (use DataSource.transaction for automatic rollback):**
-
-```typescript
-// Use DataSource.transaction() for automatic rollback
-@Injectable()
-export class OrdersService {
-  constructor(private dataSource: DataSource) {}
-
-  async createOrder(userId: string, items: OrderItem[]): Promise<Order> {
-    return this.dataSource.transaction(async (manager) => {
-      // All operations use the same transactional manager
-      const order = await manager.save(Order, { userId, status: 'pending' });
-
-      for (const item of items) {
-        await manager.save(OrderItem, { orderId: order.id, ...item });
-        await manager.decrement(Inventory, { productId: item.productId }, 'stock', item.quantity);
-      }
-
-      // If this throws, everything rolls back
-      await this.paymentService.chargeWithManager(manager, order.id);
-
-      return order;
-    });
-  }
-}
-
-// QueryRunner for manual transaction control
-@Injectable()
-export class TransferService {
-  constructor(private dataSource: DataSource) {}
-
-  async transfer(fromId: string, toId: string, amount: number): Promise<void> {
-    const queryRunner = this.dataSource.createQueryRunner();
-    await queryRunner.connect();
-    await queryRunner.startTransaction();
-
-    try {
-      // Debit source account
-      await queryRunner.manager.decrement(Account, { id: fromId }, 'balance', amount);
-
-      // Verify sufficient funds
-      const source = await queryRunner.manager.findOne(Account, {
-        where: { id: fromId },
-      });
-      if (source.balance < 0) {
-        throw new BadRequestException('Insufficient funds');
-      }
-
-      // Credit destination account
-      await queryRunner.manager.increment(Account, { id: toId }, 'balance', amount);
-
-      // Log the transaction
-      await queryRunner.manager.save(TransactionLog, {
-        fromId,
-        toId,
-        amount,
-        timestamp: new Date(),
-      });
-
-      await queryRunner.commitTransaction();
-    } catch (error) {
-      await queryRunner.rollbackTransaction();
-      throw error;
-    } finally {
-      await queryRunner.release();
-    }
-  }
-}
-
-// Repository method with transaction support
-@Injectable()
-export class UsersRepository {
-  constructor(
-    @InjectRepository(User) private repo: Repository<User>,
-    private dataSource: DataSource
-  ) {}
-
-  async createWithProfile(userData: CreateUserDto, profileData: CreateProfileDto): Promise<User> {
-    return this.dataSource.transaction(async (manager) => {
-      const user = await manager.save(User, userData);
-      await manager.save(Profile, { ...profileData, userId: user.id });
-      return user;
-    });
-  }
-}
-```
-
-Reference: [TypeORM Transactions](https://typeorm.io/transactions)
@@ -1,215 +0,0 @@
---
-title: Implement Graceful Shutdown
-impact: MEDIUM-HIGH
-impactDescription: Proper shutdown handling ensures zero-downtime deployments
-tags: devops, graceful-shutdown, lifecycle, kubernetes
---
-
-## Implement Graceful Shutdown
-
-Handle SIGTERM and SIGINT signals to gracefully shutdown your NestJS application. Stop accepting new requests, wait for in-flight requests to complete, close database connections, and clean up resources. This prevents data loss and connection errors during deployments.
-
-**Incorrect (ignoring shutdown signals):**
-
-```typescript
-// Ignore shutdown signals
-async function bootstrap() {
-  const app = await NestFactory.create(AppModule);
-  await app.listen(3000);
-  // App crashes immediately on SIGTERM
-  // In-flight requests fail
-  // Database connections are abruptly closed
-}
-
-// Long-running tasks without cancellation
-@Injectable()
-export class ProcessingService {
-  async processLargeFile(file: File): Promise<void> {
-    // No way to interrupt this during shutdown
-    for (let i = 0; i < file.chunks.length; i++) {
-      await this.processChunk(file.chunks[i]);
-      // May run for minutes, blocking shutdown
-    }
-  }
-}
-```
-
-**Correct (enable shutdown hooks and handle cleanup):**
-
-```typescript
-// Enable shutdown hooks in main.ts
-async function bootstrap() {
-  const app = await NestFactory.create(AppModule);
-
-  // Enable shutdown hooks
-  app.enableShutdownHooks();
-
-  // Optional: Add timeout for forced shutdown
-  const server = await app.listen(3000);
-  server.setTimeout(30000); // 30 second timeout
-
-  // Handle graceful shutdown
-  const signals = ['SIGTERM', 'SIGINT'];
-  signals.forEach((signal) => {
-    process.on(signal, async () => {
-      console.log(`Received ${signal}, starting graceful shutdown...`);
-
-      // Stop accepting new connections
-      server.close(async () => {
-        console.log('HTTP server closed');
-        await app.close();
-        process.exit(0);
-      });
-
-      // Force exit after timeout
-      setTimeout(() => {
-        console.error('Forced shutdown after timeout');
-        process.exit(1);
-      }, 30000);
-    });
-  });
-}
-
-// Lifecycle hooks for cleanup
-@Injectable()
-export class DatabaseService implements OnApplicationShutdown {
-  private readonly connections: Connection[] = [];
-
-  async onApplicationShutdown(signal?: string): Promise<void> {
-    console.log(`Database service shutting down on ${signal}`);
-
-    // Close all connections gracefully
-    await Promise.all(this.connections.map((conn) => conn.close()));
-
-    console.log('All database connections closed');
-  }
-}
-
-// Queue processor with graceful shutdown
-@Injectable()
-export class QueueService implements OnApplicationShutdown, OnModuleDestroy {
-  private isShuttingDown = false;
-
-  onModuleDestroy(): void {
-    this.isShuttingDown = true;
-  }
-
-  async onApplicationShutdown(): Promise<void> {
-    // Wait for current jobs to complete
-    await this.queue.close();
-  }
-
-  async processJob(job: Job): Promise<void> {
-    if (this.isShuttingDown) {
-      throw new Error('Service is shutting down');
-    }
-    await this.doWork(job);
-  }
-}
-
-// WebSocket gateway cleanup
-@WebSocketGateway()
-export class EventsGateway implements OnApplicationShutdown {
-  @WebSocketServer()
-  server: Server;
-
-  async onApplicationShutdown(): Promise<void> {
-    // Notify all connected clients
-    this.server.emit('shutdown', { message: 'Server is shutting down' });
-
-    // Close all connections
-    this.server.disconnectSockets();
-  }
-}
-
-// Health check integration
-@Injectable()
-export class ShutdownService {
-  private isShuttingDown = false;
-
-  startShutdown(): void {
-    this.isShuttingDown = true;
-  }
-
-  isShutdown(): boolean {
-    return this.isShuttingDown;
-  }
-}
-
-@Controller('health')
-export class HealthController {
-  constructor(private shutdownService: ShutdownService) {}
-
-  @Get('ready')
-  @HealthCheck()
-  readiness(): Promise<HealthCheckResult> {
-    // Return 503 during shutdown - k8s stops sending traffic
-    if (this.shutdownService.isShutdown()) {
-      throw new ServiceUnavailableException('Shutting down');
-    }
-
-    return this.health.check([() => this.db.pingCheck('database')]);
-  }
-}
-
-// Integrate with shutdown
-@Injectable()
-export class AppShutdownService implements OnApplicationShutdown {
-  constructor(private shutdownService: ShutdownService) {}
-
-  async onApplicationShutdown(): Promise<void> {
-    // Mark as unhealthy first
-    this.shutdownService.startShutdown();
-
-    // Wait for k8s to update endpoints
-    await this.sleep(5000);
-
-    // Then proceed with cleanup
-  }
-}
-
-// Request tracking for in-flight requests
-@Injectable()
-export class RequestTracker implements NestMiddleware, OnApplicationShutdown {
-  private activeRequests = 0;
-  private isShuttingDown = false;
-  private shutdownPromise: Promise<void> | null = null;
-  private resolveShutdown: (() => void) | null = null;
-
-  use(req: Request, res: Response, next: NextFunction): void {
-    if (this.isShuttingDown) {
-      res.status(503).send('Service Unavailable');
-      return;
-    }
-
-    this.activeRequests++;
-
-    res.on('finish', () => {
-      this.activeRequests--;
-      if (this.isShuttingDown && this.activeRequests === 0 && this.resolveShutdown) {
-        this.resolveShutdown();
-      }
-    });
-
-    next();
-  }
-
-  async onApplicationShutdown(): Promise<void> {
-    this.isShuttingDown = true;
-
-    if (this.activeRequests > 0) {
-      console.log(`Waiting for ${this.activeRequests} requests to complete`);
-      this.shutdownPromise = new Promise((resolve) => {
-        this.resolveShutdown = resolve;
-      });
-
-      // Wait with timeout
-      await Promise.race([this.shutdownPromise, new Promise((resolve) => setTimeout(resolve, 30000))]);
-    }
-
-    console.log('All requests completed');
-  }
-}
-```
-
-Reference: [NestJS Lifecycle Events](https://docs.nestjs.com/fundamentals/lifecycle-events)
@@ -1,160 +0,0 @@
---
-title: Use ConfigModule for Environment Configuration
-impact: LOW-MEDIUM
-impactDescription: Proper configuration prevents deployment failures
-tags: devops, configuration, environment, validation
---
-
-## Use ConfigModule for Environment Configuration
-
-Use `@nestjs/config` for environment-based configuration. Validate configuration at startup to fail fast on misconfigurations. Use namespaced configuration for organization and type safety.
-
-**Incorrect (accessing process.env directly):**
-
-```typescript
-// Access process.env directly
-@Injectable()
-export class DatabaseService {
-  constructor() {
-    // No validation, can fail at runtime
-    this.connection = new Pool({
-      host: process.env.DB_HOST,
-      port: parseInt(process.env.DB_PORT), // NaN if missing
-      password: process.env.DB_PASSWORD, // undefined if missing
-    });
-  }
-}
-
-// Scattered env access
-@Injectable()
-export class EmailService {
-  sendEmail() {
-    // Different services access env differently
-    const apiKey = process.env.SENDGRID_API_KEY || 'default';
-    // Typos go unnoticed: process.env.SENDGRID_API_KY
-  }
-}
-```
-
-**Correct (use @nestjs/config with validation):**
-
-```typescript
-// Setup validated configuration
-import { ConfigModule, ConfigService, registerAs } from '@nestjs/config';
-import * as Joi from 'joi';
-
-// config/database.config.ts
-export const databaseConfig = registerAs('database', () => ({
-  host: process.env.DB_HOST,
-  port: parseInt(process.env.DB_PORT, 10),
-  username: process.env.DB_USERNAME,
-  password: process.env.DB_PASSWORD,
-  database: process.env.DB_NAME,
-}));
-
-// config/app.config.ts
-export const appConfig = registerAs('app', () => ({
-  port: parseInt(process.env.PORT, 10) || 3000,
-  environment: process.env.NODE_ENV || 'development',
-  apiPrefix: process.env.API_PREFIX || 'api',
-}));
-
-// config/validation.schema.ts
-export const validationSchema = Joi.object({
-  NODE_ENV: Joi.string().valid('development', 'production', 'test').default('development'),
-  PORT: Joi.number().default(3000),
-  DB_HOST: Joi.string().required(),
-  DB_PORT: Joi.number().default(5432),
-  DB_USERNAME: Joi.string().required(),
-  DB_PASSWORD: Joi.string().required(),
-  DB_NAME: Joi.string().required(),
-  JWT_SECRET: Joi.string().min(32).required(),
-  REDIS_URL: Joi.string().uri().required(),
-});
-
-// app.module.ts
-@Module({
-  imports: [
-    ConfigModule.forRoot({
-      isGlobal: true, // Available everywhere without importing
-      load: [databaseConfig, appConfig],
-      validationSchema,
-      validationOptions: {
-        abortEarly: true, // Stop on first error
-        allowUnknown: true, // Allow other env vars
-      },
-    }),
-    TypeOrmModule.forRootAsync({
-      inject: [ConfigService],
-      useFactory: (config: ConfigService) => ({
-        type: 'postgres',
-        host: config.get('database.host'),
-        port: config.get('database.port'),
-        username: config.get('database.username'),
-        password: config.get('database.password'),
-        database: config.get('database.database'),
-        autoLoadEntities: true,
-      }),
-    }),
-  ],
-})
-export class AppModule {}
-
-// Type-safe configuration access
-export interface AppConfig {
-  port: number;
-  environment: 'development' | 'production' | 'test';
-  apiPrefix: string;
-}
-
-export interface DatabaseConfig {
-  host: string;
-  port: number;
-  username: string;
-  password: string;
-  database: string;
-}
-
-// Type-safe access
-@Injectable()
-export class AppService {
-  constructor(private config: ConfigService) {}
-
-  getPort(): number {
-    // Type-safe with generic
-    return this.config.get<number>('app.port');
-  }
-
-  getDatabaseConfig(): DatabaseConfig {
-    return this.config.get<DatabaseConfig>('database');
-  }
-}
-
-// Inject namespaced config directly
-@Injectable()
-export class DatabaseService {
-  constructor(
-    @Inject(databaseConfig.KEY)
-    private dbConfig: ConfigType<typeof databaseConfig>
-  ) {
-    // Full type inference!
-    const host = this.dbConfig.host; // string
-    const port = this.dbConfig.port; // number
-  }
-}
-
-// Environment files support
-ConfigModule.forRoot({
-  envFilePath: [`.env.${process.env.NODE_ENV}.local`, `.env.${process.env.NODE_ENV}`, '.env.local', '.env'],
-});
-
-// .env.development
-// DB_HOST=localhost
-// DB_PORT=5432
-
-// .env.production
-// DB_HOST=prod-db.example.com
-// DB_PORT=5432
-```
-
-Reference: [NestJS Configuration](https://docs.nestjs.com/techniques/configuration)
@@ -1,227 +0,0 @@
---
-title: Use Structured Logging
-impact: MEDIUM-HIGH
-impactDescription: Structured logging enables effective debugging and monitoring
-tags: devops, logging, structured-logs, pino
---
-
-## Use Structured Logging
-
-Use NestJS Logger with structured JSON output in production. Include contextual information (request ID, user ID, operation) to trace requests across services. Avoid console.log and implement proper log levels.
-
-**Incorrect (using console.log in production):**
-
-```typescript
-// Use console.log in production
-@Injectable()
-export class UsersService {
-  async createUser(dto: CreateUserDto): Promise<User> {
-    console.log('Creating user:', dto);
-    // Not structured, no levels, lost in production logs
-
-    try {
-      const user = await this.repo.save(dto);
-      console.log('User created:', user.id);
-      return user;
-    } catch (error) {
-      console.log('Error:', error); // Using log for errors
-      throw error;
-    }
-  }
-}
-
-// Log sensitive data
-console.log('Login attempt:', { email, password }); // SECURITY RISK!
-
-// Inconsistent log format
-logger.log('User ' + userId + ' created at ' + new Date());
-// Hard to parse, no structure
-```
-
-**Correct (use structured logging with context):**
-
-```typescript
-// Configure logger in main.ts
-async function bootstrap() {
-  const app = await NestFactory.create(AppModule, {
-    logger:
-      process.env.NODE_ENV === 'production' ? ['error', 'warn', 'log'] : ['error', 'warn', 'log', 'debug', 'verbose'],
-  });
-}
-
-// Use NestJS Logger with context
-@Injectable()
-export class UsersService {
-  private readonly logger = new Logger(UsersService.name);
-
-  async createUser(dto: CreateUserDto): Promise<User> {
-    this.logger.log('Creating user', { email: dto.email });
-
-    try {
-      const user = await this.repo.save(dto);
-      this.logger.log('User created', { userId: user.id });
-      return user;
-    } catch (error) {
-      this.logger.error('Failed to create user', error.stack, {
-        email: dto.email,
-      });
-      throw error;
-    }
-  }
-}
-
-// Custom logger for JSON output
-@Injectable()
-export class JsonLogger implements LoggerService {
-  log(message: string, context?: object): void {
-    console.log(
-      JSON.stringify({
-        level: 'info',
-        timestamp: new Date().toISOString(),
-        message,
-        ...context,
-      })
-    );
-  }
-
-  error(message: string, trace?: string, context?: object): void {
-    console.error(
-      JSON.stringify({
-        level: 'error',
-        timestamp: new Date().toISOString(),
-        message,
-        trace,
-        ...context,
-      })
-    );
-  }
-
-  warn(message: string, context?: object): void {
-    console.warn(
-      JSON.stringify({
-        level: 'warn',
-        timestamp: new Date().toISOString(),
-        message,
-        ...context,
-      })
-    );
-  }
-
-  debug(message: string, context?: object): void {
-    console.debug(
-      JSON.stringify({
-        level: 'debug',
-        timestamp: new Date().toISOString(),
-        message,
-        ...context,
-      })
-    );
-  }
-}
-
-// Request context logging with ClsModule
-import { ClsModule, ClsService } from 'nestjs-cls';
-
-@Module({
-  imports: [
-    ClsModule.forRoot({
-      global: true,
-      middleware: {
-        mount: true,
-        generateId: true,
-      },
-    }),
-  ],
-})
-export class AppModule {}
-
-// Middleware to set request context
-@Injectable()
-export class RequestContextMiddleware implements NestMiddleware {
-  constructor(private cls: ClsService) {}
-
-  use(req: Request, res: Response, next: NextFunction): void {
-    const requestId = req.headers['x-request-id'] || randomUUID();
-    this.cls.set('requestId', requestId);
-    this.cls.set('userId', req.user?.id);
-
-    res.setHeader('x-request-id', requestId);
-    next();
-  }
-}
-
-// Logger that includes request context
-@Injectable()
-export class ContextLogger {
-  constructor(private cls: ClsService) {}
-
-  log(message: string, data?: object): void {
-    console.log(
-      JSON.stringify({
-        level: 'info',
-        timestamp: new Date().toISOString(),
-        requestId: this.cls.get('requestId'),
-        userId: this.cls.get('userId'),
-        message,
-        ...data,
-      })
-    );
-  }
-
-  error(message: string, error: Error, data?: object): void {
-    console.error(
-      JSON.stringify({
-        level: 'error',
-        timestamp: new Date().toISOString(),
-        requestId: this.cls.get('requestId'),
-        userId: this.cls.get('userId'),
-        message,
-        error: error.message,
-        stack: error.stack,
-        ...data,
-      })
-    );
-  }
-}
-
-// Pino integration for high-performance logging
-import { LoggerModule } from 'nestjs-pino';
-
-@Module({
-  imports: [
-    LoggerModule.forRoot({
-      pinoHttp: {
-        level: process.env.NODE_ENV === 'production' ? 'info' : 'debug',
-        transport: process.env.NODE_ENV !== 'production' ? { target: 'pino-pretty' } : undefined,
-        redact: ['req.headers.authorization', 'req.body.password'],
-        serializers: {
-          req: (req) => ({
-            method: req.method,
-            url: req.url,
-            query: req.query,
-          }),
-          res: (res) => ({
-            statusCode: res.statusCode,
-          }),
-        },
-      },
-    }),
-  ],
-})
-export class AppModule {}
-
-// Usage with Pino
-@Injectable()
-export class UsersService {
-  constructor(private logger: PinoLogger) {
-    this.logger.setContext(UsersService.name);
-  }
-
-  async findOne(id: string): Promise<User> {
-    this.logger.info({ userId: id }, 'Finding user');
-    // Pino uses first arg for data, second for message
-  }
-}
-```
-
-Reference: [NestJS Logger](https://docs.nestjs.com/techniques/logger)
@@ -1,104 +0,0 @@
---
-title: Avoid Service Locator Anti-Pattern
-impact: HIGH
-impactDescription: Hides dependencies and breaks testability
-tags: dependency-injection, anti-patterns, testing
---
-
-## Avoid Service Locator Anti-Pattern
-
-Avoid using `ModuleRef.get()` or global containers to resolve dependencies at runtime. This hides dependencies, makes code harder to test, and breaks the benefits of dependency injection. Use constructor injection instead.
-
-**Incorrect (service locator anti-pattern):**
-
-```typescript
-// Use ModuleRef to get dependencies dynamically
-@Injectable()
-export class OrdersService {
-  constructor(private moduleRef: ModuleRef) {}
-
-  async createOrder(dto: CreateOrderDto): Promise<Order> {
-    // Dependencies are hidden - not visible in constructor
-    const usersService = this.moduleRef.get(UsersService);
-    const inventoryService = this.moduleRef.get(InventoryService);
-    const paymentService = this.moduleRef.get(PaymentService);
-
-    const user = await usersService.findOne(dto.userId);
-    // ... rest of logic
-  }
-}
-
-// Global singleton container
-class ServiceContainer {
-  private static instance: ServiceContainer;
-  private services = new Map<string, any>();
-
-  static getInstance(): ServiceContainer {
-    if (!this.instance) {
-      this.instance = new ServiceContainer();
-    }
-    return this.instance;
-  }
-
-  get<T>(key: string): T {
-    return this.services.get(key);
-  }
-}
-```
-
-**Correct (constructor injection with explicit dependencies):**
-
-```typescript
-// Use constructor injection - dependencies are explicit
-@Injectable()
-export class OrdersService {
-  constructor(
-    private usersService: UsersService,
-    private inventoryService: InventoryService,
-    private paymentService: PaymentService
-  ) {}
-
-  async createOrder(dto: CreateOrderDto): Promise<Order> {
-    const user = await this.usersService.findOne(dto.userId);
-    const inventory = await this.inventoryService.check(dto.items);
-    // Dependencies are clear and testable
-  }
-}
-
-// Easy to test with mocks
-describe('OrdersService', () => {
-  let service: OrdersService;
-
-  beforeEach(async () => {
-    const module = await Test.createTestingModule({
-      providers: [
-        OrdersService,
-        { provide: UsersService, useValue: mockUsersService },
-        { provide: InventoryService, useValue: mockInventoryService },
-        { provide: PaymentService, useValue: mockPaymentService },
-      ],
-    }).compile();
-
-    service = module.get(OrdersService);
-  });
-});
-
-// VALID: Factory pattern for dynamic instantiation
-@Injectable()
-export class HandlerFactory {
-  constructor(private moduleRef: ModuleRef) {}
-
-  getHandler(type: string): Handler {
-    switch (type) {
-      case 'email':
-        return this.moduleRef.get(EmailHandler);
-      case 'sms':
-        return this.moduleRef.get(SmsHandler);
-      default:
-        return this.moduleRef.get(DefaultHandler);
-    }
-  }
-}
-```
-
-Reference: [NestJS Module Reference](https://docs.nestjs.com/fundamentals/module-ref)
@@ -1,165 +0,0 @@
---
-title: Apply Interface Segregation Principle
-impact: HIGH
-impactDescription: Reduces coupling and improves testability by 30-50%
-tags: dependency-injection, interfaces, solid, isp
---
-
-## Apply Interface Segregation Principle
-
-Clients should not be forced to depend on interfaces they don't use. In NestJS, this means keeping interfaces small and focused on specific capabilities rather than creating "fat" interfaces that bundle unrelated methods. When a service only needs to send emails, it shouldn't depend on an interface that also includes SMS, push notifications, and logging. Split large interfaces into role-based ones.
-
-**Incorrect (fat interface forcing unused dependencies):**
-
-```typescript
-// Fat interface - forces all consumers to depend on everything
-interface NotificationService {
-  sendEmail(to: string, subject: string, body: string): Promise<void>;
-  sendSms(phone: string, message: string): Promise<void>;
-  sendPush(userId: string, notification: PushPayload): Promise<void>;
-  sendSlack(channel: string, message: string): Promise<void>;
-  logNotification(type: string, payload: any): Promise<void>;
-  getDeliveryStatus(id: string): Promise<DeliveryStatus>;
-  retryFailed(id: string): Promise<void>;
-  scheduleNotification(dto: ScheduleDto): Promise<string>;
-}
-
-// Consumer only needs email, but must mock everything for tests
-@Injectable()
-export class OrdersService {
-  constructor(
-    private notifications: NotificationService // Depends on 8 methods, uses 1
-  ) {}
-
-  async confirmOrder(order: Order): Promise<void> {
-    await this.notifications.sendEmail(
-      order.customer.email,
-      'Order Confirmed',
-      `Your order ${order.id} has been confirmed.`
-    );
-  }
-}
-
-// Testing is painful - must mock unused methods
-const mockNotificationService = {
-  sendEmail: jest.fn(),
-  sendSms: jest.fn(), // Never used, but required
-  sendPush: jest.fn(), // Never used, but required
-  sendSlack: jest.fn(), // Never used, but required
-  logNotification: jest.fn(), // Never used, but required
-  getDeliveryStatus: jest.fn(), // Never used, but required
-  retryFailed: jest.fn(), // Never used, but required
-  scheduleNotification: jest.fn(), // Never used, but required
-};
-```
-
-**Correct (segregated interfaces by capability):**
-
-```typescript
-// Segregated interfaces - each focused on one capability
-interface EmailSender {
-  sendEmail(to: string, subject: string, body: string): Promise<void>;
-}
-
-interface SmsSender {
-  sendSms(phone: string, message: string): Promise<void>;
-}
-
-interface PushSender {
-  sendPush(userId: string, notification: PushPayload): Promise<void>;
-}
-
-interface NotificationLogger {
-  logNotification(type: string, payload: any): Promise<void>;
-}
-
-interface NotificationScheduler {
-  scheduleNotification(dto: ScheduleDto): Promise<string>;
-}
-
-// Implementation can implement multiple interfaces
-@Injectable()
-export class NotificationService implements EmailSender, SmsSender, PushSender {
-  async sendEmail(to: string, subject: string, body: string): Promise<void> {
-    // Email implementation
-  }
-
-  async sendSms(phone: string, message: string): Promise<void> {
-    // SMS implementation
-  }
-
-  async sendPush(userId: string, notification: PushPayload): Promise<void> {
-    // Push implementation
-  }
-}
-
-// Or separate implementations
-@Injectable()
-export class SendGridEmailService implements EmailSender {
-  async sendEmail(to: string, subject: string, body: string): Promise<void> {
-    // SendGrid-specific implementation
-  }
-}
-
-// Consumer depends only on what it needs
-@Injectable()
-export class OrdersService {
-  constructor(
-    @Inject(EMAIL_SENDER) private emailSender: EmailSender // Minimal dependency
-  ) {}
-
-  async confirmOrder(order: Order): Promise<void> {
-    await this.emailSender.sendEmail(
-      order.customer.email,
-      'Order Confirmed',
-      `Your order ${order.id} has been confirmed.`
-    );
-  }
-}
-
-// Testing is simple - only mock what's used
-const mockEmailSender: EmailSender = {
-  sendEmail: jest.fn(),
-};
-
-// Module registration with tokens
-export const EMAIL_SENDER = Symbol('EMAIL_SENDER');
-export const SMS_SENDER = Symbol('SMS_SENDER');
-
-@Module({
-  providers: [
-    { provide: EMAIL_SENDER, useClass: SendGridEmailService },
-    { provide: SMS_SENDER, useClass: TwilioSmsService },
-  ],
-  exports: [EMAIL_SENDER, SMS_SENDER],
-})
-export class NotificationModule {}
-```
-
-**Combining interfaces when needed:**
-
-```typescript
-// Sometimes a consumer legitimately needs multiple capabilities
-interface EmailAndSmsSender extends EmailSender, SmsSender {}
-
-// Or use intersection types
-type MultiChannelSender = EmailSender & SmsSender & PushSender;
-
-// Consumer that genuinely needs multiple channels
-@Injectable()
-export class AlertService {
-  constructor(
-    @Inject(MULTI_CHANNEL_SENDER)
-    private sender: EmailSender & SmsSender
-  ) {}
-
-  async sendCriticalAlert(user: User, message: string): Promise<void> {
-    await Promise.all([
-      this.sender.sendEmail(user.email, 'Critical Alert', message),
-      this.sender.sendSms(user.phone, message),
-    ]);
-  }
-}
-```
-
-Reference: [Interface Segregation Principle](https://en.wikipedia.org/wiki/Interface_segregation_principle)
@@ -1,217 +0,0 @@
---
-title: Honor Liskov Substitution Principle
-impact: HIGH
-impactDescription: Ensures implementations are truly interchangeable without breaking callers
-tags: dependency-injection, inheritance, solid, lsp
---
-
-## Honor Liskov Substitution Principle
-
-Subtypes must be substitutable for their base types without altering program correctness. In NestJS with dependency injection, this means any implementation of an interface or abstract class must honor the contract completely. A mock payment service used in tests must behave like a real payment service (return similar shapes, handle errors the same way). Violating LSP causes subtle bugs when swapping implementations.
-
-**Incorrect (implementation violates the contract):**
-
-```typescript
-// Base interface with clear contract
-interface PaymentGateway {
-  /**
-   * Charges the specified amount.
-   * @returns PaymentResult on success
-   * @throws PaymentFailedException on payment failure
-   */
-  charge(amount: number, currency: string): Promise<PaymentResult>;
-}
-
-// Production implementation - follows the contract
-@Injectable()
-export class StripeService implements PaymentGateway {
-  async charge(amount: number, currency: string): Promise<PaymentResult> {
-    const response = await this.stripe.charges.create({ amount, currency });
-    return { success: true, transactionId: response.id, amount };
-  }
-}
-
-// Mock that violates LSP - different behavior!
-@Injectable()
-export class MockPaymentService implements PaymentGateway {
-  async charge(amount: number, currency: string): Promise<PaymentResult> {
-    // VIOLATION 1: Throws for valid input (contract says return PaymentResult)
-    if (amount > 1000) {
-      throw new Error('Mock does not support large amounts');
-    }
-
-    // VIOLATION 2: Returns null instead of PaymentResult
-    if (currency !== 'USD') {
-      return null as any; // Real service would convert or reject properly
-    }
-
-    // VIOLATION 3: Missing required field
-    return { success: true } as PaymentResult; // Missing transactionId!
-  }
-}
-
-// Consumer trusts the contract
-@Injectable()
-export class OrdersService {
-  constructor(@Inject(PAYMENT_GATEWAY) private payment: PaymentGateway) {}
-
-  async checkout(order: Order): Promise<void> {
-    const result = await this.payment.charge(order.total, order.currency);
-    // These fail with MockPaymentService:
-    await this.saveTransaction(result.transactionId); // undefined!
-    await this.sendReceipt(result); // might be null!
-  }
-}
-```
-
-**Correct (implementations honor the contract):**
-
-```typescript
-// Well-defined interface with documented behavior
-interface PaymentGateway {
-  /**
-   * Charges the specified amount.
-   * @param amount - Amount in smallest currency unit (cents)
-   * @param currency - ISO 4217 currency code
-   * @returns PaymentResult with transactionId, success status, and amount
-   * @throws PaymentFailedException if charge is declined
-   * @throws InvalidCurrencyException if currency is not supported
-   */
-  charge(amount: number, currency: string): Promise<PaymentResult>;
-
-  /**
-   * Refunds a previous charge.
-   * @throws TransactionNotFoundException if transactionId is invalid
-   */
-  refund(transactionId: string, amount?: number): Promise<RefundResult>;
-}
-
-// Production implementation
-@Injectable()
-export class StripeService implements PaymentGateway {
-  async charge(amount: number, currency: string): Promise<PaymentResult> {
-    try {
-      const response = await this.stripe.charges.create({ amount, currency });
-      return {
-        success: true,
-        transactionId: response.id,
-        amount: response.amount,
-      };
-    } catch (error) {
-      if (error.type === 'card_error') {
-        throw new PaymentFailedException(error.message);
-      }
-      throw error;
-    }
-  }
-
-  async refund(transactionId: string, amount?: number): Promise<RefundResult> {
-    // Implementation...
-  }
-}
-
-// Mock that honors LSP - same contract, same behavior shape
-@Injectable()
-export class MockPaymentService implements PaymentGateway {
-  private transactions = new Map<string, PaymentResult>();
-
-  async charge(amount: number, currency: string): Promise<PaymentResult> {
-    // Honor the contract: validate currency like real service would
-    if (!['USD', 'EUR', 'GBP'].includes(currency)) {
-      throw new InvalidCurrencyException(`Unsupported currency: ${currency}`);
-    }
-
-    // Simulate decline for specific test scenarios
-    if (amount === 99999) {
-      throw new PaymentFailedException('Card declined (test scenario)');
-    }
-
-    // Return same shape as production
-    const result: PaymentResult = {
-      success: true,
-      transactionId: `mock_${Date.now()}_${Math.random().toString(36)}`,
-      amount,
-    };
-
-    this.transactions.set(result.transactionId, result);
-    return result;
-  }
-
-  async refund(transactionId: string, amount?: number): Promise<RefundResult> {
-    // Honor the contract: throw if transaction not found
-    if (!this.transactions.has(transactionId)) {
-      throw new TransactionNotFoundException(transactionId);
-    }
-
-    return {
-      success: true,
-      refundId: `refund_${transactionId}`,
-      amount: amount ?? this.transactions.get(transactionId)!.amount,
-    };
-  }
-}
-
-// Consumer can swap implementations safely
-@Injectable()
-export class OrdersService {
-  constructor(@Inject(PAYMENT_GATEWAY) private payment: PaymentGateway) {}
-
-  async checkout(order: Order): Promise<Order> {
-    try {
-      const result = await this.payment.charge(order.total, order.currency);
-      // Works with both StripeService and MockPaymentService
-      order.transactionId = result.transactionId;
-      order.status = 'paid';
-      return order;
-    } catch (error) {
-      if (error instanceof PaymentFailedException) {
-        order.status = 'payment_failed';
-        return order;
-      }
-      throw error;
-    }
-  }
-}
-```
-
-**Testing LSP compliance:**
-
-```typescript
-// Shared test suite that any implementation must pass
-function testPaymentGatewayContract(createGateway: () => PaymentGateway) {
-  describe('PaymentGateway contract', () => {
-    let gateway: PaymentGateway;
-
-    beforeEach(() => {
-      gateway = createGateway();
-    });
-
-    it('returns PaymentResult with all required fields', async () => {
-      const result = await gateway.charge(1000, 'USD');
-      expect(result).toHaveProperty('success');
-      expect(result).toHaveProperty('transactionId');
-      expect(result).toHaveProperty('amount');
-      expect(typeof result.transactionId).toBe('string');
-    });
-
-    it('throws InvalidCurrencyException for unsupported currency', async () => {
-      await expect(gateway.charge(1000, 'INVALID')).rejects.toThrow(InvalidCurrencyException);
-    });
-
-    it('throws TransactionNotFoundException for invalid refund', async () => {
-      await expect(gateway.refund('nonexistent')).rejects.toThrow(TransactionNotFoundException);
-    });
-  });
-}
-
-// Run against all implementations
-describe('StripeService', () => {
-  testPaymentGatewayContract(() => new StripeService(mockStripeClient));
-});
-
-describe('MockPaymentService', () => {
-  testPaymentGatewayContract(() => new MockPaymentService());
-});
-```
-
-Reference: [Liskov Substitution Principle](https://en.wikipedia.org/wiki/Liskov_substitution_principle)
@@ -1,86 +0,0 @@
---
-title: Prefer Constructor Injection
-impact: CRITICAL
-impactDescription: Required for proper DI and testing
-tags: dependency-injection, constructor, testing
---
-
-## Prefer Constructor Injection
-
-Always use constructor injection over property injection. Constructor injection makes dependencies explicit, enables TypeScript type checking, ensures dependencies are available when the class is instantiated, and improves testability. This is required for proper DI, testing, and TypeScript support.
-
-**Incorrect (property injection with hidden dependencies):**
-
-```typescript
-// Property injection - avoid unless necessary
-@Injectable()
-export class UsersService {
-  @Inject()
-  private userRepo: UserRepository; // Hidden dependency
-
-  @Inject('CONFIG')
-  private config: ConfigType; // Also hidden
-
-  async findAll() {
-    return this.userRepo.find();
-  }
-}
-
-// Problems:
-// 1. Dependencies not visible in constructor
-// 2. Service can be instantiated without dependencies in tests
-// 3. TypeScript can't enforce dependency types at instantiation
-```
-
-**Correct (constructor injection with explicit dependencies):**
-
-```typescript
-// Constructor injection - explicit and testable
-@Injectable()
-export class UsersService {
-  constructor(
-    private readonly userRepo: UserRepository,
-    @Inject('CONFIG') private readonly config: ConfigType
-  ) {}
-
-  async findAll(): Promise<User[]> {
-    return this.userRepo.find();
-  }
-}
-
-// Testing is straightforward
-describe('UsersService', () => {
-  let service: UsersService;
-  let mockRepo: jest.Mocked<UserRepository>;
-
-  beforeEach(() => {
-    mockRepo = {
-      find: jest.fn(),
-      save: jest.fn(),
-    } as any;
-
-    service = new UsersService(mockRepo, { dbUrl: 'test' });
-  });
-
-  it('should find all users', async () => {
-    mockRepo.find.mockResolvedValue([{ id: '1', name: 'Test' }]);
-    const result = await service.findAll();
-    expect(result).toHaveLength(1);
-  });
-});
-
-// Only use property injection for optional dependencies
-@Injectable()
-export class LoggingService {
-  @Optional()
-  @Inject('ANALYTICS')
-  private analytics?: AnalyticsService;
-
-  log(message: string) {
-    console.log(message);
-    this.analytics?.track('log', message); // Optional enhancement
-  }
-}
-```
-
-Reference: [NestJS Providers](https://docs.nestjs.com/providers)
@@ -1,94 +0,0 @@
---
-title: Understand Provider Scopes
-impact: CRITICAL
-impactDescription: Prevents data leaks and performance issues
-tags: dependency-injection, scopes, request-context
---
-
-## Understand Provider Scopes
-
-NestJS has three provider scopes: DEFAULT (singleton), REQUEST (per-request instance), and TRANSIENT (new instance for each injection). Most providers should be singletons. Request-scoped providers have performance implications as they bubble up through the dependency tree. Understanding scopes prevents memory leaks and incorrect data sharing.
-
-**Incorrect (wrong scope usage):**
-
-```typescript
-// Request-scoped when not needed (performance hit)
-@Injectable({ scope: Scope.REQUEST })
-export class UsersService {
-  // This creates a new instance for EVERY request
-  // All dependencies also become request-scoped
-  async findAll() {
-    return this.userRepo.find();
-  }
-}
-
-// Singleton with mutable request state
-@Injectable() // Default: singleton
-export class RequestContextService {
-  private userId: string; // DANGER: Shared across all requests!
-
-  setUser(userId: string) {
-    this.userId = userId; // Overwrites for all concurrent requests
-  }
-
-  getUser() {
-    return this.userId; // Returns wrong user!
-  }
-}
-```
-
-**Correct (appropriate scope for each use case):**
-
-```typescript
-// Singleton for stateless services (default, most common)
-@Injectable()
-export class UsersService {
-  constructor(private readonly userRepo: UserRepository) {}
-
-  async findById(id: string): Promise<User> {
-    return this.userRepo.findOne({ where: { id } });
-  }
-}
-
-// Request-scoped ONLY when you need request context
-@Injectable({ scope: Scope.REQUEST })
-export class RequestContextService {
-  private userId: string;
-
-  setUser(userId: string) {
-    this.userId = userId;
-  }
-
-  getUser(): string {
-    return this.userId;
-  }
-}
-
-// Better: Use NestJS built-in request context
-import { REQUEST } from '@nestjs/core';
-import { Request } from 'express';
-
-@Injectable({ scope: Scope.REQUEST })
-export class AuditService {
-  constructor(@Inject(REQUEST) private request: Request) {}
-
-  log(action: string) {
-    console.log(`User ${this.request.user?.id} performed ${action}`);
-  }
-}
-
-// Best: Use ClsModule for async context (no scope bubble-up)
-import { ClsService } from 'nestjs-cls';
-
-@Injectable() // Stays singleton!
-export class AuditService {
-  constructor(private cls: ClsService) {}
-
-  log(action: string) {
-    const userId = this.cls.get('userId');
-    console.log(`User ${userId} performed ${action}`);
-  }
-}
-```
-
-Reference: [NestJS Injection Scopes](https://docs.nestjs.com/fundamentals/injection-scopes)
@@ -1,99 +0,0 @@
---
-title: Use Injection Tokens for Interfaces
-impact: HIGH
-impactDescription: Enables interface-based DI at runtime
-tags: dependency-injection, tokens, interfaces
---
-
-## Use Injection Tokens for Interfaces
-
-TypeScript interfaces are erased at compile time and can't be used as injection tokens. Use string tokens, symbols, or abstract classes when you want to inject implementations of interfaces. This enables swapping implementations for testing or different environments.
-
-**Incorrect (interface can't be used as token):**
-
-```typescript
-// Interface can't be used as injection token
-interface PaymentGateway {
-  charge(amount: number): Promise<PaymentResult>;
-}
-
-@Injectable()
-export class StripeService implements PaymentGateway {
-  charge(amount: number) {
-    /* ... */
-  }
-}
-
-@Injectable()
-export class OrdersService {
-  // This WON'T work - PaymentGateway doesn't exist at runtime
-  constructor(private payment: PaymentGateway) {}
-}
-```
-
-**Correct (symbol tokens or abstract classes):**
-
-```typescript
-// Option 1: String/Symbol tokens (most flexible)
-export const PAYMENT_GATEWAY = Symbol('PAYMENT_GATEWAY');
-
-export interface PaymentGateway {
-  charge(amount: number): Promise<PaymentResult>;
-}
-
-@Injectable()
-export class StripeService implements PaymentGateway {
-  async charge(amount: number): Promise<PaymentResult> {
-    // Stripe implementation
-  }
-}
-
-@Injectable()
-export class MockPaymentService implements PaymentGateway {
-  async charge(amount: number): Promise<PaymentResult> {
-    return { success: true, id: 'mock-id' };
-  }
-}
-
-// Module registration
-@Module({
-  providers: [
-    {
-      provide: PAYMENT_GATEWAY,
-      useClass: process.env.NODE_ENV === 'test' ? MockPaymentService : StripeService,
-    },
-  ],
-  exports: [PAYMENT_GATEWAY],
-})
-export class PaymentModule {}
-
-// Injection
-@Injectable()
-export class OrdersService {
-  constructor(@Inject(PAYMENT_GATEWAY) private payment: PaymentGateway) {}
-
-  async createOrder(dto: CreateOrderDto) {
-    await this.payment.charge(dto.amount);
-  }
-}
-
-// Option 2: Abstract class (carries runtime type info)
-export abstract class PaymentGateway {
-  abstract charge(amount: number): Promise<PaymentResult>;
-}
-
-@Injectable()
-export class StripeService extends PaymentGateway {
-  async charge(amount: number): Promise<PaymentResult> {
-    // Implementation
-  }
-}
-
-// No @Inject needed with abstract class
-@Injectable()
-export class OrdersService {
-  constructor(private payment: PaymentGateway) {}
-}
-```
-
-Reference: [NestJS Custom Providers](https://docs.nestjs.com/fundamentals/custom-providers)
@@ -1,125 +0,0 @@
---
-title: Handle Async Errors Properly
-impact: HIGH
-impactDescription: Prevents process crashes from unhandled rejections
-tags: error-handling, async, promises
---
-
-## Handle Async Errors Properly
-
-NestJS automatically catches errors from async route handlers, but errors from background tasks, event handlers, and manually created promises can crash your application. Always handle async errors explicitly and use global handlers as a safety net.
-
-**Incorrect (fire-and-forget without error handling):**
-
-```typescript
-// Fire-and-forget without error handling
-@Injectable()
-export class UsersService {
-  async createUser(dto: CreateUserDto): Promise<User> {
-    const user = await this.repo.save(dto);
-
-    // Fire and forget - if this fails, error is unhandled!
-    this.emailService.sendWelcome(user.email);
-
-    return user;
-  }
-}
-
-// Unhandled promise in event handler
-@Injectable()
-export class OrdersService {
-  @OnEvent('order.created')
-  handleOrderCreated(event: OrderCreatedEvent) {
-    // This returns a promise but it's not awaited!
-    this.processOrder(event);
-    // Errors will crash the process
-  }
-
-  private async processOrder(event: OrderCreatedEvent): Promise<void> {
-    await this.inventoryService.reserve(event.items);
-    await this.notificationService.send(event.userId);
-  }
-}
-
-// Missing try-catch in scheduled tasks
-@Cron('0 0 * * *')
-async dailyCleanup(): Promise<void> {
-  await this.cleanupService.run();
-  // If this throws, no error handling
-}
-```
-
-**Correct (explicit async error handling):**
-
-```typescript
-// Handle fire-and-forget with explicit catch
-@Injectable()
-export class UsersService {
-  private readonly logger = new Logger(UsersService.name);
-
-  async createUser(dto: CreateUserDto): Promise<User> {
-    const user = await this.repo.save(dto);
-
-    // Explicitly catch and log errors
-    this.emailService.sendWelcome(user.email).catch((error) => {
-      this.logger.error('Failed to send welcome email', error.stack);
-      // Optionally queue for retry
-    });
-
-    return user;
-  }
-}
-
-// Properly handle async event handlers
-@Injectable()
-export class OrdersService {
-  private readonly logger = new Logger(OrdersService.name);
-
-  @OnEvent('order.created')
-  async handleOrderCreated(event: OrderCreatedEvent): Promise<void> {
-    try {
-      await this.processOrder(event);
-    } catch (error) {
-      this.logger.error('Failed to process order', { event, error });
-      // Don't rethrow - would crash the process
-      await this.deadLetterQueue.add('order.created', event);
-    }
-  }
-}
-
-// Safe scheduled tasks
-@Injectable()
-export class CleanupService {
-  private readonly logger = new Logger(CleanupService.name);
-
-  @Cron('0 0 * * *')
-  async dailyCleanup(): Promise<void> {
-    try {
-      await this.cleanupService.run();
-      this.logger.log('Daily cleanup completed');
-    } catch (error) {
-      this.logger.error('Daily cleanup failed', error.stack);
-      // Alert or retry logic
-    }
-  }
-}
-
-// Global unhandled rejection handler in main.ts
-async function bootstrap() {
-  const app = await NestFactory.create(AppModule);
-  const logger = new Logger('Bootstrap');
-
-  process.on('unhandledRejection', (reason, promise) => {
-    logger.error('Unhandled Rejection at:', promise, 'reason:', reason);
-  });
-
-  process.on('uncaughtException', (error) => {
-    logger.error('Uncaught Exception:', error);
-    process.exit(1);
-  });
-
-  await app.listen(3000);
-}
-```
-
-Reference: [Node.js Unhandled Rejections](https://nodejs.org/api/process.html#event-unhandledrejection)
@@ -1,114 +0,0 @@
---
-title: Throw HTTP Exceptions from Services
-impact: HIGH
-impactDescription: Keeps controllers thin and simplifies error handling
-tags: error-handling, exceptions, services
---
-
-## Throw HTTP Exceptions from Services
-
-It's acceptable (and often preferable) to throw `HttpException` subclasses from services in HTTP applications. This keeps controllers thin and allows services to communicate appropriate error states. For truly layer-agnostic services, use domain exceptions that map to HTTP status codes.
-
-**Incorrect (return error objects instead of throwing):**
-
-```typescript
-// Return error objects instead of throwing
-@Injectable()
-export class UsersService {
-  async findById(id: string): Promise<{ user?: User; error?: string }> {
-    const user = await this.repo.findOne({ where: { id } });
-    if (!user) {
-      return { error: 'User not found' }; // Controller must check this
-    }
-    return { user };
-  }
-}
-
-@Controller('users')
-export class UsersController {
-  @Get(':id')
-  async findOne(@Param('id') id: string) {
-    const result = await this.usersService.findById(id);
-    if (result.error) {
-      throw new NotFoundException(result.error);
-    }
-    return result.user;
-  }
-}
-```
-
-**Correct (throw exceptions directly from service):**
-
-```typescript
-// Throw exceptions directly from service
-@Injectable()
-export class UsersService {
-  constructor(private readonly repo: UserRepository) {}
-
-  async findById(id: string): Promise<User> {
-    const user = await this.repo.findOne({ where: { id } });
-    if (!user) {
-      throw new NotFoundException(`User #${id} not found`);
-    }
-    return user;
-  }
-
-  async create(dto: CreateUserDto): Promise<User> {
-    const existing = await this.repo.findOne({
-      where: { email: dto.email },
-    });
-    if (existing) {
-      throw new ConflictException('Email already registered');
-    }
-    return this.repo.save(dto);
-  }
-
-  async update(id: string, dto: UpdateUserDto): Promise<User> {
-    const user = await this.findById(id); // Throws if not found
-    Object.assign(user, dto);
-    return this.repo.save(user);
-  }
-}
-
-// Controller stays thin
-@Controller('users')
-export class UsersController {
-  @Get(':id')
-  findOne(@Param('id') id: string): Promise<User> {
-    return this.usersService.findById(id);
-  }
-
-  @Post()
-  create(@Body() dto: CreateUserDto): Promise<User> {
-    return this.usersService.create(dto);
-  }
-}
-
-// For layer-agnostic services, use domain exceptions
-export class EntityNotFoundException extends Error {
-  constructor(
-    public readonly entity: string,
-    public readonly id: string
-  ) {
-    super(`${entity} with ID "${id}" not found`);
-  }
-}
-
-// Map to HTTP in exception filter
-@Catch(EntityNotFoundException)
-export class EntityNotFoundFilter implements ExceptionFilter {
-  catch(exception: EntityNotFoundException, host: ArgumentsHost) {
-    const ctx = host.switchToHttp();
-    const response = ctx.getResponse<Response>();
-
-    response.status(404).json({
-      statusCode: 404,
-      message: exception.message,
-      entity: exception.entity,
-      id: exception.id,
-    });
-  }
-}
-```
-
-Reference: [NestJS Exception Filters](https://docs.nestjs.com/exception-filters)
@@ -1,128 +0,0 @@
---
-title: Use Exception Filters for Error Handling
-impact: HIGH
-impactDescription: Consistent, centralized error handling
-tags: error-handling, exception-filters, consistency
---
-
-## Use Exception Filters for Error Handling
-
-Never catch exceptions and manually format error responses in controllers. Use NestJS exception filters to handle errors consistently across your application. Create custom exception filters for specific error types and a global filter for unhandled exceptions.
-
-**Incorrect (manual error handling in controllers):**
-
-```typescript
-// Manual error handling in controllers
-@Controller('users')
-export class UsersController {
-  @Get(':id')
-  async findOne(@Param('id') id: string, @Res() res: Response) {
-    try {
-      const user = await this.usersService.findById(id);
-      if (!user) {
-        return res.status(404).json({
-          statusCode: 404,
-          message: 'User not found',
-        });
-      }
-      return res.json(user);
-    } catch (error) {
-      console.error(error);
-      return res.status(500).json({
-        statusCode: 500,
-        message: 'Internal server error',
-      });
-    }
-  }
-}
-```
-
-**Correct (exception filters with consistent handling):**
-
-```typescript
-// Use built-in and custom exceptions
-@Controller('users')
-export class UsersController {
-  @Get(':id')
-  async findOne(@Param('id') id: string): Promise<User> {
-    const user = await this.usersService.findById(id);
-    if (!user) {
-      throw new NotFoundException(`User #${id} not found`);
-    }
-    return user;
-  }
-}
-
-// Custom domain exception
-export class UserNotFoundException extends NotFoundException {
-  constructor(userId: string) {
-    super({
-      statusCode: 404,
-      error: 'Not Found',
-      message: `User with ID "${userId}" not found`,
-      code: 'USER_NOT_FOUND',
-    });
-  }
-}
-
-// Custom exception filter for domain errors
-@Catch(DomainException)
-export class DomainExceptionFilter implements ExceptionFilter {
-  catch(exception: DomainException, host: ArgumentsHost) {
-    const ctx = host.switchToHttp();
-    const response = ctx.getResponse<Response>();
-    const request = ctx.getRequest<Request>();
-
-    const status = exception.getStatus?.() || 400;
-
-    response.status(status).json({
-      statusCode: status,
-      code: exception.code,
-      message: exception.message,
-      timestamp: new Date().toISOString(),
-      path: request.url,
-    });
-  }
-}
-
-// Global exception filter for unhandled errors
-@Catch()
-export class AllExceptionsFilter implements ExceptionFilter {
-  constructor(private readonly logger: Logger) {}
-
-  catch(exception: unknown, host: ArgumentsHost) {
-    const ctx = host.switchToHttp();
-    const response = ctx.getResponse<Response>();
-    const request = ctx.getRequest<Request>();
-
-    const status = exception instanceof HttpException ? exception.getStatus() : HttpStatus.INTERNAL_SERVER_ERROR;
-
-    const message = exception instanceof HttpException ? exception.message : 'Internal server error';
-
-    this.logger.error(`${request.method} ${request.url}`, exception instanceof Error ? exception.stack : exception);
-
-    response.status(status).json({
-      statusCode: status,
-      message,
-      timestamp: new Date().toISOString(),
-      path: request.url,
-    });
-  }
-}
-
-// Register globally in main.ts
-app.useGlobalFilters(new AllExceptionsFilter(app.get(Logger)), new DomainExceptionFilter());
-
-// Or via module
-@Module({
-  providers: [
-    {
-      provide: APP_FILTER,
-      useClass: AllExceptionsFilter,
-    },
-  ],
-})
-export class AppModule {}
-```
-
-Reference: [NestJS Exception Filters](https://docs.nestjs.com/exception-filters)
@@ -1,157 +0,0 @@
---
-title: AI Integration Boundary (ADR-018 / ADR-020)
-impact: CRITICAL
-impactDescription: AI runs on Admin Desktop only; AI → DMS API → DB (never direct); human-in-the-loop validation mandatory; full audit trail.
-tags: ai, ollama, boundary, adr-018, adr-020, privacy, audit
---
-
-## AI Integration Boundary
-
-LCBP3 uses **on-premises AI only** (Ollama on Admin Desktop) with strict isolation from data layers.
-
---
-
-## The Boundary
-
-```
-┌────────────────────────────────────────────────────────────┐
-│  User Browser (Next.js)                                    │
-└─────────────────────────┬──────────────────────────────────┘
-                          │  (authenticated HTTPS)
-┌─────────────────────────▼──────────────────────────────────┐
-│  DMS API (NestJS)  ◀── enforces CASL, validation, audit    │
-│   ├─ AiGateway (proxies to Ollama)                          │
-│   └─ DB + Storage (Elasticsearch, MariaDB, File System)    │
-└─────────────────────────┬──────────────────────────────────┘
-                          │ (HTTP → Admin Desktop, internal)
-┌─────────────────────────▼──────────────────────────────────┐
-│  Admin Desktop (Desk-5439)                                 │
-│   ├─ Ollama (Gemma 4)                                       │
-│   ├─ PaddleOCR (Thai + English)                             │
-│   └─ n8n orchestration                                      │
-└────────────────────────────────────────────────────────────┘
-```
-
-**❗ Admin Desktop has NO network access to MariaDB, no SMB to storage, no shared secrets.** It receives base64-encoded file bytes over HTTPS and returns extracted text + suggestions.
-
---
-
-## Required Patterns
-
-### 1. AiGateway Module (backend)
-
-```typescript
-@Module({
-  controllers: [AiController],
-  providers: [AiService, AiGateway, AiAuditLogger],
-  exports: [AiService],
-})
-export class AiModule {}
-
-@Injectable()
-export class AiService {
-  async extractMetadata(fileId: number, user: User): Promise<ExtractedMetadata> {
-    // 1. Authorize (CASL: user can read this file)
-    await this.ability.ensureCan(user, 'read', File, fileId);
-
-    // 2. Load file (DMS API, inside the boundary)
-    const fileBytes = await this.storageService.read(fileId);
-
-    // 3. Call Admin Desktop AI over HTTP
-    const raw = await this.aiGateway.extract(fileBytes);
-
-    // 4. Validate AI output schema (Zod)
-    const parsed = ExtractedMetadataSchema.parse(raw);
-
-    // 5. Audit log (who, what, when, model, confidence)
-    await this.auditLogger.log({
-      userId: user.id,
-      action: 'ai.extract_metadata',
-      fileId,
-      model: raw.model,
-      confidence: parsed.confidence,
-    });
-
-    // 6. Return — frontend MUST render for human confirmation
-    return parsed;
-  }
-}
-```
-
-### 2. Human-in-the-Loop
-
-AI output is **never persisted directly**. Users must confirm via `DocumentReviewForm`:
-
-```tsx
-<DocumentReviewForm
-  document={doc}
-  aiSuggestions={suggestions}
-  onConfirm={(reviewed) => saveMetadata(reviewed)} // user edits applied
-/>
-```
-
-The `user_confirmed_at` timestamp and diff (AI suggestion → final value) are stored in the audit log.
-
-### 3. Rate Limiting
-
-```typescript
-@Post('ai/extract')
-@UseGuards(JwtAuthGuard, CaslAbilityGuard, ThrottlerGuard)
-@Throttle({ default: { limit: 10, ttl: 60_000 } }) // 10 req/min/user
-async extract(@Body() dto: ExtractDto) { /* ... */ }
-```
-
---
-
-## ❌ Forbidden
-
-```typescript
-// ❌ AI container connecting to DB
-// docker-compose.yml inside ai-service:
-// environment:
-//   DATABASE_URL: mysql://...  ← NEVER
-
-// ❌ AI SDK calling cloud API
-import OpenAI from 'openai'; // ❌ No cloud AI SDKs in production code
-const client = new OpenAI({ apiKey: ... });
-
-// ❌ Persisting AI output without human confirm
-async extractAndSave(fileId: number) {
-  const metadata = await this.ai.extract(fileId);
-  await this.repo.save({ fileId, ...metadata }); // ❌ skips human review
-}
-
-// ❌ Skipping audit log
-const result = await this.aiGateway.extract(bytes); // no logging
-return result;
-```
-
---
-
-## Audit Log Schema
-
-```sql
-CREATE TABLE ai_audit_log (
-  id INT AUTO_INCREMENT PRIMARY KEY,
-  public_id UUID UNIQUE NOT NULL,
-  user_id INT NOT NULL,
-  action VARCHAR(64) NOT NULL,       -- 'ai.extract_metadata', 'ai.classify', etc.
-  file_id INT,
-  model VARCHAR(64),                  -- 'gemma-4:7b', 'paddleocr-v3'
-  confidence DECIMAL(4,3),
-  input_hash CHAR(64),                -- SHA-256 of input for replay detection
-  output_summary JSON,
-  human_confirmed_at DATETIME,
-  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
-  INDEX idx_user_created (user_id, created_at),
-  INDEX idx_file (file_id)
-);
-```
-
---
-
-## Reference
-
- [ADR-018 AI Boundary](../../../../specs/06-Decision-Records/ADR-018-ai-boundary.md)
- [ADR-020 AI Intelligence Integration](../../../../specs/06-Decision-Records/ADR-020-ai-intelligence-integration.md)
- [ADR-017 Ollama Data Migration](../../../../specs/06-Decision-Records/ADR-017-ollama-data-migration.md)
@@ -1,181 +0,0 @@
---
-title: Workflow Engine + Document Numbering + Workflow Context (ADR-001 / 002 / 021)
-impact: CRITICAL
-impactDescription: DSL-based state machine; double-lock numbering; integrated workflow context exposed to clients.
-tags: workflow, numbering, redlock, version-column, adr-001, adr-002, adr-021
---
-
-## Workflow Engine + Numbering + Context
-
-LCBP3 uses a **unified workflow engine** (DSL-based state machine) across RFA, Transmittal, Correspondence, Circulation, and Shop Drawing. Every state transition goes through the same engine — no per-type routing tables.
-
---
-
-## ADR-001: Unified Workflow Engine
-
-### State Transition Pattern
-
-```typescript
-@Injectable()
-export class WorkflowEngine {
-  async transition(
-    instanceId: string,
-    action: WorkflowAction,
-    actor: User,
-    context?: WorkflowContext,
-  ): Promise<WorkflowInstance> {
-    // 1. Load current state from DB (never trust client-provided state)
-    const instance = await this.repo.findOneByPublicId(instanceId);
-    if (!instance) throw new NotFoundException();
-
-    // 2. Validate transition against DSL
-    const dsl = await this.dslService.load(instance.workflowTypeId);
-    const nextState = dsl.resolve(instance.currentState, action);
-    if (!nextState) {
-      throw new BusinessException(
-        `Action ${action} not allowed from state ${instance.currentState}`,
-        'ไม่สามารถดำเนินการนี้ได้ในสถานะปัจจุบัน',
-        'กรุณาตรวจสอบขั้นตอนการอนุมัติ',
-        'WF_INVALID_TRANSITION',
-      );
-    }
-
-    // 3. Apply transition atomically (optimistic lock via @VersionColumn)
-    instance.currentState = nextState;
-    await this.repo.save(instance); // throws OptimisticLockVersionMismatchError on race
-
-    // 4. Emit event for listeners (notifications via BullMQ — ADR-008)
-    this.eventBus.publish(new WorkflowTransitionedEvent(instance, action, actor));
-
-    return instance;
-  }
-}
-```
-
-### ❌ Anti-Patterns
-
- ❌ Hard-coded `switch (state)` in controllers/services
- ❌ Trusting `currentState` from request body
- ❌ Creating separate routing tables per document type
-
---
-
-## ADR-002: Document Numbering (Double-Lock)
-
-Concurrent requests for a new document number **must** use both:
-
-1. **Redis Redlock** — distributed lock across app instances
-2. **TypeORM `@VersionColumn`** — optimistic lock on counter row
-
-### Counter Entity
-
-```typescript
-@Entity('document_number_counters')
-@Unique(['projectId', 'documentTypeId'])
-export class DocumentNumberCounter extends UuidBaseEntity {
-  @Column({ name: 'project_id' })
-  projectId: number;
-
-  @Column({ name: 'document_type_id' })
-  documentTypeId: number;
-
-  @Column({ name: 'last_number', default: 0 })
-  lastNumber: number;
-
-  @VersionColumn()
-  version: number; // ❗ Optimistic lock — do not rename, do not remove
-}
-```
-
-### Service Pattern
-
-```typescript
-@Injectable()
-export class DocumentNumberingService {
-  constructor(
-    @InjectRepository(DocumentNumberCounter)
-    private counterRepo: Repository<DocumentNumberCounter>,
-    private redlock: RedlockService,
-    private readonly logger: Logger,
-  ) {}
-
-  async generateNext(ctx: NumberingContext): Promise<string> {
-    const lockKey = `doc_num:${ctx.projectId}:${ctx.documentTypeId}`;
-
-    // Distributed lock — 3s TTL, up to 5 retries
-    const lock = await this.redlock.acquire([lockKey], 3000);
-
-    try {
-      // Optimistic lock via @VersionColumn
-      const counter = await this.counterRepo.findOne({
-        where: { projectId: ctx.projectId, documentTypeId: ctx.documentTypeId },
-      });
-
-      if (!counter) {
-        throw new NotFoundException('Counter not initialized for this project/type');
-      }
-
-      counter.lastNumber += 1;
-      await this.counterRepo.save(counter); // may throw OptimisticLockVersionMismatchError
-
-      return this.formatNumber(ctx, counter.lastNumber);
-    } catch (err) {
-      if (err instanceof OptimisticLockVersionMismatchError) {
-        this.logger.warn(`Numbering race detected for ${lockKey}, retrying`);
-        // Let caller retry via BullMQ retry policy
-      }
-      throw err;
-    } finally {
-      await lock.release();
-    }
-  }
-
-  private formatNumber(ctx: NumberingContext, seq: number): string {
-    // e.g. "LCBP3-RFA-0042"
-    return `${ctx.projectCode}-${ctx.typeCode}-${String(seq).padStart(4, '0')}`;
-  }
-}
-```
-
-### ❌ Anti-Patterns
-
- ❌ App-side counter only (`let counter = 0; counter++`)
- ❌ Using `findOne` + `update` without `@VersionColumn`
- ❌ Using only Redis lock without DB optimistic lock (race if Redis fails)
-
---
-
-## ADR-021: Integrated Workflow Context
-
-Every workflow-aware API response **must** expose:
-
-```typescript
-export class WorkflowEnvelope<T> {
-  data: T;
-
-  workflow: {
-    instancePublicId: string;
-    currentState: string;       // e.g. 'pending_review'
-    availableActions: string[]; // e.g. ['approve', 'reject', 'request-revision']
-    canEdit: boolean;           // computed from CASL + current state
-    lastTransitionAt: string;   // ISO 8601
-  };
-
-  stepAttachments?: Array<{     // files produced by the current/previous step
-    publicId: string;
-    fileName: string;
-    stepCode: string;
-    downloadUrl: string;
-  }>;
-}
-```
-
-Frontend uses `workflow.availableActions` to render buttons — no client-side state machine logic.
-
---
-
-## Reference
-
- [ADR-001 Unified Workflow Engine](../../../../specs/06-Decision-Records/ADR-001-unified-workflow-engine.md)
- [ADR-002 Document Numbering Strategy](../../../../specs/06-Decision-Records/ADR-002-document-numbering-strategy.md)
- [ADR-021 Workflow Context](../../../../specs/06-Decision-Records/ADR-021-workflow-context.md)
@@ -1,226 +0,0 @@
---
-title: Implement Health Checks for Microservices
-impact: MEDIUM-HIGH
-impactDescription: Health checks enable orchestrators to manage service lifecycle
-tags: microservices, health-checks, terminus, kubernetes
---
-
-## Implement Health Checks for Microservices
-
-Implement liveness and readiness probes using `@nestjs/terminus`. Liveness checks determine if the service should be restarted. Readiness checks determine if the service can accept traffic. Proper health checks enable Kubernetes and load balancers to route traffic correctly.
-
-**Incorrect (simple ping that doesn't check dependencies):**
-
-```typescript
-// Simple ping that doesn't check dependencies
-@Controller('health')
-export class HealthController {
-  @Get()
-  check(): string {
-    return 'OK'; // Service might be unhealthy but returns OK
-  }
-}
-
-// Health check that blocks on slow dependencies
-@Controller('health')
-export class HealthController {
-  @Get()
-  async check(): Promise<string> {
-    // If database is slow, health check times out
-    await this.userRepo.findOne({ where: { id: '1' } });
-    await this.redis.ping();
-    await this.externalApi.healthCheck();
-    return 'OK';
-  }
-}
-```
-
-**Correct (use @nestjs/terminus for comprehensive health checks):**
-
-```typescript
-// Use @nestjs/terminus for comprehensive health checks
-import {
-  HealthCheckService,
-  HttpHealthIndicator,
-  TypeOrmHealthIndicator,
-  HealthCheck,
-  DiskHealthIndicator,
-  MemoryHealthIndicator,
-} from '@nestjs/terminus';
-
-@Controller('health')
-export class HealthController {
-  constructor(
-    private health: HealthCheckService,
-    private http: HttpHealthIndicator,
-    private db: TypeOrmHealthIndicator,
-    private disk: DiskHealthIndicator,
-    private memory: MemoryHealthIndicator,
-  ) {}
-
-  // Liveness probe - is the service alive?
-  @Get('live')
-  @HealthCheck()
-  liveness() {
-    return this.health.check([
-      // Basic checks only
-      () => this.memory.checkHeap('memory_heap', 200 * 1024 * 1024), // 200MB
-    ]);
-  }
-
-  // Readiness probe - can the service handle traffic?
-  @Get('ready')
-  @HealthCheck()
-  readiness() {
-    return this.health.check([
-      () => this.db.pingCheck('database'),
-      () =>
-        this.http.pingCheck('redis', 'http://redis:6379', { timeout: 1000 }),
-      () =>
-        this.disk.checkStorage('disk', { path: '/', thresholdPercent: 0.9 }),
-    ]);
-  }
-
-  // Deep health check for debugging
-  @Get('deep')
-  @HealthCheck()
-  deepCheck() {
-    return this.health.check([
-      () => this.db.pingCheck('database'),
-      () => this.memory.checkHeap('memory_heap', 200 * 1024 * 1024),
-      () => this.memory.checkRSS('memory_rss', 300 * 1024 * 1024),
-      () =>
-        this.disk.checkStorage('disk', { path: '/', thresholdPercent: 0.9 }),
-      () =>
-        this.http.pingCheck('external-api', 'https://api.example.com/health'),
-    ]);
-  }
-}
-
-// Custom indicator for business-specific health
-@Injectable()
-export class QueueHealthIndicator extends HealthIndicator {
-  constructor(private queueService: QueueService) {
-    super();
-  }
-
-  async isHealthy(key: string): Promise<HealthIndicatorResult> {
-    const queueStats = await this.queueService.getStats();
-
-    const isHealthy = queueStats.failedCount < 100;
-    const result = this.getStatus(key, isHealthy, {
-      waiting: queueStats.waitingCount,
-      active: queueStats.activeCount,
-      failed: queueStats.failedCount,
-    });
-
-    if (!isHealthy) {
-      throw new HealthCheckError('Queue unhealthy', result);
-    }
-
-    return result;
-  }
-}
-
-// Redis health indicator
-@Injectable()
-export class RedisHealthIndicator extends HealthIndicator {
-  constructor(@InjectRedis() private redis: Redis) {
-    super();
-  }
-
-  async isHealthy(key: string): Promise<HealthIndicatorResult> {
-    try {
-      const pong = await this.redis.ping();
-      return this.getStatus(key, pong === 'PONG');
-    } catch (error) {
-      throw new HealthCheckError('Redis check failed', this.getStatus(key, false));
-    }
-  }
-}
-
-// Use custom indicators
-@Get('ready')
-@HealthCheck()
-readiness() {
-  return this.health.check([
-    () => this.db.pingCheck('database'),
-    () => this.redis.isHealthy('redis'),
-    () => this.queue.isHealthy('job-queue'),
-  ]);
-}
-
-// Graceful shutdown handling
-@Injectable()
-export class GracefulShutdownService implements OnApplicationShutdown {
-  private isShuttingDown = false;
-
-  isShutdown(): boolean {
-    return this.isShuttingDown;
-  }
-
-  async onApplicationShutdown(signal: string): Promise<void> {
-    this.isShuttingDown = true;
-    console.log(`Shutting down on ${signal}`);
-
-    // Wait for in-flight requests
-    await new Promise((resolve) => setTimeout(resolve, 5000));
-  }
-}
-
-// Health check respects shutdown state
-@Get('ready')
-@HealthCheck()
-readiness() {
-  if (this.shutdownService.isShutdown()) {
-    throw new ServiceUnavailableException('Shutting down');
-  }
-
-  return this.health.check([
-    () => this.db.pingCheck('database'),
-  ]);
-}
-```
-
-### Kubernetes Configuration
-
-```yaml
-# Kubernetes deployment with probes
-apiVersion: apps/v1
-kind: Deployment
-metadata:
-  name: api-service
-spec:
-  template:
-    spec:
-      containers:
-        - name: api
-          image: api-service:latest
-          ports:
-            - containerPort: 3000
-          livenessProbe:
-            httpGet:
-              path: /health/live
-              port: 3000
-            initialDelaySeconds: 30
-            periodSeconds: 10
-            timeoutSeconds: 5
-            failureThreshold: 3
-          readinessProbe:
-            httpGet:
-              path: /health/ready
-              port: 3000
-            initialDelaySeconds: 5
-            periodSeconds: 5
-            timeoutSeconds: 3
-            failureThreshold: 3
-          startupProbe:
-            httpGet:
-              path: /health/live
-              port: 3000
-            initialDelaySeconds: 0
-            periodSeconds: 5
-            failureThreshold: 30
-```
-
-Reference: [NestJS Terminus](https://docs.nestjs.com/recipes/terminus)
@@ -1,167 +0,0 @@
---
-title: Use Message and Event Patterns Correctly
-impact: MEDIUM
-impactDescription: Proper patterns ensure reliable microservice communication
-tags: microservices, message-pattern, event-pattern, communication
---
-
-## Use Message and Event Patterns Correctly
-
-NestJS microservices support two communication patterns: request-response (MessagePattern) and event-based (EventPattern). Use MessagePattern when you need a response, and EventPattern for fire-and-forget notifications. Understanding the difference prevents communication bugs.
-
-**Incorrect (using wrong pattern for use case):**
-
-```typescript
-// Use @MessagePattern for fire-and-forget
-@Controller()
-export class NotificationsController {
-  @MessagePattern('user.created')
-  async handleUserCreated(data: UserCreatedEvent) {
-    // This WAITS for response, blocking the sender
-    await this.emailService.sendWelcome(data.email);
-    // If email fails, sender gets an error (coupling!)
-  }
-}
-
-// Use @EventPattern expecting a response
-@Controller()
-export class OrdersController {
-  @EventPattern('inventory.check')
-  async checkInventory(data: CheckInventoryDto) {
-    const available = await this.inventory.check(data);
-    return available; // This return value is IGNORED with @EventPattern!
-  }
-}
-
-// Tight coupling in client
-@Injectable()
-export class UsersService {
-  async createUser(dto: CreateUserDto): Promise<User> {
-    const user = await this.repo.save(dto);
-
-    // Blocks until notification service responds
-    await this.client.send('user.created', user).toPromise();
-    // If notification service is down, user creation fails!
-
-    return user;
-  }
-}
-```
-
-**Correct (use MessagePattern for request-response, EventPattern for fire-and-forget):**
-
-```typescript
-// MessagePattern: Request-Response (when you NEED a response)
-@Controller()
-export class InventoryController {
-  @MessagePattern({ cmd: 'check_inventory' })
-  async checkInventory(data: CheckInventoryDto): Promise<InventoryResult> {
-    const result = await this.inventoryService.check(data.productId, data.quantity);
-    return result; // Response sent back to caller
-  }
-}
-
-// Client expects response
-@Injectable()
-export class OrdersService {
-  async createOrder(dto: CreateOrderDto): Promise<Order> {
-    // Check inventory - we NEED this response to proceed
-    const inventory = await firstValueFrom(
-      this.inventoryClient.send<InventoryResult>(
-        { cmd: 'check_inventory' },
-        { productId: dto.productId, quantity: dto.quantity },
-      ),
-    );
-
-    if (!inventory.available) {
-      throw new BadRequestException('Insufficient inventory');
-    }
-
-    return this.repo.save(dto);
-  }
-}
-
-// EventPattern: Fire-and-Forget (for notifications, side effects)
-@Controller()
-export class NotificationsController {
-  @EventPattern('user.created')
-  async handleUserCreated(data: UserCreatedEvent): Promise<void> {
-    // No return value needed - just process the event
-    await this.emailService.sendWelcome(data.email);
-    await this.analyticsService.track('user_signup', data);
-    // If this fails, it doesn't affect the sender
-  }
-}
-
-// Client emits event without waiting
-@Injectable()
-export class UsersService {
-  async createUser(dto: CreateUserDto): Promise<User> {
-    const user = await this.repo.save(dto);
-
-    // Fire and forget - doesn't block, doesn't wait
-    this.eventClient.emit('user.created', {
-      userId: user.id,
-      email: user.email,
-      timestamp: new Date(),
-    });
-
-    return user; // User creation succeeds regardless of event handling
-  }
-}
-
-// Hybrid pattern for critical events
-@Injectable()
-export class OrdersService {
-  async createOrder(dto: CreateOrderDto): Promise<Order> {
-    const order = await this.repo.save(dto);
-
-    // Critical: inventory reservation (use MessagePattern)
-    const reserved = await firstValueFrom(
-      this.inventoryClient.send({ cmd: 'reserve_inventory' }, {
-        orderId: order.id,
-        items: dto.items,
-      }),
-    );
-
-    if (!reserved.success) {
-      await this.repo.delete(order.id);
-      throw new BadRequestException('Could not reserve inventory');
-    }
-
-    // Non-critical: notifications (use EventPattern)
-    this.eventClient.emit('order.created', {
-      orderId: order.id,
-      userId: dto.userId,
-      total: dto.total,
-    });
-
-    return order;
-  }
-}
-
-// Error handling patterns
-// MessagePattern errors propagate to caller
-@MessagePattern({ cmd: 'get_user' })
-async getUser(userId: string): Promise<User> {
-  const user = await this.repo.findOne({ where: { id: userId } });
-  if (!user) {
-    throw new RpcException('User not found'); // Received by caller
-  }
-  return user;
-}
-
-// EventPattern errors should be handled locally
-@EventPattern('order.created')
-async handleOrderCreated(data: OrderCreatedEvent): Promise<void> {
-  try {
-    await this.processOrder(data);
-  } catch (error) {
-    // Log and potentially retry - don't throw
-    this.logger.error('Failed to process order event', error);
-    await this.deadLetterQueue.add(data);
-  }
-}
-```
-
-Reference: [NestJS Microservices](https://docs.nestjs.com/microservices/basics)
@@ -1,246 +0,0 @@
---
-title: Use Message Queues for Background Jobs
-impact: MEDIUM-HIGH
-impactDescription: Queues enable reliable background processing
-tags: microservices, queues, bullmq, background-jobs
---
-
-## Use Message Queues for Background Jobs
-
-Use `@nestjs/bullmq` for background job processing. Queues decouple long-running tasks from HTTP requests, enable retry logic, and distribute workload across workers. Use them for emails, file processing, notifications, and any task that shouldn't block user requests.
-
-**Incorrect (long-running tasks in HTTP handlers):**
-
-```typescript
-// Long-running tasks in HTTP handlers
-@Controller('reports')
-export class ReportsController {
-  @Post()
-  async generate(@Body() dto: GenerateReportDto): Promise<Report> {
-    // This blocks the request for potentially minutes
-    const data = await this.fetchLargeDataset(dto);
-    const report = await this.processData(data); // Slow!
-    await this.sendEmail(dto.email, report); // Can fail!
-    return report; // Client times out
-  }
-}
-
-// Fire-and-forget without retry
-@Injectable()
-export class EmailService {
-  async sendWelcome(email: string): Promise<void> {
-    // If this fails, email is never sent
-    await this.mailer.send({ to: email, template: 'welcome' });
-    // No retry, no tracking, no visibility
-  }
-}
-
-// Use setInterval for scheduled tasks
-setInterval(async () => {
-  await cleanupOldRecords();
-}, 60000); // No error handling, memory leaks
-```
-
-**Correct (use BullMQ for background processing):**
-
-```typescript
-// Configure BullMQ
-import { BullModule } from '@nestjs/bullmq';
-
-@Module({
-  imports: [
-    BullModule.forRoot({
-      connection: {
-        host: 'localhost',
-        port: 6379,
-      },
-      defaultJobOptions: {
-        removeOnComplete: 1000,
-        removeOnFail: 5000,
-        attempts: 3,
-        backoff: {
-          type: 'exponential',
-          delay: 1000,
-        },
-      },
-    }),
-    BullModule.registerQueue({ name: 'email' }, { name: 'reports' }, { name: 'notifications' }),
-  ],
-})
-export class QueueModule {}
-
-// Producer: Add jobs to queue
-@Injectable()
-export class ReportsService {
-  constructor(@InjectQueue('reports') private reportsQueue: Queue) {}
-
-  async requestReport(dto: GenerateReportDto): Promise<{ jobId: string }> {
-    // Return immediately, process in background
-    const job = await this.reportsQueue.add('generate', dto, {
-      priority: dto.urgent ? 1 : 10,
-      delay: dto.scheduledFor ? Date.parse(dto.scheduledFor) - Date.now() : 0,
-    });
-
-    return { jobId: job.id };
-  }
-
-  async getJobStatus(jobId: string): Promise<JobStatus> {
-    const job = await this.reportsQueue.getJob(jobId);
-    return {
-      status: await job.getState(),
-      progress: job.progress,
-      result: job.returnvalue,
-    };
-  }
-}
-
-// Consumer: Process jobs
-@Processor('reports')
-export class ReportsProcessor {
-  private readonly logger = new Logger(ReportsProcessor.name);
-
-  @Process('generate')
-  async generateReport(job: Job<GenerateReportDto>): Promise<Report> {
-    this.logger.log(`Processing report job ${job.id}`);
-
-    // Update progress
-    await job.updateProgress(10);
-
-    const data = await this.fetchData(job.data);
-    await job.updateProgress(50);
-
-    const report = await this.processData(data);
-    await job.updateProgress(90);
-
-    await this.saveReport(report);
-    await job.updateProgress(100);
-
-    return report;
-  }
-
-  @OnQueueActive()
-  onActive(job: Job) {
-    this.logger.log(`Processing job ${job.id}`);
-  }
-
-  @OnQueueCompleted()
-  onCompleted(job: Job, result: any) {
-    this.logger.log(`Job ${job.id} completed`);
-  }
-
-  @OnQueueFailed()
-  onFailed(job: Job, error: Error) {
-    this.logger.error(`Job ${job.id} failed: ${error.message}`);
-  }
-}
-
-// Email queue with retry
-@Processor('email')
-export class EmailProcessor {
-  @Process('send')
-  async sendEmail(job: Job<SendEmailDto>): Promise<void> {
-    const { to, template, data } = job.data;
-
-    try {
-      await this.mailer.send({
-        to,
-        template,
-        context: data,
-      });
-    } catch (error) {
-      // BullMQ will retry based on job options
-      throw error;
-    }
-  }
-}
-
-// Usage
-@Injectable()
-export class NotificationService {
-  constructor(@InjectQueue('email') private emailQueue: Queue) {}
-
-  async sendWelcome(user: User): Promise<void> {
-    await this.emailQueue.add(
-      'send',
-      {
-        to: user.email,
-        template: 'welcome',
-        data: { name: user.name },
-      },
-      {
-        attempts: 5,
-        backoff: { type: 'exponential', delay: 5000 },
-      }
-    );
-  }
-}
-
-// Scheduled jobs
-@Injectable()
-export class ScheduledJobsService implements OnModuleInit {
-  constructor(@InjectQueue('maintenance') private queue: Queue) {}
-
-  async onModuleInit(): Promise<void> {
-    // Clean up old reports daily at midnight
-    await this.queue.add(
-      'cleanup',
-      {},
-      {
-        repeat: { cron: '0 0 * * *' },
-        jobId: 'daily-cleanup', // Prevent duplicates
-      }
-    );
-
-    // Send digest every hour
-    await this.queue.add(
-      'digest',
-      {},
-      {
-        repeat: { every: 60 * 60 * 1000 },
-        jobId: 'hourly-digest',
-      }
-    );
-  }
-}
-
-@Processor('maintenance')
-export class MaintenanceProcessor {
-  @Process('cleanup')
-  async cleanup(): Promise<void> {
-    await this.cleanupOldReports();
-    await this.cleanupExpiredSessions();
-  }
-
-  @Process('digest')
-  async sendDigest(): Promise<void> {
-    const users = await this.getUsersForDigest();
-    for (const user of users) {
-      await this.emailQueue.add('send', { to: user.email, template: 'digest' });
-    }
-  }
-}
-
-// Queue monitoring with Bull Board
-import { BullBoardModule } from '@bull-board/nestjs';
-import { BullMQAdapter } from '@bull-board/api/bullMQAdapter';
-
-@Module({
-  imports: [
-    BullBoardModule.forRoot({
-      route: '/admin/queues',
-      adapter: ExpressAdapter,
-    }),
-    BullBoardModule.forFeature({
-      name: 'email',
-      adapter: BullMQAdapter,
-    }),
-    BullBoardModule.forFeature({
-      name: 'reports',
-      adapter: BullMQAdapter,
-    }),
-  ],
-})
-export class AdminModule {}
-```
-
-Reference: [NestJS Queues](https://docs.nestjs.com/techniques/queues)
@@ -1,109 +0,0 @@
---
-title: Use Async Lifecycle Hooks Correctly
-impact: HIGH
-impactDescription: Improper async handling blocks application startup
-tags: performance, lifecycle, async, hooks
---
-
-## Use Async Lifecycle Hooks Correctly
-
-NestJS lifecycle hooks (`onModuleInit`, `onApplicationBootstrap`, etc.) support async operations. However, misusing them can block application startup or cause race conditions. Understand the lifecycle order and use hooks appropriately.
-
-**Incorrect (fire-and-forget async without await):**
-
-```typescript
-// Fire-and-forget async without await
-@Injectable()
-export class DatabaseService implements OnModuleInit {
-  onModuleInit() {
-    // This runs but doesn't block - app starts before DB is ready!
-    this.connect();
-  }
-
-  private async connect() {
-    await this.pool.connect();
-    console.log('Database connected');
-  }
-}
-
-// Heavy blocking operations in constructor
-@Injectable()
-export class ConfigService {
-  private config: Config;
-
-  constructor() {
-    // BLOCKS entire module instantiation synchronously
-    this.config = fs.readFileSync('config.json');
-  }
-}
-```
-
-**Correct (return promises from async hooks):**
-
-```typescript
-// Return promise from async hooks
-@Injectable()
-export class DatabaseService implements OnModuleInit {
-  private pool: Pool;
-
-  async onModuleInit(): Promise<void> {
-    // NestJS waits for this to complete before continuing
-    await this.pool.connect();
-    console.log('Database connected');
-  }
-
-  async onModuleDestroy(): Promise<void> {
-    // Clean up resources on shutdown
-    await this.pool.end();
-    console.log('Database disconnected');
-  }
-}
-
-// Use onApplicationBootstrap for cross-module dependencies
-@Injectable()
-export class CacheWarmerService implements OnApplicationBootstrap {
-  constructor(
-    private cache: CacheService,
-    private products: ProductsService
-  ) {}
-
-  async onApplicationBootstrap(): Promise<void> {
-    // All modules are initialized, safe to warm cache
-    const products = await this.products.findPopular();
-    await this.cache.warmup(products);
-  }
-}
-
-// Heavy init in async hooks, not constructor
-@Injectable()
-export class ConfigService implements OnModuleInit {
-  private config: Config;
-
-  constructor() {
-    // Keep constructor synchronous and fast
-  }
-
-  async onModuleInit(): Promise<void> {
-    // Async loading in lifecycle hook
-    this.config = await this.loadConfig();
-  }
-
-  private async loadConfig(): Promise<Config> {
-    const file = await fs.promises.readFile('config.json');
-    return JSON.parse(file.toString());
-  }
-
-  get<T>(key: string): T {
-    return this.config[key];
-  }
-}
-
-// Enable shutdown hooks in main.ts
-async function bootstrap() {
-  const app = await NestFactory.create(AppModule);
-  app.enableShutdownHooks(); // Enable SIGTERM/SIGINT handling
-  await app.listen(3000);
-}
-```
-
-Reference: [NestJS Lifecycle Events](https://docs.nestjs.com/fundamentals/lifecycle-events)
@@ -1,118 +0,0 @@
---
-title: Use Lazy Loading for Large Modules
-impact: MEDIUM
-impactDescription: Improves startup time for large applications
-tags: performance, lazy-loading, modules, optimization
---
-
-## Use Lazy Loading for Large Modules
-
-NestJS supports lazy-loading modules, which defers initialization until first use. This is valuable for large applications where some features are rarely used, serverless deployments where cold start time matters, or when certain modules have heavy initialization costs.
-
-**Incorrect (loading everything eagerly):**
-
-```typescript
-// Load everything eagerly in a large app
-@Module({
-  imports: [
-    UsersModule,
-    OrdersModule,
-    PaymentsModule,
-    ReportsModule, // Heavy, rarely used
-    AnalyticsModule, // Heavy, rarely used
-    AdminModule, // Only admins use this
-    LegacyModule, // Migration module, rarely used
-    BulkImportModule, // Used once a month
-  ],
-})
-export class AppModule {}
-
-// All modules initialize at startup, even if never used
-// Slow cold starts in serverless
-// Memory wasted on unused modules
-```
-
-**Correct (lazy load rarely-used modules):**
-
-```typescript
-// Use LazyModuleLoader for optional modules
-import { LazyModuleLoader } from '@nestjs/core';
-
-@Injectable()
-export class ReportsService {
-  constructor(private lazyModuleLoader: LazyModuleLoader) {}
-
-  async generateReport(type: string): Promise<Report> {
-    // Load module only when needed
-    const { ReportsModule } = await import('./reports/reports.module');
-    const moduleRef = await this.lazyModuleLoader.load(() => ReportsModule);
-
-    const reportsService = moduleRef.get(ReportsGeneratorService);
-    return reportsService.generate(type);
-  }
-}
-
-// Lazy load admin features with caching
-@Injectable()
-export class AdminService {
-  private adminModule: ModuleRef | null = null;
-
-  constructor(private lazyModuleLoader: LazyModuleLoader) {}
-
-  private async getAdminModule(): Promise<ModuleRef> {
-    if (!this.adminModule) {
-      const { AdminModule } = await import('./admin/admin.module');
-      this.adminModule = await this.lazyModuleLoader.load(() => AdminModule);
-    }
-    return this.adminModule;
-  }
-
-  async runAdminTask(task: string): Promise<void> {
-    const moduleRef = await this.getAdminModule();
-    const taskRunner = moduleRef.get(AdminTaskRunner);
-    await taskRunner.run(task);
-  }
-}
-
-// Reusable lazy loader service
-@Injectable()
-export class ModuleLoaderService {
-  private loadedModules = new Map<string, ModuleRef>();
-
-  constructor(private lazyModuleLoader: LazyModuleLoader) {}
-
-  async load<T>(key: string, importFn: () => Promise<{ default: Type<T> } | Type<T>>): Promise<ModuleRef> {
-    if (!this.loadedModules.has(key)) {
-      const module = await importFn();
-      const moduleType = 'default' in module ? module.default : module;
-      const moduleRef = await this.lazyModuleLoader.load(() => moduleType);
-      this.loadedModules.set(key, moduleRef);
-    }
-    return this.loadedModules.get(key)!;
-  }
-}
-
-// Preload modules in background after startup
-@Injectable()
-export class ModulePreloader implements OnApplicationBootstrap {
-  constructor(private lazyModuleLoader: LazyModuleLoader) {}
-
-  async onApplicationBootstrap(): Promise<void> {
-    setTimeout(async () => {
-      await this.preloadModule(() => import('./reports/reports.module'));
-    }, 5000); // 5 seconds after startup
-  }
-
-  private async preloadModule(importFn: () => Promise<any>): Promise<void> {
-    try {
-      const module = await importFn();
-      const moduleType = module.default || Object.values(module)[0];
-      await this.lazyModuleLoader.load(() => moduleType);
-    } catch (error) {
-      console.warn('Failed to preload module', error);
-    }
-  }
-}
-```
-
-Reference: [NestJS Lazy Loading Modules](https://docs.nestjs.com/fundamentals/lazy-loading-modules)
@@ -1,131 +0,0 @@
---
-title: Optimize Database Queries
-impact: HIGH
-impactDescription: Database queries are typically the largest source of latency
-tags: performance, database, queries, optimization
---
-
-## Optimize Database Queries
-
-Select only needed columns, use proper indexes, avoid over-fetching relations, and consider query performance when designing your data access. Most API slowness traces back to inefficient database queries.
-
-**Incorrect (over-fetching data and missing indexes):**
-
-```typescript
-// Select everything when you need few fields
-@Injectable()
-export class UsersService {
-  async findAllEmails(): Promise<string[]> {
-    const users = await this.repo.find();
-    // Fetches ALL columns for ALL users
-    return users.map((u) => u.email);
-  }
-
-  async getUserSummary(id: string): Promise<UserSummary> {
-    const user = await this.repo.findOne({
-      where: { id },
-      relations: ['posts', 'posts.comments', 'posts.comments.author', 'followers'],
-    });
-    // Over-fetches massive relation tree
-    return { name: user.name, postCount: user.posts.length };
-  }
-}
-
-// No indexes on frequently queried columns
-@Entity()
-export class Order {
-  @Column()
-  userId: string; // No index - full table scan on every lookup
-
-  @Column()
-  status: string; // No index - slow status filtering
-}
-```
-
-**Correct (select only needed data with proper indexes):**
-
-```typescript
-// Select only needed columns
-@Injectable()
-export class UsersService {
-  async findAllEmails(): Promise<string[]> {
-    const users = await this.repo.find({
-      select: ['email'], // Only fetch email column
-    });
-    return users.map((u) => u.email);
-  }
-
-  // Use QueryBuilder for complex selections
-  async getUserSummary(id: string): Promise<UserSummary> {
-    return this.repo
-      .createQueryBuilder('user')
-      .select('user.name', 'name')
-      .addSelect('COUNT(post.id)', 'postCount')
-      .leftJoin('user.posts', 'post')
-      .where('user.id = :id', { id })
-      .groupBy('user.id')
-      .getRawOne();
-  }
-
-  // Fetch relations only when needed
-  async getFullProfile(id: string): Promise<User> {
-    return this.repo.findOne({
-      where: { id },
-      relations: ['posts'], // Only immediate relation
-      select: {
-        id: true,
-        name: true,
-        email: true,
-        posts: {
-          id: true,
-          title: true,
-        },
-      },
-    });
-  }
-}
-
-// Add indexes on frequently queried columns
-@Entity()
-@Index(['userId'])
-@Index(['status'])
-@Index(['createdAt'])
-@Index(['userId', 'status']) // Composite index for common query pattern
-export class Order {
-  @PrimaryGeneratedColumn('uuid')
-  id: string;
-
-  @Column()
-  userId: string;
-
-  @Column()
-  status: string;
-
-  @CreateDateColumn()
-  createdAt: Date;
-}
-
-// Always paginate large datasets
-@Injectable()
-export class OrdersService {
-  async findAll(page = 1, limit = 20): Promise<PaginatedResult<Order>> {
-    const [items, total] = await this.repo.findAndCount({
-      skip: (page - 1) * limit,
-      take: limit,
-      order: { createdAt: 'DESC' },
-    });
-
-    return {
-      items,
-      meta: {
-        page,
-        limit,
-        total,
-        totalPages: Math.ceil(total / limit),
-      },
-    };
-  }
-}
-```
-
-Reference: [TypeORM Query Builder](https://typeorm.io/select-query-builder)
@@ -1,123 +0,0 @@
---
-title: Use Caching Strategically
-impact: HIGH
-impactDescription: Dramatically reduces database load and response times
-tags: performance, caching, redis, optimization
---
-
-## Use Caching Strategically
-
-Implement caching for expensive operations, frequently accessed data, and external API calls. Use NestJS CacheModule with appropriate TTLs and cache invalidation strategies. Don't cache everything - focus on high-impact areas.
-
-**Incorrect (no caching or caching everything):**
-
-```typescript
-// No caching for expensive, repeated queries
-@Injectable()
-export class ProductsService {
-  async getPopular(): Promise<Product[]> {
-    // Runs complex aggregation query EVERY request
-    return this.productsRepo
-      .createQueryBuilder('p')
-      .leftJoin('p.orders', 'o')
-      .select('p.*, COUNT(o.id) as orderCount')
-      .groupBy('p.id')
-      .orderBy('orderCount', 'DESC')
-      .limit(20)
-      .getMany();
-  }
-}
-
-// Cache everything without thought
-@Injectable()
-export class UsersService {
-  @CacheKey('users')
-  @CacheTTL(3600)
-  @UseInterceptors(CacheInterceptor)
-  async findAll(): Promise<User[]> {
-    // Caching user list for 1 hour is wrong if data changes frequently
-    return this.usersRepo.find();
-  }
-}
-```
-
-**Correct (strategic caching with proper invalidation):**
-
-```typescript
-// Setup caching module
-@Module({
-  imports: [
-    CacheModule.registerAsync({
-      imports: [ConfigModule],
-      inject: [ConfigService],
-      useFactory: (config: ConfigService) => ({
-        stores: [new KeyvRedis(config.get('REDIS_URL'))],
-        ttl: 60 * 1000, // Default 60s
-      }),
-    }),
-  ],
-})
-export class AppModule {}
-
-// Manual caching for granular control
-@Injectable()
-export class ProductsService {
-  constructor(
-    @Inject(CACHE_MANAGER) private cache: Cache,
-    private productsRepo: ProductRepository
-  ) {}
-
-  async getPopular(): Promise<Product[]> {
-    const cacheKey = 'products:popular';
-
-    // Try cache first
-    const cached = await this.cache.get<Product[]>(cacheKey);
-    if (cached) return cached;
-
-    // Cache miss - fetch and cache
-    const products = await this.fetchPopularProducts();
-    await this.cache.set(cacheKey, products, 5 * 60 * 1000); // 5 min TTL
-    return products;
-  }
-
-  // Invalidate cache on changes
-  async updateProduct(id: string, dto: UpdateProductDto): Promise<Product> {
-    const product = await this.productsRepo.save({ id, ...dto });
-    await this.cache.del('products:popular'); // Invalidate
-    return product;
-  }
-}
-
-// Decorator-based caching with auto-interceptor
-@Controller('categories')
-@UseInterceptors(CacheInterceptor)
-export class CategoriesController {
-  @Get()
-  @CacheTTL(30 * 60 * 1000) // 30 minutes - categories rarely change
-  findAll(): Promise<Category[]> {
-    return this.categoriesService.findAll();
-  }
-
-  @Get(':id')
-  @CacheTTL(60 * 1000) // 1 minute
-  @CacheKey('category')
-  findOne(@Param('id') id: string): Promise<Category> {
-    return this.categoriesService.findOne(id);
-  }
-}
-
-// Event-based cache invalidation
-@Injectable()
-export class CacheInvalidationService {
-  constructor(@Inject(CACHE_MANAGER) private cache: Cache) {}
-
-  @OnEvent('product.created')
-  @OnEvent('product.updated')
-  @OnEvent('product.deleted')
-  async invalidateProductCaches(event: ProductEvent) {
-    await Promise.all([this.cache.del('products:popular'), this.cache.del(`product:${event.productId}`)]);
-  }
-}
-```
-
-Reference: [NestJS Caching](https://docs.nestjs.com/techniques/caching)
@@ -1,146 +0,0 @@
---
-title: Implement Secure JWT Authentication
-impact: CRITICAL
-impactDescription: Essential for secure APIs
-tags: security, jwt, authentication, tokens
---
-
-## Implement Secure JWT Authentication
-
-Use `@nestjs/jwt` with `@nestjs/passport` for authentication. Store secrets securely, use appropriate token lifetimes, implement refresh tokens, and validate tokens properly. Never expose sensitive data in JWT payloads.
-
-**Incorrect (insecure JWT implementation):**
-
-```typescript
-// Hardcode secrets
-@Module({
-  imports: [
-    JwtModule.register({
-      secret: 'my-secret-key', // Exposed in code
-      signOptions: { expiresIn: '7d' }, // Too long
-    }),
-  ],
-})
-export class AuthModule {}
-
-// Store sensitive data in JWT
-async login(user: User): Promise<{ accessToken: string }> {
-  const payload = {
-    sub: user.id,
-    email: user.email,
-    password: user.password, // NEVER include password!
-    ssn: user.ssn, // NEVER include sensitive data!
-    isAdmin: user.isAdmin, // Can be tampered if not verified
-  };
-  return { accessToken: this.jwtService.sign(payload) };
-}
-
-// Skip token validation
-@Injectable()
-export class JwtStrategy extends PassportStrategy(Strategy) {
-  constructor() {
-    super({
-      jwtFromRequest: ExtractJwt.fromAuthHeaderAsBearerToken(),
-      secretOrKey: 'my-secret',
-    });
-  }
-
-  async validate(payload: any): Promise<any> {
-    return payload; // No validation of user existence
-  }
-}
-```
-
-**Correct (secure JWT with refresh tokens):**
-
-```typescript
-// Secure JWT configuration
-@Module({
-  imports: [
-    JwtModule.registerAsync({
-      imports: [ConfigModule],
-      inject: [ConfigService],
-      useFactory: (config: ConfigService) => ({
-        secret: config.get<string>('JWT_SECRET'),
-        signOptions: {
-          expiresIn: '15m', // Short-lived access tokens
-          issuer: config.get<string>('JWT_ISSUER'),
-          audience: config.get<string>('JWT_AUDIENCE'),
-        },
-      }),
-    }),
-    PassportModule.register({ defaultStrategy: 'jwt' }),
-  ],
-})
-export class AuthModule {}
-
-// Minimal JWT payload
-@Injectable()
-export class AuthService {
-  async login(user: User): Promise<TokenResponse> {
-    // Only include necessary, non-sensitive data
-    const payload: JwtPayload = {
-      sub: user.id,
-      email: user.email,
-      roles: user.roles,
-      iat: Math.floor(Date.now() / 1000),
-    };
-
-    const accessToken = this.jwtService.sign(payload);
-    const refreshToken = await this.createRefreshToken(user.id);
-
-    return { accessToken, refreshToken, expiresIn: 900 };
-  }
-
-  private async createRefreshToken(userId: string): Promise<string> {
-    const token = randomBytes(32).toString('hex');
-    const hashedToken = await bcrypt.hash(token, 10);
-
-    await this.refreshTokenRepo.save({
-      userId,
-      token: hashedToken,
-      expiresAt: new Date(Date.now() + 7 * 24 * 60 * 60 * 1000), // 7 days
-    });
-
-    return token;
-  }
-}
-
-// Proper JWT strategy with validation
-@Injectable()
-export class JwtStrategy extends PassportStrategy(Strategy) {
-  constructor(
-    private config: ConfigService,
-    private usersService: UsersService
-  ) {
-    super({
-      jwtFromRequest: ExtractJwt.fromAuthHeaderAsBearerToken(),
-      secretOrKey: config.get<string>('JWT_SECRET'),
-      ignoreExpiration: false,
-      issuer: config.get<string>('JWT_ISSUER'),
-      audience: config.get<string>('JWT_AUDIENCE'),
-    });
-  }
-
-  async validate(payload: JwtPayload): Promise<User> {
-    // Verify user still exists and is active
-    const user = await this.usersService.findById(payload.sub);
-
-    if (!user || !user.isActive) {
-      throw new UnauthorizedException('User not found or inactive');
-    }
-
-    // Verify token wasn't issued before password change
-    if (user.passwordChangedAt) {
-      const tokenIssuedAt = new Date(payload.iat * 1000);
-      if (tokenIssuedAt < user.passwordChangedAt) {
-        throw new UnauthorizedException('Token invalidated by password change');
-      }
-    }
-
-    return user;
-  }
-}
-```
-
-Reference: [NestJS Authentication](https://docs.nestjs.com/security/authentication)
@@ -1,137 +0,0 @@
---
-title: Two-Phase File Upload + ClamAV (ADR-016)
-impact: CRITICAL
-impactDescription: Upload → Temp → ClamAV scan → Commit → Permanent. Whitelist + 50MB cap. StorageService only.
-tags: file-upload, clamav, security, adr-016, storage
---
-
-## Two-Phase File Upload (ADR-016)
-
-**Never write uploaded files directly to permanent storage.** All uploads must go through:
-
-```
-Client → Upload endpoint → Temp storage → ClamAV scan → Commit endpoint → Permanent storage
-```
-
---
-
-## Constraints (non-negotiable)
-
-| Rule | Value |
-| --- | --- |
-| Allowed MIME types | `application/pdf`, `image/vnd.dwg`, `application/vnd.openxmlformats-officedocument.wordprocessingml.document`, `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`, `application/zip` |
-| Allowed extensions | `.pdf`, `.dwg`, `.docx`, `.xlsx`, `.zip` |
-| Max size | 50 MB |
-| Temp TTL | 24 h (purged by cron) |
-| Virus scan | ClamAV (blocking) |
-| Mover | `StorageService` only — never `fs.rename` directly from controller |
-
---
-
-## Phase 1: Upload to Temp
-
-```typescript
-@Post('upload')
-@UseGuards(JwtAuthGuard, ThrottlerGuard)
-@UseInterceptors(FileInterceptor('file', {
-  limits: { fileSize: 50 * 1024 * 1024 }, // 50 MB
-}))
-async uploadTemp(
-  @UploadedFile() file: Express.Multer.File,
-  @CurrentUser() user: User,
-): Promise<{ tempId: string; expiresAt: string }> {
-  // 1. Validate MIME + extension (defense in depth)
-  this.fileValidator.assertAllowed(file);
-
-  // 2. Scan with ClamAV
-  const scanResult = await this.clamavService.scan(file.buffer);
-  if (!scanResult.clean) {
-    throw new BusinessException(
-      `ClamAV rejected: ${scanResult.signature}`,
-      'ไฟล์ไม่ปลอดภัย ระบบตรวจพบความเสี่ยง',
-      'กรุณาตรวจสอบไฟล์และลองใหม่อีกครั้ง',
-      'FILE_INFECTED',
-    );
-  }
-
-  // 3. Save to temp (encrypted at rest)
-  const tempId = await this.storageService.saveToTemp(file, user.id);
-
-  return {
-    tempId,
-    expiresAt: addHours(new Date(), 24).toISOString(),
-  };
-}
-```
-
---
-
-## Phase 2: Commit in Transaction
-
-The business operation (e.g., creating a Correspondence) promotes temp files to permanent **in the same DB transaction**.
-
-```typescript
-async createCorrespondence(dto: CreateCorrespondenceDto, user: User) {
-  return this.dataSource.transaction(async (manager) => {
-    // 1. Create domain entity
-    const entity = await manager.save(Correspondence, {
-      ...dto,
-      createdById: user.id,
-    });
-
-    // 2. Commit temp files → permanent (ACID together with entity)
-    await this.storageService.commitFiles(
-      dto.tempFileIds,
-      { entityId: entity.id, entityType: 'correspondence' },
-      manager,
-    );
-
-    return entity;
-  });
-}
-```
-
-If the transaction rolls back, temp files remain and expire in 24h — no orphaned permanent files.
-
---
-
-## StorageService Contract
-
-```typescript
-export interface StorageService {
-  saveToTemp(file: Express.Multer.File, ownerId: number): Promise<string>;
-  commitFiles(
-    tempIds: string[],
-    target: { entityId: number; entityType: string },
-    manager: EntityManager,
-  ): Promise<FileRecord[]>;
-  purgeExpiredTemp(): Promise<number>; // called by cron
-  getPermanentPath(fileId: number): Promise<string>;
-}
-```
-
---
-
-## ❌ Forbidden
-
-```typescript
-// ❌ Direct write to permanent
-fs.writeFileSync(`/var/storage/${file.originalname}`, file.buffer);
-
-// ❌ Skip ClamAV
-await this.storageService.savePermanent(file);
-
-// ❌ Non-whitelist MIME
-@UseInterceptors(FileInterceptor('file')) // no size or type limit
-
-// ❌ Commit outside transaction
-const entity = await this.repo.save(...);
-await this.storageService.commitFiles(tempIds, ...); // race: entity exists, files may fail
-```
-
---
-
-## Reference
-
- [ADR-016 Security & Authentication](../../../../specs/06-Decision-Records/ADR-016-security-authentication.md)
- [Edge Cases](../../../../specs/01-Requirements/01-06-edge-cases-and-rules.md) — file upload scenarios
@@ -1,125 +0,0 @@
---
-title: Implement Rate Limiting
-impact: HIGH
-impactDescription: Protects against abuse and ensures fair resource usage
-tags: security, rate-limiting, throttler, protection
---
-
-## Implement Rate Limiting
-
-Use `@nestjs/throttler` to limit request rates per client. Apply different limits for different endpoints - stricter for auth endpoints, more relaxed for read operations. Consider using Redis for distributed rate limiting in clustered deployments.
-
-**Incorrect (no rate limiting on sensitive endpoints):**
-
-```typescript
-// No rate limiting on sensitive endpoints
-@Controller('auth')
-export class AuthController {
-  @Post('login')
-  async login(@Body() dto: LoginDto): Promise<TokenResponse> {
-    // Attackers can brute-force credentials
-    return this.authService.login(dto);
-  }
-
-  @Post('forgot-password')
-  async forgotPassword(@Body() dto: ForgotPasswordDto): Promise<void> {
-    // Can be abused to spam users with emails
-    return this.authService.sendResetEmail(dto.email);
-  }
-}
-
-// Same limits for all endpoints
-@UseGuards(ThrottlerGuard)
-@Controller('api')
-export class ApiController {
-  @Get('public-data')
-  async getPublic() {} // Should allow more requests
-
-  @Post('process-payment')
-  async payment() {} // Should be more restrictive
-}
-```
-
-**Correct (configured throttler with endpoint-specific limits):**
-
-```typescript
-// Configure throttler globally with multiple limits
-import { ThrottlerModule, ThrottlerGuard } from '@nestjs/throttler';
-
-@Module({
-  imports: [
-    ThrottlerModule.forRoot([
-      {
-        name: 'short',
-        ttl: 1000, // 1 second
-        limit: 3, // 3 requests per second
-      },
-      {
-        name: 'medium',
-        ttl: 10000, // 10 seconds
-        limit: 20, // 20 requests per 10 seconds
-      },
-      {
-        name: 'long',
-        ttl: 60000, // 1 minute
-        limit: 100, // 100 requests per minute
-      },
-    ]),
-  ],
-  providers: [
-    {
-      provide: APP_GUARD,
-      useClass: ThrottlerGuard,
-    },
-  ],
-})
-export class AppModule {}
-
-// Override limits per endpoint
-@Controller('auth')
-export class AuthController {
-  @Post('login')
-  @Throttle({ short: { limit: 5, ttl: 60000 } }) // 5 attempts per minute
-  async login(@Body() dto: LoginDto): Promise<TokenResponse> {
-    return this.authService.login(dto);
-  }
-
-  @Post('forgot-password')
-  @Throttle({ short: { limit: 3, ttl: 3600000 } }) // 3 per hour
-  async forgotPassword(@Body() dto: ForgotPasswordDto): Promise<void> {
-    return this.authService.sendResetEmail(dto.email);
-  }
-}
-
-// Skip throttling for certain routes
-@Controller('health')
-export class HealthController {
-  @Get()
-  @SkipThrottle()
-  check(): string {
-    return 'OK';
-  }
-}
-
-// Custom throttle per user type
-@Injectable()
-export class CustomThrottlerGuard extends ThrottlerGuard {
-  protected async getTracker(req: Request): Promise<string> {
-    // Use user ID if authenticated, IP otherwise
-    return req.user?.id || req.ip;
-  }
-
-  protected async getLimit(context: ExecutionContext): Promise<number> {
-    const request = context.switchToHttp().getRequest();
-
-    // Higher limits for authenticated users
-    if (request.user) {
-      return request.user.isPremium ? 1000 : 200;
-    }
-
-    return 50; // Anonymous users
-  }
-}
-```
-
-Reference: [NestJS Throttler](https://docs.nestjs.com/security/rate-limiting)
@@ -1,139 +0,0 @@
---
-title: Sanitize Output to Prevent XSS
-impact: HIGH
-impactDescription: XSS vulnerabilities can compromise user sessions and data
-tags: security, xss, sanitization, html
---
-
-## Sanitize Output to Prevent XSS
-
-While NestJS APIs typically return JSON (which browsers don't execute), XSS risks exist when rendering HTML, storing user content, or when frontend frameworks improperly handle API responses. Sanitize user-generated content before storage and use proper Content-Type headers.
-
-**Incorrect (storing raw HTML without sanitization):**
-
-```typescript
-// Store raw HTML from users
-@Injectable()
-export class CommentsService {
-  async create(dto: CreateCommentDto): Promise<Comment> {
-    // User can inject: <script>steal(document.cookie)</script>
-    return this.repo.save({
-      content: dto.content, // Raw, unsanitized
-      authorId: dto.authorId,
-    });
-  }
-}
-
-// Return HTML without sanitization
-@Controller('pages')
-export class PagesController {
-  @Get(':slug')
-  @Header('Content-Type', 'text/html')
-  async getPage(@Param('slug') slug: string): Promise<string> {
-    const page = await this.pagesService.findBySlug(slug);
-    // If page.content contains user input, XSS is possible
-    return `<html><body>${page.content}</body></html>`;
-  }
-}
-
-// Reflect user input in errors
-@Get(':id')
-async findOne(@Param('id') id: string): Promise<User> {
-  const user = await this.repo.findOne({ where: { id } });
-  if (!user) {
-    // XSS if id contains malicious content and error is rendered
-    throw new NotFoundException(`User ${id} not found`);
-  }
-  return user;
-}
-```
-
-**Correct (sanitize content and use proper headers):**
-
-```typescript
-// Sanitize HTML content before storage
-import * as sanitizeHtml from 'sanitize-html';
-
-@Injectable()
-export class CommentsService {
-  private readonly sanitizeOptions: sanitizeHtml.IOptions = {
-    allowedTags: ['b', 'i', 'em', 'strong', 'a', 'p', 'br'],
-    allowedAttributes: {
-      a: ['href', 'title'],
-    },
-    allowedSchemes: ['http', 'https', 'mailto'],
-  };
-
-  async create(dto: CreateCommentDto): Promise<Comment> {
-    return this.repo.save({
-      content: sanitizeHtml(dto.content, this.sanitizeOptions),
-      authorId: dto.authorId,
-    });
-  }
-}
-
-// Use validation pipe to strip HTML
-import { Transform } from 'class-transformer';
-
-export class CreatePostDto {
-  @IsString()
-  @MaxLength(1000)
-  @Transform(({ value }) => sanitizeHtml(value, { allowedTags: [] }))
-  title: string;
-
-  @IsString()
-  @Transform(({ value }) =>
-    sanitizeHtml(value, {
-      allowedTags: ['p', 'br', 'b', 'i', 'a'],
-      allowedAttributes: { a: ['href'] },
-    }),
-  )
-  content: string;
-}
-
-// Set proper Content-Type headers
-@Controller('api')
-export class ApiController {
-  @Get('data')
-  @Header('Content-Type', 'application/json')
-  async getData(): Promise<DataResponse> {
-    // JSON response - browser won't execute scripts
-    return this.service.getData();
-  }
-}
-
-// Sanitize error messages
-@Get(':id')
-async findOne(@Param('id', ParseUUIDPipe) id: string): Promise<User> {
-  const user = await this.repo.findOne({ where: { id } });
-  if (!user) {
-    // UUID validation ensures safe format
-    throw new NotFoundException('User not found');
-  }
-  return user;
-}
-
-// Use Helmet for CSP headers
-import helmet from 'helmet';
-
-async function bootstrap() {
-  const app = await NestFactory.create(AppModule);
-
-  app.use(
-    helmet({
-      contentSecurityPolicy: {
-        directives: {
-          defaultSrc: ["'self'"],
-          scriptSrc: ["'self'"],
-          styleSrc: ["'self'", "'unsafe-inline'"],
-          imgSrc: ["'self'", 'data:', 'https:'],
-        },
-      },
-    }),
-  );
-
-  await app.listen(3000);
-}
-```
-
-Reference: [OWASP XSS Prevention](https://cheatsheetseries.owasp.org/cheatsheets/Cross_Site_Scripting_Prevention_Cheat_Sheet.html)
@@ -1,129 +0,0 @@
---
-title: Use Guards for Authentication and Authorization
-impact: HIGH
-impactDescription: Enforces access control before handlers execute
-tags: security, guards, authentication, authorization
---
-
-## Use Guards for Authentication and Authorization
-
-Guards determine whether a request should be handled based on authentication state, roles, permissions, or other conditions. They run after middleware but before pipes and interceptors, making them ideal for access control. Use guards instead of manual checks in controllers.
-
-**Incorrect (manual auth checks in every handler):**
-
-```typescript
-// Manual auth checks in every handler
-@Controller('admin')
-export class AdminController {
-  @Get('users')
-  async getUsers(@Request() req) {
-    if (!req.user) {
-      throw new UnauthorizedException();
-    }
-    if (!req.user.roles.includes('admin')) {
-      throw new ForbiddenException();
-    }
-    return this.adminService.getUsers();
-  }
-
-  @Delete('users/:id')
-  async deleteUser(@Request() req, @Param('id') id: string) {
-    if (!req.user) {
-      throw new UnauthorizedException();
-    }
-    if (!req.user.roles.includes('admin')) {
-      throw new ForbiddenException();
-    }
-    return this.adminService.deleteUser(id);
-  }
-}
-```
-
-**Correct (guards with declarative decorators):**
-
-```typescript
-// JWT Auth Guard
-@Injectable()
-export class JwtAuthGuard implements CanActivate {
-  constructor(
-    private jwtService: JwtService,
-    private reflector: Reflector
-  ) {}
-
-  async canActivate(context: ExecutionContext): Promise<boolean> {
-    // Check for @Public() decorator
-    const isPublic = this.reflector.getAllAndOverride<boolean>('isPublic', [context.getHandler(), context.getClass()]);
-    if (isPublic) return true;
-
-    const request = context.switchToHttp().getRequest();
-    const token = this.extractToken(request);
-
-    if (!token) {
-      throw new UnauthorizedException('No token provided');
-    }
-
-    try {
-      request.user = await this.jwtService.verifyAsync(token);
-      return true;
-    } catch {
-      throw new UnauthorizedException('Invalid token');
-    }
-  }
-
-  private extractToken(request: Request): string | undefined {
-    const [type, token] = request.headers.authorization?.split(' ') ?? [];
-    return type === 'Bearer' ? token : undefined;
-  }
-}
-
-// Roles Guard
-@Injectable()
-export class RolesGuard implements CanActivate {
-  constructor(private reflector: Reflector) {}
-
-  canActivate(context: ExecutionContext): boolean {
-    const requiredRoles = this.reflector.getAllAndOverride<Role[]>('roles', [context.getHandler(), context.getClass()]);
-
-    if (!requiredRoles) return true;
-
-    const { user } = context.switchToHttp().getRequest();
-    return requiredRoles.some((role) => user.roles?.includes(role));
-  }
-}
-
-// Decorators
-export const Public = () => SetMetadata('isPublic', true);
-export const Roles = (...roles: Role[]) => SetMetadata('roles', roles);
-
-// Register guards globally
-@Module({
-  providers: [
-    { provide: APP_GUARD, useClass: JwtAuthGuard },
-    { provide: APP_GUARD, useClass: RolesGuard },
-  ],
-})
-export class AppModule {}
-
-// Clean controller
-@Controller('admin')
-@Roles(Role.Admin) // Applied to all routes
-export class AdminController {
-  @Get('users')
-  getUsers(): Promise<User[]> {
-    return this.adminService.getUsers();
-  }
-
-  @Delete('users/:id')
-  deleteUser(@Param('id') id: string): Promise<void> {
-    return this.adminService.deleteUser(id);
-  }
-
-  @Public() // Override: no auth required
-  @Get('health')
-  health() {
-    return { status: 'ok' };
-  }
-}
-```
-
-Reference: [NestJS Guards](https://docs.nestjs.com/guards)
@@ -1,150 +0,0 @@
---
-title: Validate All Input with DTOs and Pipes
-impact: HIGH
-impactDescription: First line of defense against attacks
-tags: security, validation, dto, pipes
---
-
-## Validate All Input with DTOs and Pipes
-
-Always validate incoming data using class-validator decorators on DTOs and the global ValidationPipe. Never trust user input. Validate all request bodies, query parameters, and route parameters before processing.
-
-**Incorrect (trust raw input without validation):**
-
-```typescript
-// Trust raw input without validation
-@Controller('users')
-export class UsersController {
-  @Post()
-  create(@Body() body: any) {
-    // body could contain anything - SQL injection, XSS, etc.
-    return this.usersService.create(body);
-  }
-
-  @Get()
-  findAll(@Query() query: any) {
-    // query.limit could be "'; DROP TABLE users; --"
-    return this.usersService.findAll(query.limit);
-  }
-}
-
-// DTOs without validation decorators
-export class CreateUserDto {
-  name: string; // No validation
-  email: string; // Could be "not-an-email"
-  age: number; // Could be "abc" or -999
-}
-```
-
-**Correct (validated DTOs with global ValidationPipe):**
-
-```typescript
-// Enable ValidationPipe globally in main.ts
-async function bootstrap() {
-  const app = await NestFactory.create(AppModule);
-
-  app.useGlobalPipes(
-    new ValidationPipe({
-      whitelist: true, // Strip unknown properties
-      forbidNonWhitelisted: true, // Throw on unknown properties
-      transform: true, // Auto-transform to DTO types
-      transformOptions: {
-        enableImplicitConversion: true,
-      },
-    })
-  );
-
-  await app.listen(3000);
-}
-
-// Create well-validated DTOs
-import {
-  IsString,
-  IsEmail,
-  IsInt,
-  Min,
-  Max,
-  IsOptional,
-  MinLength,
-  MaxLength,
-  Matches,
-  IsNotEmpty,
-} from 'class-validator';
-import { Transform, Type } from 'class-transformer';
-
-export class CreateUserDto {
-  @IsString()
-  @IsNotEmpty()
-  @MinLength(2)
-  @MaxLength(100)
-  @Transform(({ value }) => value?.trim())
-  name: string;
-
-  @IsEmail()
-  @Transform(({ value }) => value?.toLowerCase().trim())
-  email: string;
-
-  @IsInt()
-  @Min(0)
-  @Max(150)
-  age: number;
-
-  @IsString()
-  @MinLength(8)
-  @MaxLength(100)
-  @Matches(/^(?=.*[a-z])(?=.*[A-Z])(?=.*\d)/, {
-    message: 'Password must contain uppercase, lowercase, and number',
-  })
-  password: string;
-}
-
-// Query DTO with defaults and transformation
-export class FindUsersQueryDto {
-  @IsOptional()
-  @IsString()
-  @MaxLength(100)
-  search?: string;
-
-  @IsOptional()
-  @Type(() => Number)
-  @IsInt()
-  @Min(1)
-  @Max(100)
-  limit: number = 20;
-
-  @IsOptional()
-  @Type(() => Number)
-  @IsInt()
-  @Min(0)
-  offset: number = 0;
-}
-
-// Param validation
-export class UserIdParamDto {
-  @IsUUID('4')
-  id: string;
-}
-
-@Controller('users')
-export class UsersController {
-  @Post()
-  create(@Body() dto: CreateUserDto): Promise<User> {
-    // dto is guaranteed to be valid
-    return this.usersService.create(dto);
-  }
-
-  @Get()
-  findAll(@Query() query: FindUsersQueryDto): Promise<User[]> {
-    // query.limit is a number, query.search is sanitized
-    return this.usersService.findAll(query);
-  }
-
-  @Get(':id')
-  findOne(@Param() params: UserIdParamDto): Promise<User> {
-    // params.id is a valid UUID
-    return this.usersService.findById(params.id);
-  }
-}
-```
-
-Reference: [NestJS Validation](https://docs.nestjs.com/techniques/validation)
@@ -1,174 +0,0 @@
---
-title: Use Supertest for E2E Testing
-impact: HIGH
-impactDescription: Validates the full request/response cycle
-tags: testing, e2e, supertest, integration
---
-
-## Use Supertest for E2E Testing
-
-End-to-end tests use Supertest to make real HTTP requests against your NestJS application. They test the full stack including middleware, guards, pipes, and interceptors. E2E tests catch integration issues that unit tests miss.
-
-**Incorrect (no proper E2E setup or teardown):**
-
-```typescript
-// Only unit test controllers
-describe('UsersController', () => {
-  it('should return users', async () => {
-    const service = { findAll: jest.fn().mockResolvedValue([]) };
-    const controller = new UsersController(service as any);
-
-    const result = await controller.findAll();
-
-    expect(result).toEqual([]);
-    // Doesn't test: routes, guards, pipes, serialization
-  });
-});
-
-// E2E tests without proper setup/teardown
-describe('Users API', () => {
-  it('should create user', async () => {
-    const app = await NestFactory.create(AppModule);
-    // No proper initialization
-    // No cleanup after test
-    // Hits real database
-  });
-});
-```
-
-**Correct (proper E2E setup with Supertest):**
-
-```typescript
-// Proper E2E test setup
-import { Test, TestingModule } from '@nestjs/testing';
-import { INestApplication, ValidationPipe } from '@nestjs/common';
-import * as request from 'supertest';
-import { AppModule } from '../src/app.module';
-
-describe('UsersController (e2e)', () => {
-  let app: INestApplication;
-
-  beforeAll(async () => {
-    const moduleFixture: TestingModule = await Test.createTestingModule({
-      imports: [AppModule],
-    }).compile();
-
-    app = moduleFixture.createNestApplication();
-
-    // Apply same config as production
-    app.useGlobalPipes(
-      new ValidationPipe({
-        whitelist: true,
-        transform: true,
-        forbidNonWhitelisted: true,
-      })
-    );
-
-    await app.init();
-  });
-
-  afterAll(async () => {
-    await app.close();
-  });
-
-  describe('/users (POST)', () => {
-    it('should create a user', () => {
-      return request(app.getHttpServer())
-        .post('/users')
-        .send({ name: 'John', email: 'john@test.com' })
-        .expect(201)
-        .expect((res) => {
-          expect(res.body).toHaveProperty('id');
-          expect(res.body.name).toBe('John');
-          expect(res.body.email).toBe('john@test.com');
-        });
-    });
-
-    it('should return 400 for invalid email', () => {
-      return request(app.getHttpServer())
-        .post('/users')
-        .send({ name: 'John', email: 'invalid-email' })
-        .expect(400)
-        .expect((res) => {
-          expect(res.body.message).toContain('email');
-        });
-    });
-  });
-
-  describe('/users/:id (GET)', () => {
-    it('should return 404 for non-existent user', () => {
-      return request(app.getHttpServer()).get('/users/non-existent-id').expect(404);
-    });
-  });
-});
-
-// Testing with authentication
-describe('Protected Routes (e2e)', () => {
-  let app: INestApplication;
-  let authToken: string;
-
-  beforeAll(async () => {
-    const moduleFixture = await Test.createTestingModule({
-      imports: [AppModule],
-    }).compile();
-
-    app = moduleFixture.createNestApplication();
-    app.useGlobalPipes(new ValidationPipe({ whitelist: true }));
-    await app.init();
-
-    // Get auth token
-    const loginResponse = await request(app.getHttpServer())
-      .post('/auth/login')
-      .send({ email: 'test@test.com', password: 'password' });
-
-    authToken = loginResponse.body.accessToken;
-  });
-
-  it('should return 401 without token', () => {
-    return request(app.getHttpServer()).get('/users/me').expect(401);
-  });
-
-  it('should return user profile with valid token', () => {
-    return request(app.getHttpServer())
-      .get('/users/me')
-      .set('Authorization', `Bearer ${authToken}`)
-      .expect(200)
-      .expect((res) => {
-        expect(res.body.email).toBe('test@test.com');
-      });
-  });
-});
-
-// Database isolation for E2E tests
-describe('Orders API (e2e)', () => {
-  let app: INestApplication;
-  let dataSource: DataSource;
-
-  beforeAll(async () => {
-    const moduleFixture = await Test.createTestingModule({
-      imports: [
-        ConfigModule.forRoot({
-          envFilePath: '.env.test', // Test database config
-        }),
-        AppModule,
-      ],
-    }).compile();
-
-    app = moduleFixture.createNestApplication();
-    dataSource = moduleFixture.get(DataSource);
-    await app.init();
-  });
-
-  beforeEach(async () => {
-    // Clean database between tests
-    await dataSource.synchronize(true);
-  });
-
-  afterAll(async () => {
-    await dataSource.destroy();
-    await app.close();
-  });
-});
-```
-
-Reference: [NestJS E2E Testing](https://docs.nestjs.com/fundamentals/testing#end-to-end-testing)
@@ -1,174 +0,0 @@
---
-title: Mock External Services in Tests
-impact: HIGH
-impactDescription: Ensures fast, reliable, deterministic tests
-tags: testing, mocking, external-services, jest
---
-
-## Mock External Services in Tests
-
-Never call real external services (APIs, databases, message queues) in unit tests. Mock them to ensure tests are fast, deterministic, and don't incur costs. Use realistic mock data and test edge cases like timeouts and errors.
-
-**Incorrect (calling real APIs and databases):**
-
-```typescript
-// Call real APIs in tests
-describe('PaymentService', () => {
-  it('should process payment', async () => {
-    const service = new PaymentService(new StripeClient(realApiKey));
-    // Hits real Stripe API!
-    const result = await service.charge('tok_visa', 1000);
-    // Slow, costs money, flaky
-  });
-});
-
-// Use real database
-describe('UsersService', () => {
-  beforeEach(async () => {
-    await connection.query('DELETE FROM users'); // Modifies real DB
-  });
-
-  it('should create user', async () => {
-    const user = await service.create({ email: 'test@test.com' });
-    // Side effects on shared database
-  });
-});
-
-// Incomplete mocks
-const mockHttpService = {
-  get: jest.fn().mockResolvedValue({ data: {} }),
-  // Missing error scenarios, missing other methods
-};
-```
-
-**Correct (mock all external dependencies):**
-
-```typescript
-// Mock HTTP service properly
-describe('WeatherService', () => {
-  let service: WeatherService;
-  let httpService: jest.Mocked<HttpService>;
-
-  beforeEach(async () => {
-    const module = await Test.createTestingModule({
-      providers: [
-        WeatherService,
-        {
-          provide: HttpService,
-          useValue: {
-            get: jest.fn(),
-            post: jest.fn(),
-          },
-        },
-      ],
-    }).compile();
-
-    service = module.get(WeatherService);
-    httpService = module.get(HttpService);
-  });
-
-  it('should return weather data', async () => {
-    const mockResponse = {
-      data: { temperature: 72, humidity: 45 },
-      status: 200,
-      statusText: 'OK',
-      headers: {},
-      config: {},
-    };
-
-    httpService.get.mockReturnValue(of(mockResponse));
-
-    const result = await service.getWeather('NYC');
-
-    expect(result).toEqual({ temperature: 72, humidity: 45 });
-  });
-
-  it('should handle API timeout', async () => {
-    httpService.get.mockReturnValue(throwError(() => new Error('ETIMEDOUT')));
-
-    await expect(service.getWeather('NYC')).rejects.toThrow('Weather service unavailable');
-  });
-
-  it('should handle rate limiting', async () => {
-    httpService.get.mockReturnValue(
-      throwError(() => ({
-        response: { status: 429, data: { message: 'Rate limited' } },
-      }))
-    );
-
-    await expect(service.getWeather('NYC')).rejects.toThrow(TooManyRequestsException);
-  });
-});
-
-// Mock repository instead of database
-describe('UsersService', () => {
-  let service: UsersService;
-  let repo: jest.Mocked<Repository<User>>;
-
-  beforeEach(async () => {
-    const mockRepo = {
-      find: jest.fn(),
-      findOne: jest.fn(),
-      save: jest.fn(),
-      delete: jest.fn(),
-      createQueryBuilder: jest.fn(),
-    };
-
-    const module = await Test.createTestingModule({
-      providers: [UsersService, { provide: getRepositoryToken(User), useValue: mockRepo }],
-    }).compile();
-
-    service = module.get(UsersService);
-    repo = module.get(getRepositoryToken(User));
-  });
-
-  it('should find user by id', async () => {
-    const mockUser = { id: '1', name: 'John', email: 'john@test.com' };
-    repo.findOne.mockResolvedValue(mockUser);
-
-    const result = await service.findById('1');
-
-    expect(result).toEqual(mockUser);
-    expect(repo.findOne).toHaveBeenCalledWith({ where: { id: '1' } });
-  });
-});
-
-// Create mock factory for complex SDKs
-function createMockStripe(): jest.Mocked<Stripe> {
-  return {
-    paymentIntents: {
-      create: jest.fn(),
-      retrieve: jest.fn(),
-      confirm: jest.fn(),
-      cancel: jest.fn(),
-    },
-    customers: {
-      create: jest.fn(),
-      retrieve: jest.fn(),
-    },
-  } as any;
-}
-
-// Mock time for time-dependent tests
-describe('TokenService', () => {
-  beforeEach(() => {
-    jest.useFakeTimers();
-    jest.setSystemTime(new Date('2024-01-15'));
-  });
-
-  afterEach(() => {
-    jest.useRealTimers();
-  });
-
-  it('should expire token after 1 hour', async () => {
-    const token = await service.createToken();
-
-    // Fast-forward time
-    jest.advanceTimersByTime(61 * 60 * 1000);
-
-    expect(await service.isValid(token)).toBe(false);
-  });
-});
-```
-
-Reference: [Jest Mocking](https://jestjs.io/docs/mock-functions)
@@ -1,151 +0,0 @@
---
-title: Use Testing Module for Unit Tests
-impact: HIGH
-impactDescription: Enables proper isolated testing with mocked dependencies
-tags: testing, unit-tests, mocking, jest
---
-
-## Use Testing Module for Unit Tests
-
-Use `@nestjs/testing` module to create isolated test environments with mocked dependencies. This ensures your tests run fast, don't depend on external services, and properly test your business logic in isolation.
-
-**Incorrect (manual instantiation bypassing DI):**
-
-```typescript
-// Instantiate services manually without DI
-describe('UsersService', () => {
-  it('should create user', async () => {
-    // Manual instantiation bypasses DI
-    const repo = new UserRepository(); // Real repo!
-    const service = new UsersService(repo);
-
-    const user = await service.create({ name: 'Test' });
-    // This hits the real database!
-  });
-});
-
-// Test implementation details
-describe('UsersController', () => {
-  it('should call service', async () => {
-    const service = { create: jest.fn() };
-    const controller = new UsersController(service as any);
-
-    await controller.create({ name: 'Test' });
-
-    expect(service.create).toHaveBeenCalled(); // Tests implementation, not behavior
-  });
-});
-```
-
-**Correct (use Test.createTestingModule with mocked dependencies):**
-
-```typescript
-// Use Test.createTestingModule for proper DI
-import { Test, TestingModule } from '@nestjs/testing';
-
-describe('UsersService', () => {
-  let service: UsersService;
-  let repo: jest.Mocked<UserRepository>;
-
-  beforeEach(async () => {
-    const module: TestingModule = await Test.createTestingModule({
-      providers: [
-        UsersService,
-        {
-          provide: UserRepository,
-          useValue: {
-            save: jest.fn(),
-            findOne: jest.fn(),
-            find: jest.fn(),
-          },
-        },
-      ],
-    }).compile();
-
-    service = module.get<UsersService>(UsersService);
-    repo = module.get(UserRepository);
-  });
-
-  afterEach(() => {
-    jest.clearAllMocks();
-  });
-
-  describe('create', () => {
-    it('should save and return user', async () => {
-      const dto = { name: 'John', email: 'john@test.com' };
-      const expectedUser = { id: '1', ...dto };
-
-      repo.save.mockResolvedValue(expectedUser);
-
-      const result = await service.create(dto);
-
-      expect(result).toEqual(expectedUser);
-      expect(repo.save).toHaveBeenCalledWith(dto);
-    });
-
-    it('should throw on duplicate email', async () => {
-      repo.findOne.mockResolvedValue({ id: '1', email: 'test@test.com' });
-
-      await expect(service.create({ name: 'Test', email: 'test@test.com' })).rejects.toThrow(ConflictException);
-    });
-  });
-
-  describe('findById', () => {
-    it('should return user when found', async () => {
-      const user = { id: '1', name: 'John' };
-      repo.findOne.mockResolvedValue(user);
-
-      const result = await service.findById('1');
-
-      expect(result).toEqual(user);
-    });
-
-    it('should throw NotFoundException when not found', async () => {
-      repo.findOne.mockResolvedValue(null);
-
-      await expect(service.findById('999')).rejects.toThrow(NotFoundException);
-    });
-  });
-});
-
-// Testing guards and interceptors
-describe('RolesGuard', () => {
-  let guard: RolesGuard;
-  let reflector: Reflector;
-
-  beforeEach(async () => {
-    const module = await Test.createTestingModule({
-      providers: [RolesGuard, Reflector],
-    }).compile();
-
-    guard = module.get<RolesGuard>(RolesGuard);
-    reflector = module.get<Reflector>(Reflector);
-  });
-
-  it('should allow when no roles required', () => {
-    const context = createMockExecutionContext({ user: { roles: [] } });
-    jest.spyOn(reflector, 'getAllAndOverride').mockReturnValue(undefined);
-
-    expect(guard.canActivate(context)).toBe(true);
-  });
-
-  it('should allow admin for admin-only route', () => {
-    const context = createMockExecutionContext({ user: { roles: ['admin'] } });
-    jest.spyOn(reflector, 'getAllAndOverride').mockReturnValue(['admin']);
-
-    expect(guard.canActivate(context)).toBe(true);
-  });
-});
-
-function createMockExecutionContext(request: Partial<Request>): ExecutionContext {
-  return {
-    switchToHttp: () => ({
-      getRequest: () => request,
-    }),
-    getHandler: () => jest.fn(),
-    getClass: () => jest.fn(),
-  } as ExecutionContext;
-}
-```
-
-Reference: [NestJS Testing](https://docs.nestjs.com/fundamentals/testing)
@@ -1,301 +0,0 @@
-#!/usr/bin/env npx ts-node
-
-/**
- * Build script for generating AGENTS.md from individual rule files
- *
- * Usage: npx ts-node scripts/build-agents.ts
- *
- * This script:
- * 1. Reads all rule files from the rules/ directory
- * 2. Parses YAML frontmatter for metadata
- * 3. Groups rules by category based on filename prefix
- * 4. Generates a consolidated AGENTS.md file
- */
-
-import * as fs from 'fs';
-import * as path from 'path';
-import { fileURLToPath } from 'url';
-import { dirname } from 'path';
-
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = dirname(__filename);
-
-// Category definitions with ordering and metadata
-const CATEGORIES = [
-  { prefix: 'arch-', name: 'Architecture', impact: 'CRITICAL', section: 1 },
-  { prefix: 'di-', name: 'Dependency Injection', impact: 'CRITICAL', section: 2 },
-  { prefix: 'error-', name: 'Error Handling', impact: 'HIGH', section: 3 },
-  { prefix: 'security-', name: 'Security', impact: 'HIGH', section: 4 },
-  { prefix: 'perf-', name: 'Performance', impact: 'HIGH', section: 5 },
-  { prefix: 'test-', name: 'Testing', impact: 'MEDIUM-HIGH', section: 6 },
-  { prefix: 'db-', name: 'Database & ORM', impact: 'MEDIUM-HIGH', section: 7 },
-  { prefix: 'api-', name: 'API Design', impact: 'MEDIUM', section: 8 },
-  { prefix: 'micro-', name: 'Microservices', impact: 'MEDIUM', section: 9 },
-  { prefix: 'devops-', name: 'DevOps & Deployment', impact: 'LOW-MEDIUM', section: 10 },
-  { prefix: 'lcbp3-', name: 'LCBP3 Project-Specific', impact: 'CRITICAL', section: 11 },
-];
-
-interface RuleFrontmatter {
-  title: string;
-  impact: string;
-  impactDescription: string;
-  tags: string[];
-}
-
-interface Rule {
-  filename: string;
-  frontmatter: RuleFrontmatter;
-  content: string;
-  category: string;
-  categorySection: number;
-}
-
-function parseFrontmatter(content: string): { frontmatter: RuleFrontmatter | null; body: string } {
-  // Normalize CRLF → LF so the regex works on Windows-authored files
-  const normalized = content.replace(/\r\n/g, '\n');
-  const frontmatterRegex = /^---\n([\s\S]*?)\n---\n([\s\S]*)$/;
-  const match = normalized.match(frontmatterRegex);
-
-  if (!match) {
-    return { frontmatter: null, body: content };
-  }
-
-  const frontmatterStr = match[1];
-  const body = match[2];
-
-  // Simple YAML parsing for our expected format
-  const frontmatter: Partial<RuleFrontmatter> = {};
-  const lines = frontmatterStr.split('\n');
-  let currentKey = '';
-  let inArray = false;
-  const arrayItems: string[] = [];
-
-  for (const line of lines) {
-    if (line.match(/^[a-zA-Z]+:/)) {
-      // Save previous array if we were collecting one
-      if (inArray && currentKey === 'tags') {
-        frontmatter.tags = arrayItems;
-      }
-      inArray = false;
-      arrayItems.length = 0;
-
-      const [key, ...valueParts] = line.split(':');
-      const value = valueParts.join(':').trim();
-      currentKey = key.trim();
-
-      if (value === '') {
-        // Might be start of array
-        inArray = true;
-      } else {
-        (frontmatter as any)[currentKey] = value;
-      }
-    } else if (inArray && line.trim().startsWith('-')) {
-      arrayItems.push(line.trim().replace(/^-\s*/, ''));
-    }
-  }
-
-  // Save final array if needed
-  if (inArray && currentKey === 'tags') {
-    frontmatter.tags = arrayItems;
-  }
-
-  return {
-    frontmatter: frontmatter as RuleFrontmatter,
-    body: body.trim(),
-  };
-}
-
-function getCategoryForFile(filename: string): { name: string; section: number } | null {
-  for (const cat of CATEGORIES) {
-    if (filename.startsWith(cat.prefix)) {
-      return { name: cat.name, section: cat.section };
-    }
-  }
-  return null;
-}
-
-function readMetadata(): any {
-  const metadataPath = path.join(__dirname, '..', 'metadata.json');
-  return JSON.parse(fs.readFileSync(metadataPath, 'utf-8'));
-}
-
-function readRules(): Rule[] {
-  const rulesDir = path.join(__dirname, '..', 'rules');
-  const files = fs.readdirSync(rulesDir).filter((f) => f.endsWith('.md') && !f.startsWith('_'));
-
-  const rules: Rule[] = [];
-
-  for (const file of files) {
-    const filePath = path.join(rulesDir, file);
-    const content = fs.readFileSync(filePath, 'utf-8');
-    const { frontmatter, body } = parseFrontmatter(content);
-
-    if (!frontmatter) {
-      console.warn(`Warning: No frontmatter found in ${file}`);
-      continue;
-    }
-
-    const category = getCategoryForFile(file);
-    if (!category) {
-      console.warn(`Warning: Unknown category for ${file}`);
-      continue;
-    }
-
-    rules.push({
-      filename: file,
-      frontmatter,
-      content: body,
-      category: category.name,
-      categorySection: category.section,
-    });
-  }
-
-  return rules;
-}
-
-function generateTableOfContents(rulesByCategory: Map<string, Rule[]>): string {
-  let toc = '## Table of Contents\n\n';
-
-  for (const cat of CATEGORIES) {
-    const rules = rulesByCategory.get(cat.name);
-    if (!rules || rules.length === 0) continue;
-
-    // Section anchor format: #1-architecture
-    const sectionAnchor = `${cat.section}-${cat.name.toLowerCase().replace(/[^a-z0-9]+/g, '-')}`;
-    toc += `${cat.section}. [${cat.name}](#${sectionAnchor}) — **${cat.impact}**\n`;
-
-    for (let i = 0; i < rules.length; i++) {
-      const rule = rules[i];
-      // Rule anchor format: #11-rule-title
-      const ruleNum = `${cat.section}${i + 1}`;
-      const anchor = `${ruleNum}-${rule.frontmatter.title.toLowerCase().replace(/[^a-z0-9]+/g, '-')}`;
-      toc += `   - ${cat.section}.${i + 1} [${rule.frontmatter.title}](#${anchor})\n`;
-    }
-  }
-
-  return toc;
-}
-
-function generateAgentsMd(rules: Rule[], metadata: any): string {
-  // Group rules by category
-  const rulesByCategory = new Map<string, Rule[]>();
-
-  for (const rule of rules) {
-    if (!rulesByCategory.has(rule.category)) {
-      rulesByCategory.set(rule.category, []);
-    }
-    rulesByCategory.get(rule.category)!.push(rule);
-  }
-
-  // Sort rules within each category alphabetically
-  for (const [category, categoryRules] of rulesByCategory) {
-    categoryRules.sort((a, b) => a.filename.localeCompare(b.filename));
-  }
-
-  // Build document
-  let doc = `# NestJS Best Practices
-
-**Version ${metadata.version}**
-${metadata.organization}
-${metadata.date}
-
-> **Note:**
-> This document is mainly for agents and LLMs to follow when maintaining,
-> generating, or refactoring NestJS codebases. Humans may also find it
-> useful, but guidance here is optimized for automation and consistency
-> by AI-assisted workflows.
-
---
-
-## Abstract
-
-${metadata.abstract}
-
---
-
-`;
-
-  // Add table of contents
-  doc += generateTableOfContents(rulesByCategory);
-  doc += '\n---\n\n';
-
-  // Add rules by category
-  for (const cat of CATEGORIES) {
-    const categoryRules = rulesByCategory.get(cat.name);
-    if (!categoryRules || categoryRules.length === 0) continue;
-
-    doc += `## ${cat.section}. ${cat.name}\n\n`;
-    doc += `**Section Impact: ${cat.impact}**\n\n`;
-
-    for (let i = 0; i < categoryRules.length; i++) {
-      const rule = categoryRules[i];
-      const ruleNumber = `${cat.section}.${i + 1}`;
-
-      // Add rule header with number (anchor will be auto-generated as #11-title)
-      doc += `### ${ruleNumber} ${rule.frontmatter.title}\n\n`;
-      doc += `**Impact: ${rule.frontmatter.impact}** — ${rule.frontmatter.impactDescription}\n\n`;
-
-      // Add rule content (skip the first header since we already added it)
-      let ruleContent = rule.content;
-      // Remove the first h1 or h2 header if it matches the title
-      ruleContent = ruleContent.replace(/^#{1,2}\s+.*\n+/, '');
-      // Remove the impact line if present (we already added it)
-      ruleContent = ruleContent.replace(/^\*\*Impact:.*\*\*.*\n+/, '');
-
-      doc += ruleContent;
-      doc += '\n\n---\n\n';
-    }
-  }
-
-  // Add references footer
-  doc += `## References
-
-`;
-  for (const ref of metadata.references) {
-    doc += `- ${ref}\n`;
-  }
-
-  doc += `
---
-
-*Generated by build-agents.ts on ${new Date().toISOString().split('T')[0]}*
-`;
-
-  return doc;
-}
-
-function main() {
-  console.log('Building AGENTS.md...\n');
-
-  const metadata = readMetadata();
-  console.log(`Version: ${metadata.version}`);
-  console.log(`Organization: ${metadata.organization}\n`);
-
-  const rules = readRules();
-  console.log(`Found ${rules.length} rules\n`);
-
-  // Count by category
-  const counts = new Map<string, number>();
-  for (const rule of rules) {
-    counts.set(rule.category, (counts.get(rule.category) || 0) + 1);
-  }
-
-  console.log('Rules by category:');
-  for (const cat of CATEGORIES) {
-    const count = counts.get(cat.name) || 0;
-    if (count > 0) {
-      console.log(`  ${cat.name}: ${count}`);
-    }
-  }
-  console.log('');
-
-  const agentsMd = generateAgentsMd(rules, metadata);
-
-  const outputPath = path.join(__dirname, '..', 'AGENTS.md');
-  fs.writeFileSync(outputPath, agentsMd);
-
-  console.log(`Generated AGENTS.md (${agentsMd.length} bytes)`);
-  console.log(`Output: ${outputPath}`);
-}
-
-main();
@@ -1,16 +0,0 @@
-#!/bin/bash
-
-# Build script for generating AGENTS.md
-# Usage: ./build.sh
-
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-cd "$SCRIPT_DIR"
-
-# Check if ts-node is available
-if command -v npx &> /dev/null; then
-    echo "Running build with ts-node..."
-    npx ts-node build-agents.ts
-else
-    echo "Error: npx not found. Please install Node.js."
-    exit 1
-fi
@@ -1,15 +0,0 @@
-{
-  "name": "nestjs-best-practices-scripts",
-  "version": "1.0.0",
-  "type": "module",
-  "description": "Build scripts for NestJS Best Practices skillset",
-  "scripts": {
-    "build": "npx ts-node build-agents.ts",
-    "build:watch": "npx nodemon --watch ../rules --ext md --exec 'npx ts-node build-agents.ts'"
-  },
-  "devDependencies": {
-    "typescript": "^5.0.0",
-    "ts-node": "^10.9.0",
-    "@types/node": "^20.0.0"
-  }
-}
@@ -1,362 +0,0 @@
---
-name: next-best-practices
-description: Next.js best practices for LCBP3-DMS frontend. Enforces ADR-019 (publicId only, no parseInt/id fallback), TanStack Query + RHF + Zod, shadcn/ui, i18n, ADR-007 error UX, ADR-021 IntegratedBanner/WorkflowLifecycle, two-phase file upload.
-version: 1.8.9
-scope: frontend
-user-invocable: false
---
-
-# Next.js Best Practices
-
-Apply these rules when writing or reviewing Next.js code.
-
-## File Conventions
-
-See [file-conventions.md](./file-conventions.md) for:
-
- Project structure and special files
- Route segments (dynamic, catch-all, groups)
- Parallel and intercepting routes
- Middleware rename in v16 (middleware → proxy)
-
-## RSC Boundaries
-
-Detect invalid React Server Component patterns.
-
-See [rsc-boundaries.md](./rsc-boundaries.md) for:
-
- Async client component detection (invalid)
- Non-serializable props detection
- Server Action exceptions
-
-## Async Patterns
-
-Next.js 15+ async API changes.
-
-See [async-patterns.md](./async-patterns.md) for:
-
- Async `params` and `searchParams`
- Async `cookies()` and `headers()`
- Migration codemod
-
-## Runtime Selection
-
-See [runtime-selection.md](./runtime-selection.md) for:
-
- Default to Node.js runtime
- When Edge runtime is appropriate
-
-## Directives
-
-See [directives.md](./directives.md) for:
-
- `'use client'`, `'use server'` (React)
- `'use cache'` (Next.js)
-
-## Functions
-
-See [functions.md](./functions.md) for:
-
- Navigation hooks: `useRouter`, `usePathname`, `useSearchParams`, `useParams`
- Server functions: `cookies`, `headers`, `draftMode`, `after`
- Generate functions: `generateStaticParams`, `generateMetadata`
-
-## Error Handling
-
-See [error-handling.md](./error-handling.md) for:
-
- `error.tsx`, `global-error.tsx`, `not-found.tsx`
- `redirect`, `permanentRedirect`, `notFound`
- `forbidden`, `unauthorized` (auth errors)
- `unstable_rethrow` for catch blocks
-
-## Data Patterns
-
-Project-specific: See [uuid-handling.md](./uuid-handling.md) for ADR-019 UUID handling patterns.
-
-See [data-patterns.md](./data-patterns.md) for:
-
- Server Components vs Server Actions vs Route Handlers
- Avoiding data waterfalls (`Promise.all`, Suspense, preload)
- Client component data fetching
-
-## Route Handlers
-
-See [route-handlers.md](./route-handlers.md) for:
-
- `route.ts` basics
- GET handler conflicts with `page.tsx`
- Environment behavior (no React DOM)
- When to use vs Server Actions
-
-## Metadata & OG Images
-
-See [metadata.md](./metadata.md) for:
-
- Static and dynamic metadata
- `generateMetadata` function
- OG image generation with `next/og`
- File-based metadata conventions
-
-## Image Optimization
-
-See [image.md](./image.md) for:
-
- Always use `next/image` over `<img>`
- Remote images configuration
- Responsive `sizes` attribute
- Blur placeholders
- Priority loading for LCP
-
-## Font Optimization
-
-See [font.md](./font.md) for:
-
- `next/font` setup
- Google Fonts, local fonts
- Tailwind CSS integration
- Preloading subsets
-
-## Bundling
-
-See [bundling.md](./bundling.md) for:
-
- Server-incompatible packages
- CSS imports (not link tags)
- Polyfills (already included)
- ESM/CommonJS issues
- Bundle analysis
-
-## Scripts
-
-See [scripts.md](./scripts.md) for:
-
- `next/script` vs native script tags
- Inline scripts need `id`
- Loading strategies
- Google Analytics with `@next/third-parties`
-
-## Hydration Errors
-
-See [hydration-error.md](./hydration-error.md) for:
-
- Common causes (browser APIs, dates, invalid HTML)
- Debugging with error overlay
- Fixes for each cause
-
-## Suspense Boundaries
-
-See [suspense-boundaries.md](./suspense-boundaries.md) for:
-
- CSR bailout with `useSearchParams` and `usePathname`
- Which hooks require Suspense boundaries
-
-## Parallel & Intercepting Routes
-
-See [parallel-routes.md](./parallel-routes.md) for:
-
- Modal patterns with `@slot` and `(.)` interceptors
- `default.tsx` for fallbacks
- Closing modals correctly with `router.back()`
-
-## i18n (Thai / English)
-
-See [i18n.md](./i18n.md) for:
-
- `useTranslations('namespace')` pattern
- Key naming (kebab-case, feature-namespaced)
- When Zod messages stay inline vs i18n
- Server-side `userMessage` passthrough
-
-## Two-Phase File Upload
-
-See [two-phase-upload.md](./two-phase-upload.md) for:
-
- `useDropzone` + `useMutation` hook
- `tempFileIds` form-state pattern
- Whitelist MIME / max-size (must mirror backend)
- Clear-on-submit / expired-temp handling
-
-## Self-Hosting
-
-See [self-hosting.md](./self-hosting.md) for:
-
- `output: 'standalone'` for Docker
- Cache handlers for multi-instance ISR
- What works vs needs extra setup
-
-## NAP-DMS Project-Specific Rules (MUST FOLLOW)
-
-These rules are mandatory for the NAP-DMS LCBP3 frontend project:
-
-### State Management (บังคับใช้)
-
-**Server State - TanStack Query (React Query)**
-
-```tsx
-import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
-
-// ❌ ห้ามใช้ useEffect โดยตรง
-// ✅ ใช้ TanStack Query
-export function useCorrespondences(projectId: string) {
-  return useQuery({
-    queryKey: ['correspondences', projectId],
-    queryFn: () => correspondenceService.getAll(projectId),
-    staleTime: 5 * 60 * 1000,
-  });
-}
-```
-
-**Form State - React Hook Form + Zod**
-
-```tsx
-import { useForm } from 'react-hook-form';
-import { zodResolver } from '@hookform/resolvers/zod';
-import * as z from 'zod';
-
-const schema = z.object({
-  title: z.string().min(1, 'กรุณาระบุหัวเรื่อง'),
-  projectUuid: z.string().uuid('กรุณาเลือกโปรเจกต์'),
-});
-
-const form = useForm({
-  resolver: zodResolver(schema),
-});
-```
-
-### ADR-019 UUID Handling (CRITICAL — March 2026 Pattern)
-
-> **Updated:** ใช้ `publicId` ตรงๆ — ห้ามใช้ `id ?? ''` fallback หรือ `uuid` ร่วม.
-
-```tsx
-// ✅ CORRECT — Interface มีแค่ publicId
-interface Contract {
-  publicId?: string; // UUID from API — ใช้ตัวนี้
-  contractCode: string;
-  contractName: string;
-}
-
-// ✅ CORRECT — Select options (ไม่มี fallback)
-const options = contracts.map((c) => ({
-  label: `${c.contractName} (${c.contractCode})`,
-  value: c.publicId ?? '', // ใช้ publicId ล้วน
-  key: c.publicId ?? c.contractCode, // fallback ไป business field ได้
-}));
-
-// ❌ WRONG — pattern เก่า (ห้าม)
-interface OldContract {
-  id?: number; // ❌ อย่า expose INT id
-  uuid?: string; // ❌ ใช้ชื่อ uuid
-  publicId?: string;
-}
-const oldValue = String(c.publicId ?? c.id ?? ''); // ❌ `id ?? ''` fallback ห้าม
-
-// ❌ NEVER parseInt on UUID
-// const badId = parseInt(projectPublicId); // "019505..." → 19 (WRONG!)
-
-// ✅ ส่ง UUID string ตรงๆ ไป API
-apiClient.get(`/projects/${projectPublicId}`);
-```
-
-### Naming Conventions
-
-**Code Identifiers - ภาษาอังกฤษ**
-
-```tsx
-// ✅ Correct
-interface Correspondence {
-  documentNumber: string;
-  createdAt: string;
-}
-
-// ❌ Wrong
-interface เอกสาร {
-  เลขที่: string;
-}
-```
-
-**Comments - ภาษาไทย**
-
-```tsx
-// ✅ Correct - อธิบาย logic เป็นภาษาไทย
-// ตรวจสอบว่ามีการระบุ projectUuid หรือไม่
-if (!data.projectUuid) {
-  throw new Error('กรุณาเลือกโปรเจกต์');
-}
-
-// ❌ Wrong - ห้ามใช้ภาษาอังกฤษใน comments
-// Check if projectUuid is provided
-```
-
-### UI Components
-
-**บังคับใช้ shadcn/ui**
-
-```tsx
-// ✅ Correct
-import { Button } from '@/components/ui/button';
-import { Card, CardContent } from '@/components/ui/card';
-
-// ❌ Wrong - ไม่สร้าง component เองถ้ามีใน shadcn
-const MyButton = () => <button className="...">Click</button>;
-```
-
-### File Upload Pattern
-
-```tsx
-import { useDropzone } from 'react-dropzone';
-
-// Two-phase upload
-const onDrop = useCallback(async (files: File[]) => {
-  // Phase 1: Upload to temp
-  const tempFiles = await Promise.all(files.map((file) => uploadService.uploadTemp(file)));
-  setTempIds(tempFiles.map((f) => f.tempId));
-}, []);
-
-// Phase 2: Commit on form submit
-const onSubmit = async (data: FormData) => {
-  await correspondenceService.create({
-    ...data,
-    tempFileIds,
-  });
-};
-```
-
-### API Client Setup
-
-```typescript
-// lib/api/client.ts
-const apiClient = axios.create({
-  baseURL: process.env.NEXT_PUBLIC_API_URL,
-  timeout: 30000,
-});
-
-// Auto-add Idempotency-Key
-apiClient.interceptors.request.use((config) => {
-  if (['post', 'put', 'patch'].includes(config.method?.toLowerCase() || '')) {
-    config.headers['Idempotency-Key'] = uuidv4();
-  }
-  return config;
-});
-```
-
-### Anti-Patterns (ห้ามทำ)
-
- ❌ Fetch data ใน useEffect โดยตรง (ใช้ TanStack Query)
- ❌ Props drilling ลึกเกิน 3 levels
- ❌ Inline styles (ใช้ Tailwind)
- ❌ `console.log` ใน committed code
- ❌ `parseInt()` / `Number()` / `+` บน UUID values (ADR-019)
- ❌ `id ?? ''` fallback บน `publicId` (ใช้ `publicId ?? ''` หรือ fallback ไป business field)
- ❌ Expose `uuid` คู่กับ `publicId` ใน interface (ใช้ `publicId` อย่างเดียว)
- ❌ ใช้ index เป็น key ใน list
- ❌ Snake_case ใน form field names (ใช้ camelCase)
- ❌ Hardcode Thai/English string ใน component (ใช้ i18n keys)
- ❌ `any` type (strict mode)
-
---
-
-See [debug-tricks.md](./debug-tricks.md) for:
-
- MCP endpoint for AI-assisted debugging
- Rebuild specific routes with `--debug-build-paths`
@@ -1,84 +0,0 @@
-# Async Patterns
-
-In Next.js 15+, `params`, `searchParams`, `cookies()`, and `headers()` are asynchronous.
-
-## Async Params and SearchParams
-
-Always type them as `Promise<...>` and await them.
-
-### Pages and Layouts
-
-```tsx
-type Props = { params: Promise<{ slug: string }> };
-
-export default async function Page({ params }: Props) {
-  const { slug } = await params;
-}
-```
-
-### Route Handlers
-
-```tsx
-export async function GET(request: Request, { params }: { params: Promise<{ id: string }> }) {
-  const { id } = await params;
-}
-```
-
-### SearchParams
-
-```tsx
-type Props = {
-  params: Promise<{ slug: string }>;
-  searchParams: Promise<{ query?: string }>;
-};
-
-export default async function Page({ params, searchParams }: Props) {
-  const { slug } = await params;
-  const { query } = await searchParams;
-}
-```
-
-### Synchronous Components
-
-Use `React.use()` for non-async components:
-
-```tsx
-import { use } from 'react';
-
-type Props = { params: Promise<{ slug: string }> };
-
-export default function Page({ params }: Props) {
-  const { slug } = use(params);
-}
-```
-
-### generateMetadata
-
-```tsx
-type Props = { params: Promise<{ slug: string }> };
-
-export async function generateMetadata({ params }: Props): Promise<Metadata> {
-  const { slug } = await params;
-  return { title: slug };
-}
-```
-
-## Async Cookies and Headers
-
-```tsx
-import { cookies, headers } from 'next/headers';
-
-export default async function Page() {
-  const cookieStore = await cookies();
-  const headersList = await headers();
-
-  const theme = cookieStore.get('theme');
-  const userAgent = headersList.get('user-agent');
-}
-```
-
-## Migration Codemod
-
-```bash
-npx @next/codemod@latest next-async-request-api .
-```
@@ -1,182 +0,0 @@
-# Bundling
-
-Fix common bundling issues with third-party packages.
-
-## Server-Incompatible Packages
-
-Some packages use browser APIs (`window`, `document`, `localStorage`) and fail in Server Components.
-
-### Error Signs
-
-```
-ReferenceError: window is not defined
-ReferenceError: document is not defined
-ReferenceError: localStorage is not defined
-Module not found: Can't resolve 'fs'
-```
-
-### Solution 1: Mark as Client-Only
-
-If the package is only needed on client:
-
-```tsx
-// Bad: Fails - package uses window
-import SomeChart from 'some-chart-library';
-
-export default function Page() {
-  return <SomeChart />;
-}
-
-// Good: Use dynamic import with ssr: false
-import dynamic from 'next/dynamic';
-
-const SomeChart = dynamic(() => import('some-chart-library'), {
-  ssr: false,
-});
-
-export default function Page() {
-  return <SomeChart />;
-}
-```
-
-### Solution 2: Externalize from Server Bundle
-
-For packages that should run on server but have bundling issues:
-
-```js
-// next.config.js
-module.exports = {
-  serverExternalPackages: ['problematic-package'],
-};
-```
-
-Use this for:
-
- Packages with native bindings (sharp, bcrypt)
- Packages that don't bundle well (some ORMs)
- Packages with circular dependencies
-
-### Solution 3: Client Component Wrapper
-
-Wrap the entire usage in a client component:
-
-```tsx
-// components/ChartWrapper.tsx
-'use client';
-
-import { Chart } from 'chart-library';
-
-export function ChartWrapper(props) {
-  return <Chart {...props} />;
-}
-
-// app/page.tsx (server component)
-import { ChartWrapper } from '@/components/ChartWrapper';
-
-export default function Page() {
-  return <ChartWrapper data={data} />;
-}
-```
-
-## CSS Imports
-
-Import CSS files instead of using `<link>` tags. Next.js handles bundling and optimization.
-
-```tsx
-// Bad: Manual link tag
-<link rel="stylesheet" href="/styles.css" />;
-
-// Good: Import CSS
-import './styles.css';
-
-// Good: CSS Modules
-import styles from './Button.module.css';
-```
-
-## Polyfills
-
-Next.js includes common polyfills automatically. Don't load redundant ones from polyfill.io or similar CDNs.
-
-Already included: `Array.from`, `Object.assign`, `Promise`, `fetch`, `Map`, `Set`, `Symbol`, `URLSearchParams`, and 50+ others.
-
-```tsx
-// Bad: Redundant polyfills
-<script src="https://polyfill.io/v3/polyfill.min.js?features=fetch,Promise,Array.from" />
-
-// Good: Next.js includes these automatically
-```
-
-## ESM/CommonJS Issues
-
-### Error Signs
-
-```
-SyntaxError: Cannot use import statement outside a module
-Error: require() of ES Module
-Module not found: ESM packages need to be imported
-```
-
-### Solution: Transpile Package
-
-```js
-// next.config.js
-module.exports = {
-  transpilePackages: ['some-esm-package', 'another-package'],
-};
-```
-
-## Common Problematic Packages
-
-| Package         | Issue           | Solution                                                        |
-| --------------- | --------------- | --------------------------------------------------------------- |
-| `sharp`         | Native bindings | `serverExternalPackages: ['sharp']`                             |
-| `bcrypt`        | Native bindings | `serverExternalPackages: ['bcrypt']` or use `bcryptjs`          |
-| `canvas`        | Native bindings | `serverExternalPackages: ['canvas']`                            |
-| `recharts`      | Uses window     | `dynamic(() => import('recharts'), { ssr: false })`             |
-| `react-quill`   | Uses document   | `dynamic(() => import('react-quill'), { ssr: false })`          |
-| `mapbox-gl`     | Uses window     | `dynamic(() => import('mapbox-gl'), { ssr: false })`            |
-| `monaco-editor` | Uses window     | `dynamic(() => import('@monaco-editor/react'), { ssr: false })` |
-| `lottie-web`    | Uses document   | `dynamic(() => import('lottie-react'), { ssr: false })`         |
-
-## Bundle Analysis
-
-Analyze bundle size with the built-in analyzer (Next.js 16.1+):
-
-```bash
-next experimental-analyze
-```
-
-This opens an interactive UI to:
-
- Filter by route, environment (client/server), and type
- Inspect module sizes and import chains
- View treemap visualization
-
-Save output for comparison:
-
-```bash
-next experimental-analyze --output
-# Output saved to .next/diagnostics/analyze
-```
-
-Reference: https://nextjs.org/docs/app/guides/package-bundling
-
-## Migrating from Webpack to Turbopack
-
-Turbopack is the default bundler in Next.js 15+. If you have custom webpack config, migrate to Turbopack-compatible alternatives:
-
-```js
-// next.config.js
-module.exports = {
-  // Good: Works with Turbopack
-  serverExternalPackages: ['package'],
-  transpilePackages: ['package'],
-
-  // Bad: Webpack-only - migrate away from this
-  webpack: (config) => {
-    // custom webpack config
-  },
-};
-```
-
-Reference: https://nextjs.org/docs/app/building-your-application/upgrading/from-webpack-to-turbopack
@@ -1,300 +0,0 @@
-# Data Patterns
-
-Choose the right data fetching pattern for each use case.
-
-## Decision Tree
-
-```
-Need to fetch data?
-├── From a Server Component?
-│   └── Use: Fetch directly (no API needed)
-│
-├── From a Client Component?
-│   ├── Is it a mutation (POST/PUT/DELETE)?
-│   │   └── Use: Server Action
-│   └── Is it a read (GET)?
-│       └── Use: Route Handler OR pass from Server Component
-│
-├── Need external API access (webhooks, third parties)?
-│   └── Use: Route Handler
-│
-└── Need REST API for mobile app / external clients?
-    └── Use: Route Handler
-```
-
-## Pattern 1: Server Components (Preferred for Reads)
-
-Fetch data directly in Server Components - no API layer needed.
-
-```tsx
-// app/users/page.tsx
-async function UsersPage() {
-  // Direct database access - no API round-trip
-  const users = await db.user.findMany();
-
-  // Or fetch from external API
-  const posts = await fetch('https://api.example.com/posts').then((r) => r.json());
-
-  return (
-    <ul>
-      {users.map((user) => (
-        <li key={user.id}>{user.name}</li>
-      ))}
-    </ul>
-  );
-}
-```
-
-**Benefits**:
-
- No API to maintain
- No client-server waterfall
- Secrets stay on server
- Direct database access
-
-## Pattern 2: Server Actions (Preferred for Mutations)
-
-Server Actions are the recommended way to handle mutations.
-
-```tsx
-// app/actions.ts
-'use server';
-
-import { revalidatePath } from 'next/cache';
-
-export async function createPost(formData: FormData) {
-  const title = formData.get('title') as string;
-
-  await db.post.create({ data: { title } });
-
-  revalidatePath('/posts');
-}
-
-export async function deletePost(id: string) {
-  await db.post.delete({ where: { id } });
-
-  revalidateTag('posts');
-}
-```
-
-```tsx
-// app/posts/new/page.tsx
-import { createPost } from '@/app/actions';
-
-export default function NewPost() {
-  return (
-    <form action={createPost}>
-      <input name="title" required />
-      <button type="submit">Create</button>
-    </form>
-  );
-}
-```
-
-**Benefits**:
-
- End-to-end type safety
- Progressive enhancement (works without JS)
- Automatic request handling
- Integrated with React transitions
-
-**Constraints**:
-
- POST only (no GET caching semantics)
- Internal use only (no external access)
- Cannot return non-serializable data
-
-## Pattern 3: Route Handlers (APIs)
-
-Use Route Handlers when you need a REST API.
-
-```tsx
-// app/api/posts/route.ts
-import { NextRequest, NextResponse } from 'next/server';
-
-// GET is cacheable
-export async function GET(request: NextRequest) {
-  const posts = await db.post.findMany();
-  return NextResponse.json(posts);
-}
-
-// POST for mutations
-export async function POST(request: NextRequest) {
-  const body = await request.json();
-  const post = await db.post.create({ data: body });
-  return NextResponse.json(post, { status: 201 });
-}
-```
-
-**When to use**:
-
- External API access (mobile apps, third parties)
- Webhooks from external services
- GET endpoints that need HTTP caching
- OpenAPI/Swagger documentation needed
-
-**When NOT to use**:
-
- Internal data fetching (use Server Components)
- Mutations from your UI (use Server Actions)
-
-## Avoiding Data Waterfalls
-
-### Problem: Sequential Fetches
-
-```tsx
-// Bad: Sequential waterfalls
-async function Dashboard() {
-  const user = await getUser(); // Wait...
-  const posts = await getPosts(); // Then wait...
-  const comments = await getComments(); // Then wait...
-
-  return <div>...</div>;
-}
-```
-
-### Solution 1: Parallel Fetching with Promise.all
-
-```tsx
-// Good: Parallel fetching
-async function Dashboard() {
-  const [user, posts, comments] = await Promise.all([getUser(), getPosts(), getComments()]);
-
-  return <div>...</div>;
-}
-```
-
-### Solution 2: Streaming with Suspense
-
-```tsx
-// Good: Show content progressively
-import { Suspense } from 'react';
-
-async function Dashboard() {
-  return (
-    <div>
-      <Suspense fallback={<UserSkeleton />}>
-        <UserSection />
-      </Suspense>
-      <Suspense fallback={<PostsSkeleton />}>
-        <PostsSection />
-      </Suspense>
-    </div>
-  );
-}
-
-async function UserSection() {
-  const user = await getUser(); // Fetches independently
-  return <div>{user.name}</div>;
-}
-
-async function PostsSection() {
-  const posts = await getPosts(); // Fetches independently
-  return <PostList posts={posts} />;
-}
-```
-
-### Solution 3: Preload Pattern
-
-```tsx
-// lib/data.ts
-import { cache } from 'react';
-
-export const getUser = cache(async (id: string) => {
-  return db.user.findUnique({ where: { id } });
-});
-
-export const preloadUser = (id: string) => {
-  void getUser(id); // Fire and forget
-};
-```
-
-```tsx
-// app/user/[id]/page.tsx
-import { getUser, preloadUser } from '@/lib/data';
-
-export default async function UserPage({ params }) {
-  const { id } = await params;
-
-  // Start fetching early
-  preloadUser(id);
-
-  // Do other work...
-
-  // Data likely ready by now
-  const user = await getUser(id);
-  return <div>{user.name}</div>;
-}
-```
-
-## Client Component Data Fetching
-
-When Client Components need data:
-
-### Option 1: Pass from Server Component (Preferred)
-
-```tsx
-// Server Component
-async function Page() {
-  const data = await fetchData();
-  return <ClientComponent initialData={data} />;
-}
-
-// Client Component
-('use client');
-function ClientComponent({ initialData }) {
-  const [data, setData] = useState(initialData);
-  // ...
-}
-```
-
-### Option 2: Fetch on Mount (When Necessary)
-
-```tsx
-'use client';
-import { useEffect, useState } from 'react';
-
-function ClientComponent() {
-  const [data, setData] = useState(null);
-
-  useEffect(() => {
-    fetch('/api/data')
-      .then((r) => r.json())
-      .then(setData);
-  }, []);
-
-  if (!data) return <Loading />;
-  return <div>{data.value}</div>;
-}
-```
-
-### Option 3: Server Action for Reads (Works But Not Ideal)
-
-Server Actions can be called from Client Components for reads, but this is not their intended purpose:
-
-```tsx
-'use client';
-import { getData } from './actions';
-import { useEffect, useState } from 'react';
-
-function ClientComponent() {
-  const [data, setData] = useState(null);
-
-  useEffect(() => {
-    getData().then(setData);
-  }, []);
-
-  return <div>{data?.value}</div>;
-}
-```
-
-**Note**: Server Actions always use POST, so no HTTP caching. Prefer Route Handlers for cacheable reads.
-
-## Quick Reference
-
-| Pattern                | Use Case                    | HTTP Method | Caching              |
-| ---------------------- | --------------------------- | ----------- | -------------------- |
-| Server Component fetch | Internal reads              | Any         | Full Next.js caching |
-| Server Action          | Mutations, form submissions | POST only   | No                   |
-| Route Handler          | External APIs, webhooks     | Any         | GET can be cached    |
-| Client fetch to API    | Client-side reads           | Any         | HTTP cache headers   |
@@ -1,122 +0,0 @@
-# Debug Tricks
-
-Tricks to speed up debugging Next.js applications.
-
-## MCP Endpoint (Dev Server)
-
-Next.js exposes a `/_next/mcp` endpoint in development for AI-assisted debugging via MCP (Model Context Protocol).
-
- **Next.js 16+**: Enabled by default, use `next-devtools-mcp`
- **Next.js < 16**: Requires `experimental.mcpServer: true` in next.config.js
-
-Reference: https://nextjs.org/docs/app/guides/mcp
-
-**Important**: Find the actual port of the running Next.js dev server (check terminal output or `package.json` scripts). Don't assume port 3000.
-
-### Request Format
-
-The endpoint uses JSON-RPC 2.0 over HTTP POST:
-
-```bash
-curl -X POST http://localhost:<port>/_next/mcp \
-  -H "Content-Type: application/json" \
-  -H "Accept: application/json, text/event-stream" \
-  -d '{
-    "jsonrpc": "2.0",
-    "id": "1",
-    "method": "tools/call",
-    "params": {
-      "name": "<tool-name>",
-      "arguments": {}
-    }
-  }'
-```
-
-### Available Tools
-
-#### `get_errors`
-
-Get current errors from dev server (build errors, runtime errors with source-mapped stacks):
-
-```json
-{ "name": "get_errors", "arguments": {} }
-```
-
-#### `get_routes`
-
-Discover all routes by scanning filesystem:
-
-```json
-{ "name": "get_routes", "arguments": {} }
-// Optional: { "name": "get_routes", "arguments": { "routerType": "app" } }
-```
-
-Returns: `{ "appRouter": ["/", "/api/users/[id]", ...], "pagesRouter": [...] }`
-
-#### `get_project_metadata`
-
-Get project path and dev server URL:
-
-```json
-{ "name": "get_project_metadata", "arguments": {} }
-```
-
-Returns: `{ "projectPath": "/path/to/project", "devServerUrl": "http://localhost:3000" }`
-
-#### `get_page_metadata`
-
-Get runtime metadata about current page render (requires active browser session):
-
-```json
-{ "name": "get_page_metadata", "arguments": {} }
-```
-
-Returns segment trie data showing layouts, boundaries, and page components.
-
-#### `get_logs`
-
-Get path to Next.js development log file:
-
-```json
-{ "name": "get_logs", "arguments": {} }
-```
-
-Returns path to `<distDir>/logs/next-development.log`
-
-#### `get_server_action_by_id`
-
-Locate a Server Action by ID:
-
-```json
-{ "name": "get_server_action_by_id", "arguments": { "actionId": "<action-id>" } }
-```
-
-### Example: Get Errors
-
-```bash
-curl -X POST http://localhost:<port>/_next/mcp \
-  -H "Content-Type: application/json" \
-  -H "Accept: application/json, text/event-stream" \
-  -d '{"jsonrpc":"2.0","id":"1","method":"tools/call","params":{"name":"get_errors","arguments":{}}}'
-```
-
-## Rebuild Specific Routes (Next.js 16+)
-
-Use `--debug-build-paths` to rebuild only specific routes instead of the entire app:
-
-```bash
-# Rebuild a specific route
-next build --debug-build-paths "/dashboard"
-
-# Rebuild routes matching a glob
-next build --debug-build-paths "/api/*"
-
-# Dynamic routes
-next build --debug-build-paths "/blog/[slug]"
-```
-
-Use this to:
-
- Quickly verify a build fix without full rebuild
- Debug static generation issues for specific pages
- Iterate faster on build errors
@@ -1,74 +0,0 @@
-# Directives
-
-## React Directives
-
-These are React directives, not Next.js specific.
-
-### `'use client'`
-
-Marks a component as a Client Component. Required for:
-
- React hooks (`useState`, `useEffect`, etc.)
- Event handlers (`onClick`, `onChange`)
- Browser APIs (`window`, `localStorage`)
-
-```tsx
-'use client';
-
-import { useState } from 'react';
-
-export function Counter() {
-  const [count, setCount] = useState(0);
-  return <button onClick={() => setCount(count + 1)}>{count}</button>;
-}
-```
-
-Reference: https://react.dev/reference/rsc/use-client
-
-### `'use server'`
-
-Marks a function as a Server Action. Can be passed to Client Components.
-
-```tsx
-'use server';
-
-export async function submitForm(formData: FormData) {
-  // Runs on server
-}
-```
-
-Or inline within a Server Component:
-
-```tsx
-export default function Page() {
-  async function submit() {
-    'use server';
-    // Runs on server
-  }
-  return <form action={submit}>...</form>;
-}
-```
-
-Reference: https://react.dev/reference/rsc/use-server
-
---
-
-## Next.js Directive
-
-### `'use cache'`
-
-Marks a function or component for caching. Part of Next.js Cache Components.
-
-```tsx
-'use cache';
-
-export async function getCachedData() {
-  return await fetchData();
-}
-```
-
-Requires `cacheComponents: true` in `next.config.ts`.
-
-For detailed usage including cache profiles, `cacheLife()`, `cacheTag()`, and `updateTag()`, see the `next-cache-components` skill.
-
-Reference: https://nextjs.org/docs/app/api-reference/directives/use-cache
@@ -1,216 +0,0 @@
-# Error Handling
-
-Handle errors gracefully in Next.js applications.
-
-Reference: https://nextjs.org/docs/app/getting-started/error-handling
-
-## Error Boundaries
-
-### `error.tsx`
-
-Catches errors in a route segment and its children:
-
-```tsx
-'use client';
-
-export default function Error({ error, reset }: { error: Error & { digest?: string }; reset: () => void }) {
-  return (
-    <div>
-      <h2>Something went wrong!</h2>
-      <button onClick={() => reset()}>Try again</button>
-    </div>
-  );
-}
-```
-
-**Important:** `error.tsx` must be a Client Component.
-
-### `global-error.tsx`
-
-Catches errors in root layout:
-
-```tsx
-'use client';
-
-export default function GlobalError({ error, reset }: { error: Error & { digest?: string }; reset: () => void }) {
-  return (
-    <html>
-      <body>
-        <h2>Something went wrong!</h2>
-        <button onClick={() => reset()}>Try again</button>
-      </body>
-    </html>
-  );
-}
-```
-
-**Important:** Must include `<html>` and `<body>` tags.
-
-## Server Actions: Navigation API Gotcha
-
-**Do NOT wrap navigation APIs in try-catch.** They throw special errors that Next.js handles internally.
-
-Reference: https://nextjs.org/docs/app/api-reference/functions/redirect#behavior
-
-```tsx
-'use server'
-
-import { redirect } from 'next/navigation'
-import { notFound } from 'next/navigation'
-
-// Bad: try-catch catches the navigation "error"
-async function createPost(formData: FormData) {
-  try {
-    const post = await db.post.create({ ... })
-    redirect(`/posts/${post.id}`)  // This throws!
-  } catch (error) {
-    // redirect() throw is caught here - navigation fails!
-    return { error: 'Failed to create post' }
-  }
-}
-
-// Good: Call navigation APIs outside try-catch
-async function createPost(formData: FormData) {
-  let post
-  try {
-    post = await db.post.create({ ... })
-  } catch (error) {
-    return { error: 'Failed to create post' }
-  }
-  redirect(`/posts/${post.id}`)  // Outside try-catch
-}
-
-// Good: Re-throw navigation errors
-async function createPost(formData: FormData) {
-  try {
-    const post = await db.post.create({ ... })
-    redirect(`/posts/${post.id}`)
-  } catch (error) {
-    if (error instanceof Error && error.message === 'NEXT_REDIRECT') {
-      throw error  // Re-throw navigation errors
-    }
-    return { error: 'Failed to create post' }
-  }
-}
-```
-
-Same applies to:
-
- `redirect()` - 307 temporary redirect
- `permanentRedirect()` - 308 permanent redirect
- `notFound()` - 404 not found
- `forbidden()` - 403 forbidden
- `unauthorized()` - 401 unauthorized
-
-Use `unstable_rethrow()` to re-throw these errors in catch blocks:
-
-```tsx
-import { unstable_rethrow } from 'next/navigation';
-
-async function action() {
-  try {
-    // ...
-    redirect('/success');
-  } catch (error) {
-    unstable_rethrow(error); // Re-throws Next.js internal errors
-    return { error: 'Something went wrong' };
-  }
-}
-```
-
-## Redirects
-
-```tsx
-import { redirect, permanentRedirect } from 'next/navigation';
-
-// 307 Temporary - use for most cases
-redirect('/new-path');
-
-// 308 Permanent - use for URL migrations (cached by browsers)
-permanentRedirect('/new-url');
-```
-
-## Auth Errors
-
-Trigger auth-related error pages:
-
-```tsx
-import { forbidden, unauthorized } from 'next/navigation';
-
-async function Page() {
-  const session = await getSession();
-
-  if (!session) {
-    unauthorized(); // Renders unauthorized.tsx (401)
-  }
-
-  if (!session.hasAccess) {
-    forbidden(); // Renders forbidden.tsx (403)
-  }
-
-  return <Dashboard />;
-}
-```
-
-Create corresponding error pages:
-
-```tsx
-// app/forbidden.tsx
-export default function Forbidden() {
-  return <div>You don't have access to this resource</div>;
-}
-
-// app/unauthorized.tsx
-export default function Unauthorized() {
-  return <div>Please log in to continue</div>;
-}
-```
-
-## Not Found
-
-### `not-found.tsx`
-
-Custom 404 page for a route segment:
-
-```tsx
-export default function NotFound() {
-  return (
-    <div>
-      <h2>Not Found</h2>
-      <p>Could not find the requested resource</p>
-    </div>
-  );
-}
-```
-
-### Triggering Not Found
-
-```tsx
-import { notFound } from 'next/navigation';
-
-export default async function Page({ params }: { params: Promise<{ id: string }> }) {
-  const { id } = await params;
-  const post = await getPost(id);
-
-  if (!post) {
-    notFound(); // Renders closest not-found.tsx
-  }
-
-  return <div>{post.title}</div>;
-}
-```
-
-## Error Hierarchy
-
-Errors bubble up to the nearest error boundary:
-
-```
-app/
-├── error.tsx           # Catches errors from all children
-├── blog/
-│   ├── error.tsx       # Catches errors in /blog/*
-│   └── [slug]/
-│       ├── error.tsx   # Catches errors in /blog/[slug]
-│       └── page.tsx
-└── layout.tsx          # Errors here go to global-error.tsx
-```
@@ -1,141 +0,0 @@
-# File Conventions
-
-Next.js App Router uses file-based routing with special file conventions.
-
-## Project Structure
-
-Reference: https://nextjs.org/docs/app/getting-started/project-structure
-
-```
-app/
-├── layout.tsx          # Root layout (required)
-├── page.tsx            # Home page (/)
-├── loading.tsx         # Loading UI
-├── error.tsx           # Error UI
-├── not-found.tsx       # 404 UI
-├── global-error.tsx    # Global error UI
-├── route.ts            # API endpoint
-├── template.tsx        # Re-rendered layout
-├── default.tsx         # Parallel route fallback
-├── blog/
-│   ├── page.tsx        # /blog
-│   └── [slug]/
-│       └── page.tsx    # /blog/:slug
-└── (group)/            # Route group (no URL impact)
-    └── page.tsx
-```
-
-## Special Files
-
-| File            | Purpose                                  |
-| --------------- | ---------------------------------------- |
-| `page.tsx`      | UI for a route segment                   |
-| `layout.tsx`    | Shared UI for segment and children       |
-| `loading.tsx`   | Loading UI (Suspense boundary)           |
-| `error.tsx`     | Error UI (Error boundary)                |
-| `not-found.tsx` | 404 UI                                   |
-| `route.ts`      | API endpoint                             |
-| `template.tsx`  | Like layout but re-renders on navigation |
-| `default.tsx`   | Fallback for parallel routes             |
-
-## Route Segments
-
-```
-app/
-├── blog/               # Static segment: /blog
-├── [slug]/             # Dynamic segment: /:slug
-├── [...slug]/          # Catch-all: /a/b/c
-├── [[...slug]]/        # Optional catch-all: / or /a/b/c
-└── (marketing)/        # Route group (ignored in URL)
-```
-
-## Parallel Routes
-
-```
-app/
-├── @analytics/
-│   └── page.tsx
-├── @sidebar/
-│   └── page.tsx
-└── layout.tsx          # Receives { analytics, sidebar } as props
-```
-
-## Intercepting Routes
-
-```
-app/
-├── feed/
-│   └── page.tsx
-├── @modal/
-│   └── (.)photo/[id]/  # Intercepts /photo/[id] from /feed
-│       └── page.tsx
-└── photo/[id]/
-    └── page.tsx
-```
-
-Conventions:
-
- `(.)` - same level
- `(..)` - one level up
- `(..)(..)` - two levels up
- `(...)` - from root
-
-## Private Folders
-
-```
-app/
-├── _components/        # Private folder (not a route)
-│   └── Button.tsx
-└── page.tsx
-```
-
-Prefix with `_` to exclude from routing.
-
-## Middleware / Proxy
-
-### Next.js 14-15: `middleware.ts`
-
-```ts
-// middleware.ts (root of project)
-import { NextResponse } from 'next/server';
-import type { NextRequest } from 'next/server';
-
-export function middleware(request: NextRequest) {
-  // Auth, redirects, rewrites, etc.
-  return NextResponse.next();
-}
-
-export const config = {
-  matcher: ['/dashboard/:path*', '/api/:path*'],
-};
-```
-
-### Next.js 16+: `proxy.ts`
-
-Renamed for clarity - same capabilities, different names:
-
-```ts
-// proxy.ts (root of project)
-import { NextResponse } from 'next/server';
-import type { NextRequest } from 'next/server';
-
-export function proxy(request: NextRequest) {
-  // Same logic as middleware
-  return NextResponse.next();
-}
-
-export const proxyConfig = {
-  matcher: ['/dashboard/:path*', '/api/:path*'],
-};
-```
-
-| Version | File            | Export         | Config        |
-| ------- | --------------- | -------------- | ------------- |
-| v14-15  | `middleware.ts` | `middleware()` | `config`      |
-| v16+    | `proxy.ts`      | `proxy()`      | `proxyConfig` |
-
-**Migration**: Run `npx @next/codemod@latest upgrade` to auto-rename.
-
-## File Conventions Reference
-
-Reference: https://nextjs.org/docs/app/api-reference/file-conventions
@@ -1,246 +0,0 @@
-# Font Optimization
-
-Use `next/font` for automatic font optimization with zero layout shift.
-
-## Google Fonts
-
-```tsx
-// app/layout.tsx
-import { Inter } from 'next/font/google';
-
-const inter = Inter({ subsets: ['latin'] });
-
-export default function RootLayout({ children }: { children: React.ReactNode }) {
-  return (
-    <html lang="en" className={inter.className}>
-      <body>{children}</body>
-    </html>
-  );
-}
-```
-
-## Multiple Fonts
-
-```tsx
-import { Inter, Roboto_Mono } from 'next/font/google';
-
-const inter = Inter({
-  subsets: ['latin'],
-  variable: '--font-inter',
-});
-
-const robotoMono = Roboto_Mono({
-  subsets: ['latin'],
-  variable: '--font-roboto-mono',
-});
-
-export default function RootLayout({ children }: { children: React.ReactNode }) {
-  return (
-    <html lang="en" className={`${inter.variable} ${robotoMono.variable}`}>
-      <body>{children}</body>
-    </html>
-  );
-}
-```
-
-Use in CSS:
-
-```css
-body {
-  font-family: var(--font-inter);
-}
-
-code {
-  font-family: var(--font-roboto-mono);
-}
-```
-
-## Font Weights and Styles
-
-```tsx
-// Single weight
-const inter = Inter({
-  subsets: ['latin'],
-  weight: '400',
-});
-
-// Multiple weights
-const inter = Inter({
-  subsets: ['latin'],
-  weight: ['400', '500', '700'],
-});
-
-// Variable font (recommended) - includes all weights
-const inter = Inter({
-  subsets: ['latin'],
-  // No weight needed - variable fonts support all weights
-});
-
-// With italic
-const inter = Inter({
-  subsets: ['latin'],
-  style: ['normal', 'italic'],
-});
-```
-
-## Local Fonts
-
-```tsx
-import localFont from 'next/font/local';
-
-const myFont = localFont({
-  src: './fonts/MyFont.woff2',
-});
-
-// Multiple files for different weights
-const myFont = localFont({
-  src: [
-    {
-      path: './fonts/MyFont-Regular.woff2',
-      weight: '400',
-      style: 'normal',
-    },
-    {
-      path: './fonts/MyFont-Bold.woff2',
-      weight: '700',
-      style: 'normal',
-    },
-  ],
-});
-
-// Variable font
-const myFont = localFont({
-  src: './fonts/MyFont-Variable.woff2',
-  variable: '--font-my-font',
-});
-```
-
-## Tailwind CSS Integration
-
-```tsx
-// app/layout.tsx
-import { Inter } from 'next/font/google';
-
-const inter = Inter({
-  subsets: ['latin'],
-  variable: '--font-inter',
-});
-
-export default function RootLayout({ children }) {
-  return (
-    <html lang="en" className={inter.variable}>
-      <body>{children}</body>
-    </html>
-  );
-}
-```
-
-```js
-// tailwind.config.js
-module.exports = {
-  theme: {
-    extend: {
-      fontFamily: {
-        sans: ['var(--font-inter)'],
-      },
-    },
-  },
-};
-```
-
-## Preloading Subsets
-
-Only load needed character subsets:
-
-```tsx
-// Latin only (most common)
-const inter = Inter({ subsets: ['latin'] });
-
-// Multiple subsets
-const inter = Inter({ subsets: ['latin', 'latin-ext', 'cyrillic'] });
-```
-
-## Display Strategy
-
-Control font loading behavior:
-
-```tsx
-const inter = Inter({
-  subsets: ['latin'],
-  display: 'swap', // Default - shows fallback, swaps when loaded
-});
-
-// Options:
-// 'auto' - browser decides
-// 'block' - short block period, then swap
-// 'swap' - immediate fallback, swap when ready (recommended)
-// 'fallback' - short block, short swap, then fallback
-// 'optional' - short block, no swap (use if font is optional)
-```
-
-## Don't Use Manual Font Links
-
-Always use `next/font` instead of `<link>` tags for Google Fonts.
-
-```tsx
-// Bad: Manual link tag (blocks rendering, no optimization)
-<link href="https://fonts.googleapis.com/css2?family=Inter" rel="stylesheet" />
-
-// Bad: Missing display and preconnect
-<link href="https://fonts.googleapis.com/css2?family=Inter" rel="stylesheet" />
-
-// Good: Use next/font (self-hosted, zero layout shift)
-import { Inter } from 'next/font/google'
-
-const inter = Inter({ subsets: ['latin'] })
-```
-
-## Common Mistakes
-
-```tsx
-// Bad: Importing font in every component
-// components/Button.tsx
-import { Inter } from 'next/font/google'
-const inter = Inter({ subsets: ['latin'] }) // Creates new instance each time!
-
-// Good: Import once in layout, use CSS variable
-// app/layout.tsx
-const inter = Inter({ subsets: ['latin'], variable: '--font-inter' })
-
-// Bad: Using @import in CSS (blocks rendering)
-/* globals.css */
-@import url('https://fonts.googleapis.com/css2?family=Inter');
-
-// Good: Use next/font (self-hosted, no network request)
-import { Inter } from 'next/font/google'
-
-// Bad: Loading all weights when only using a few
-const inter = Inter({ subsets: ['latin'] }) // Loads all weights
-
-// Good: Specify only needed weights (for non-variable fonts)
-const inter = Inter({ subsets: ['latin'], weight: ['400', '700'] })
-
-// Bad: Missing subset - loads all characters
-const inter = Inter({})
-
-// Good: Always specify subset
-const inter = Inter({ subsets: ['latin'] })
-```
-
-## Font in Specific Components
-
-```tsx
-// For component-specific fonts, export from a shared file
-// lib/fonts.ts
-import { Inter, Playfair_Display } from 'next/font/google';
-
-export const inter = Inter({ subsets: ['latin'], variable: '--font-inter' });
-export const playfair = Playfair_Display({ subsets: ['latin'], variable: '--font-playfair' });
-
-// components/Heading.tsx
-import { playfair } from '@/lib/fonts';
-
-export function Heading({ children }) {
-  return <h1 className={playfair.className}>{children}</h1>;
-}
-```
@@ -1,108 +0,0 @@
-# Functions
-
-Next.js function APIs.
-
-Reference: https://nextjs.org/docs/app/api-reference/functions
-
-## Navigation Hooks (Client)
-
-| Hook                        | Purpose                                                        | Reference                                                                                |
-| --------------------------- | -------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
-| `useRouter`                 | Programmatic navigation (`push`, `replace`, `back`, `refresh`) | [Docs](https://nextjs.org/docs/app/api-reference/functions/use-router)                   |
-| `usePathname`               | Get current pathname                                           | [Docs](https://nextjs.org/docs/app/api-reference/functions/use-pathname)                 |
-| `useSearchParams`           | Read URL search parameters                                     | [Docs](https://nextjs.org/docs/app/api-reference/functions/use-search-params)            |
-| `useParams`                 | Access dynamic route parameters                                | [Docs](https://nextjs.org/docs/app/api-reference/functions/use-params)                   |
-| `useSelectedLayoutSegment`  | Active child segment (one level)                               | [Docs](https://nextjs.org/docs/app/api-reference/functions/use-selected-layout-segment)  |
-| `useSelectedLayoutSegments` | All active segments below layout                               | [Docs](https://nextjs.org/docs/app/api-reference/functions/use-selected-layout-segments) |
-| `useLinkStatus`             | Check link prefetch status                                     | [Docs](https://nextjs.org/docs/app/api-reference/functions/use-link-status)              |
-| `useReportWebVitals`        | Report Core Web Vitals metrics                                 | [Docs](https://nextjs.org/docs/app/api-reference/functions/use-report-web-vitals)        |
-
-## Server Functions
-
-| Function     | Purpose                                      | Reference                                                              |
-| ------------ | -------------------------------------------- | ---------------------------------------------------------------------- |
-| `cookies`    | Read/write cookies                           | [Docs](https://nextjs.org/docs/app/api-reference/functions/cookies)    |
-| `headers`    | Read request headers                         | [Docs](https://nextjs.org/docs/app/api-reference/functions/headers)    |
-| `draftMode`  | Enable preview of unpublished CMS content    | [Docs](https://nextjs.org/docs/app/api-reference/functions/draft-mode) |
-| `after`      | Run code after response finishes streaming   | [Docs](https://nextjs.org/docs/app/api-reference/functions/after)      |
-| `connection` | Wait for connection before dynamic rendering | [Docs](https://nextjs.org/docs/app/api-reference/functions/connection) |
-| `userAgent`  | Parse User-Agent header                      | [Docs](https://nextjs.org/docs/app/api-reference/functions/userAgent)  |
-
-## Generate Functions
-
-| Function                | Purpose                                 | Reference                                                                           |
-| ----------------------- | --------------------------------------- | ----------------------------------------------------------------------------------- |
-| `generateStaticParams`  | Pre-render dynamic routes at build time | [Docs](https://nextjs.org/docs/app/api-reference/functions/generate-static-params)  |
-| `generateMetadata`      | Dynamic metadata                        | [Docs](https://nextjs.org/docs/app/api-reference/functions/generate-metadata)       |
-| `generateViewport`      | Dynamic viewport config                 | [Docs](https://nextjs.org/docs/app/api-reference/functions/generate-viewport)       |
-| `generateSitemaps`      | Multiple sitemaps for large sites       | [Docs](https://nextjs.org/docs/app/api-reference/functions/generate-sitemaps)       |
-| `generateImageMetadata` | Multiple OG images per route            | [Docs](https://nextjs.org/docs/app/api-reference/functions/generate-image-metadata) |
-
-## Request/Response
-
-| Function        | Purpose                        | Reference                                                                  |
-| --------------- | ------------------------------ | -------------------------------------------------------------------------- |
-| `NextRequest`   | Extended Request with helpers  | [Docs](https://nextjs.org/docs/app/api-reference/functions/next-request)   |
-| `NextResponse`  | Extended Response with helpers | [Docs](https://nextjs.org/docs/app/api-reference/functions/next-response)  |
-| `ImageResponse` | Generate OG images             | [Docs](https://nextjs.org/docs/app/api-reference/functions/image-response) |
-
-## Common Examples
-
-### Navigation
-
-Use `next/link` for internal navigation instead of `<a>` tags.
-
-```tsx
-// Bad: Plain anchor tag
-<a href="/about">About</a>;
-
-// Good: Next.js Link
-import Link from 'next/link';
-
-<Link href="/about">About</Link>;
-```
-
-Active link styling:
-
-```tsx
-'use client';
-
-import Link from 'next/link';
-import { usePathname } from 'next/navigation';
-
-export function NavLink({ href, children }) {
-  const pathname = usePathname();
-
-  return (
-    <Link href={href} className={pathname === href ? 'active' : ''}>
-      {children}
-    </Link>
-  );
-}
-```
-
-### Static Generation
-
-```tsx
-// app/blog/[slug]/page.tsx
-export async function generateStaticParams() {
-  const posts = await getPosts();
-  return posts.map((post) => ({ slug: post.slug }));
-}
-```
-
-### After Response
-
-```tsx
-import { after } from 'next/server';
-
-export async function POST(request: Request) {
-  const data = await processRequest(request);
-
-  after(async () => {
-    await logAnalytics(data);
-  });
-
-  return Response.json({ success: true });
-}
-```
@@ -1,86 +0,0 @@
-# Hydration Errors
-
-Diagnose and fix React hydration mismatch errors.
-
-## Error Signs
-
- "Hydration failed because the initial UI does not match"
- "Text content does not match server-rendered HTML"
-
-## Debugging
-
-In development, click the hydration error to see the server/client diff.
-
-## Common Causes and Fixes
-
-### Browser-only APIs
-
-```tsx
-// Bad: Causes mismatch - window doesn't exist on server
-<div>{window.innerWidth}</div>;
-
-// Good: Use client component with mounted check
-('use client');
-import { useState, useEffect } from 'react';
-
-export function ClientOnly({ children }: { children: React.ReactNode }) {
-  const [mounted, setMounted] = useState(false);
-  useEffect(() => setMounted(true), []);
-  return mounted ? children : null;
-}
-```
-
-### Date/Time Rendering
-
-Server and client may be in different timezones:
-
-```tsx
-// Bad: Causes mismatch
-<span>{new Date().toLocaleString()}</span>;
-
-// Good: Render on client only
-('use client');
-const [time, setTime] = useState<string>();
-useEffect(() => setTime(new Date().toLocaleString()), []);
-```
-
-### Random Values or IDs
-
-```tsx
-// Bad: Random values differ between server and client
-<div id={Math.random().toString()}>
-
-// Good: Use useId hook
-import { useId } from 'react'
-
-function Input() {
-  const id = useId()
-  return <input id={id} />
-}
-```
-
-### Invalid HTML Nesting
-
-```tsx
-// Bad: Invalid - div inside p
-<p><div>Content</div></p>
-
-// Bad: Invalid - p inside p
-<p><p>Nested</p></p>
-
-// Good: Valid nesting
-<div><p>Content</p></div>
-```
-
-### Third-party Scripts
-
-Scripts that modify DOM during hydration.
-
-```tsx
-// Good: Use next/script with afterInteractive
-import Script from 'next/script';
-
-export default function Page() {
-  return <Script src="https://example.com/script.js" strategy="afterInteractive" />;
-}
-```
@@ -1,79 +0,0 @@
-# i18n (Thai / English)
-
-LCBP3 frontend **must not** hardcode Thai or English UI strings in components.
-
-## Rules
-
-1. **All user-facing strings go through the i18n layer** (`next-intl` / `i18next` — check `frontend/package.json`).
-2. **Keys use kebab-case**, namespaced by feature:
-   - `correspondence.list.title`
-   - `correspondence.form.submit`
-   - `common.actions.cancel`
-3. **Comments in code remain Thai** (business logic explanation); **only UI copy** goes through i18n.
-4. **Error messages** from backend (via ADR-007 `userMessage`) are already localized server-side — render them directly, don't translate client-side.
-
---
-
-## ❌ Wrong
-
-```tsx
-export function CorrespondenceHeader() {
-  return <h1>รายการหนังสือติดต่อ</h1>; // ❌ hardcoded Thai
-}
-
-toast.success('บันทึกสำเร็จ'); // ❌ hardcoded
-```
-
---
-
-## ✅ Right
-
-```tsx
-import { useTranslations } from 'next-intl';
-
-export function CorrespondenceHeader() {
-  const t = useTranslations('correspondence.list');
-  return <h1>{t('title')}</h1>;
-}
-
-toast.success(t('save.success'));
-```
-
-Translation files:
-
-```json
-// messages/th.json
-{
-  "correspondence": {
-    "list": { "title": "รายการหนังสือติดต่อ" },
-    "save":  { "success": "บันทึกสำเร็จ" }
-  }
-}
-
-// messages/en.json
-{
-  "correspondence": {
-    "list": { "title": "Correspondence List" },
-    "save":  { "success": "Saved successfully" }
-  }
-}
-```
-
---
-
-## Zod Error Messages
-
-Zod error messages shown in forms **do** stay in Thai inline (per `specs/05-Engineering-Guidelines/05-03-frontend-guidelines.md`), because they're schema-bound and rarely need translation. If dual-language support becomes required, wrap with an i18n-aware resolver:
-
-```ts
-const schema = z.object({
-  projectUuid: z.string().uuid(t('validation.project.required')),
-});
-```
-
---
-
-## Reference
-
- [i18n Guidelines](../../../specs/05-Engineering-Guidelines/05-08-i18n-guidelines.md)
- [Frontend Guidelines](../../../specs/05-Engineering-Guidelines/05-03-frontend-guidelines.md)
@@ -1,173 +0,0 @@
-# Image Optimization
-
-Use `next/image` for automatic image optimization.
-
-## Always Use next/image
-
-```tsx
-// Bad: Avoid native img
-<img src="/hero.png" alt="Hero" />;
-
-// Good: Use next/image
-import Image from 'next/image';
-<Image src="/hero.png" alt="Hero" width={800} height={400} />;
-```
-
-## Required Props
-
-Images need explicit dimensions to prevent layout shift:
-
-```tsx
-// Local images - dimensions inferred automatically
-import heroImage from './hero.png'
-<Image src={heroImage} alt="Hero" />
-
-// Remote images - must specify width/height
-<Image src="https://example.com/image.jpg" alt="Hero" width={800} height={400} />
-
-// Or use fill for parent-relative sizing
-<div style={{ position: 'relative', width: '100%', height: 400 }}>
-  <Image src="/hero.png" alt="Hero" fill style={{ objectFit: 'cover' }} />
-</div>
-```
-
-## Remote Images Configuration
-
-Remote domains must be configured in `next.config.js`:
-
-```js
-// next.config.js
-module.exports = {
-  images: {
-    remotePatterns: [
-      {
-        protocol: 'https',
-        hostname: 'example.com',
-        pathname: '/images/**',
-      },
-      {
-        protocol: 'https',
-        hostname: '*.cdn.com', // Wildcard subdomain
-      },
-    ],
-  },
-};
-```
-
-## Responsive Images
-
-Use `sizes` to tell the browser which size to download:
-
-```tsx
-// Full-width hero
-<Image
-  src="/hero.png"
-  alt="Hero"
-  fill
-  sizes="100vw"
-/>
-
-// Responsive grid (3 columns on desktop, 1 on mobile)
-<Image
-  src="/card.png"
-  alt="Card"
-  fill
-  sizes="(max-width: 768px) 100vw, 33vw"
-/>
-
-// Fixed sidebar image
-<Image
-  src="/avatar.png"
-  alt="Avatar"
-  width={200}
-  height={200}
-  sizes="200px"
-/>
-```
-
-## Blur Placeholder
-
-Prevent layout shift with placeholders:
-
-```tsx
-// Local images - automatic blur hash
-import heroImage from './hero.png'
-<Image src={heroImage} alt="Hero" placeholder="blur" />
-
-// Remote images - provide blurDataURL
-<Image
-  src="https://example.com/image.jpg"
-  alt="Hero"
-  width={800}
-  height={400}
-  placeholder="blur"
-  blurDataURL="data:image/jpeg;base64,/9j/4AAQSkZJRg..."
-/>
-
-// Or use color placeholder
-<Image
-  src="https://example.com/image.jpg"
-  alt="Hero"
-  width={800}
-  height={400}
-  placeholder="empty"
-  style={{ backgroundColor: '#e0e0e0' }}
-/>
-```
-
-## Priority Loading
-
-Use `priority` for above-the-fold images (LCP):
-
-```tsx
-// Hero image - loads immediately
-<Image src="/hero.png" alt="Hero" fill priority />
-
-// Below-fold images - lazy loaded by default (no priority needed)
-<Image src="/card.png" alt="Card" width={400} height={300} />
-```
-
-## Common Mistakes
-
-```tsx
-// Bad: Missing sizes with fill - downloads largest image
-<Image src="/hero.png" alt="Hero" fill />
-
-// Good: Add sizes for proper responsive behavior
-<Image src="/hero.png" alt="Hero" fill sizes="100vw" />
-
-// Bad: Using width/height for aspect ratio only
-<Image src="/hero.png" alt="Hero" width={16} height={9} />
-
-// Good: Use actual display dimensions or fill with sizes
-<Image src="/hero.png" alt="Hero" fill sizes="100vw" style={{ objectFit: 'cover' }} />
-
-// Bad: Remote image without config
-<Image src="https://untrusted.com/image.jpg" alt="Image" width={400} height={300} />
-// Error: Invalid src prop, hostname not configured
-
-// Good: Add hostname to next.config.js remotePatterns
-```
-
-## Static Export
-
-When using `output: 'export'`, use `unoptimized` or custom loader:
-
-```tsx
-// Option 1: Disable optimization
-<Image src="/hero.png" alt="Hero" width={800} height={400} unoptimized />;
-
-// Option 2: Global config
-// next.config.js
-module.exports = {
-  output: 'export',
-  images: { unoptimized: true },
-};
-
-// Option 3: Custom loader (Cloudinary, Imgix, etc.)
-const cloudinaryLoader = ({ src, width, quality }) => {
-  return `https://res.cloudinary.com/demo/image/upload/w_${width},q_${quality || 75}/${src}`;
-};
-
-<Image loader={cloudinaryLoader} src="sample.jpg" alt="Sample" width={800} height={400} />;
-```
@@ -1,293 +0,0 @@
-# Metadata
-
-Add SEO metadata to Next.js pages using the Metadata API.
-
-## Important: Server Components Only
-
-The `metadata` object and `generateMetadata` function are **only supported in Server Components**. They cannot be used in Client Components.
-
-If the target page has `'use client'`:
-
-1. Remove `'use client'` if possible, move client logic to child components
-2. Or extract metadata to a parent Server Component layout
-3. Or split the file: Server Component with metadata imports Client Components
-
-## Static Metadata
-
-```tsx
-import type { Metadata } from 'next';
-
-export const metadata: Metadata = {
-  title: 'Page Title',
-  description: 'Page description for search engines',
-};
-```
-
-## Dynamic Metadata
-
-```tsx
-import type { Metadata } from 'next';
-
-type Props = { params: Promise<{ slug: string }> };
-
-export async function generateMetadata({ params }: Props): Promise<Metadata> {
-  const { slug } = await params;
-  const post = await getPost(slug);
-  return { title: post.title, description: post.description };
-}
-```
-
-## Avoid Duplicate Fetches
-
-Use React `cache()` when the same data is needed for both metadata and page:
-
-```tsx
-import { cache } from 'react';
-
-export const getPost = cache(async (slug: string) => {
-  return await db.posts.findFirst({ where: { slug } });
-});
-```
-
-## Viewport
-
-Separate from metadata for streaming support:
-
-```tsx
-import type { Viewport } from 'next';
-
-export const viewport: Viewport = {
-  width: 'device-width',
-  initialScale: 1,
-  themeColor: '#000000',
-};
-
-// Or dynamic
-export function generateViewport({ params }): Viewport {
-  return { themeColor: getThemeColor(params) };
-}
-```
-
-## Title Templates
-
-In root layout for consistent naming:
-
-```tsx
-export const metadata: Metadata = {
-  title: { default: 'Site Name', template: '%s | Site Name' },
-};
-```
-
-## Metadata File Conventions
-
-Reference: https://nextjs.org/docs/app/getting-started/project-structure#metadata-file-conventions
-
-Place these files in `app/` directory (or route segments):
-
-| File                            | Purpose                                       |
-| ------------------------------- | --------------------------------------------- |
-| `favicon.ico`                   | Favicon                                       |
-| `icon.png` / `icon.svg`         | App icon                                      |
-| `apple-icon.png`                | Apple app icon                                |
-| `opengraph-image.png`           | OG image                                      |
-| `twitter-image.png`             | Twitter card image                            |
-| `sitemap.ts` / `sitemap.xml`    | Sitemap (use `generateSitemaps` for multiple) |
-| `robots.ts` / `robots.txt`      | Robots directives                             |
-| `manifest.ts` / `manifest.json` | Web app manifest                              |
-
-## SEO Best Practice: Static Files Are Often Enough
-
-For most sites, **static metadata files provide excellent SEO coverage**:
-
-```
-app/
-├── favicon.ico
-├── opengraph-image.png     # Works for both OG and Twitter
-├── sitemap.ts
-├── robots.ts
-└── layout.tsx              # With title/description metadata
-```
-
-**Tips:**
-
- A single `opengraph-image.png` covers both Open Graph and Twitter (Twitter falls back to OG)
- Static `title` and `description` in layout metadata is sufficient for most pages
- Only use dynamic `generateMetadata` when content varies per page
-
---
-
-# OG Image Generation
-
-Generate dynamic Open Graph images using `next/og`.
-
-## Important Rules
-
-1. **Use `next/og`** - not `@vercel/og` (it's built into Next.js)
-2. **No searchParams** - OG images can't access search params, use route params instead
-3. **Avoid Edge runtime** - Use default Node.js runtime
-
-```tsx
-// Good
-import { ImageResponse } from 'next/og';
-
-// Bad
-// import { ImageResponse } from '@vercel/og'
-// export const runtime = 'edge'
-```
-
-## Basic OG Image
-
-```tsx
-// app/opengraph-image.tsx
-import { ImageResponse } from 'next/og';
-
-export const alt = 'Site Name';
-export const size = { width: 1200, height: 630 };
-export const contentType = 'image/png';
-
-export default function Image() {
-  return new ImageResponse(
-    (
-      <div
-        style={{
-          fontSize: 128,
-          background: 'white',
-          width: '100%',
-          height: '100%',
-          display: 'flex',
-          alignItems: 'center',
-          justifyContent: 'center',
-        }}
-      >
-        Hello World
-      </div>
-    ),
-    { ...size }
-  );
-}
-```
-
-## Dynamic OG Image
-
-```tsx
-// app/blog/[slug]/opengraph-image.tsx
-import { ImageResponse } from 'next/og';
-
-export const alt = 'Blog Post';
-export const size = { width: 1200, height: 630 };
-export const contentType = 'image/png';
-
-type Props = { params: Promise<{ slug: string }> };
-
-export default async function Image({ params }: Props) {
-  const { slug } = await params;
-  const post = await getPost(slug);
-
-  return new ImageResponse(
-    (
-      <div
-        style={{
-          fontSize: 48,
-          background: 'linear-gradient(to bottom, #1a1a1a, #333)',
-          color: 'white',
-          width: '100%',
-          height: '100%',
-          display: 'flex',
-          flexDirection: 'column',
-          alignItems: 'center',
-          justifyContent: 'center',
-          padding: 48,
-        }}
-      >
-        <div style={{ fontSize: 64, fontWeight: 'bold' }}>{post.title}</div>
-        <div style={{ marginTop: 24, opacity: 0.8 }}>{post.description}</div>
-      </div>
-    ),
-    { ...size }
-  );
-}
-```
-
-## Custom Fonts
-
-```tsx
-import { ImageResponse } from 'next/og';
-import { join } from 'path';
-import { readFile } from 'fs/promises';
-
-export default async function Image() {
-  const fontPath = join(process.cwd(), 'assets/fonts/Inter-Bold.ttf');
-  const fontData = await readFile(fontPath);
-
-  return new ImageResponse(<div style={{ fontFamily: 'Inter', fontSize: 64 }}>Custom Font Text</div>, {
-    width: 1200,
-    height: 630,
-    fonts: [{ name: 'Inter', data: fontData, style: 'normal' }],
-  });
-}
-```
-
-## File Naming
-
- `opengraph-image.tsx` - Open Graph (Facebook, LinkedIn)
- `twitter-image.tsx` - Twitter/X cards (optional, falls back to OG)
-
-## Styling Notes
-
-ImageResponse uses Flexbox layout:
-
- Use `display: 'flex'`
- No CSS Grid support
- Styles must be inline objects
-
-## Multiple OG Images
-
-Use `generateImageMetadata` for multiple images per route:
-
-```tsx
-// app/blog/[slug]/opengraph-image.tsx
-import { ImageResponse } from 'next/og';
-
-export async function generateImageMetadata({ params }) {
-  const images = await getPostImages(params.slug);
-  return images.map((img, idx) => ({
-    id: idx,
-    alt: img.alt,
-    size: { width: 1200, height: 630 },
-    contentType: 'image/png',
-  }));
-}
-
-export default async function Image({ params, id }) {
-  const images = await getPostImages(params.slug);
-  const image = images[id];
-  return new ImageResponse(/* ... */);
-}
-```
-
-## Multiple Sitemaps
-
-Use `generateSitemaps` for large sites:
-
-```tsx
-// app/sitemap.ts
-import type { MetadataRoute } from 'next';
-
-export async function generateSitemaps() {
-  // Return array of sitemap IDs
-  return [{ id: 0 }, { id: 1 }, { id: 2 }];
-}
-
-export default async function sitemap({ id }: { id: number }): Promise<MetadataRoute.Sitemap> {
-  const start = id * 50000;
-  const end = start + 50000;
-  const products = await getProducts(start, end);
-
-  return products.map((product) => ({
-    url: `https://example.com/product/${product.id}`,
-    lastModified: product.updatedAt,
-  }));
-}
-```
-
-Generates `/sitemap/0.xml`, `/sitemap/1.xml`, etc.
--- a/Show More
+++ b/Show More
Author	SHA1	Message	Date
admin	d4e2f23f16	Backup: docs: update README and patch 2git.ps1 \| 2025-12-06 15:30:17 Spec Validation / validate-markdown (push) Has been cancelled Details Spec Validation / validate-diagrams (push) Has been cancelled Details Spec Validation / check-todos (push) Has been cancelled Details	2025-12-06 15:30:17 +07:00
admin	fc6cf11818	Merge branch 'main' of github.com:peancharoen/lcbp3 Spec Validation / validate-markdown (push) Has been cancelled Details Spec Validation / validate-diagrams (push) Has been cancelled Details Spec Validation / check-todos (push) Has been cancelled Details	2025-12-06 15:26:56 +07:00
admin	eeff27a511	Backup: docs: update README \| 2025-12-06 15:21:14 Spec Validation / validate-markdown (push) Has been cancelled Details Spec Validation / validate-diagrams (push) Has been cancelled Details Spec Validation / check-todos (push) Has been cancelled Details	2025-12-06 15:24:06 +07:00
admin	ff0f1884e1	remove large vsix file and add to gitignore Spec Validation / validate-markdown (push) Has been cancelled Details Spec Validation / validate-diagrams (push) Has been cancelled Details Spec Validation / check-todos (push) Has been cancelled Details	2025-12-06 14:47:36 +07:00
admin	2b8e63a7b0	251206:1400 version 1.5.1 Spec Validation / validate-markdown (push) Has been cancelled Details Spec Validation / validate-diagrams (push) Has been cancelled Details Spec Validation / check-todos (push) Has been cancelled Details	2025-12-06 14:42:32 +07:00
admin	477fe6b287	251205:2300 debug backend/frontend Spec Validation / validate-markdown (push) Has been cancelled Details Spec Validation / validate-diagrams (push) Has been cancelled Details Spec Validation / check-todos (push) Has been cancelled Details	2025-12-05 23:42:12 +07:00
admin	c05e715e03	251205:1500 debug backend/frontend Spec Validation / validate-markdown (push) Has been cancelled Details Spec Validation / validate-diagrams (push) Has been cancelled Details Spec Validation / check-todos (push) Has been cancelled Details	2025-12-05 14:52:15 +07:00
admin	18f78f8a5e	251205:0000 Just start debug backend/frontend Spec Validation / validate-markdown (push) Has been cancelled Details Spec Validation / validate-diagrams (push) Has been cancelled Details Spec Validation / check-todos (push) Has been cancelled Details	2025-12-05 00:32:02 +07:00
admin	474982af87	251204:1700 Prepare to version 1.5.1 Spec Validation / validate-markdown (push) Has been cancelled Details Spec Validation / validate-diagrams (push) Has been cancelled Details Spec Validation / check-todos (push) Has been cancelled Details	2025-12-04 16:50:09 +07:00
admin	d33663f7a9	251204:2300 Prepare 1.5.1 Spec Validation / validate-markdown (push) Has been cancelled Details Spec Validation / validate-diagrams (push) Has been cancelled Details Spec Validation / check-todos (push) Has been cancelled Details	2025-12-04 00:01:18 +07:00
admin	e04ec1243d	251203:1700 Prepare to version 1.6 Spec Validation / validate-markdown (push) Has been cancelled Details Spec Validation / validate-diagrams (push) Has been cancelled Details Spec Validation / check-todos (push) Has been cancelled Details	2025-12-03 17:31:40 +07:00
admin	d74218bb2a	251202:2300 Prepare 1.5.1 Spec Validation / validate-markdown (push) Has been cancelled Details Spec Validation / validate-diagrams (push) Has been cancelled Details Spec Validation / check-todos (push) Has been cancelled Details	2025-12-03 01:16:27 +07:00
admin	79344ef4b1	251202:1700 Prepare to version 1.6 Spec Validation / validate-markdown (push) Has been cancelled Details Spec Validation / validate-diagrams (push) Has been cancelled Details Spec Validation / check-todos (push) Has been cancelled Details	2025-12-02 17:29:42 +07:00
admin	8f4b28519d	251202:1300 Spec Validation / validate-markdown (push) Has been cancelled Details Spec Validation / validate-diagrams (push) Has been cancelled Details Spec Validation / check-todos (push) Has been cancelled Details	2025-12-02 13:26:05 +07:00
admin	7c32a96dcb	251202:1000 Prepare to version 1.5 use spec-kit Spec Validation / validate-markdown (push) Has been cancelled Details Spec Validation / validate-diagrams (push) Has been cancelled Details Spec Validation / check-todos (push) Has been cancelled Details	2025-12-02 10:01:47 +07:00
admin	f54a906bcd	251202:0000 Spec Validation / validate-markdown (push) Has been cancelled Details Spec Validation / validate-diagrams (push) Has been cancelled Details Spec Validation / check-todos (push) Has been cancelled Details	2025-12-02 06:58:05 +07:00
admin	00b8995f84	251201:1700 Prepare to version 1.5 use spec-kit Spec Validation / validate-markdown (push) Has been cancelled Details Spec Validation / validate-diagrams (push) Has been cancelled Details Spec Validation / check-todos (push) Has been cancelled Details	2025-12-01 17:00:32 +07:00
admin	047e1b88ce	Main: revise specs to 1.5.0 (completed) Spec Validation / validate-markdown (push) Has been cancelled Details Spec Validation / validate-diagrams (push) Has been cancelled Details Spec Validation / check-todos (push) Has been cancelled Details	2025-12-01 01:28:32 +07:00
admin	ce795b26e2	Prepare to version 1.5 use spec-kit	2025-11-30 13:58:46 +07:00
admin	c302c5f9b1	251130:0000 1.4.5 Update Backend&Frontend Plan	2025-11-30 01:38:15 +07:00
admin	138b09d0c8	251129:1700 update to 1.4.5	2025-11-29 16:50:34 +07:00
admin	6cafa6a2b9	251128:1700 Backend to T3.1.1	2025-11-28 17:12:05 +07:00
admin	43f6bd1f40	update workspace	2025-11-28 00:40:32 +07:00
admin	1883c0bb59	update extension	2025-11-27 23:55:36 +07:00
admin	f725bd5d3e	251127:1700 Frontend Start Build	2025-11-27 17:08:49 +07:00
admin	b42c8c0c9f	251126:1700 1.4.4	2025-11-26 16:43:48 +07:00
admin	bfa8d3df83	251126:1300 test run	2025-11-26 14:38:24 +07:00
admin	5fe2ea92ce	251126:1200 แก้ไข document-numbering:ข้อกำหนด, ตาราง	2025-11-26 13:24:32 +07:00
admin	13c9554be7	251125:2300 build table	2025-11-26 00:43:17 +07:00
admin	fa6f6a5fc9	251125:1200 6B	2025-11-25 21:15:02 +07:00
admin	0ce895c96a	251125:0000 Phase 6 wait start dev Check	2025-11-25 00:28:33 +07:00
admin	0e5d7e7e9e	251124:1702 Ready to Phase 7	2025-11-24 17:03:36 +07:00
admin	cb6faacba6	251124:1700 Ready to Phase 7	2025-11-24 17:01:58 +07:00
admin	3d9b6e4d05	251123:2300 Update T1	2025-11-24 08:15:15 +07:00
admin	9c970f8ed8	251123:0200 T6.1 to DO	2025-11-23 02:23:38 +07:00
admin	fe977ced6d	docs: Relocate project documentation files to a new subdirectory and add a versioned archive.	2025-11-22 20:30:51 +07:00
admin	7eb9a1a633	251122:1700 Phase 4	2025-11-22 17:21:55 +07:00
admin	6d1e2c668c	251121:1700 Backend T3 wait testt	2025-11-21 17:16:40 +07:00