stewart hu 80835138e9 Scaffold repo for implementation handoff

- README: orientation, doc map, target package layout (pointers only,
  no duplicated architecture content)
- CLAUDE.md: agent operating manual — invariants as code-review rules,
  conventions, do-not list, task reading order
- ROADMAP: M1-M5 with verifiable acceptance criteria, phase-2 fence
- GLOSSARY: canonical Chinese-term → code-name mapping
- docs/adr/: eight ADRs recording settled decisions and rejected
  alternatives
- docs/open-questions.md: consolidated TODO(业务) tracker by owner and
  blocking milestone
- .gitignore; untrack .DS_Store

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019u5SLNweVio6ozJX7yfxQr

🔮 View transcript: https://logs.lojong.info/s/e8u90k3t33w590r7b5y7yzqh

2026-09-01 21:13:00 -04:00

996 B

Raw Blame History

ADR-0002: zod as schema source of truth

Status: accepted · 2026-09

Context: Business objects cross TS runtime ↔ Python skills; schema drift between languages is the classic failure. Someone must own the truth.

Decision: Hand-written zod schemas in packages/domain are the only source. Build exports JSON Schema to contracts/ (committed, versioned); pydantic models are generated from those (never hand-edited). Golden fixtures validated by both CIs. Data representation rules in docs/11 §3.3 are part of the contract (decimal strings for money, units in field names, etc.).

Alternatives: Hand-written JSON Schema as neutral source (revisit if Python-side partners need co-ownership — the contracts/ layer stays identical); protobuf/gRPC (rejected: call volume doesn't need it, lineage snapshots should be human-readable, partner onboarding cost).

Consequences: Python teams depend only on contracts/, never on TS internals — org boundary = code boundary.

996 B Raw Blame History

ADR-0002: zod as schema source of truth

996 B

Raw Blame History