KArtSell.Aegis/AGENTS.md

K-ArtSell Aegis AI Coding Constitution v12.0

1. 자동주문과 KIS 제출 Capability는 OFF다. 별도 승인 Release 전 구현·활성화·우회하지 않는다.
2. 채팅과 생성 코드는 Source of Truth가 아니다. 모든 변경은 Source / Assumption / Unknown / Decision Required를 표시한다.
3. 한 PR은 한 Vertical Slice 또는 한 동작보존 리팩터링 목적만 가진다.
4. Endpoint→Application→Pure Policy→Dapper SQL→Outbox→Tests 경계를 지킨다.
5. Domain Policy는 시간·랜덤·네트워크·DB·DI Container를 직접 읽지 않는다.
6. Generic Repository, God Service, Service Locator, Job 내 비즈니스 정책, 조기 Microservice 분리를 금지한다.
7. 모듈은 다른 모듈 Source Table을 직접 조회하지 않는다. 승인된 Contract/Read Model만 사용한다.
8. DateTime.Now/UtcNow를 직접 사용하지 않고 IClock과 MarketCalendar를 사용한다.
9. 금융값은 decimal, 명시적 rounding, 단위 계약을 사용한다. 모델 내부 double은 경계에서 변환한다.
10. SellRatioOfLot, SellQuantity, TargetPortfolioWeightAfter, StrategicCoreFloorWeight를 혼용하지 않는다.
11. EvidenceSnapshot·DatasetId·Model/Config/Code SHA 없이 Decision/Recommendation을 저장하지 않는다.
12. Command/Job는 IdempotencyKey/JobRunId/Watermark를 갖고 replay를 견딘다.
13. Evidence/Decision/Audit는 update/delete하지 않고 append/correction event로 보존한다.
14. Write Model은 정규화·append·revision, 화면은 version/watermark/rebuild가 있는 Read Model이다.
15. 서버 상태는 TanStack Query가 소유한다. Pinia에 API 응답을 복제하지 않는다.
16. FE request/response는 Zod로 runtime validation하고 같은 retry에 같은 Idempotency-Key를 재사용한다.
17. /internal/* Endpoint는 Roles 또는 Policies를 선언하며 익명 접근을 허용하지 않는다.
18. 알고리즘 변경은 Policy ID, Golden, Frozen OOS, cost×2, false-exit/reentry/ES, ModelCard를 동반한다.
19. 새 library/pattern/table/threshold는 ADR/Issue 승인 없이 도입하지 않는다.
20. 실행하지 못한 build/test/migration을 통과했다고 기록하지 않는다.
21. AI 생성 Migration은 fresh/upgrade/re-run/failure rehearsal 및 DBA 승인 없이는 병합하지 않는다.
22. 실고객 데이터·실계좌·실주문 키·secret를 prompt/fixture/log/trace에 넣지 않는다.
23. Metric·Alert·Runbook·Rollback·Owner/Secondary가 없으면 Done이 아니다.

v12.1 execution-readiness delta

• Every change must cite Requirement/Slice/Policy/Data/API/DB/Job/UI/Test IDs.
• Production commands load Evidence/Model/Config from approved server-side PIT context; never trust client-supplied evidence.
• Write models are normalized and append/correction based. Denormalization is allowed only in versioned, rebuildable read models.
• Outbox/Inbox/JobRun/Projection operations require scope, idempotency, watermark, hashes, and replay evidence.
• No generic repository, God service, reflection plugin framework, premature microservice, or unapproved threshold.
• Refactoring and policy changes must be separate PRs with characterization or Golden tests first.
• Never claim a build, migration, test, Shadow period, PBO, or DSR result that was not executed and preserved as evidence.

v12.2 strategic data-semantics delta

• CurrentSecurityPortfolioWeight, CurrentLotPortfolioWeight, SellRatioOfLot, and StrategicCoreFloorWeight are distinct units. Never reintroduce the ambiguous CurrentPortfolioWeight into active decision code.
• A lot-relative sell changes security weight by CurrentLotPortfolioWeight * SellRatioOfLot.
• Persist the ordered policy trace with Applied/Blocked/NotApplicable dispositions; do not expose raw internal scores directly to customers.
• Prior migrations are immutable. v12.2 changes belong in migration 0014 or later.
• The six current-session attachments and their SHA-256 values are part of the release evidence.
• Use the reviewed templates under templates/; do not bulk-generate unapproved modules or placeholder implementations.

v12.3 execution and semantic-version delta

• weight_semantics_version=1 contexts are legacy ambiguous data and must never enter active decisions; rebuild them as version 2 from explicit security and lot weights.
• A positive opportunity edge with a zero or missing requested sell ratio is BLOCKED. Never clamp missing intent to a minimum sell.
• Policy IDs, priorities and thresholds must match contracts/policies/sell-policy-contract.v1.json; drift blocks G2.
• Decision/API/Event/DB evidence must preserve decision_contract_version and policy_trace_schema_version.
• Outcome metrics must name a definition version, population, numerator, denominator, window and aggregation. Do not equate 63-session research output with an annual target without approval.
• scripts/scaffold_slice.py is dry-run by default, refuses overwrite and produces SCAFFOLD_ONLY code. Generated files are not approved implementation.
• The seven cumulative attachments and their SHA-256 values are part of v12.3 release evidence.

v12.4 Model Operations Constitution

• Scheduler automation is limited to EVALUATION_ONLY, PROPOSAL_ONLY and DRILL_ONLY.
• Never generate or merge automatic model promotion, rollback, threshold mutation, code change, automatic order or KIS submission paths.
• Every evaluation request freezes Dataset/Model/Config/Code/Contract VersionSet from an approved server-side context.
• Metric changes require a versioned numerator, denominator, window, aggregation, PIT/revision rule and Golden/OOS impact.
• Improvement proposals are documents and records only; they do not edit model, policy, configuration or source files.
• Drift thresholds, false-exit definition and retention policy are DECISION_REQUIRED until approved.

v14.0 UI / Model Feedback non-negotiables

• Feature code MUST NOT import PrimeVue or AG Grid directly. Use shared UI ports and screen types.
• UI provider changes require contract, accessibility, visual, state-matrix and performance evidence.
• Model operation automation stops at evaluation/proposal. Model activation is human change approval only.
• J39 and every new schedule remain disabled until their source, calendar, ownership and alert contracts are approved.
• Never claim .NET, pnpm, PostgreSQL, Playwright or Shadow evidence passed unless the actual artifact is attached.