feat(validate): warn on undeclared agent.output refs and field-level mismatches in explicit mode

[jrob5756]

Closes #105.

PR #125 added explicit-mode warnings for undeclared workflow.input / agent.output references. While building on top of it, I confirmed (by running real workflows that pass validation and crash at runtime) two follow-up gaps that still produce the exact TemplateError: 'dict object' has no attribute 'X' symptom from #105.

Gap A — Field-level precision

When an agent declares input: [a.output.foo], the engine (engine/context.py:_add_agent_input) copies only the foo field into the agent's ctx. A prompt that then references {{ a.output.bar }} fails at runtime — same 'dict object' has no attribute 'bar' error the issue body quotes. The validator previously tracked declared agents as a flat set[str] of names, so this slipped through.

Fix: track declared fields per root as dict[str, set[str | None]] (where None in the set means "whole-output declared, any field allowed"), and emit a warning naming the missing field when a template references a field not in the declared set. Same logic applies to static parallel groups (pg.outputs.member.field — the engine field-slices on len ≥ 3). For-each groups are intentionally skipped because the engine copies whole members regardless of .field suffix (elif is_for_each_dict or len(remaining_parts) == 2), so field-precision warnings would be false positives there.

Gap B — Script/sub-workflow agent.output exclusion was too broad

agent.type not in ("script", "workflow") previously suppressed both workflow.input and agent.output warnings. But the engine's _LOCAL_RENDER_AGENT_TYPES carve-out only populates workflow.input for these types — agent.output references still raise KeyError in _add_explicit_input if undeclared.

Fix: split the gate. Keep the script/workflow/human_gate exclusion for workflow.input warnings only; for agent.output warnings, only exclude human_gate (whose prompts render in accumulate mode).

Other improvements

• _extract_template_refs returns a typed TemplateRefs NamedTuple carrying field detail (agent_output_fields, group_member_fields, group_error_refs) alongside the existing flat agent_refs set.
• AST walker filters inner-link Getattr nodes — for {{ a.output.bar }}, only the outermost Getattr (attrs=["output", "bar"]) is processed. The inner Getattr (attrs=["output"]) is the .node of the outer, so emitting it separately would falsely register a whole-output reference and suppress the field-precision warning.
• AST walker detects method-call Getattr nodes (those that are the callee of a Call). {% for k,v in a.output.items() %} now registers as a whole-output ref rather than a field ref to items — eliminates a class of false positives.
• human_gate agents added to the explicit-mode exclusion list — fixes a pre-existing false-positive warning. Gate prompts render via context.get_for_template() which forces mode='accumulate', so explicit-mode declarations are not required.
• Documented limitations in _extract_template_refs: bracket access (a.output["x"]) and dynamic field access (a.output[var]) are intentionally not detected.

Example output

Issue #105's exact example:

⚠ agent 'intake' prompt references 'workflow.input.prompt' but agent 'intake'
  does not declare 'workflow.input.prompt' in its input: list (explicit context mode)

Gap A (new):

⚠ agent 'b' args[0] references 'a.output.bar' but agent 'b' only declares
  a.output.foo in its input: list (explicit context mode)

Gap B (newly caught):

⚠ agent 'scripty' args[0] references 'a.output' but agent 'scripty' does not
  declare 'a.output' in its input: list (explicit context mode)

Testing

