universal-dev-standards 4.2.0 → 5.0.0-beta.10

package/bundled/core/project-context-memory.md

@@ -0,0 +1,180 @@
+# Project Context Memory Standards
+
+> **Language**: English | [繁體中文](../locales/zh-TW/core/project-context-memory.md)
+
+**Version**: 1.0.0
+**Last Updated**: 2026-02-09
+**Applicability**: All software projects using AI assistants
+**Scope**: uds-specific
+
+---
+
+## Purpose
+
+This standard defines a structured system for capturing, retrieving, and enforcing **project-specific** context, architectural decisions, and domain knowledge. Unlike Developer Memory (which is universal and transferable), Project Context Memory acts as the "long-term brain" for a specific codebase, ensuring AI assistants adhere to local conventions and historical decisions.
+
+---
+
+## Quick Reference
+
+### Memory Entry Schema
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | string | Unique identifier (`PRJ-YYYY-NNNN`) |
+| `type` | enum | `decision` / `convention` / `structure` / `glossary` |
+| `summary` | string | One-sentence summary of the context |
+| `status` | enum | `active` / `proposed` / `deprecated` |
+| `scope` | list | Files or directories this applies to |
+
+### Storage Location
+
+Entries are stored in **Markdown with YAML Frontmatter** to ensure both human readability (documentation) and machine parsability.
+
+- **Directory**: `.project-context/`
+- **Format**: `.md` files
+
+---
+
+## 1. Memory Schema
+
+### 1.1 Full Schema Definition
+
+```markdown
+---
+id: "PRJ-2026-0001"              # Required: Unique ID
+type: decision                   # Required: Category
+status: active                   # Required: active | proposed | deprecated
+created_at: "2026-02-09"         # Required: ISO date
+confidence: 1.0                  # Required: 0.0–1.0 (Project facts usually start high)
+authors: ["user-name", "ai-assistant"]
+
+# Scope & Triggers (Context Awareness)
+scope:                           # Where this rule applies
+  - "src/api/**"
+  - "src/services/**"
+triggers:                        # Keywords/patterns to wake up this memory
+  - "error handling"
+  - "API response"
+  - "try-catch"
+
+# Relationships
+related: ["PRJ-2026-0004"]       # Related project memories
+supersedes: []                   # IDs of decisions this replaces
+---
+
+# Unified API Error Handling
+
+## Context
+We previously handled errors inconsistently across controllers, leading to frontend parsing issues.
+
+## Decision
+All API endpoints must return errors in the `StandardErrorResponse` format defined in `src/types/api.ts`.
+Do not throw raw exceptions in controllers; wrap them in `ApiError` class.
+
+## Constraint
+- Forbidden: `res.status(500).json({ error: err.message })`
+- Required: `next(new ApiError(500, 'internal_error', err.message))`
+```
+
+### 1.2 ID Format
+
+| Component | Format | Example |
+|-----------|--------|---------|
+| Prefix | `PRJ` | `PRJ` |
+| Year | `YYYY` | `2026` |
+| Sequence | `NNNN` | `0001` |
+| Full | `PRJ-YYYY-NNNN` | `PRJ-2026-0001` |
+
+---
+
+## 2. Memory Categories (Taxonomy)
+
+| Category | Description | Example |
+|----------|-------------|---------|
+| `decision` | Architectural Decision Records (Lightweight ADRs) | "Use Hexagonal Architecture for core domain" |
+| `convention` | Mandatory coding styles or patterns | "All interface names must start with 'I'" |
+| `structure` | Directory responsibilities and boundaries | "`src/shared` must not import from `src/features`" |
+| `glossary` | Ubiquitous Language / Domain Terms | "'User' refers to Admin; 'Customer' is the end-user" |
+| `constraint` | Hard technical limits or bans | "No usage of `lodash` (use native ES6+)" |
+| `workflow` | Process-specific rules | "Migrations must be generated via CLI, not manual SQL" |
+
+---
+
+## 3. Operations Protocol
+
+### 3.1 Proactive Extraction (Record)
+
+The AI must actively listen for "Consensus Moments" in the conversation.
+
+**Triggers:**
+*   "Let's agree to..."
+*   "From now on, we use..."
+*   "The architecture should be..."
+*   Repeatedly correcting the AI on the same project-specific rule.
+
+**Workflow:**
+1.  AI detects a consensus or rule.
+2.  AI proposes: "This seems like a project-level decision. Should I save it to Project Context?"
+3.  User confirms.
+4.  AI generates a `.project-context/topic-name.md` file.
+
+### 3.2 Context Injection (Query)
+
+**Triggers:**
+*   **Planning Phase**: When the user asks to "build a feature", scan `structure` and `decision` memories.
+*   **Coding Phase**: When editing a file in `scope`, scan `convention` memories.
+*   **Review Phase**: Check if code violates `constraint` memories.
+
+**Behavior:**
+*   AI must **read** relevant context files *before* generating code.
+*   AI must **cite** the memory ID when enforcing a rule (e.g., "Per PRJ-2026-0012, I'm using the factory pattern here").
+
+### 3.3 Lifecycle Management (Review)
+
+**Staleness Detection:**
+*   If a file path mentioned in `scope` no longer exists.
+*   If a code pattern mentioned in `Constraint` is nowhere to be found.
+*   AI should proactively ask: "Is PRJ-2025-0045 still active?"
+
+**Deprecation:**
+*   When a new `decision` contradicts an old one, the old one's `status` changes to `deprecated`, and `supersedes` field is updated in the new one.
+
+---
+
+## 4. Comparison with Developer Memory
+
+| Feature | Developer Memory (`core/developer-memory.md`) | Project Context Memory (`core/project-context-memory.md`) |
+| :--- | :--- | :--- |
+| **Scope** | Universal / Cross-Project | **Local / Project-Specific** |
+| **Privacy** | De-identified (Strict) | **Identified** (Specific paths/names allowed) |
+| **Content** | "How to use React useEffect" | "How WE use React in THIS app" |
+| **Storage** | `.memory/` (Global/User) | `.project-context/` (Repo) |
+| **Goal** | Skill Acquisition | **Consistency & Compliance** |
+
+---
+
+## 5. Architecture Decision
+
+### 5.1 "Always-On" Protocol
+Like Developer Memory, Project Context is an **Always-On Protocol**. The AI does not need explicit commands to use it. It is part of the "Physics" of the agent's environment.
+
+### 5.2 Storage Strategy
+We use **Split-File Storage** (one Markdown file per topic) rather than a single huge `GEMINI.md` or JSON file.
+*   **Reason 1**: Git-friendly diffs.
+*   **Reason 2**: Lower token usage (AI only reads relevant files based on `scope/triggers`).
+*   **Reason 3**: Human-readable documentation.
+
+---
+
+## Version History
+
+| Version | Date | Changes |
+|---------|------|---------|
+| 1.0.0 | 2026-02-09 | Initial standard definition |
+
+---
+
+## License
+
+This standard is released under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/).

