@lvlup-sw/exarchos 2.0.1

package/skills/implementation-planning/references/testing-strategy-guide.md

@@ -0,0 +1,88 @@
+# Testing Strategy Guide
+
+When creating implementation plans, assign a `testingStrategy` to each task. This field controls which verification techniques agents apply during implementation.
+
+## Schema
+
+```typescript
+testingStrategy: {
+  exampleTests: true;           // Always required (literal true)
+  propertyTests: boolean;       // Property-based tests required?
+  benchmarks: boolean;          // Performance benchmarks required?
+  properties?: string[];        // Guidance: which properties to verify
+  performanceSLAs?: PerformanceSLA[]; // Guidance: performance targets
+}
+```
+
+## Category Requirements
+
+Assign `propertyTests: true` when the task involves any of these categories:
+
+| Category | Example Code | Properties to Test |
+|---|---|---|
+| **Data transformations** | Parse/serialize, encode/decode, format/unformat | Roundtrip: `decode(encode(x)) === x` |
+| **State machines** | Workflow HSM, circuit breaker, connection lifecycle | Transition validity: no invalid state reachable from any valid state |
+| **Collections/ordering** | Sort, filter, deduplicate, paginate, merge | Idempotence: `sort(sort(x)) === sort(x)` |
+| **Concurrency** | Optimistic locking, CAS, event ordering | Linearizability: concurrent operations produce valid state |
+| **Serialization** | Event schemas, API contracts, JSON/YAML/TOML | Schema compliance: output matches declared schema for all inputs |
+| **Mathematical operations** | Scoring, percentages, budgets, rates | Invariants: `score >= 0 && score <= 1.0`, conservation laws |
+
+Assign `propertyTests: false` when the task is:
+- Pure wiring (DI registration, configuration binding)
+- UI layout or styling
+- Simple CRUD without business logic
+- Documentation or content-only changes
+
+## Populating the `properties` Array
+
+When `propertyTests: true`, provide guidance strings in the `properties` array describing which properties to verify:
+
+```json
+{
+  "exampleTests": true,
+  "propertyTests": true,
+  "benchmarks": false,
+  "properties": [
+    "roundtrip: decode(encode(x)) === x for all valid inputs",
+    "idempotence: format(format(x)) === format(x)"
+  ]
+}
+```
+
+## Benchmark Requirements
+
+Assign `benchmarks: true` when the task involves any of these categories:
+
+| Category | Example Code | What to Measure |
+|---|---|---|
+| **Event store operations** | Append, query, snapshot | Throughput (ops/sec), p99 latency |
+| **View materialization** | Projection apply, cold-start rebuild | Events/sec, cold-start time |
+| **Serialization hot paths** | JSON parse/stringify, schema validation | Throughput, memory allocation |
+| **Query-heavy reads** | CQRS projections, aggregations | Query latency under load |
+
+Assign `benchmarks: false` when the task is:
+- Pure wiring, configuration, or DI registration
+- Content-only changes (Markdown, documentation)
+- Test infrastructure (test helpers, fixtures)
+- UI components or styling
+
+When `benchmarks: true`, populate `performanceSLAs` with targets:
+
+```json
+{
+  "exampleTests": true,
+  "propertyTests": false,
+  "benchmarks": true,
+  "performanceSLAs": [
+    { "operation": "event-append", "metric": "p99_ms", "threshold": 10 }
+  ]
+}
+```
+
+## Auto-Determination
+
+The planner MUST auto-determine `propertyTests` and `benchmarks` for each task based on the category tables above. Do NOT leave these fields for the implementer to decide. Analyze each task's description and file paths to match against the categories. When uncertain, default to `false`.
+
+## Reference
+
+See [Autonomous Code Verification design](../../../docs/designs/2026-02-15-autonomous-code-verification.md#when-to-require-property-based-tests) for the full rationale and category taxonomy.

package/skills/quality-review/SKILL.md

@@ -0,0 +1,278 @@
+---
+name: quality-review
+description: "Stage 2 code quality review after spec compliance passes. Use when the user says 'quality review', 'check code quality', or runs /review (stage 2). Requires spec-review to have passed first (stage 2 of /review). Checks SOLID principles, DRY, security, and test quality. Do NOT use for spec compliance — use spec-review instead. Do NOT use for brainstorming."
+metadata:
+  author: exarchos
+  version: 1.0.0
+  mcp-server: exarchos
+  category: workflow
+  phase-affinity: review
+---
+
+# Quality Review Skill
+
+## Overview
+
+Stage 2 of two-stage review: Assess code quality, maintainability, and engineering best practices.
+
+**Prerequisite:** Spec review must PASS before quality review.
+
+## Triggers
+
+Activate this skill when:
+- Spec review has passed
+- `/review` command (after spec review)
+- Ready to assess code quality
+- Before synthesis/merge
+
+## Execution Context
+
+This skill runs in a SUBAGENT spawned by the orchestrator, not inline.
+
+The orchestrator provides the state file path, diff output from `~/.claude/scripts/review-diff.sh`, task ID, and spec review results (must be PASS).
+
+The subagent reads the state file for artifact paths, uses the diff output instead of full files, runs static analysis, performs a code walkthrough, generates a report, and returns the verdict.
+
+### Context-Efficient Input
+
+Instead of reading full files, receive the integrated diff:
+
+```bash
+# Generate integrated diff for review (Graphite stack vs main)
+gt diff main > /tmp/stack-diff.patch
+
+# Alternative: git diff for integration branch
+git diff main...integration-branch > /tmp/integration-diff.patch
+
+# Alternative: use gh CLI to get PR diff
+# gh pr diff <number>
+# Or use GitHub MCP pull_request_read with method "get_diff" if available
+```
+
+This reduces context consumption by 80-90% while providing the complete picture.
+
+### Review Scope: Combined Changes
+
+After delegation completes, quality review examines:
+- The **complete stack diff** (all task branches vs main), or the **feature/integration-branch** diff when using integration branches
+- All changes across all tasks in one view
+- The full picture of combined code quality
+
+This enables catching:
+- Cross-task SOLID violations
+- Duplicate code across task boundaries
+- Inconsistent patterns between tasks
+
+## Review Scope
+
+**Quality Review focuses on:**
+- Code quality and readability
+- SOLID principles
+- Error handling
+- Test quality
+- Performance considerations
+- Security basics
+
+**Does NOT re-check:**
+- Functional completeness (spec review)
+- TDD compliance (spec review)
+
+## Review Process
+
+### Step 0: Verify Spec Review Passed (MANDATORY)
+
+Before proceeding, confirm spec review passed for all tasks:
+
+```
+action: "get", featureId: "<id>", query: "reviews"
+```
+
+If ANY task has `specReview.status !== "pass"`, STOP and return:
+```json
+{ "verdict": "blocked", "summary": "Spec review not passed — run spec-review first" }
+```
+
+### Step 1: Static Analysis
+
+Run the static analysis gate:
+
+```bash
+scripts/static-analysis-gate.sh --repo-root <repo-root>
+```
+
+The script runs lint, typecheck, and quality-check (if available), distinguishing errors from warnings.
+
+**On exit 0:** All analysis passes -- proceed to Step 2.
+**On exit 1:** Errors found -- fix before continuing review.
+
+### Step 2: Code Walkthrough
+
+Assess each modified file against the quality checklists:
+- Consult `references/code-quality-checklist.md` for code quality, SOLID, DRY, and structural criteria
+- Consult `references/security-checklist.md` for security review criteria
+- Consult `references/typescript-standards.md` for TypeScript-specific conventions (file organization, naming, patterns)
+
+### Step 2.5: Security Scan (Automated)
+
+Run automated security pattern detection:
+
+```bash
+scripts/security-scan.sh --repo-root <repo-root> --base-branch main
+```
+
+**On exit 0:** No security patterns detected.
+**On exit 1:** Potential security issues found -- include in review report.
+
+### Step 3: Generate Report
+
+Use the template from `references/review-report-template.md` to structure the review output.
+
+## Priority Levels
+
+| Priority | Action | Examples |
+|----------|--------|----------|
+| **HIGH** | Must fix before merge | Security issues, data loss risks |
+| **MEDIUM** | Should fix, may defer | SOLID violations, complexity |
+| **LOW** | Nice to have | Style preferences, minor refactors |
+
+### Priority Classification Rules
+
+- **HIGH:** security vulnerabilities, data loss risk, API contract breaks, uncaught exception paths
+- **MEDIUM:** SOLID violations (LSP, ISP), cyclomatic complexity >15, test coverage <70%
+- **LOW:** naming, code style, comment clarity, non-impactful performance
+
+If classification is ambiguous, default to MEDIUM and flag for human decision.
+
+## Fix Loop for HIGH-Priority
+
+If HIGH-priority issues found:
+
+1. Create fix task listing each HIGH finding with file, issue, and required fix
+2. Dispatch to implementer subagent
+3. Re-review quality after fixes
+4. Only mark APPROVED when all HIGH items resolved and tests pass
+
+## Required Output Format
+
+The subagent MUST return results as structured JSON. The orchestrator parses this JSON to populate state. Any other format is an error.
+
+```json
+{
+  "verdict": "pass | fail | blocked",
+  "summary": "1-2 sentence summary",
+  "issues": [
+    {
+      "severity": "HIGH | MEDIUM | LOW",
+      "category": "security | solid | dry | perf | naming | other",
+      "file": "path/to/file",
+      "line": 123,
+      "description": "Issue description",
+      "required_fix": "What must change"
+    }
+  ],
+  "test_results": {
+    "passed": 0,
+    "failed": 0,
+    "coverage_percent": 0
+  }
+}
+```
+
+## Anti-Patterns
+
+| Don't | Do Instead |
+|-------|------------|
+| Block on LOW priority | Accept and track for later |
+| Review before spec passes | Complete spec review first |
+| Be overly pedantic | Focus on impactful issues |
+| Skip security checks | Always verify basics |
+| Accept poor test quality | Tests are code too |
+| Apply generic standards to language issues | Reference language-specific rules |
+
+## Cross-Task Integration Issues
+
+If an issue spans multiple tasks:
+1. Classify as "cross-task integration"
+2. Create fix task specifying ALL affected tasks
+3. Dispatch fix to implementer with context from all affected tasks
+4. Mark original tasks as blocked until cross-task fix completes
+
+## State Management
+
+**On review complete:**
+```
+action: "set", featureId: "<id>", updates: {
+  "reviews": { "quality": { "status": "pass", "summary": "...", "issues": [...] } }
+}
+```
+
+**On all reviews pass — advance to synthesis:**
+```
+action: "set", featureId: "<id>", phase: "synthesize"
+```
+
+## Completion Criteria
+
+- [ ] Static analysis passes
+- [ ] All HIGH-priority issues fixed
+- [ ] No security vulnerabilities
+- [ ] Test quality acceptable
+- [ ] Code is maintainable
+- [ ] State file updated with review results
+
+## Determine Verdict
+
+Classify review findings into a routing verdict:
+
+```bash
+scripts/review-verdict.sh --high <N> --medium <N> --low <N>
+```
+
+**On exit 0 (APPROVED):** Proceed to synthesis.
+**On exit 1 (NEEDS_FIXES):** Route to `/exarchos:delegate --fixes`.
+**On exit 2 (BLOCKED):** Return to design phase.
+
+## Transition
+
+All transitions happen **immediately** without user confirmation:
+
+### If APPROVED:
+1. Update state: `action: "set", featureId: "<id>", phase: "synthesize"`
+2. Output: "Quality review passed. Auto-continuing to synthesis..."
+3. Auto-invoke synthesize:
+   ```typescript
+   Skill({ skill: "exarchos:synthesize", args: "<feature-name>" })
+   ```
+
+### If NEEDS_FIXES:
+1. Update state: `action: "set", featureId: "<id>", updates: { "reviews": { "quality": { "status": "fail", "issues": [...] } } }`
+2. Output: "Quality review found [N] HIGH-priority issues. Auto-continuing to fixes..."
+3. Auto-invoke delegate with fix tasks:
+   ```typescript
+   Skill({ skill: "exarchos:delegate", args: "--fixes <plan-path>" })
+   ```
+
+### If BLOCKED:
+1. Update state: `action: "set", featureId: "<id>", phase: "blocked"`
+2. Output: "Quality review blocked: [issue]. Returning to design..."
+3. Auto-invoke ideate for redesign:
+   ```typescript
+   Skill({ skill: "exarchos:ideate", args: "--redesign <feature-name>" })
+   ```
+
+This is NOT a human checkpoint - workflow continues autonomously.
+
+## Exarchos Integration
+
+When Exarchos MCP tools are available, emit gate events during review:
+
+1. **Read CI status** via `gh pr checks <number>` (or GitHub MCP `pull_request_read` with method `get_status` if available)
+2. **Emit gate events** via `exarchos_event` with `action: "append"`, type `gate.executed` (include `gateName`, `layer`, `passed`, `duration`)
+3. **Read unified status** via `exarchos_view` with `action: "tasks"`, `fields: ["taskId", "status", "title"]`, `limit: 20`
+4. **When all per-PR gates pass**, apply `stack-ready` label to the PR
+
+## Performance Notes
+
+- Complete each step fully before advancing — quality over speed
+- Do not skip validation checks even when the change appears trivial
+- Read each checklist file completely before scoring. Do not skip security or SOLID checks even for small changes.

package/skills/quality-review/references/code-quality-checklist.md

@@ -0,0 +1,159 @@
+# Code Quality Checklist
+
+Detailed review criteria for code quality, SOLID principles, DRY enforcement, and structural standards. Used during Step 2 of the quality review process.
+
+## 1. Code Quality
+
+| Aspect | Check For |
+|--------|-----------|
+| Readability | Clear variable/function names |
+| Complexity | Functions <30 lines, single responsibility |
+| Duplication | DRY - no copy-paste code |
+| Comments | Only where logic isn't self-evident |
+| Formatting | Consistent with project style |
+
+## 1.1 DRY Enforcement
+
+| Pattern | Threshold | Priority |
+|---------|-----------|----------|
+| Identical code blocks | 3+ occurrences OR 5+ lines | HIGH (3+), MEDIUM (2) |
+| Similar code (literals differ) | 3+ occurrences | MEDIUM |
+| Repeated validation logic | 2+ locations | HIGH |
+| Repeated business rules | 2+ locations | HIGH |
+| Copy-pasted tests | 3+ similar tests | LOW |
+| Magic literals | Same value 3+ times | MEDIUM |
+
+**Detection approach (prefer MCP tools):**
+- Use `search_for_pattern` to find duplicate code blocks
+- Use `find_referencing_symbols` to trace dependency usage
+- Use `get_symbols_overview` to understand module structure
+
+**Detection checklist:**
+- [ ] Search for identical multi-line blocks (5+ lines duplicated)
+- [ ] Flag validation code outside designated validation layer
+- [ ] Trace business rule conditionals - must have single source
+- [ ] Check for repeated string/number literals without constants
+
+## 2. SOLID Principles
+
+| Principle | Verify | Specific Checks |
+|-----------|--------|-----------------|
+| **S**RP | One reason to change | Max 1 public type/file; class name matches responsibility |
+| **O**CP | Extensible without modification | No switch/if-else on types; uses strategy/polymorphism |
+| **L**SP | Subtypes substitutable | No `NotImplementedException`; no precondition strengthening |
+| **I**SP | No forced dependencies | Interface <= 5 methods; no empty implementations |
+| **D**IP | Depend on abstractions | No `new` for services; constructor injection only |
+
+### ISP Violation Patterns
+
+| Pattern | Detection | Priority |
+|---------|-----------|----------|
+| Fat interface (> 5 methods) | Count methods on interface | MEDIUM |
+| Mixed read/write interface | Check for getters + mutators together | MEDIUM |
+| Empty/throw implementations | Scan for `NotImplementedException`, empty bodies | HIGH |
+| Vague interface names | `IService`, `IManager`, `IHandler` without qualifier | LOW |
+| Partial interface usage | Client uses < 50% of interface methods | MEDIUM |
+
+**ISP Checklist:**
+- [ ] No interface has more than 5 methods
+- [ ] Interfaces are role-specific (IReadable, IWritable, not IDataAccess)
+- [ ] No classes implement interfaces with NotImplementedException
+- [ ] Interface names describe a single capability
+
+## 2.1 Control Flow Standards
+
+| Standard | Check For |
+|----------|-----------|
+| Guard clauses | Validate at method entry, not nested |
+| Early returns | Exit as soon as result is known |
+| No arrow code | Deeply nested if/else is a smell |
+| Conditional abstraction | Large switch/if-else extracted to helper |
+
+### Guard Clause Pattern
+
+**Preferred:**
+```typescript
+if (input == null) return;
+// Main logic flat
+```
+
+**Avoid:**
+```typescript
+if (input != null) {
+  // Entire body nested
+}
+```
+
+## 2.2 Structural Standards
+
+| Standard | Check For | Priority |
+|----------|-----------|----------|
+| One responsibility per file | Public types in dedicated files | HIGH |
+| Composition over inheritance | See checklist below | MEDIUM-HIGH |
+| Sealed by default | `sealed` unless designed for extension | LOW |
+
+### Composition Over Inheritance Checklist
+
+| Smell | Detection | Priority | Fix |
+|-------|-----------|----------|-----|
+| Inheritance depth > 2 | Count hierarchy levels | MEDIUM | Refactor to delegation |
+| Base class, multiple concerns | Base has unrelated methods | MEDIUM | Split into interfaces + composition |
+| `protected` for code sharing | Many protected methods (> 2/class) | MEDIUM | Extract to utility or inject strategy |
+| Override that only extends | `super.method()` + additions | MEDIUM | Use decorator pattern |
+| Inherit for one method | Extends to reuse single method | HIGH | Compose with delegation |
+
+**Composition Checklist:**
+- [ ] Inheritance represents true "is-a" relationship, not code reuse
+- [ ] Class hierarchy depth <= 2
+- [ ] `protected` methods rare (< 2 per class)
+- [ ] No override methods that just call super + add logic
+
+**Language-specific rules:** See `~/.claude/rules/coding-standards-{language}.md`
+
+## 3. Error Handling
+
+| Check | Verify |
+|-------|--------|
+| Errors caught | Try/catch where needed |
+| Errors meaningful | Clear error messages |
+| Errors propagated | Proper error bubbling |
+| No silent failures | All errors handled or logged |
+| Input validation | At system boundaries |
+
+## 4. Test Quality
+
+| Aspect | Verify |
+|--------|--------|
+| Arrange-Act-Assert | Clear test structure |
+| Test isolation | No shared state issues |
+| Meaningful assertions | Not just "expect(true)" |
+| Edge cases | Boundary conditions tested |
+| Error paths | Failure scenarios covered |
+
+## 5. Performance
+
+| Check | Verify |
+|-------|--------|
+| No N+1 queries | Batch operations used |
+| Efficient algorithms | No obvious O(n^2) when O(n) works |
+| Memory management | No leaks, proper cleanup |
+| Async patterns | Proper await usage |
+
+## 6. Frontend Aesthetics (if applicable)
+
+For frontend code (React, Vue, HTML/CSS, etc.), verify distinctive design:
+
+| Check | Verify |
+|-------|--------|
+| Distinctive typography | Not using Inter, Roboto, Arial, or system defaults |
+| Intentional color palette | CSS variables defined, not ad-hoc colors |
+| Purposeful motion | Orchestrated animations, not scattered micro-interactions |
+| Atmospheric backgrounds | Layered/textured, not flat solid colors |
+| Overall distinctiveness | Doesn't exhibit "AI slop" patterns |
+
+**Anti-patterns to flag:**
+- Purple gradients on white backgrounds
+- Perfectly centered symmetric layouts
+- Generic font choices
+- Flat #f5f5f5 or pure white/black backgrounds
+- Animation without purpose

package/skills/quality-review/references/review-report-template.md

@@ -0,0 +1,65 @@
+# Quality Review Report Template
+
+Use this template to structure the output of Step 3 (Generate Report) in the quality review process.
+
+## Template
+
+```markdown
+## Quality Review Report
+
+### Summary
+- Status: [APPROVED | NEEDS_FIXES | BLOCKED]
+- Reviewed: [timestamp]
+- Reviewer: Claude Code
+
+### Findings Summary
+
+| Severity | Category | File:Line | Issue |
+|----------|----------|-----------|-------|
+| HIGH | [category] | `path/to/file.ts:42` | [Brief description] |
+| MEDIUM | [category] | `path/to/file.ts:88` | [Brief description] |
+| LOW | [category] | `path/to/file.ts:15` | [Brief description] |
+
+### Findings Detail
+
+#### HIGH-Priority
+1. [Finding title]
+   - File: `path/to/file.ts:42`
+   - Category: [security | correctness | performance | maintainability]
+   - Current: [What the code does now]
+   - Fix: [Required change]
+
+#### MEDIUM-Priority
+1. [Finding title]
+   - File: `path/to/file.ts:88`
+   - Category: [security | correctness | performance | maintainability]
+   - Current: [What the code does now]
+   - Suggestion: [Recommended change]
+
+#### LOW-Priority
+1. [Finding title]
+   - File: `path/to/file.ts:15`
+   - Category: [style | documentation | optimization]
+   - Note: [Observation]
+
+### Verdict
+[APPROVED] Ready for synthesis
+[NEEDS_FIXES] Fix HIGH-priority items, then re-review
+[BLOCKED] Critical issues require design discussion
+```
+
+## Verdict Criteria
+
+| Verdict | Condition |
+|---------|-----------|
+| **APPROVED** | No HIGH-priority findings; MEDIUM/LOW acceptable |
+| **NEEDS_FIXES** | One or more HIGH-priority findings that must be resolved |
+| **BLOCKED** | Critical architectural or security issues requiring design discussion |
+
+## Report Guidelines
+
+- List every finding with file path and line number
+- HIGH-priority findings must include a concrete fix description
+- MEDIUM priority findings should include a suggested approach
+- LOW priority findings are observations for future improvement
+- The verdict drives the next workflow transition (synthesize, fix loop, or redesign)

package/skills/quality-review/references/security-checklist.md

@@ -0,0 +1,79 @@
+# Security Review Checklist
+
+Security review criteria based on OWASP Top 10 patterns. Used during Step 2 of the quality review process.
+
+## Security Basics
+
+| Check | Verify |
+|-------|--------|
+| Input sanitization | User input validated |
+| No secrets in code | Use environment variables |
+| SQL injection | Parameterized queries |
+| XSS prevention | Output encoding |
+
+## OWASP Top 10 (2021) Patterns
+
+When reviewing code that handles user input, authentication, or data access, check for these common vulnerability patterns:
+
+### Broken Access Control (A01)
+- Authorization checks on every endpoint
+- No direct object references without access validation
+- Default deny for permissions
+
+### Cryptographic Failures (A02)
+- No secrets, API keys, or credentials in source code
+- Sensitive data encrypted at rest and in transit
+- PII properly handled per data classification
+
+### Injection (A03)
+- SQL queries use parameterized statements, never string concatenation
+- Shell commands use safe APIs, never template strings with user input
+- Output encoding applied to all user-controlled data (XSS)
+- Content Security Policy headers set
+
+### Insecure Design (A04)
+- Threat modeling performed for critical flows
+- Business logic validated server-side
+- Rate limiting and resource controls in place
+
+### Security Misconfiguration (A05)
+- No debug mode in production config
+- Error messages don't leak stack traces or internal details
+- Security headers configured (CORS, CSP, HSTS)
+
+### Vulnerable and Outdated Components (A06)
+- Dependencies checked for known vulnerabilities
+- No end-of-life frameworks or libraries
+- Component versions tracked and updated
+
+### Identification and Authentication Failures (A07)
+- Passwords are hashed with bcrypt/argon2, never stored in plaintext
+- Session tokens have sufficient entropy
+- Rate limiting on authentication endpoints
+
+### Software and Data Integrity Failures (A08)
+- User input is validated before deserialization
+- Type checking enforced on deserialized objects
+- No eval() or equivalent on untrusted data
+- CI/CD pipeline integrity verified
+
+### Security Logging and Monitoring Failures (A09)
+- Security-relevant events are logged
+- Logs do not contain sensitive data
+- Alerting configured for suspicious activity
+
+### Server-Side Request Forgery (A10)
+- URL inputs validated against allowlists
+- Internal network access restricted from user-controlled requests
+- DNS rebinding protections in place
+
+## Detection Checklist
+
+- [ ] No hardcoded secrets or API keys
+- [ ] All user input validated at system boundaries
+- [ ] SQL/NoSQL queries use parameterized statements
+- [ ] Output encoding applied for XSS prevention
+- [ ] Authentication uses secure hashing algorithms
+- [ ] Authorization checks present on all endpoints
+- [ ] Error messages do not expose internal details
+- [ ] Dependencies checked for known vulnerabilities

package/skills/quality-review/references/typescript-standards.md

@@ -0,0 +1,24 @@
+# TypeScript Standards
+
+## File Organization
+
+- **One primary export per file**: Main class/function/component as default or named export
+- **Barrel exports OK**: `index.ts` can re-export from module
+- **Co-locate tests**: `component.test.ts` alongside `component.ts`
+
+## Type Design
+
+| Rule | Standard |
+|------|----------|
+| Interfaces over type aliases | For object shapes that might be extended |
+| Discriminated unions | For type-safe variant handling |
+| `readonly` by default | For properties that shouldn't change |
+| No `any` | Use `unknown` with type guards or proper generics |
+| Strict mode | `strict: true` in tsconfig required |
+
+## Modern TypeScript
+
+- **Const assertions**: Use `as const` for literal types
+- **Template literal types**: For string pattern validation
+- **No assertions without guards**: `as` requires prior type check
+- **Satisfies operator**: For type checking without widening