# Change Summary for Commit / PR

## Suggested commit title

`fix: gitea seed recovery and workflow checkout ref`

## Suggested PR title

`Synology KIS workflow recovery, branch checkout fix, and seed JSON tracking`

## What changed

- Updated `.gitea/workflows/kis_data_collection.yml` to checkout the triggering ref instead of always fetching `main`.
- Added a `Prepare Raw Seed Snapshot` step that accepts `GatherTradingData.json`, regenerates it from `GatherTradingData.xlsx`, or downloads the workbook from Google Drive when `.clasprc.json` is available.
- Switched KIS credential guards to explicit shell checks with clearer error messages.
- Applied the same checkout and seed-recovery logic to `.gitea/workflows/qualitative_sell_strategy.yml`.
- Tracked `GatherTradingData.json` in git so the runner always receives a canonical seed snapshot.
- Updated `tools/validate_platform_transition_wbs_v1.py` to validate the new workflow structure without false positives from shell guards.
- Expanded the Gitea variables runbook and failure analysis docs with the new recovery path and Google Drive fallback.

## Evidence to cite in the PR

- `python tools/validate_platform_transition_wbs_v1.py`
- `python tools/validate_gitea_secrets_contract_v1.py`
- `python tools/validate_gitea_token_home_v1.py --dispatch --workflow kis_data_collection.yml --ref codex/roadmap-publish`
- `python tools/validate_gitea_token_home_v1.py --dispatch --workflow qualitative_sell_strategy.yml --ref codex/roadmap-publish`

## Verified runtime result

- `run 165` on `kis_data_collection.yml` succeeded after the checkout-ref and seed changes.
- `Prepare Raw Seed Snapshot` passed with the tracked `GatherTradingData.json`.
- The KIS collector wrote SQLite output and the run completed successfully.

## Seed file decision

- `GatherTradingData.json`: track in git.
- `GatherTradingData.xlsx`: keep untracked and ignored unless a future workflow explicitly needs the workbook in the repo checkout. The current workflow can regenerate or download the workbook when needed.