• 14 new tests across TestExtractTemplateRefs, TestExplicitModeWarnings (script/sub-workflow agent.output, sub-workflow workflow.input carve-out regression, human_gate false-positive regression), and a new TestExplicitModeFieldPrecision class (field precision, whole-output declarations, method-call filter, static parallel precision, for-each precision skip, sub-workflow input_mapping field precision).
• Existing tests updated for the new NamedTuple return shape.
• 2640 tests pass, 15 skipped (full repo suite, -m "not performance").
• make lint ✅
• make typecheck: only the pre-existing dialog_evaluator.py diagnostic (verified by stashing and re-running on main).
• All examples/*.yaml continue to validate without unexpected warnings.

Decisions that may need a closer look

• Severity: kept as warning per feat(validation): warn when explicit-mode agent prompts reference undeclared inputs #105's framing, even for field-mismatch cases where runtime failure is essentially certain. Rationale: consistency, and templates can still legitimately use guards/defaults.
• TemplateRefs is a typed NamedTuple, not a dataclass — chosen for slightly cleaner tuple-style unpacking in tests and zero runtime overhead. No behavior difference.
• Dict-method filter is belt-and-suspenders — the primary defense is the Call-node filter (handles a.output.items()); _DICT_METHOD_NAMES covers the rarer case of referencing a method without calling it ({{ a.output.items }} as a value).

Suggested commit on merge: feat(validate): warn on undeclared agent.output refs and field-level mismatches in explicit mode (#NNN)

[jrob5756]

Review-driven update

I ran a multi-agent review (code-review, test-analyzer, silent-failure-hunter, type-design-analyzer, code-simplifier) before flagging this PR for human review. Two agents independently caught the same real bug I had missed, plus a related TemplateAssertionError leak. Force-pushed 249423d to address them along with smaller polish.

Bugs fixed (verified at runtime, not just on paper)

1. pg.errors / pg.outputs namespace conflation in the declared-input tracking. INPUT_REF_PATTERN used a non-capturing (?:outputs|errors) group, so declaration-side tracking merged the two namespaces. This caused two symptoms:

   • False negative: input: ["pg.errors"] + prompt: "{{ pg.outputs.a.val }}" → no warning. The runtime would KeyError on "outputs".
   • Misleading message: input: ["pg.errors.a.foo"] + prompt: "{{ pg.outputs.a.bar }}" → warning text said "only declares pg.outputs.a.foo" — but the user declared pg.errors.a.foo, not pg.outputs.a.foo.

   Fixed by adding a pg_kind named capture and splitting tracking into three independent accumulators (declared_agent_output_fields, declared_group_output_member_fields + declared_groups_with_outputs, declared_group_errors). Iteration in _validate_template_references now goes over the structured TemplateRefs maps directly (one block per namespace) so the kinds can't leak across.

2. TemplateAssertionError leak: _extract_template_refs only caught TemplateSyntaxError. Templates that parse but trip a semantic check during meta.find_undeclared_variables (e.g., duplicate {% block %} names) would hard-fail validation. Now also caught — render-time will surface the precise error if the workflow actually runs.

Test additions (13 new, total 27 new on the PR)

• Namespace separation matrix: three tests asserting that outputs and errors declarations don't suppress warnings for the other namespace, plus an explicit regression test that the message never reads "only declares pg.outputs.a.foo" when the declaration was for pg.errors.a.foo.
• Static parallel matrix: whole-group / whole-member / exact-field / bare-member-with-specific-decl shapes.
• Optional ? suffix in explicit-mode declarations.
• Mixed bare + specific extractor case: {{ a.output }} {{ a.output.foo }} exercises both prefix-chain dedup paths simultaneously.
• Method-call filter on specific-field decl — the previous test used a whole-output decl which didn't actually exercise the filter logic (test-analyzer's catch).
• pg_kind regex capture regression.
• TemplateAssertionError graceful-degradation path.

Code polish (from code-simplifier suggestions)

• Track group-outputs declaration set during the parsing pass instead of recomputing {g for (g, _) in declared_group_output_member_fields} per template iteration.
• Hoist declared_list join out of the field-precision inner loop.
• Split compound guards in the group-output block to mirror the agent-output block style.
• Skipped: helper extraction for the three "unknown agent" error blocks (modest savings, light risk) and field-name renaming on TemplateRefs (touches the NamedTuple shape — could be a follow-up).

Verification

• 151 validator/CLI tests pass (up from 138).
• Full suite: 2653 passed, 15 skipped.
• make lint clean.
• All examples/*.yaml validate without unexpected warnings.
• Both runtime-failure scenarios from issue feat(validation): warn when explicit-mode agent prompts reference undeclared inputs #105 now caught at validation time with informative messages.

Diff vs previous push:

src/conductor/config/validator.py   | +/- changes
tests/test_config/test_validator.py | 13 new tests