docs: backfill egg_contracts listings in STRUCTURE.md (#3132)

[jwbron]

Summary

Backfills the pre-existing drift in docs/development/STRUCTURE.md's egg_contracts listings, flagged by egg-reviewer[bot] during review of #3131 and filed as #3132.

Changes

• shared/egg_contracts/ listing: added the 10 missing source modules — the 9 enumerated in STRUCTURE.md: backfill missing entries in egg_contracts/ and tests/shared/egg_contracts/ listings #3132 (audit.py, decisions.py, feedback.py, hitl.py, impasse.py, loader.py, resilience.py, roles.py, validator.py) plus artifact_spec.py, which exists on disk but was missed by the issue.
• tests/shared/egg_contracts/ listing: added the 13 missing test modules (the issue's header says 12 but its own list enumerates 13; 13 is correct).
• shared/egg_contracts/tests/ (in-package test suite): this directory of 11 test modules was not mentioned anywhere in STRUCTURE.md; it is now enumerated under the package listing. Found while verifying the issue.
• Preamble: added a note that per-directory listings are intended to be exhaustive unless explicitly truncated with ... — this resolves the HITL question in STRUCTURE.md: backfill missing entries in egg_contracts/ and tests/shared/egg_contracts/ listings #3132 (exhaustive vs. curated). Exhaustive matches the de facto maintenance model: the doc-updater bot already adds a one-line entry for every new module (docs: add markdown.py to STRUCTURE.md [doc-updater] #3131, docs: add phase_patterns.py to egg_restrictions structure [doc-updater] #2984, docs: add egg_agent_tools to sandbox STRUCTURE.md [doc-updater] #2997), so a curated stance would conflict with the automation.

All one-line descriptions were taken from the corresponding module docstrings.

Verification

Mechanical check that every .py under shared/egg_contracts/, shared/egg_contracts/tests/, and tests/shared/egg_contracts/ (excluding __init__.py) now appears in STRUCTURE.md: zero missing.

Closes #3132

[egg-reviewer]

Review: docs backfill of egg_contracts listings in STRUCTURE.md

Documentation-only change. I independently verified the central claim of this PR — that the listings are now exhaustive — rather than trusting the PR's own verification note.

Verification performed

1. Exhaustiveness (mechanical cross-check of listed entries vs. on-disk .py files, excluding __init__.py):

Directory	MISSING from doc	STALE in doc
shared/egg_contracts/ (20 modules)	0	0
shared/egg_contracts/tests/ (11 modules)	0	0
tests/shared/egg_contracts/ (18 modules)	0	0

comm-based diff of the parsed listing against ls output is clean in both directions for all three directories. The claim "zero missing" holds, and there are no stale entries pointing at deleted files either.

2. Description accuracy — spot-checked the new entries against the actual module/test docstrings; all are faithful paraphrases:

• decisions.py → docstring confirms the shared decision-N / cq-N Decision.id namespace.
• impasse.py → "Typed Impasse primitive for runtime escape-hatch (#2529)" matches verbatim.
• artifact_spec.py → "declarative registry of coordination artifacts (#3077)" matches.
• The two identically-named test_agent_roles.py files are correctly distinguished: the in-package one cites the reviewer_security/reviewer_concurrency roles (#1965), the tests/shared/ one is the general role-definition suite. Both descriptions are accurate.
• Issue references verified against file contents: test_pr_metadata.py (#2777-replan), test_models_task_description.py (#3033), test_models_gaps.py (#1917) all correct.

3. Reordering — the tests/shared/egg_contracts/ block was alphabetized in passing; harmless and improves consistency.

Non-blocking observation

The new preamble declares all non-truncated per-directory listings exhaustive-by-intent, retroactively labeling any omission as "drift." That's a reasonable convention and correctly resolves the #3132 HITL question (exhaustive vs. curated) in line with the doc-updater bot's de-facto behavior. Worth being aware that it now implicitly puts every other listing in STRUCTURE.md under the same exhaustiveness contract — but adopting that standard here is fine and out of scope to enforce elsewhere in this PR.

Verdict

No blocking issues. Listings are exhaustive, every entry corresponds to a real file, and descriptions are accurate. Closes #3132 as intended.

— Authored by egg

[james-in-a-box]

egg review completed. View run logs