package/bundled/core/project-structure.md

@@ -1,8 +1,11 @@
 # Project Structure Standard
 
-**Version**: 1.0.1
-**Last Updated**: 2025-12-24
+**Version**: 1.1.0
+**Last Updated**: 2026-01-24
 **Applicability**: All software projects
+**Scope**: partial
+**Industry Standards**: Maven Standard Directory Layout
+**References**: [github.com](https://github.com/golang-standards/project-layout)
 
 **English** | [繁體中文](../locales/zh-TW/core/project-structure.md)
 
@@ -222,6 +225,311 @@ project-root/
 
 ---
 
+## Monorepo vs Polyrepo Decision Guide
+
+### Decision Matrix
+
+Use this matrix to determine which approach fits your project:
+
+| Factor | Monorepo Favored | Polyrepo Favored |
+|--------|------------------|------------------|
+| **Code Sharing** | High (shared libs, components) | Low (independent services) |
+| **Team Structure** | Single team or tight collaboration | Autonomous teams |
+| **Release Cadence** | Coordinated releases | Independent releases |
+| **CI/CD Complexity** | Unified pipeline acceptable | Need isolated pipelines |
+| **Repository Size** | < 5GB, < 1M files | Large assets, long history |
+| **Dependency Management** | Centralized version control | Team-specific versions OK |
+| **Tooling Investment** | Willing to invest in tooling | Prefer simple git workflow |
+
+### Decision Flowchart
+
+```
+┌─────────────────────────────────────────┐
+│ Do multiple projects share significant  │
+│ code or dependencies?                   │
+└───────────────┬─────────────────────────┘
+                │
+        ┌───────┴───────┐
+        ▼               ▼
+       YES              NO
+        │               │
+        ▼               ▼
+┌───────────────┐ ┌─────────────────────┐
+│ Consider      │ │ Do teams need       │
+│ MONOREPO      │ │ release independence│
+└───────┬───────┘ └──────────┬──────────┘
+        │                    │
+        ▼            ┌───────┴───────┐
+┌───────────────┐    ▼               ▼
+│ Can you invest│   YES              NO
+│ in tooling?   │    │               │
+└───────┬───────┘    ▼               ▼
+        │      ┌──────────┐   ┌──────────┐
+┌───────┴───────┐│ POLYREPO │   │ MONOREPO │
+▼               ▼└──────────┘   │ may work │
+YES            NO               └──────────┘
+│               │
+▼               ▼
+┌──────────┐  ┌──────────┐
+│ MONOREPO │  │ POLYREPO │
+│ (full)   │  │ (simpler)│
+└──────────┘  └──────────┘
+```
+
+---
+
+## Monorepo Tools Comparison
+
+### Tool Selection Matrix
+
+| Feature | Turborepo | Nx | Lerna | Rush |
+|---------|-----------|----|----|------|
+| **Primary Use** | Task running | Full framework | Publishing | Enterprise |
+| **Learning Curve** | Low | Medium-High | Low | High |
+| **Build Speed** | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐⭐⭐ |
+| **Remote Caching** | ✅ Built-in | ✅ Nx Cloud | ❌ Manual | ✅ Built-in |
+| **Code Generation** | ❌ | ✅ Extensive | ❌ | ❌ |
+| **Affected Detection** | ✅ | ✅ | ✅ | ✅ |
+| **Framework Support** | Framework-agnostic | React, Angular, etc. | Any | Any |
+| **Maintenance** | Vercel | Nrwl | Lerna-Lite fork | Microsoft |
+| **Best For** | Small-medium teams | Large teams, enterprise | Simple publishing | Enterprise-scale |
+
+### Quick Selection Guide
+
+**Choose Turborepo if**:
+- You want minimal configuration
+- Primary need is fast builds with caching
+- Team is small to medium (< 50 developers)
+- You prefer convention over configuration
+
+**Choose Nx if**:
+- You need code generation and scaffolding
+- You want built-in framework integrations
+- Team is large or enterprise-scale
+- You need advanced dependency graph visualization
+
+**Choose Lerna if**:
+- Primary need is npm package publishing
+- You want simple, familiar tooling
+- You're migrating from individual packages
+
+**Choose Rush if**:
+- You're in an enterprise environment
+- You need strict dependency isolation
+- You have complex approval workflows
+- You're using pnpm at scale
+
+### Turborepo Example
+
+```json
+// turbo.json
+{
+  "$schema": "https://turbo.build/schema.json",
+  "globalDependencies": [".env"],
+  "tasks": {
+    "build": {
+      "dependsOn": ["^build"],
+      "outputs": ["dist/**", ".next/**"]
+    },
+    "test": {
+      "dependsOn": ["build"],
+      "inputs": ["src/**", "test/**"]
+    },
+    "lint": {
+      "dependsOn": ["^lint"]
+    },
+    "dev": {
+      "cache": false,
+      "persistent": true
+    }
+  }
+}
+```
+
+### Nx Example
+
+```json
+// nx.json
+{
+  "$schema": "./node_modules/nx/schemas/nx-schema.json",
+  "targetDefaults": {
+    "build": {
+      "dependsOn": ["^build"],
+      "cache": true
+    },
+    "test": {
+      "cache": true
+    }
+  },
+  "namedInputs": {
+    "default": ["{projectRoot}/**/*"],
+    "production": ["default", "!{projectRoot}/**/*.spec.ts"]
+  },
+  "defaultBase": "main"
+}
+```
+
+---
+
+## Workspace Configuration
+
+### pnpm Workspaces
+
+```yaml
+# pnpm-workspace.yaml
+packages:
+  - 'apps/*'
+  - 'packages/*'
+  - 'tools/*'
+```
+
+```json
+// package.json (root)
+{
+  "name": "my-monorepo",
+  "private": true,
+  "scripts": {
+    "build": "turbo run build",
+    "dev": "turbo run dev",
+    "test": "turbo run test",
+    "lint": "turbo run lint"
+  },
+  "devDependencies": {
+    "turbo": "^2.0.0"
+  }
+}
+```
+
+### Yarn Workspaces
+
+```json
+// package.json (root)
+{
+  "name": "my-monorepo",
+  "private": true,
+  "workspaces": [
+    "apps/*",
+    "packages/*"
+  ],
+  "scripts": {
+    "build": "yarn workspaces foreach -pt run build",
+    "test": "yarn workspaces foreach run test"
+  }
+}
+```
+
+### npm Workspaces
+
+```json
+// package.json (root)
+{
+  "name": "my-monorepo",
+  "private": true,
+  "workspaces": [
+    "apps/*",
+    "packages/*"
+  ],
+  "scripts": {
+    "build": "npm run build --workspaces",
+    "test": "npm run test --workspaces --if-present"
+  }
+}
+```
+
+---
+
+## Package-based Architecture
+
+### Concept
+
+Package-based architecture organizes code by **feature boundaries** rather than technical layers. Each package is a self-contained unit with clear interfaces.
+
+```
+Traditional (Layer-based)          Package-based (Feature-based)
+─────────────────────────          ────────────────────────────
+src/                               packages/
+├── controllers/                   ├── authentication/
+│   ├── userController.js         │   ├── api/
+│   └── orderController.js        │   ├── domain/
+├── services/                      │   ├── infrastructure/
+│   ├── userService.js            │   └── index.ts
+│   └── orderService.js           ├── orders/
+├── models/                        │   ├── api/
+│   ├── user.js                   │   ├── domain/
+│   └── order.js                  │   ├── infrastructure/
+└── repositories/                  │   └── index.ts
+    ├── userRepository.js         └── shared/
+    └── orderRepository.js            ├── database/
+                                      └── utils/
+```
+
+### Benefits
+
+| Benefit | Description |
+|---------|-------------|
+| **Clear Boundaries** | Each package has explicit public API |
+| **Independent Testing** | Test packages in isolation |
+| **Parallel Development** | Teams work on separate packages |
+| **Selective Deployment** | Deploy only changed packages |
+| **Code Ownership** | Clear ownership per package |
+
+### Package Structure Template
+
+```
+packages/feature-name/
+├── package.json          # Package metadata
+├── tsconfig.json         # TypeScript config (if applicable)
+├── src/
+│   ├── index.ts          # Public API exports
+│   ├── api/              # External interfaces (REST, GraphQL, etc.)
+│   ├── domain/           # Business logic
+│   │   ├── entities/
+│   │   ├── services/
+│   │   └── events/
+│   └── infrastructure/   # External integrations
+│       ├── database/
+│       └── external-services/
+├── tests/
+│   ├── unit/
+│   └── integration/
+└── README.md             # Package documentation
+```
+
+### Public API Design
+
+```typescript
+// packages/authentication/src/index.ts
+// Only export what other packages need
+
+// Domain types
+export type { User, AuthToken, AuthResult } from './domain/types';
+
+// Service interfaces
+export { AuthService } from './domain/services/auth-service';
+
+// API handlers (if needed by other packages)
+export { createAuthRouter } from './api/routes';
+
+// Do NOT export internal implementation details
+// ❌ export { hashPassword } from './infrastructure/crypto';
+```
+
+### Inter-Package Dependencies
+
+```json
+// packages/orders/package.json
+{
+  "name": "@myorg/orders",
+  "version": "1.0.0",
+  "dependencies": {
+    "@myorg/authentication": "workspace:*",
+    "@myorg/shared": "workspace:*"
+  }
+}
+```
+
+---
+
 ## IDE and Editor Artifacts
 
 ### Common Artifacts to Gitignore
@@ -334,6 +642,7 @@ Before committing, verify:
 
 | Version | Date | Changes |
 |---------|------|---------|
+| 1.1.0 | 2026-01-24 | Added: Monorepo vs Polyrepo decision guide, Monorepo tools comparison (Turborepo, Nx, Lerna, Rush), Workspace configuration examples, Package-based Architecture |
 | 1.0.1 | 2025-12-24 | Added: Related Standards section |
 | 1.0.0 | 2025-12-11 | Initial project structure standard |
 
@@ -346,6 +655,10 @@ Before committing, verify:
 - [Python Packaging User Guide](https://packaging.python.org/en/latest/)
 - [Standard Go Project Layout](https://github.com/golang-standards/project-layout)
 - [Maven Standard Directory Layout](https://maven.apache.org/guides/introduction/introduction-to-the-standard-directory-layout.html)
+- [Turborepo Documentation](https://turbo.build/repo/docs) - Modern build system for JavaScript/TypeScript monorepos
+- [Nx Documentation](https://nx.dev/getting-started/intro) - Smart monorepo tool with advanced features
+- [pnpm Workspaces](https://pnpm.io/workspaces) - Fast, disk-efficient package manager workspaces
+- [Monorepo Explained](https://monorepo.tools/) - Comprehensive guide to monorepo tools
 
 ---