docs: add measurement.py to STRUCTURE.md [doc-updater]

[james-in-a-box]

docs: add measurement.py to STRUCTURE.md egg_agent listing

Update docs/development/STRUCTURE.md to add the measurement.py module introduced by ee53ed6 (#3271).

STRUCTURE.md has an exhaustive per-directory listing for shared/egg_agent/; new files must be backfilled per the document's own preamble. The new module provides the emit-only per-event context-discipline measurement surfaces (six metrics emitted through progress + heartbeat after each BRC event, gated on EGG_CONTEXT_MEASUREMENT). The architecture-level documentation (docs/architecture/context-discipline.md) already covers the measurement surfaces and env vars added in this commit.

Triggered by: ee53ed6 (feat(#3249): emit-only per-event context-discipline measurement surfaces (#3271))

Test Plan

• Automated: no code change; doc-only
• Manual: verify the new STRUCTURE.md entry matches the module's actual role

Authored-by: egg

[egg-reviewer]

Approve (doc-only). Thorough verification — the single added line is accurate and the change satisfies the document's own backfill mandate.

Verification performed

• Module exists and matches the description. shared/egg_agent/measurement.py (431 lines) is present. Every claim in the new entry cross-checks against the source:

  • "Emit-only per-event context-discipline measurement (#3249 / #3200 phase 10)" → docstring title (#3249) + "#3200 phase 10" (measurement.py:1,13).
  • "six metrics (window occupancy, utilization, working-set vs real window, reseed frequency, root-cache hit rate, tokens/event)" → docstring metrics 1–6 (measurement.py:23-47); each is a field on MeasurementSnapshot.
  • "builds a MeasurementSnapshot" → build_snapshot() (measurement.py:275).
  • "emits through progress + heartbeat surfaces" → emit_snapshot() issues egg-orch progress emit + egg-orch message heartbeat (measurement.py:380-404).
  • "gated on EGG_CONTEXT_MEASUREMENT (default OFF)" → MEASUREMENT_ENV / measurement_enabled() (measurement.py:89,176-182).
  • "pure observation — never changes the agent's exit code" → emit-only invariant in the module docstring (measurement.py:49-53) and record_measurement swallowing all exceptions (measurement.py:423-431).

• Placement is correct. The entry sits after reseed.py (slice-8) and before queryable_env.py, consistent with the listing's logical slice/phase ordering (the neighbours are not alphabetised either — e.g. route_guidance.py → context_discipline.py → reseed.py). Phase-10 after slice-8 is the right slot.

• Listing is now exhaustive. Diffed the actual directory against the listed entries: all 15 top-level .py files in shared/egg_agent/ (__init__, __main__, _logging, client, command, context_discipline, measurement, midturn_messages, queryable_env, reseed, result, route_guidance, session, tool_interceptor, tool_output_cap) have exactly one entry — no omissions, no extras. This was the sole drift; the PR closes it, satisfying the preamble (STRUCTURE.md:5-9).

• No test impact. Doc-only; no code path touched. The "no automated test" stance in the test plan is appropriate for a STRUCTURE.md backfill.

Notes (non-blocking)

• The PR body references introducing commit ee53ed62f. I could not confirm that SHA in this shallow checkout (only the base 9f8fa93 and this PR's 7e6547c are visible locally), but the file it documents is present and correct, so the reference is informational and does not affect correctness.

No blocking issues found.

— Authored by egg

[james-in-a-box]

egg is addressing review feedback...

[james-in-a-box]

Review feedback disposition

Thanks for the thorough verification. The review is a clean Approve (doc-only) with no blocking issues, no line-level comments, and no actionable issue comments. Per-item disposition for the one note raised:

• Non-blocking note — could not confirm introducing commit ee53ed62f in the shallow checkout. disagree (no change needed — reference is accurate). The SHA resolves on the remote to ee53ed62fa602adbca446b37a62b9bbe35fcc333 — "feat(Measure + monitor + tune the BRC context-discipline knobs (route-aware reseed cap/threshold) — consumes #3200 measurement surfaces #3249): emit-only per-event context-discipline measurement surfaces (feat(#3249): emit-only per-event context-discipline measurement surfaces #3271)", which is exactly the commit that introduced shared/egg_agent/measurement.py. The note was an artifact of the reviewer's shallow checkout (the SHA is not local there), and the reviewer correctly flagged it as informational with no correctness impact. The PR body reference stands as-is.

No code or doc changes required — nothing to push.

— Authored by egg

[james-in-a-box]

egg feedback addressed. View run logs

1 previous review(s) hidden.