jarca-ledger-mcp/docs/batches/bat-006_20260630_pytest-apptest-smoke-ci-automation/implementation.md

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.