hk-ipo/rules/rule_change_log.md

# Rule Change Log

## 2026-06-22 - Add defensive IPO break-risk/reward overlay

Request:

- Evaluate the current IPO batch from break probability, cash efficiency, and risk/reward rather than only heat-adjusted upside.

Change:

- Added `rules/ipo_break_risk_reward_v0.yaml` as an experimental overlay.
- Split the new lens into break protection, capital efficiency, and upside optionality.
- Added empirical calibration anchors from `analysis_model_v0_dataset.csv`, including historical D1 break rates by T0 score, offer-size bucket, and final public oversubscription bucket.
- Updated the 2026-06-22 latest IPO report with a defensive risk/reward ranking for the 13 current candidates.

Rationale:

- A low subscription multiple can improve allocation and cash-lockup efficiency, but it does not automatically reduce break risk.
- Mature profitable issuers such as `01688` may have better defensive risk/reward than their heat score implies, while high-heat names such as `01956` remain more pop-driven.

Verification:

- Recomputed the calibration anchors from the current model dataset.
- Checked that the overlay is documented as ordinal and comparative, not as a standalone probability forecast.

## 2026-06-15 - Add T0.95 late-order heat stage

Request:

- Treat near-deadline heat as usable when the user can still place an IPO order at T0.95.

Change:

- Added `T0_95_final_heat` to the analyst skill as a separate actionable late-order stage.
- Added `rules/ipo_score_v0_95_final_heat_trial.yaml` for stage-safe T0.95 heat scoring and timing discipline.
- Updated the archivist skill and `scripts/archive_t0_5_market_heat.py` so market-heat snapshots can be explicitly archived as `T0_95_final_heat`.

Rationale:

- If the user can still place, amend, or cancel an order near the subscription cutoff, near-final heat is a legitimate live decision input.
- Historical final public oversubscription can help calibrate near-final heat buckets, but it remains post-hoc calibration unless the value was visible before the user's executable order cutoff.

Verification:

- Kept the script default stage as `T0_5_market_heat` for backward compatibility.
- Added explicit `--stage T0_95_final_heat` support for late-order snapshots.
- Verified with py_compile, script help output, dataset rebuild, and `git diff --check`.

## 2026-06-15 - Use Chinese for analyst reports

Request:

- Make analyst reports Chinese by default and record the rule in the analyst skill.

Change:

- Added a Simplified Chinese default language rule to the analyst skill.
- Updated the single-ticker report generator to write Chinese Markdown reports while preserving ticker symbols, stage codes, rule ids, score buckets, and source paths as machine-readable identifiers.
- Regenerated the 06106 T0 report in Chinese.
- Documented the Chinese report default in README.

Rationale:

- The analysis workflow is intended for Chinese-language IPO subscription decisions, while project identifiers still need to remain stable for scripts and audits.

Verification:

- Generated a 06106 dry-run report and checked the Chinese sections.
- Regenerated `reports/2026-06-15_06106_T0_prospectus_analysis.md`.
- Ran py_compile for the report generator and git diff --check.

## 2026-06-15 - Add concrete stage dates to reports

Request:

- Every analyst report should note the specific dates behind T0, T1, T2, and D1 for the covered IPO.

Change:

- Added a `Stage Calendar` section to the single-ticker report generator.
- Required analyst reports to show the ticker-specific T0 subscription window, T1 allotment-result date, T2 grey-market date/window, and D1 listing date.
- Updated the 06106 T0 report to include its concrete stage dates.

Rationale:

- The T0/T1/T2/D1 labels are project analysis stages, so reports should always bind them to actual calendar dates for the IPO under review.

Verification:

- Generated a 06106 dry-run report and checked the stage calendar.
- Ran py_compile for the report generator.
- Ran git diff --check.

## 2026-06-15 - Clarify short-exit IPO strategy horizon

Request:

- Emphasize that the analyst model is focused on selling allocated IPO shares in T2 grey market or on D1, not long-term holding.

Change:

- Added an explicit T2/D1 sell horizon to the analyst skill.
- Updated `ipo_score_v0` targets and holding policy to make D1 sell return the primary modeled label and T2 the intended extension when reliable grey-market data exists.
- Clarified that D5/D20/D60 are review labels only, not holding-period targets.
- Updated single-ticker reports and the report generator to show T2/D1 exit discipline.

Rationale:

- The subscription decision should optimize for immediate IPO exit execution, not a long-term equity thesis.
- This preserves stage safety while aligning report language, model targets, and review labels with the actual trading process.

Verification:

- Generated dry-run single-ticker reports after the template update.
- Rebuilt the analysis model report with the same dataset timestamp to refresh language without changing model rows.
- Ran py_compile for the modified scripts and checked Markdown/report text for the new T2/D1 discipline.

## 2026-06-15 - Refresh `ipo_score_v0` after T1 demand backfill

Request:

- Re-analyze the model using the known historical archive after T1 demand text backfill.

Change:

- Regenerated `data/snapshots/analysis_model_v0_dataset.csv` from the current SQLite archive.
- Refreshed `reports/2026-06-15_analysis_model_v0.md` with the expanded T1 demand coverage and new empirical calibration.
- Kept the `ipo_score_v0` score formula unchanged because the expanded sample still shows non-monotonic middle and low score buckets.
- Updated model limitations to reflect that T1 is structurally complete for listed rows, while field-level NULLs remain when source documents do not explicitly state a field.

Rationale:

- T1 structured coverage increased from 154 to 291 rows after archivist backfilled demand facts from extracted PDF text.
- The high-conviction bucket remains clearly differentiated, but the rest of the calibration is not strong enough to justify a v1 rule change.
- Avoiding a threshold rewrite here preserves the feedback loop: future rule changes should be tied to reviewed predictions and named error cases.

Verification:

- Rebuilt the analysis dataset and model report from `data/hk_ipo.sqlite`.
- Confirmed post-listing returns remain labels only and are not score inputs.
- Confirmed durable source paths remain repo-relative.

## 2026-06-15 - Introduce `ipo_score_v0`

Request:

- Start digesting the downloaded IPO archive and build the first analyst model.

Change:

- Added `rules/ipo_score_v0.yaml` as the initial transparent scoring baseline.
- Added `scripts/build_analysis_dataset.py` to generate a feature dataset and calibration report from `data/hk_ipo.sqlite`.
- Added `data/snapshots/analysis_model_v0_dataset.csv` as the first model-ready snapshot.
- Added `reports/2026-06-15_analysis_model_v0.md` to document coverage, calibration, and known gaps.

Rationale:

- The archive now has enough T0 facts and D1/D5/D20/D60 labels to support a repeatable baseline.
- T1 demand data is partially structured and highly informative where available.
- T2 grey-market data remains blocked until a reliable source exists, so it is excluded from v0.

Verification:

- Generated the dataset from the current SQLite archive.
- Confirmed the model keeps post-listing returns as labels only.
- Recorded non-monotonic middle buckets as a limitation rather than overfitting them away.