Update sphinx-needs-expert agent with latest sphinx-needs features

[patdhlk]

Problem

The sphinx-needs-expert subagent (agents/sphinx-needs-expert/agent.md) has knowledge gaps relative to current sphinx-needs capabilities. This issue documents the specific gaps found by comparing the agent's content against current sphinx-needs documentation (verified via context7).

Specific gaps

1. Outdated configuration terminology

Agent says (line 57-59):

Extra options: custom fields added to all need types.
Extra link types: option, incoming, outgoing with their bidirectional semantics.

Current sphinx-needs: The term extra_options was renamed to fields in sphinx-needs 8+. Configuration in ubproject.toml uses:

[needs.fields.my_field]
description = "..."
schema.type = "string"

[needs.links.my_link]
outgoing = "..."
incoming = "..."

Impact: The expert may recommend deprecated needs_extra_options patterns or fail to recognize modern field/link configuration.

Fix: Replace all references to extra_options with fields. Update config examples to use [needs.fields.*] and [needs.links.*] TOML syntax.

2. Missing schema validation knowledge

Agent says (line 85):

ubc schema validate — Schema compliance report

Current sphinx-needs: Schema validation is configured per-field with schema.* properties:

[needs.fields.asil]
description = "Automotive Safety Integrity Level"
schema.type = "string"
schema.enum = ["QM", "A", "B", "C", "D"]

[needs.fields.efforts]
description = "FTE days"
schema.type = "integer"
schema.minimum = 0

Plus project-level schema: schema_definitions_from_json, schema_debug_active, schema_debug_ignore.

Impact: The expert cannot guide users on field-level validation, JSON schema integration, or debug modes.

Fix: Add schema validation section covering field-level constraints, JSON schema definitions, and debug configuration.

3. Missing needarch directive

Agent does not mention needarch.

Current sphinx-needs: needarch is a specialized variant of needuml that works inside needs and provides need() and import() Jinja functions for dynamic architecture diagrams embedded within need directives.

Impact: Expert won't suggest needarch for embedded diagrams in requirements.

Fix: Add needarch to the detailed need parsing section (capability 3).

4. Missing needuml Jinja context functions

Agent does not mention Jinja functions in needuml.

Current sphinx-needs: needuml supports Jinja2 context with:

• needs — dict of all needs keyed by ID
• flow(id) — render a need as PlantUML using needflow layout
• filter(filter_string) — filter needs dynamically
• Full Jinja2 loops and conditionals for dynamic diagram generation

Impact: Expert misses a significant capability for dynamic visualization.

Fix: Document needuml Jinja context in capability 3.

5. Missing needs_import_keys (v4.2.0)

Agent mentions needimport (line 49) but not needs_import_keys.

Current sphinx-needs: needs_import_keys (added v4.2.0) maps keys to file paths for use with needimport, simplifying import configuration.

Fix: Add to schema understanding section (capability 4).

6. Missing needs_debug_filters (v4.0.0)

Agent does not mention filter debugging.

Current sphinx-needs: needs_debug_filters = True logs all filter processing to debug_filters.jsonl in the build output. Essential for debugging complex filters in needtable, needflow, needlist.

Fix: Add to data access Tier 3 as a debugging aid.

7. Missing needflow advanced options

Agent does not detail needflow options.

Current sphinx-needs: needflow now supports:

• engine — plantuml (default) or graphviz (v2.3.0)
• root_id / root_direction / root_depth — scoped flows from a single need (v2.2.0)
• show_filters — display filter info below chart (v2.3.0)
• show_legend — display type color legend (v2.3.0)
• alt — alt text for generated image (v2.3.0)

Impact: Expert can't recommend scoped flows or graphviz rendering.

Fix: Add needflow options to capability 3 or a new visualization section.

8. extra_links terminology in Tier 3 parsing

Agent says (line 123-124):

extra_links: Link type definitions...
extra_options: List of custom option names...

Current sphinx-needs: In ubproject.toml:

• Links are under [needs.links.*] (not extra_links)
• Fields are under [needs.fields.*] (not extra_options)

The conf.py fallback still uses needs_extra_links and needs_extra_options, but the agent should prefer TOML-first terminology.

Fix: Update Tier 3 Step B to use current TOML paths. Keep conf.py fallback with old names clearly marked as legacy.

9. Missing need_part in parsing documentation

Agent mentions need_part is not explicitly covered in parsing rules.

Current sphinx-needs: :need_part: creates testable sub-parts within a need, referenced as NEED_ID.part_id. These participate in links (e.g., :tests: SPEC_001.subspec_1).

Impact: Expert may not parse or resolve need_part references correctly.

Fix: Add need_part parsing to capability 3, including the ID.part_id reference syntax.

10. Missing needextend details

Agent mentions needextend (line 49) but only as a directive name.

Current sphinx-needs: needextend dynamically modifies existing needs post-definition. Modified needs get is_modified and modifications fields. Useful for bulk updates and conditional modifications.

Fix: Document needextend behavior and the is_modified/modifications meta-fields.

Files to modify

agents/sphinx-needs-expert/agent.md

Approach

1. Use context7 to verify each fix against current sphinx-needs docs before writing
2. Update terminology: extra_options → fields, extra_links → links (in TOML context)
3. Add missing directives and features to relevant capability sections
4. Keep the agent's structure (capabilities, data access tiers, output formats) unchanged
5. Mark conf.py patterns as legacy/fallback where TOML equivalents exist

Acceptance criteria

• All 10 gaps listed above are addressed
• No references to extra_options remain (replaced with fields)
• TOML config examples use [needs.fields.*] and [needs.links.*] syntax
• needarch, needuml Jinja functions, needextend, need_part documented
• Schema validation (field-level + JSON schema) documented
• needflow advanced options documented
• All changes verified against sphinx-needs docs via context7