KArtSell.Aegis/AGENTS.md

K-ArtSell Aegis AI Coding Constitution v12.0

Default execution procedure

All work in this repository MUST follow docs/CURRENT/WBS_EXECUTION_PROCEDURES.md as the default operating procedure, together with this constitution. Before editing, select exactly one WBS item from docs/CURRENT/CATALOGS/WBS_MASTER.csv, verify dependencies, Gate, Requirement/API/DB/Job/UI/Test IDs, Acceptance_Evidence, and Artifact. Record Source / Assumption / Unknown / Decision Required, then execute, collect actual evidence, update WBS_PROGRESS_TRACKER.csv, and commit with the WBS_ID. Do not mark a WBS item COMPLETED or claim a test/build/migration result without preserved execution evidence.

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.

v16.0 Gitea API & CI/CD Automation

Environment Setup

Gitea API Token:

# Set GITEA_TOKEN_TAXBAIK environment variable
# This token enables:
# - Pull request automation (labels, milestones, comments)
# - Issue management (create, update, close)
# - Release management (tags, release notes)
# - CI/CD pipeline integration

# On Windows (PowerShell):
$env:GITEA_TOKEN_TAXBAIK = "your-token-here"

# On macOS/Linux (bash):
export GITEA_TOKEN_TAXBAIK="your-token-here"

# Verify:
echo $GITEA_TOKEN_TAXBAIK

Gitea API Patterns

