chore(jarca-ledger): finalize approved batch docs, dashboard, and CI smoke updates

2026-06-30 16:06:47 +09:00
parent 67d8d4871b
commit 4929e52189
75 changed files with 8367 additions and 252 deletions
@@ -0,0 +1,106 @@
+# BAT-006 Implementation
+
+## Implementation Status
+- Status: completed-for-qc
+- Completed At (KST): 2026-06-30 15:23:00 KST
+- Scope: REQ-006 CI automation, synthetic fixture entrypoints, local CI smoke reproduction docs, and StagePilot evidence/state updates.
+- Boundary: REQ-006 is not marked Implemented yet; QC by `jarcaledgerqc` is the next gate.
+
+## Changed Files
+
+### CI workflow
+- `.github/workflows/ci.yml`
+  - Added GitHub Actions workflow triggers for `pull_request`, `push` to `main`, and `workflow_dispatch`.
+  - Added stable gate jobs/check names:
+    - `pytest-regression`
+    - `dashboard-app-test`
+    - `dashboard-http-smoke`
+    - `db-safety-smoke`
+  - Each job installs with `uv` and runs its narrow CI gate command.
+
+### CI fixture and smoke wrappers
+- `scripts/ci_fixture_db.py`
+  - Added deterministic synthetic fixture DB builder for CI/AppTest/smoke checks.
+  - Refuses the operating ledger DB default path and only allows CI fixture filenames.
+  - Seeds synthetic accounts, budget, and transactions, then verifies SQLite integrity.
+- `scripts/ci_dashboard_http_smoke.py`
+  - Added dashboard HTTP smoke wrapper.
+  - Creates a temp synthetic fixture DB, starts Streamlit on loopback, polls for HTTP 200 readiness, and terminates/kills the process during cleanup.
+  - Emits status-only JSON with fixture/readiness/cleanup result.
+- `scripts/ci_db_safety_smoke.py`
+  - Added DB safety wrapper.
+  - Creates temp synthetic source/backup/target DB paths, invokes `scripts/ledger_restore_smoke.py`, and refuses the operating DB path.
+  - Emits status-only JSON with restore/integrity/health result.
+
+### Tests
+- `tests/test_dashboard_app.py`
+  - Added Streamlit AppTest coverage that creates a synthetic fixture DB through `scripts/ci_fixture_db.py`, sets `JARCA_LEDGER_DB_PATH`, and checks core pages render without Streamlit exceptions.
+  - Existing transfer review helper tests remain covered in the dashboard AppTest command.
+
+### Documentation
+- `docs/project-structure.md`
+  - Documented `.github/workflows/ci.yml`, CI fixture builder, HTTP smoke wrapper, DB safety wrapper, stable gate names, and synthetic fixture policy.
+- `docs/runtime-flows.md`
+  - Added `CI validation gates` flow and clarified that browser screenshot/DOM evidence remains local evidence, not a required CI gate.
+- `docs/runbooks/ci-smoke.md`
+  - Added local reproduction commands, wrapper responsibilities, stable GitHub Actions job names, browser evidence boundary, and failure triage guidance.
+- `docs/batches/bat-006_20260630_pytest-apptest-smoke-ci-automation/implementation.md`
+  - Replaced planned placeholder with actual implementation/evidence log.
+- `docs/batches/bat-006_20260630_pytest-apptest-smoke-ci-automation/verification.md`
+  - Added AC-by-AC verification evidence and command results.
+- `docs/batches/bat-006_20260630_pytest-apptest-smoke-ci-automation/index.md`
+  - Moved BAT-006 batch status from `planned` to `release-candidate` for QC.
+- `docs/batches/index.md`
+  - Moved BAT-006 register status from `planned` to `release-candidate`.
+
+## Execution Log
+
+All commands below were run from `/root/projects/jarca-ledger-mcp`.
+
+1. Pytest regression gate
+   - Command: `uv run pytest --ignore=tests/test_dashboard_app.py -q`
+   - Result: PASS, exit code 0.
+   - Output: `............ss...............ss... [100%]`
+
+2. Streamlit AppTest gate
+   - Command: `uv run pytest tests/test_dashboard_app.py -q`
+   - Result: PASS, exit code 0.
+   - Output: `.... [100%]`
+
+3. Dashboard HTTP smoke gate
+   - Command: `uv run python scripts/ci_dashboard_http_smoke.py --host 127.0.0.1 --port 18501 --timeout 45`
+   - Result: PASS, exit code 0.
+   - Output summary:
+     - `success: true`
+     - `gate: dashboard-http-smoke`
+     - `fixture: synthetic`
+     - `fixture_integrity: ok`
+     - `http_status: 200`
+     - `cleanup: terminated`
+
+4. DB safety smoke gate
+   - Command: `uv run python scripts/ci_db_safety_smoke.py --timeout 45`
+   - Result: PASS, exit code 0.
+   - Output summary:
+     - `success: true`
+     - `gate: db-safety-smoke`
+     - `fixture: synthetic`
+     - `fixture_integrity: ok`
+     - `restore_smoke_exit_code: 0`
+     - `restored_exists: true`
+     - `restored_integrity: ok`
+     - `health_success: true`
+     - `operating_db_used: false`
+
+## Validation Summary
+
+- GitHub Actions workflow exists with required BAT-006 trigger shape and stable job names.
+- CI/AppTest/HTTP/DB safety commands pass locally against synthetic/temp DBs.
+- Wrapper output is status-only and does not expose real account identifiers, operating DB data, raw payloads, source financial filenames, or passwords.
+- Browser screenshot/DOM evidence is intentionally not a required CI gate and remains covered by the local browser evidence runbook/flow.
+
+## Remaining Risks / QC Notes
+
+- Remote GitHub Actions has not been executed in this local handoff; QC should confirm the workflow on GitHub if remote runner access is available.
+- Branch protection required-check enforcement is repository configuration outside this codebase.
+- REQ-006 must remain not Implemented until `jarcaledgerqc` completes QC and the requirement implementation state is explicitly confirmed.