fix(sdlc): unify coord event-log path resolution onto coord_base_dir()

[ryanklee]

Summary

Collapses coord event-log path resolution onto the canonical shared.coord_event_log resolvers in the dispatch launcher and the retro-grant watcher, killing the dead root-owned /var/lib/hapax/coord defaults that uid 1000 could never mkdir.

Root cause (final audit, cluster 3 — split-brain SSOT, dispatch HARD-BLOCK):

• coord_event_log_from_env() (hapax-methodology-dispatch) and coord-retro-grant-watch hardcoded /var/lib/hapax/coord/* defaults instead of calling the resolvers coord_event_log.py and coord-grant-mint already use.
• No systemd unit sets the env overrides, so in production the dead defaults fired: the dispatch-launch append() PermissionError'd on /var/lib mkdir, the fail-open spool ALSO PermissionError'd, and CoordDispatchError propagated → the launch coord write HARD-BLOCKED. The live ledger holds only origin=cli stage transitions, zero dispatch.launch.
• The retro-grant reader and the grant-mint writer disagreed on the grants dir, so retro-grants never fulfilled.

Changes

• hapax-methodology-dispatch: coord_event_log_from_env() defaults derive from coord_base_dir() (→ ~/.cache/hapax/coord). Per-surface HAPAX_COORD_* overrides still win (test isolation relies on them).
• coord-retro-grant-watch: resolves grants dir + key via default_grant_dir()/default_grant_key() — exact reader/writer parity with coord-grant-mint. Dead constants removed; docstring reconciled.
• docs: design doc §4.3/§4.4 + driving-session anchors reconciled to ~/.cache/hapax/coord with a supersession note (no dual live paths).
• tests: test_coord_path_unification.py (scripts-no-/var/lib lint + unset-resolves-to-cache-base); test_coord_retro_grant_watch.py end-to-end reader/writer parity.

Verification

• pytest coord path-unify + retro + grant-mint → 13 passed; test_hapax_methodology_dispatch.py → 36 passed (no regression).
• ruff check / ruff format --check / pyright clean on changed files.
• Live ledger: ~/.cache/hapax/coord provisioned + writable; baseline 10 sdlc.stage_transition, 0 dispatch/launch.

Acceptance criteria

• grep -rn '/var/lib/hapax/coord' scripts/ returns nothing (lint test enforces).
• coord-retro-grant-watch reads the same grants dir coord-grant-mint writes (parity test).
• coord_event_log_from_env() unset → coord_base_dir() (~/.cache/hapax/coord).
• Design doc §4.3/§10-anchors cite ~/.cache/hapax/coord; workspace CLAUDE.md cites no coord path. Vault source copy of the master design is outside this task's mutation scope — flagged for the operator.
• Ruff/tests pass.

Post-deploy (runtime realization, not a PR deliverable): the AC "a live dispatch-launch writes a coord event to ~/.cache/hapax/coord/ledger.db" realizes once this lands on origin/main and the dispatch path is deployed. The code fix + mechanism are proven here (dispatch suite asserts events land in the resolved ledger; resolver test proves the default base; live tree confirmed writable with 0 dispatch.launch today).

Task: reform-coord-eventlog-path-unify-20260601 · AuthorityCase: CASE-CROSS-RUNTIME-COMMS-001

🤖 Generated with Claude Code

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR migrates coord event-log, grant file, and spool persistence from root-owned /var/lib/hapax/coord/ to user-writable ~/.cache/hapax/coord/. The design spec is updated to document new canonical paths, two scripts are refactored to use shared path-resolution helpers, and comprehensive tests enforce the migration and prevent regressions.

Changes

Coord Storage Path Migration

Layer / File(s)	Summary
Design specification update docs/superpowers/specs/2026-05-30-sdlc-frictionless-self-direction-design.md	Event-log location updated to ~/.cache/hapax/coord/ledger.db (with JSONL mirror), spool intake relocated to the same cache base, grant files now stored at ~/.cache/hapax/coord/grants/<id>.grant, and "Key anchors" section updated to reflect relocated log path.
Script path resolution unification scripts/coord-retro-grant-watch, scripts/hapax-methodology-dispatch	coord-retro-grant-watch now imports and uses default_grant_dir() and default_grant_key() from shared coord helpers instead of hardcoded /var/lib/... defaults; hapax-methodology-dispatch imports coord_base_dir() and derives ledger/jsonl/spool paths from it, preserving env-var overrides while changing fallback paths to user-writable cache.
Path migration test coverage tests/scripts/test_coord_path_unification.py, tests/scripts/test_coord_retro_grant_watch.py	New test_coord_path_unification.py scans scripts to ensure no hardcoded /var/lib/hapax/coord literals and validates coord_event_log_from_env() resolves to $HOME/.cache/hapax/coord without env overrides; new integration test in test_coord_retro_grant_watch.py validates retro-grant watcher fulfillment behavior when only the canonical HAPAX_COORD_DIR base is set.

🎯 2 (Simple) | ⏱️ ~15 minutes

Possibly related PRs

• hapax-systems/hapax-council#3805: Updates scripts/coord-retro-grant-watch and coord event-log/grant path resolution to use shared user-writable ~/.cache/hapax/coord defaults instead of /var/lib/..., which directly complements escape-grant/retro-grant flow expecting grant files to be found and verified by the shim/watcher.

• hapax-systems/hapax-council#3822: Changes coord SSOT default paths (ledger/jsonl/spool and grant dir/key) to resolve under user-writable ~/.cache/hapax/coord via shared env/base-dir helpers, removing hardcoded /var/lib/hapax/coord and aligning escape-grant/grant-mint behavior accordingly.

• hapax-systems/hapax-council#3793: Modifies scripts/hapax-methodology-dispatch's coord_event_log_from_env()/coord event-log construction to use coord_base_dir under ~/.cache/hapax/coord, directly aligning with the retrieved PR that introduces env-derived event-log wiring for atomic dispatch fusion.

Poem

🐰 Cache-bound coordinates, clean and bright,
No /var/lib shadows in the night!
User-writable paths now lead the way,
Grant files dance in cache arrays.
Scripts embrace the shared, unified light!

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 20.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The PR title 'fix(sdlc): unify coord event-log path resolution onto coord_base_dir()' clearly and concisely summarizes the main change: consolidating path resolution onto a shared function for canonical defaults.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description check	✅ Passed	The PR description is comprehensive and follows the template structure with all required sections completed including Summary, AuthorityCase, Test plan, and CLAUDE.md hygiene checklist.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch eta/reform-coord-eventlog-path-unify-20260601

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}