Hot-loader ignores --spec filter and re-introduces completed specs

[mickume]

Bug Summary

When af plan --spec <name> is used to create a filtered plan, the hot-loader at sync barriers discovers and injects unrelated specs into the running graph — including specs that were completed long ago. This causes af code to create worktrees, dispatch sessions, and burn tokens on work that was never requested.

Reproduction

1. Have multiple spec directories on disk, some already completed (e.g. 01_nightshift_afspec_models, 06_duckdb_reader_writer_split)
2. Run af plan --spec 09_worktree_path_collision — DB correctly contains only spec 09
3. Run af code
4. After the first sync barrier fires (default: every 5 completed tasks), the hot-loader scans the full specs directory and injects specs 01 and 06 into the live graph
5. Worktrees, branches, and sessions are created for those unrelated specs

Root Cause

The bug is a logic interaction between save_plan's full-table wipe and the hot-loader's Gate 4 ("already complete") check.

hot_load.py:294:

if are_all_tasks_done(spec_path) and _are_all_plan_nodes_done(spec.name, db_conn):

Gate 4 requires both conditions:

• are_all_tasks_done() — checks tasks.json checkboxes
• _are_all_plan_nodes_done() — checks plan_nodes table in DuckDB

But save_plan() (persistence.py:86-88) does DELETE FROM plan_nodes before inserting the filtered plan. So after af plan --spec 09, specs 01 and 06 have zero rows in plan_nodes. _are_all_plan_nodes_done() returns False when total == 0 (line 220: total > 0 and total == done), causing Gate 4 to fail open — treating "not in this plan" as "not done yet."

hot_load.py:306-329 (discover_new_specs):

all_specs = discover_specs(specs_dir)  # no filter_spec passed

The hot-loader scans the entire specs directory with no awareness of the filtered_spec metadata stored in plan_meta.

Impact

• Wastes API tokens on sessions for already-completed specs
• Creates stale worktrees and branches that collide with each other (multiple nodes sharing group 0 worktree paths)
• Cascade of workspace setup failures (git worktree collisions) that trigger retry loops
• Undermines the purpose of --spec filtering entirely

Observed Log Evidence

[INFO] agentfox.engine.barrier: Sync barrier 1 triggered at 5 completed tasks
[INFO] agentfox.engine.hot_load: Hot-loaded 2 new spec(s): 01_nightshift_afspec_models, 06_duckdb_reader_writer_split
[INFO] agentfox.graph.injection: Injected reviewer node '01_nightshift_afspec_models:0:reviewer:pre-review' at runtime
[INFO] agentfox.engine.graph_sync: State transition: node=01_nightshift_afspec_models:0:reviewer:drift-review from=pending to=in_progress reason=dispatched
[INFO] agentfox.engine.graph_sync: State transition: node=06_duckdb_reader_writer_split:0:reviewer:drift-review from=pending to=in_progress reason=dispatched

Suggested Fix

Two complementary changes:

1. _are_all_plan_nodes_done() should return True (not False) when total == 0 and the plan was filtered. Alternatively, Gate 4 should treat "no plan nodes AND plan has filtered_spec set AND this spec is not the filtered spec" as "skip."

2. discover_new_specs_gated() should respect filtered_spec from plan_meta. If the persisted plan has a filtered_spec, the hot-loader should only consider that spec as a candidate — or at minimum exclude specs not matching the filter.

Affected Files

• packages/agentfox/agentfox/engine/hot_load.py — discover_new_specs_gated(), _are_all_plan_nodes_done()
• packages/agentfox/agentfox/graph/persistence.py — plan_meta.filtered_spec (already stored, just not consulted by hot-loader)

[mickume]

Analysis

Auto-generated by af-fix. Reviewing issue context and codebase.

Diagnosis

Classification: bug

Root Cause / Problem:
discover_new_specs_gated() in hot_load.py scans the entire specs directory without consulting the filtered_spec metadata stored in graph.metadata.filtered_spec. When af plan --spec X creates a filtered plan, save_plan() wipes all plan_nodes rows before inserting only spec X's nodes. At the next sync barrier, the hot-loader discovers specs A and B on disk, finds them not in known_specs, and evaluates Gate 4 — but _are_all_plan_nodes_done() returns False (because total == 0 for those specs after the wipe), so the gate fails open and the specs are re-introduced.

The filtered_spec value is already persisted in plan_meta and loaded into graph.metadata.filtered_spec — it's just never consulted by the hot-loader.

Planned Fix

Approach:

1. Add a filtered_spec: str | None parameter to discover_new_specs_gated(). When set, reject any candidate spec whose name doesn't match the filter before running the gate pipeline.
2. In hot_load_into_graph(), read graph.metadata.filtered_spec and pass it to discover_new_specs_gated().

This is the minimal, correct fix. The _are_all_plan_nodes_done() behavior of returning False when total == 0 is semantically correct for its intended purpose — the real problem is that the hot-loader shouldn't be considering those specs at all.

Files to modify:

• packages/agentfox/agentfox/engine/hot_load.py — Add filtered_spec parameter to discover_new_specs_gated(), pass from hot_load_into_graph()
• packages/agentfox/tests/unit/engine/test_hot_load_gates.py — Add tests for filtered_spec behavior

---

Analysis by af-fix. Implementation follows.

[mickume]

Fix Implemented

Auto-generated by af-fix.

Summary

Added a filtered_spec parameter to discover_new_specs_gated() that rejects candidate specs not matching the filter before gate evaluation. In hot_load_into_graph(), graph.metadata.filtered_spec is now passed through to the gated discovery function. This prevents the hot-loader from re-introducing completed specs when af plan --spec X was used.

Changes

File	Change
packages/agentfox/agentfox/engine/hot_load.py	Added filtered_spec parameter to discover_new_specs_gated() with pre-filter; passed graph.metadata.filtered_spec from hot_load_into_graph()
packages/agentfox/tests/unit/engine/test_hot_load_gates.py	Added 4 tests for filtered_spec behavior

Tests

• test_unrelated_spec_rejected_when_filter_set: unrelated spec rejected
• test_matching_spec_passes_filter: matching spec proceeds to gates
• test_no_filter_allows_all_specs: None filter allows all specs
• test_multiple_candidates_only_match_survives: multiple candidates filtered to match only

Verification

• All existing tests pass: ✅
• New tests pass: ✅
• Linter / formatter: ✅
• No regressions: ✅

Branch

fix/issue-630-hotloader-spec-filter — ready to merge into main.

---

Fix by af-fix. Ready for review.