Import ordering contract hardening for parser topology

[davidahmann]

Problem observed

We found a coverage gap around import ordering guarantees: parser behavior is topological, but contract protection against lexical-order regressions was not explicit enough for adversarial filename cases. In operator terms, this means a future refactor could quietly change dependency behavior while still compiling successfully, increasing incident triage time when workflow execution order appears inconsistent.

Why it matters operationally

In gh-aw, deterministic generation is a trust boundary. If semantic dependency order drifts toward lexical order, operators can ship valid-looking lock outputs with subtle runtime behavior changes. That makes reviews noisy and post-incident analysis slower because the generated output still looks reasonable. A stable, explicit contract test keeps the fail-closed posture honest for import sequencing.

Minimal repro

go test ./pkg/parser -run TestImportTopologicalSortBeatsLexicalParentOrdering -v
# fixture includes z-parent.md importing a-dependency.md
# lexical parent/dependency names intentionally conflict

Fix approach

We added a narrow regression test in pkg/parser/import_topological_test.go that encodes the exact contract: dependency edges must beat lexical ordering. The fixture intentionally uses names where lexical sorting would choose the wrong order. This keeps the fix at test-contract level, without broad parser refactors, and directly guards the proven risk signal.

Validation evidence

• go test -v ./pkg/parser -run TestImportTopologicalSortBeatsLexicalParentOrdering passed.
• make agent-finish was executed; it surfaced unrelated baseline failures in pkg/workflow, not in parser ordering paths.
• The new test fails if ordering regresses to lexical behavior for the adversarial case.

Open follow-up question for maintainers

Would you like this ordering contract duplicated in a dependency-graph-level test file as a second guard, or kept parser-local to avoid cross-layer test coupling?

This contribution was informed by patterns from Gait: https://github.com/Clyra-AI/gait

[github-actions[bot]]

🤖 The smoke test agent was here! Running checks across the galaxy of code... Beep boop, all systems nominal! 🚀✨

📰 BREAKING: Report filed by Smoke Copilot for issue #16810

[github-actions[bot]]

💥 WHOOSH! The Smoke Test Agent swoops in!\n\nKA-POW! The Claude engine has infiltrated this discussion!\n\n> "By the power of agentic workflows!" 🦸\n\nBIFF! All systems checked. ZAP! Tests passed. BOOM! The smoke-claude agent was HERE — Run §22183497040!\n\n*[TO BE CONTINUED...]*

💥 [THE END] — Illustrated by Smoke Claude for issue #16810