diff --git a/CLAUDE.md b/CLAUDE.md index ef112e0e..da36b91c 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -2,6 +2,17 @@ This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. +## ⚖️ Governance: AGENTS.md v16.0 Strategic Principles + +**All work — code changes, refactors, new features, tooling — must follow AGENTS.md v16.0 guidelines:** + +- **13 Decision Criteria:** SOLID, complexity, data integrity, necessity-driven, normalization, simplicity, patterns, guardrails, traceability, reliability, maturity, right-way, tech debt +- **Work Checklist:** Every task must self-assess against 13-item decision framework before implementation +- **Anti-Patterns (Blockers):** Never gold-plate, never skip testing, never SELECT *, never magic numbers, never direct module-to-module table access +- **Tech Debt:** Recorded in registry with Impact/Effort; 20% quarterly paydown target + +**Reference:** See `AGENTS.md` section "v16.0 Strategic Architecture & Engineering Excellence" for full framework. + ## Project Overview **K-ArtSell Aegis v16.0** is a complex financial/investment advisory system built on a **Modular Monolith** with **Vertical Slice** architecture. It enforces strict execution completeness, evidence preservation, and controlled model operations—not production-ready until all validation gates (252+ trading days shadow, OOS testing, PBO/DSR verification) pass. @@ -390,33 +401,56 @@ pnpm exec playwright test --headed # Run with browser UI ## Guardrails & Anti-Patterns -### Coding Standards (from VIBE_CODING_GUARDRAILS.md) +### ✅ Work Decision Checklist (from AGENTS.md v16.0) -**Before requesting code changes, ensure these 8 inputs are present:** -1. **Source:** Reference policy, ADR, data contract, requirement ID -2. **Slice Spec:** User goal, non-goal, state transitions, RBAC -3. **Screen Spec:** Component tree, state management, a11y -4. **Contract:** Endpoint paths, event schemas, HTTP status codes, ETag/idempotency handling -5. **Data:** Schema, columns, PIT conditions, migration, index plan -6. **Tests:** Unit/integration/data/E2E/Golden scenarios + failure cases -7. **Ops:** Metrics, alerts, runbooks, rollback procedure, on-call owner -8. **Output Rule:** Changed files, commands to verify, assumptions, residual risks +Before writing code, verify: -### Blocking Rules -- **No undocumented policy IDs or thresholds.** Every numeric constant must trace to a requirement. -- **Pending decisions:** Mark with `DECISION_REQUIRED` or `DESIGN_PROPOSAL` comment. -- **One PR = one slice or one refactoring goal.** No mixing feature work + unrelated cleanup. -- **Feature changes ≠ refactoring.** Separate PRs: feature, then refactoring, then verify. -- **Never hide failing/skipped tests.** If a test fails, fix it or raise an issue. -- **SQL review:** Generated SQL must pass schema owner review, PIT validation, index analysis. -- **Algorithm changes:** Never merge without Golden/Frozen OOS diff showing no regression. -- **Real customer data:** Never include in prompts, fixtures, or logs. +- [ ] **SOLID:** Single responsibility? Dependency inversion? Substitutable abstractions? +- [ ] **Complexity:** Cyclomatic complexity ≤ 10 per method? (Policy exceptions allowed) +- [ ] **Audit:** Evidence/Revision tracked? PIT query present? `published_at <= cutoff`? +- [ ] **Necessity:** Grounded in requirement/ADR/issue? Not "might need later"? +- [ ] **Normalization:** Writes are 3NF + append + revision? Reads use denormalized projections? +- [ ] **Simplicity:** Top→bottom readability? No hidden assumptions? No magic values? +- [ ] **Pattern:** Follows Vertical Slice / Job / Component standard? Approved contract? +- [ ] **Guardrails:** Source/Assumption/Decision documented? AI decisions traced? +- [ ] **Traceability:** Artifact preserved? Reproducible? Linked to ADR/Issue/Debt ID? +- [ ] **Safety:** Idempotent? Rollback-safe? Failure modes handled? No partial success? +- [ ] **Maturity:** Contract/schema/test BEFORE implementation? No placeholders merged? +- [ ] **Right Way:** No shortcuts (--no-verify, force push)? Root cause fixed? Code reviewed? +- [ ] **Debt:** Tech debt registered with ID? Paydown target met? No new unbounded debt? + +### AI Input Packet (from VIBE_CODING_GUARDRAILS.md) + +**Before requesting code from Claude, provide all 8:** + +1. **Source:** Policy ID, ADR, requirement, data contract, reference implementation +2. **Slice Spec:** User goal, non-goal, state transitions, RBAC constraints +3. **Screen Spec:** Component tree, state ownership, a11y requirements +4. **Contract:** Endpoint path/verb, event schema, status codes, idempotency, ETag handling +5. **Data:** Schema (3NF write model), columns, PIT conditions, migration strategy, index plan +6. **Tests:** Unit/integration/data/E2E/Golden scenarios, failure cases, replay scenarios +7. **Ops:** Metrics, alerts, runbook, rollback procedure, owner/secondary +8. **Output Rule:** Changed files, verification commands, assumptions, residual risks + +### Blocking Rules (Non-Negotiable) + +- ❌ **No gold-plating:** Every line must serve a requirement. "Might need later" is debt, not code. +- ❌ **No undocumented magic:** Policy IDs, thresholds, DB columns must trace to approved source. +- ❌ **No mixed concerns:** One PR = one Vertical Slice or one refactoring goal. Never both. +- ❌ **No skipped tests:** Failing/skipped tests must be fixed or logged as DECISION_REQUIRED. +- ❌ **No SELECT \*:** Always explicit columns. Dapper + schema-qualified SQL only. +- ❌ **No direct cross-module queries:** Use approved contracts and read models only. +- ❌ **No DateTime.Now:** Inject IClock. No random/network/system time in Policy. +- ❌ **No partial success:** DB state must be consistent after success/failure. No "kind of failed". +- ❌ **No policy in Job:** Jobs execute Commands, not make decisions. Decisions stay in Domain. +- ❌ **No real customer data in code:** Never in prompt, fixture, log, trace, or test. ### Model Operations Specifics -- **Model lifecycle:** Freeze → Mature → Score → Diagnose → Hypothesis → Challenger → Validate → Review → Manual Activation. No auto-learning, auto-promotion, or auto-ordering. -- **Sell priority:** `HARD_IMPAIRMENT → PORTFOLIO_SURVIVAL → DYNAMIC_PROFIT_FLOOR → CONCENTRATION/LIQUIDITY → OPPORTUNITY_COST → REENTRY_OPTION` (immutable). + +- **Model lifecycle:** Freeze → Mature → Score → Diagnose → Hypothesis → Challenger → Validate → Review → Manual Activation (no auto-learning, auto-promotion, auto-ordering). +- **Sell priority (immutable):** `HARD_IMPAIRMENT → PORTFOLIO_SURVIVAL → DYNAMIC_PROFIT_FLOOR → CONCENTRATION/LIQUIDITY → OPPORTUNITY_COST → REENTRY_OPTION`. - **Non-value-loss sell:** Requires ReentryWatch, new CycleId/Lot, step intervals, expiry, dedup. -- **Activation gating:** Every model activation requires ModelCard, OOS/PBO/DSR evidence, maker-checker approval, effective_at timestamp, rollback justification. +- **Activation gating:** Requires ModelCard, OOS/PBO/DSR evidence, maker-checker approval, effective_at, rollback justification. ## Tools & Scripts @@ -455,14 +489,57 @@ contracts/ metrics/ # Outcome metrics schema ``` +## Tech Debt Management (from AGENTS.md v16.0) + +Every suppressed rule, deferred refactor, and architectural compromise is debt. **Manage proactively:** + +### Tech Debt Registry + +Location: `TECH_DEBT_REGISTER.md` (to be created in PR 4) + +Format: +``` +| ID | Category | Impact | Effort | Status | Debt | Owner | Notes | +|----|----------|--------|--------|--------|------|-------|-------| +| DEBT-001 | Code Analysis (CA1822) | Medium | Low | Backlog | Static method hints | Team | Can batch with refactor | +| DEBT-002 | Code Analysis (CA1873) | Low | Low | Backlog | Array allocation in logs | Team | Remove when performance-critical | +``` + +**Impact/Effort Matrix:** +- **High Impact / Low Effort:** Sprint ASAP (quick wins) +- **High Impact / High Effort:** Roadmap (quarterly sprint) +- **Low Impact / Low Effort:** Batch with feature work +- **Low Impact / High Effort:** Monitor; defer unless blocking + +### Current Debt (Provisional) + +From `Directory.Build.props` NoWarn: +- `CA1822` (static method hints) — Low priority, batch during refactors +- `CA1873` (array allocation in logging) — Monitor, low impact +- `CA1305` (culture-specific formatting) — Accept as-is for Serilog +- `CA1707` (test naming convention) — xUnit uses underscores; accept +- `CA1861` (static readonly arrays) — Low priority, batch +- `xUnit2031` (Assert.Single filter) — Test analyzer; can defer + +### Paydown Target + +**Quarterly paydown goal:** 20% of debt list resolved (by impact, not count). + +Track in: +- Sprint retrospectives +- PR descriptions (reference Debt ID when resolving) +- README.md status section + +--- + ## Validation Gates (Not Yet Passed) Do NOT claim production readiness until: -- `.NET 10 restore/build/test` on CI passes consistently -- `pnpm frozen install/typecheck/Vitest/build/Playwright` on CI passes -- PostgreSQL DbUp fresh/upgrade/re-run/failure-recovery tests pass -- Outbox/Inbox crash-recovery & audit reconciliation rehearsal passes -- 252+ trading-day shadow run with OOS at multiple market phases -- PBO (probability of backtest overfit) and DSR (daily sharpe ratio) evidence +- ✅ `.NET 10 restore/build/test` on CI passes consistently +- ⏳ `pnpm frozen install/typecheck/Vitest/build/Playwright` on CI passes (pending PR 4) +- ⏳ PostgreSQL DbUp fresh/upgrade/re-run/failure-recovery tests pass (pending PR 5) +- ⏳ Outbox/Inbox crash-recovery & audit reconciliation rehearsal passes +- ❌ 252+ trading-day shadow run with OOS at multiple market phases +- ❌ PBO (probability of backtest overfit) and DSR (daily sharpe ratio) evidence Before all gates pass: **No production deployment, no advisory-with-automation, no auto-ordering, no auto-model-promotion.**