# Vision
Build a regulatory reporting system for UCITS funds.

## Goals
- ingest fund data from multiple sources
- validate against regulatory schema
- generate board-ready reports
- maintain full audit trail

## Principles
- every output must be traceable
- no generation without spec approval
- human review before submission

Fund Data → Ingestion → Validation
          → Report Generation → Output

Components:
- ingestion layer (CSV/API)
- regulatory schema validator
- report generator
- audit trail (decisions.md)

Storage:
- Postgres (fund data + audit)
- decisions.md (reasoning trace)

# CLAUDE.md

## Rules
- follow architecture.md strictly
- never bypass spec files
- prefer incremental changes
- maintain explicit reasoning traces

## Output style
- structured reasoning
- no hidden assumptions

def build_system(spec):
    assert spec.is_clear()
    assert spec.is_minimal()

    system = init(spec)

    while not system.is_stable():
        system = iterate(system)

    return system

class SystemGuard {
  validate(action) {
    if (!action.intent) {
      throw new Error("Missing intent");
    }

    return this.normalize(action);
  }
}

## Constraint
Never generate a migration without a rollback in decisions.md.
Never add a dependency without updating architecture.md.

## Gate
Before any implementation step: confirm spec is unambiguous.
If not — stop and ask.

You are a staff backend engineer who has built
high-availability financial data pipelines at
$1B+ AUM scale.

Review this system design. Identify every flaw,
scaling risk, and architectural contradiction.
Be brutal. Do not soften findings.

Security:
- No audit log for failed validations — UCITS requires
  record of all exceptions, not just passes
- Report proceeds even if 0 positions validate — must fail-safe

Compliance:
- ISIN lookup uses local cache only — stale data risk
  for newly listed instruments
- Board report timestamp not in UTC — ambiguous for
  cross-border fund reporting

Infrastructure:
- No retry logic for CSV ingestion — single network
  failure breaks the pipeline silently

ISIN,         Qty,    NAV,     CCY
GB0002634946  10,000  £15.23   GBP  ✓
IE00B4L5Y983   5,000  €112.45  EUR  ✓
US0378331005   2,500  $174.82  USD  ✓
GB00B0CTWC01     800  £42.10   GBP  ✗ ISIN mismatch
...
844 valid · 3 flagged

UCITS Compliance Report — Q1 2026
Fund: Carne UCITS Strategy Fund
NAV Date: 31 March 2026
─────────────────────────────────
Article 84 Status:  PASS (warnings)
  ✓ 844 / 847 positions validated
  ⚠ 3 ISIN exceptions — see Annex A
  ✓ Single-issuer limits: compliant
  ✓ Eligible assets:    100% compliant
─────────────────────────────────
Audit trail:  decisions.md rev 14
Approved by:  [awaiting sign-off]

# CLAUDE.md — UCITS Regulatory Reporting

## Compliance Rules
- Never generate a report without validating all positions
  against UCITS Article 84 schema first
- Flag ISIN mismatches — do not suppress or round
- Every calculation must trace to a source data row
- Board report must include compliance sign-off section

## Gate
Before generating any output: confirm schema validation passed.
If validation fails: surface all errors. Stop. Do not proceed.
Human approval required before any external submission.

You are a UK FCA-registered compliance officer
with 10 years of UCITS IV and V expertise.

Review this system design for our regulatory
reporting pipeline. Identify every compliance
gap, audit failure, and regulatory risk.
Be specific. Cite the relevant UCITS articles.

Security:
- No audit log for failed validations — UCITS requires
  record of all exceptions, not just passes
- Report proceeds even if 0 positions validate — must fail-safe

Compliance:
- ISIN lookup uses local cache only — stale data risk
  for newly listed instruments
- Board report timestamp not in UTC — ambiguous for
  cross-border fund reporting

Infrastructure:
- No retry logic for CSV ingestion — single network
  failure breaks the pipeline silently

def validate_ucits_positions(
    df: pd.DataFrame,
) -> ValidationResult:
    """
    Validates fund positions against UCITS Article 84.
    Generated per architecture.md specification.
    Every error traces to source row — per CLAUDE.md rule 3.
    """
    errors = []
    for idx, row in df.iterrows():
        if not is_valid_isin(row["isin"]):
            errors.append(
                f"Row {idx}: Invalid ISIN '{row['isin']}'"
            )
        if row["nav"] < 0:
            errors.append(
                f"Row {idx}: Negative NAV not permitted"
            )
    return ValidationResult(
        passed=len(errors) == 0,
        errors=errors,
        source_rows=[e.split()[1] for e in errors],
    )

## 2026-05-20 — Post-Critique Update

### Auth Layer
Decision: Switched from stateless JWT to session tokens + Redis.
Reason: Distributed queue compatibility (Security persona).

### Fund Transfer Step 3
Decision: Added explicit rollback to T-1 state.
Reason: Audit requirement — every mutation must be reversible.
Approved by: Builder review 2026-05-20.