docs: add merge checklist and xlsx decision

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.

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.
+

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.
+