[P1] ZARA-020 — Reconcile all branches and remove divergent duplicate runtime implementations #60

Merged

lost-rob0t merged 1 commit from refactor/zara-020-canonical-runtime into master

2026-07-19 19:52:11 +00:00

lost-rob0t commented

2026-07-19 19:48:39 +00:00

(Migrated from github.com)

Summary

Closes #21.

Removes the deprecated duplicate runtime implementations and proves all wrappers delegate to canonical modules. Adds a read-only branch audit script.

Branch Audit

All 19 local + 27 remote branches were surveyed via scripts/audit-branches.sh:

Classification	Branches	Action
Merged	fix/zara-001 through fix/zara-018, feat/zara-timer-alarm-sounds, agent/ci-test-gate, cleanup, memory, fix/recover-zara-006-011	Content in master; branches not deleted (not in scope)
Obsolete (stale merge-commit artifacts)	fix/zara-003 through fix/zara-011 (remote), revert-36-, revert-44-	Content already merged via PRs; branch tips are pre-final-merge snapshots
Obsolete (superseded)	feat/intent-resolver-nextgen (local, 7 commits)	Old feature branch; useful fixes (audio overflow, nix flake HOME) already addressed by ZARA-001 through ZARA-019
Active (not disturbed)	agent/readme-rewrite (draft PR #53)	Documentation-only draft; left alone

No branch-only bug fix was silently lost. All useful fixes from the fix/zara-* and feat/intent-resolver-nextgen branches are already in master via the ZARA-001 through ZARA-019 PR series.

What changed

Removed (confirmed unused — no active imports)

zara/agent/nodes.py — deprecated, logic integrated into graph.py
zara/agent/routing.py — deprecated, logic integrated into graph.py
zara/agent/state.py — duplicate AgentState TypedDict, only imported by the two deprecated files above
zara/agent/tools/base.py — custom BaseTool/BaseSkill/PythonSkill/PrologSkill abstractions, unused (ToolRegistry uses langchain_core.tools.BaseTool)

Kept (already canonical)

scripts/zara_wake.py — thin delegate to zara.wake.main
scripts/zara_dictate.py — thin delegate to zara.dictate.cli_main (referenced by modules/dictate.pl bundled_dictation_script/1)
zara/agent/graph.py — sole active agent flow (defines AgentState, create_agent_node, should_continue, run_conversation_loop)
zara/agent/tools/registry.py — ToolRegistry using LangChain BaseTool
zara/llm.py and modules/llm_client.pl — different language implementations (Python agent-side vs Prolog runtime-side), both canonical for their respective paths

Tests

t/test_canonical_paths.py — 7 tests enforcing the canonical-runtime contract:
- Deprecated files do not exist
- graph.py is the sole AgentState source
- scripts/zara_wake.py and scripts/zara_dictate.py are thin delegates (≤15 lines, import and call canonical module)
- ToolRegistry uses LangChain BaseTool
- All setup.py console-script entrypoints resolve to callables
- zara/agent/__init__.py imports from graph.py, not deprecated files
scripts/test-canonical-paths.sh — runs the canonical-paths tests
scripts/audit-branches.sh — read-only, deterministic branch audit (lists all refs with ahead/behind/merged status and unique commit subjects)

Validation

nix develop -c bash -c 'pytest && for test_script in scripts/test-*.sh; do bash "$test_script"; done'
nix flake check
nix develop -c scripts/audit-branches.sh

All 169 pytest tests pass. All 21 shell scripts pass. All 4 flake checks pass (pytest, syntax, prolog-load, wrappers).

Dependencies

ZARA-001 through ZARA-019 — all closed.

## Summary Closes #21. Removes the deprecated duplicate runtime implementations and proves all wrappers delegate to canonical modules. Adds a read-only branch audit script. ## Branch Audit All 19 local + 27 remote branches were surveyed via `scripts/audit-branches.sh`: | Classification | Branches | Action | |---|---|---| | **Merged** | fix/zara-001 through fix/zara-018, feat/zara-timer-alarm-sounds, agent/ci-test-gate, cleanup, memory, fix/recover-zara-006-011 | Content in master; branches not deleted (not in scope) | | **Obsolete (stale merge-commit artifacts)** | fix/zara-003 through fix/zara-011 (remote), revert-36-*, revert-44-* | Content already merged via PRs; branch tips are pre-final-merge snapshots | | **Obsolete (superseded)** | feat/intent-resolver-nextgen (local, 7 commits) | Old feature branch; useful fixes (audio overflow, nix flake HOME) already addressed by ZARA-001 through ZARA-019 | | **Active (not disturbed)** | agent/readme-rewrite (draft PR #53) | Documentation-only draft; left alone | **No branch-only bug fix was silently lost.** All useful fixes from the `fix/zara-*` and `feat/intent-resolver-nextgen` branches are already in master via the ZARA-001 through ZARA-019 PR series. ## What changed ### Removed (confirmed unused — no active imports) - `zara/agent/nodes.py` — deprecated, logic integrated into `graph.py` - `zara/agent/routing.py` — deprecated, logic integrated into `graph.py` - `zara/agent/state.py` — duplicate `AgentState` TypedDict, only imported by the two deprecated files above - `zara/agent/tools/base.py` — custom `BaseTool`/`BaseSkill`/`PythonSkill`/`PrologSkill` abstractions, unused (`ToolRegistry` uses `langchain_core.tools.BaseTool`) ### Kept (already canonical) - `scripts/zara_wake.py` — thin delegate to `zara.wake.main` - `scripts/zara_dictate.py` — thin delegate to `zara.dictate.cli_main` (referenced by `modules/dictate.pl` `bundled_dictation_script/1`) - `zara/agent/graph.py` — sole active agent flow (defines `AgentState`, `create_agent_node`, `should_continue`, `run_conversation_loop`) - `zara/agent/tools/registry.py` — `ToolRegistry` using LangChain `BaseTool` - `zara/llm.py` and `modules/llm_client.pl` — different language implementations (Python agent-side vs Prolog runtime-side), both canonical for their respective paths ## Tests - `t/test_canonical_paths.py` — 7 tests enforcing the canonical-runtime contract: - Deprecated files do not exist - `graph.py` is the sole `AgentState` source - `scripts/zara_wake.py` and `scripts/zara_dictate.py` are thin delegates (≤15 lines, import and call canonical module) - `ToolRegistry` uses LangChain `BaseTool` - All `setup.py` console-script entrypoints resolve to callables - `zara/agent/__init__.py` imports from `graph.py`, not deprecated files - `scripts/test-canonical-paths.sh` — runs the canonical-paths tests - `scripts/audit-branches.sh` — read-only, deterministic branch audit (lists all refs with ahead/behind/merged status and unique commit subjects) ## Validation ```sh nix develop -c bash -c 'pytest && for test_script in scripts/test-*.sh; do bash "$test_script"; done' nix flake check nix develop -c scripts/audit-branches.sh ``` All 169 pytest tests pass. All 21 shell scripts pass. All 4 flake checks pass (pytest, syntax, prolog-load, wrappers). ## Dependencies ZARA-001 through ZARA-019 — all closed.