Common endpoints (https://gitea.taxbaik.com/api/v1):

# Create a PR comment
curl -X POST \
  -H "Authorization: token $GITEA_TOKEN_TAXBAIK" \
  -H "Content-Type: application/json" \
  -d '{"body":"Verification complete: 41/41 tests passed"}' \
  https://gitea.taxbaik.com/api/v1/repos/kjh2064/KArtSell.Aegis/issues/{issue_id}/comments

# Add labels to PR
curl -X POST \
  -H "Authorization: token $GITEA_TOKEN_TAXBAIK" \
  -d '["architecture","verified"]' \
  https://gitea.taxbaik.com/api/v1/repos/kjh2064/KArtSell.Aegis/issues/{pr_number}/labels

# Create release with notes
curl -X POST \
  -H "Authorization: token $GITEA_TOKEN_TAXBAIK" \
  -H "Content-Type: application/json" \
  -d '{"tag_name":"v16.0.1","body":"Release notes..."}' \
  https://gitea.taxbaik.com/api/v1/repos/kjh2064/KArtSell.Aegis/releases

# Query PR/Issue
curl -H "Authorization: token $GITEA_TOKEN_TAXBAIK" \
  https://gitea.taxbaik.com/api/v1/repos/kjh2064/KArtSell.Aegis/pulls?state=open

CI/CD Integration (Gitea Actions)

Leverage in .gitea/workflows/ci.yml:

- name: Comment on PR with test results
  if: github.event_name == 'pull_request'
  run: |
    curl -X POST \
      -H "Authorization: token ${{ secrets.GITEA_TOKEN }}" \
      -H "Content-Type: application/json" \
      -d "{\"body\":\"Build: ✅ Tests: 41/41 PASS\"}" \
      https://gitea.taxbaik.com/api/v1/repos/kjh2064/KArtSell.Aegis/issues/${{ github.event.pull_request.number }}/comments

Automation Best Practices (from v16.0)

• PR Labels: Auto-label based on affected module (e.g., ModelOperations, SignalEngine)
• Milestones: Link PRs to quarterly sprints for burndown tracking
• Comments: Post verification results (build, test, security scan) directly on PR
• Releases: Tag with semver + architecture contract version (e.g., v16.0.1-contract-v3.0)
• Issue Linking: Reference debt IDs, ADRs, decision logs in commits (e.g., TECH-001: Fix CA1822)

---

v16.0 Strategic Architecture & Engineering Excellence

Decision Criteria for All Work

Every task — code change, refactor, new feature, tooling, infrastructure — must be evaluated against these dimensions before implementation:

1. SOLID 원칙

• Single Responsibility: One class, one reason to change. Vertical Slice boundaries are trust boundaries.
• Open/Closed: Open for extension (new Policies, new decision gates); closed for modification (immutable Evidence, append-only migrations).
• Liskov Substitution: Handlers, Policies, Adapters are swappable; never break contract.
• Interface Segregation: IClock ≠ IDateTime; IOutboxWriter ≠ IEventBus. Ports are narrow.
• Dependency Inversion: Depend on abstractions (IClock, ILogger, IOutboxWriter); inject concretions at composition root only.
• 적용: 모듈 경계 설계, 인터페이스 분리, 스태틱 메서드 vs 인스턴스 메서드 판단.

2. 코드 리팩토링 (Code Mass & Complexity)

• Cyclomatic Complexity ≤ 10 per method (Policy는 예외: decision trees는 복잡해질 수 있음).
• Characterize → Isolate → Transform → Verify → Simplify → Observe → Close Debt (정공법).
• Dead code, unused flags, unreachable branches는 즉시 삭제. "혹시 필요할까봐"는 금지.
• Performance refactor와 기능 변경은 분리된 PR. 동시 변경은 회귀 탐지 불가.

3. 데이터 정합성 (Data Integrity & Audit)

• PIT (Point-in-Time): WHERE published_at <= cutoff AND revision = latest 필수. 시간 여행 쿼리는 audit 목적만.
• Revision Tracking: update/delete 금지. 새 버전을 append로 저장. 수정은 correction event로 보존.
• Audit Trail: EvidenceSnapshot, DatasetId, Model/Config/Code SHA는 Decision과 함께 저장. Trace 불가능하면 미완성.
• 적용: 모든 쓰기는 append/correction 패턴. 읽기는 PIT 조건. 마이그레이션은 회원가입 없음.

4. 과유불급 (Necessity-Driven, No Gold-Plating)

• "혹시 나중에 필요하면"으로 코드를 추가하지 않는다. 근거 없는 추상화 금지.
• 한 곳에서만 쓰면 분리하지 않는다. 세 곳에서 반복되면 그때 abstract.
• Feature flag, backward-compat shim, deprecation layer는 근거 있을 때만. 사용하지 않는 코드는 삭제.
• 적용: 새 service/interface/config 도입 전에 "이것이 정말 필요한가?" 자문.

5. 정규화 & 역정규화 (Normalization Strategy)

• Write Models: 3NF + append + revision. 중복 없음, 관계 명확, 이상 불가.
• Read Models: Denormalized projections. 1NF 위반 허용 (성능, 접근성). 모든 Read는 versioned, rebuildable.
• 경계: Write는 Dapper로 스키마-규정. Read는 쿼리 최적화. 양쪽 스키마 감시.
• 적용: 새 column 추가 전에 "이것은 3NF 위반인가? 그렇다면 projection으로."

6. 프로세스 단순화 (Simplicity & Clarity)

• 한 번에 한 가지만 한다. 다중 책임 = 다중 이해 실패 = 버그.
• "왜 이 순서인가?" 묻지 않아도 명확한 코드. 숨겨진 전제 금지.
• Circular dependency, magic numbers, implicit state 제거.
• 적용: 코드 흐름이 위→아래로 읽혀야 함. 뒤로 돌아가며 읽어야 하면 리팩터.

7. 패턴화, 표준화, 구조화 (Patterns & Standards)

• Vertical Slice는 단일 패턴. Endpoint → Handler → Policy → Dapper → Outbox.
• Job은 단일 책임. 비즈니스 정책은 들어가지 않음. 승인된 Command만 실행.
• Event schema는 contract-first. 구독자가 없으면 이벤트도 없음.
• 표준 컴포넌트: QueryStateBoundary, CrudForm, PermissionGuard 등은 모든 화면에서 재사용. 직접 import 금지.
• 적용: 새 pattern/component 도입 전 팀 검토. 코드 사본 3개 = abstract 신호.

8. 바이브코딩 & 홀루시네이션 통제 (AI Guardrails)

• AI 생성 코드는 근거 없음. Source/Assumption/Decision 반드시 기록.
• 금지: 근거 없는 Policy ID, threshold, DB column, API endpoint.
• SQL은 schema owner, PIT 조건, index, execution plan 검토 필수.
• 알고리즘 변경은 Golden/Frozen OOS diff 없이 병합 금지.
• 적용: "이 값은 어디서 나왔나?" 묻는 습관. 답 없으면 DECISION_REQUIRED 표시.

9. 현장감, 재현성, 이력성 (Traceability & Reproducibility)

• 현장감: Build/test/migration artifact는 보존. "통과했다고 주장"하되 증거 없으면 거짓.
• 재현성: 동일 input → 동일 output. Random, network, system time 의존은 격리. Mock 금지, integration test로.
• 이력성: Commit message는 "왜"를 기록. "버그 수정"은 불충분. "X 기능에서 Y 조건에서 Z 버그 → 원인: 로직 오류" 기록.
• 적용: CI/CD 결과물 저장, 회귀 테스트 잠금, ADR에 의사결정 기록.

10. 안정성 (Reliability & Safety)

• Idempotency: 같은 요청 → 같은 결과. 두 번 실행해도 안전.
• Rollback 불가능한 변경 금지. Migration도 down script 필수.
• Failure mode: 각 Job/Endpoint은 실패했을 때 상태를 명확히. "실패했는데 부분 성공?" 금지.
• 적용: Command/Job는 IdempotencyKey, Watermark 필수. DB constraint, NOT NULL 검증.

11. 고도화 & 컴포넌트화 (Componentization & Maturity)

• 한 번 제대로. 임시방편 금지. 기술부채는 Debt register에 기록.
• 구현 전 contract/schema/test 먼저. "하면서 배운다"는 설계 부실의 신호.
• 버전 관리: 기능이 아닌 contract 버전. API/Event/DB schema 버전 분리.
• 적용: Release note에는 contract version, breaking change, migration step 명시.

12. 정공법 (Right Way, Not Shortcuts)

• 안 되는 길에 시간 낭비하지 말되, 편한 길도 피한다 (--no-verify, force push).
• 문제 근본 해결. Symptom 치료는 debt 증가.
• 리뷰어가 "이게 최선인가?" 묻는 코드는 재작성. "충분히 좋다" ≠ "최선".
• 적용: Build 실패 → --no-verify X, 원인 파악. Merge conflict → cherry-pick X, rebase 제대로.

13. 기술부채 관리 (Tech Debt Registry)

• 부채는 기록하는 순간부터 이자 발생. 미루지 말 것.
• Debt ID: TECH-001 등으로 추적. PR/commit에서 참조.
• 우선순위: Impact (얼마나 큰가) × Effort (고치는 데 드는 비용). 고영향 저비용 우선.
• Paydown: 분기마다 debt 20% 감축 목표. 신규 debt > paydown이면 질식.
• 적용: README.md의 TECH_DEBT_REGISTER 매월 검토. 3개월 미해결 = 리팩터 스프린트 필요.

Work Decision Checklist

모든 task에 대해 다음을 자문:

• SOLID: 이 변경이 단일 책임인가? Dependency inversion을 지킬 것인가?
• Complexity: 함수/메서드 복잡도는 10 이하인가? (Policy 예외)
• Audit: Evidence/Revision 추적 가능한가? PIT 쿼리 있는가?
• Necessity: 근거 있는 변경인가? "혹시 필요하면" 아닌가?
• Normalization: 쓰기는 3NF, 읽기는 projection인가?
• Simplicity: 위→아래로 읽혀야 하는가? 숨겨진 전제 없는가?
• Pattern: 표준 Slice/Job/Component 따르는가? 새 패턴 도입은 검증됐는가?
• Guardrails: 근거 있는가? "왜"를 기록했는가?
• Traceability: Artifact 보존되는가? Reproduction 가능한가? ADR/Issue 링크 있는가?
• Safety: Idempotent인가? Rollback 가능한가? 부분 실패 케이스 처리했는가?
• Maturity: 임시방편 아닌가? Contract/schema/test 먼저 했는가?
• Right Way: Shortcut (--no-verify, force) 안 썼는가? 근본 해결했는가?
• Debt: 새로운 debt 만들지 않는가? 기존 debt 감축하는가?

Anti-Patterns (금지)

• ❌ "일단 만들고 나중에 리팩터" → Feature 초기부터 정공법
• ❌ "혹시 필요할까봐 추상화" → Necessity-driven만
• ❌ SELECT * / Generic Repository → Explicit columns, explicit logic
• ❌ "이건 작은 변경이라 테스트 스킵" → 모든 경로 characterize
• ❌ Timestamp를 직접 DateTime.Now → IClock 주입
• ❌ Policy 로직이 Job/Handler에 → Domain Policy만
• ❌ "나중에 monitoring 추가" → 배포 전 Metric/Alert/Runbook 필수
• ❌ Magic number → 근거 있는 상수, Policy ID로 추적
• ❌ "다른 모듈 테이블 조회" → Contract/Read Model만
• ❌ 스킵된 테스트 기록 안 함 → Debt register에 DECISION_REQUIRED

Execution Protocol Addendum

Before Any Change

• Read the current Source of Truth first: user-provided configuration, current schema, active contracts, and existing tests.
• Record Source / Assumption / Unknown / Decision Required in the Slice note before editing.
• Preserve user-fixed development and production configuration values. Never replace them with compose defaults, environment fallbacks, or guessed credentials.
• Classify the change as exactly one Vertical Slice or one behavior-preserving refactoring. Do not mix policy, schema, configuration, and unrelated cleanup.

Database Test Routing

• Unit tests do not connect to a database.
• Integration and migration tests use the configured test database from the test project's Development settings.
• Production database access is read-only diagnostics only unless an explicitly approved production release step says otherwise.
• Before any destructive test-database operation, parse and verify the database name is the approved test database. Refuse all other names.
• Do not infer schema from a legacy migration file. Compare active runtime SQL, tests, and the current database schema first.

Time and Timezone

• Persist instants in UTC with timezone-aware database types where the contract permits.
• Convert to KST only at display, reporting, scheduling, or MarketCalendar boundaries.
• Keep IClock.UtcNow as the application clock contract. A KST conversion requires an explicit contract and characterization test.
• Never change a timezone or reinterpret existing timestamps without a documented data-meaning decision and rehearsal evidence.

Blockers Must Be Actionable

• Do not repeatedly report that work is blocked without a concrete resolution proposal.
• For each blocker, state: exact cause, safe options, recommended option, required command or approval, and the evidence that will be produced.
• If the user has provided the required authority or test resource, proceed within that scope instead of asking for the same approval again.
• If an external prerequisite is missing, perform all safe read-only checks first, then give one precise request to unblock the next Slice.

Evidence and Completion

• Never claim completion from an intended command. Record the actual command result and artifact path.
• For migrations, preserve fresh-install, upgrade, re-run, and failure-rehearsal evidence before calling the Slice complete.
• When a change fails validation, revert or isolate the failed draft before starting the next Slice; do not leave an unapplied journal or partial scaffold as if it were approved.