From f0dd9a8ae465eb83a053627594fd57c8d864851e Mon Sep 17 00:00:00 2001 From: kjh2064 Date: Sun, 21 Jun 2026 22:47:07 +0900 Subject: [PATCH] docs: add merge checklist and xlsx decision --- .../CHANGESET_COMMIT_PR_SUMMARY_2026-06-21.md | 38 ++++++------------- ...HERTRADINGDATA_XLSX_DECISION_2026-06-21.md | 35 +++++++++++++++++ docs/MAIN_MERGE_FINAL_CHECKLIST_2026-06-21.md | 25 ++++++++++++ 3 files changed, 71 insertions(+), 27 deletions(-) create mode 100644 docs/GATHERTRADINGDATA_XLSX_DECISION_2026-06-21.md create mode 100644 docs/MAIN_MERGE_FINAL_CHECKLIST_2026-06-21.md diff --git a/docs/CHANGESET_COMMIT_PR_SUMMARY_2026-06-21.md b/docs/CHANGESET_COMMIT_PR_SUMMARY_2026-06-21.md index f08de19..97f0ee4 100644 --- a/docs/CHANGESET_COMMIT_PR_SUMMARY_2026-06-21.md +++ b/docs/CHANGESET_COMMIT_PR_SUMMARY_2026-06-21.md @@ -1,37 +1,21 @@ -# Change Summary for Commit / PR +# PR Summary -## Suggested commit title - -`fix: gitea seed recovery and workflow checkout ref` - -## Suggested PR title +## Title `Synology KIS workflow recovery, branch checkout fix, and seed JSON tracking` -## What changed +## Short Body -- 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. +- `kis_data_collection.yml` now checks out the triggering ref instead of always fetching `main`. +- `Prepare Raw Seed Snapshot` now accepts `GatherTradingData.json`, regenerates from `GatherTradingData.xlsx`, or falls back to Google Drive download via `.clasprc.json`. +- `qualitative_sell_strategy.yml` uses the same checkout and seed-recovery path. +- `GatherTradingData.json` is now tracked in git so the runner gets a canonical seed snapshot. +- `tools/validate_platform_transition_wbs_v1.py` was updated to validate the new workflow text without false positives. -## Evidence to cite in the PR +## Verified - `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` +- Gitea run `165` on `kis_data_collection.yml` succeeded +- Gitea run `166` on `qualitative_sell_strategy.yml` succeeded -## 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. diff --git a/docs/GATHERTRADINGDATA_XLSX_DECISION_2026-06-21.md b/docs/GATHERTRADINGDATA_XLSX_DECISION_2026-06-21.md new file mode 100644 index 0000000..d5d5867 --- /dev/null +++ b/docs/GATHERTRADINGDATA_XLSX_DECISION_2026-06-21.md @@ -0,0 +1,35 @@ +# GatherTradingData.xlsx Decision + +## Option A: Track `GatherTradingData.xlsx` + +Pros: + +- Runner checkout always has the workbook. +- JSON regeneration never depends on Google Drive access. +- Manual recovery is simpler for operators. + +Cons: + +- Large binary file increases repo size and diff noise. +- Workbook changes become harder to review. +- The repository becomes dependent on spreadsheet artifacts that are not needed for normal runtime collection. + +## Option B: Keep `GatherTradingData.xlsx` untracked + +Pros: + +- Repository stays smaller and cleaner. +- `GatherTradingData.json` remains the canonical runtime seed. +- Workflow can regenerate from local workbook or download it only when required. + +Cons: + +- If both seed files are missing, the workflow needs a download fallback or an operator intervention. +- Recovery depends on `.clasprc.json` or another source of truth. + +## Recommendation + +- Keep `GatherTradingData.xlsx` untracked. +- Track `GatherTradingData.json` in git. +- Preserve the workflow fallback path for regeneration and download. + diff --git a/docs/MAIN_MERGE_FINAL_CHECKLIST_2026-06-21.md b/docs/MAIN_MERGE_FINAL_CHECKLIST_2026-06-21.md new file mode 100644 index 0000000..71fc791 --- /dev/null +++ b/docs/MAIN_MERGE_FINAL_CHECKLIST_2026-06-21.md @@ -0,0 +1,25 @@ +# Main Merge Final Checklist + +## Before merge + +- Confirm PR `#67` is the active review target. +- Confirm both workflow dispatch smoke tests succeeded: + - `kis_data_collection.yml` + - `qualitative_sell_strategy.yml` +- Confirm `python tools/validate_platform_transition_wbs_v1.py` passes. +- Confirm `python tools/validate_gitea_secrets_contract_v1.py` passes. +- Confirm `GatherTradingData.json` is present in the branch. + +## Merge criteria + +- `Checkout Code` uses the triggering branch ref. +- `Prepare Raw Seed Snapshot` succeeds without manual intervention. +- KIS collector writes SQLite output successfully. +- Qualitative sell workflow runs without seed-file failure. + +## After merge + +- Re-run the two Gitea dispatch smoke tests on `main`. +- Verify the runner sees the same seed behavior on `main`. +- Keep `GatherTradingData.xlsx` untracked unless a future workflow explicitly requires it in checkout. +