bazi_translation/README.md

# bazi_translation

Codex skill for BaZi translation and naming review. It keeps BaZi/Four Pillars terms consistent across Chinese source terms, English display labels, and code identifiers.

The skill is simplified-Chinese-first:

- `简体` is the concept key.
- `标准英文` is for UI/docs when an English label is needed.
- `代码名` is for identifiers, API fields, classes, schemas, and tests.

The source PDF is not included in this repository.

This repository also includes a Nexa BaZi contract checker for programmers. It catches mixed API fields, JSON schema names, prompt variables, and module keys such as `Day_Master`, `DayMaster_Stem`, `Dominant_Deity`, and `Primary_Favorite_Element`.

## Install

Clone the repository and copy it into Codex skills:

```bash
git clone git@git.aplexlogic.com:fireparty/bazi_translation.git
mkdir -p ~/.codex/skills
rsync -a --delete bazi_translation/ ~/.codex/skills/bazi-translation/
```

Validate the skill:

```bash
python ~/.codex/skills/.system/skill-creator/scripts/quick_validate.py ~/.codex/skills/bazi-translation
```

## Use In Codex

Invoke the skill by name:

```text
Use $bazi-translation to review BaZi naming in src/bazi.
```

Typical requests:

```text
Use $bazi-translation to translate these terms into approved English and code names: 日主, 天干, 地支, 大运, 用神.
```

```text
Use $bazi-translation to review API field names in packages/bazi.
```

For Nexa:

```text
Use $bazi-translation to review Nexa BaZi API fields, prompt variables, and module keys in nexa_bazi-main.
```

## Use The Generic Checker

Run the local checker against files or directories:

```bash
python ~/.codex/skills/bazi-translation/scripts/check_bazi_names.py <path>
```

Exploratory review without failing the command:

```bash
python ~/.codex/skills/bazi-translation/scripts/check_bazi_names.py <path> --no-fail
```

List approved code names:

```bash
python ~/.codex/skills/bazi-translation/scripts/check_bazi_names.py --list-approved
```

Example output:

```text
src/chart.ts:42: dayOwner -> dayMaster
  zh: 日主; standard_en: Day Master
  line: const dayOwner = chart.dayOwner;
```

## Use The Nexa Contract Checker

Run the Nexa-specific checker against code, JSON, prompt files, or docs:

```bash
python ~/.codex/skills/bazi-translation/scripts/check_nexa_bazi_contract.py <path>
```

Migration planning mode:

```bash
python ~/.codex/skills/bazi-translation/scripts/check_nexa_bazi_contract.py <path> --no-fail
```

CI-style blocking mode, reporting only hard errors:

```bash
python ~/.codex/skills/bazi-translation/scripts/check_nexa_bazi_contract.py <path> --min-severity error
```

List loaded Nexa rules:

```bash
python ~/.codex/skills/bazi-translation/scripts/check_nexa_bazi_contract.py --list-rules
```

Example output:

```text
5 八字详解/5.7 命理符号/2.命理符号-算法与判定规则.md:14: DayMaster_Stem -> day_master_stem [error]
  concept: 日主天干
  reason: mixed case 不适合接口契约
  line: DayMaster_Stem: "辛"
```

Severity handling:

- `error`: do not add in new code; rename or add a compatibility migration.
- `warn`: likely wrong for new BaZi fields; check whether it is already published.
- `review`: not automatically unsafe, but it may show cross-system leakage or a published key that needs migration planning.

## Core Naming Rules

- Use `dayMaster`, not `dayOwner` or `dayLord`.
- Use `heavenlyStem`, not `skyStem`.
- Use `earthlyBranch`, not `groundBranch`.
- Use `luckPillar`, not `fortuneColumn`.
- Use `usefulGod`, not `useGod`.
- Use `favorableElement` in code by default; keep `Favourable Element` for book-style display text.
- Keep `Useful God` separate from `Favourable Element`.
- For Nexa JSON/API/prompt fields, use `snake_case`: `day_master`, `day_master_stem`, `dominant_ten_god`, `primary_favorite_element`.
- Do not use `deity` for Ten Gods in interfaces. Use `ten_god`.
- Do not use astrology terms such as `astral_event` for BaZi branch relationships or daily BaZi events.

## Nexa Contract Files

- `references/nexa-bazi-contract.md`: canonical Nexa BaZi API/JSON/prompt naming contract.
- `references/nexa-naming-rules.md`: practical naming rules and migration guidance.
- `references/nexa-forbidden-names.md`: deterministic bad-name table used by the checker.

## Files

- `SKILL.md`: Codex skill trigger and workflow.
- `references/terms.md`: simplified-Chinese-first dictionary.
- `references/naming-rules.md`: review rules and anti-patterns.
- `references/nexa-bazi-contract.md`: Nexa BaZi interface and prompt-variable naming contract.
- `references/nexa-naming-rules.md`: Nexa-specific naming guidance.
- `references/nexa-forbidden-names.md`: Nexa forbidden/legacy name table.
- `references/pending-terms.md`: staging area for terms needing domain review.
- `scripts/check_bazi_names.py`: source-code naming checker.
- `scripts/check_nexa_bazi_contract.py`: Nexa BaZi API/JSON/prompt naming checker.