gates.on_escalation is a reserved no-op with zero readers — document it or give it a reader

Open Beginner friendly
#486 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
2/5
Estimated time
1-3 hours
Newbie friendliness
78/100
Issue type
Documentation
Clarity
Clearly specified
Activity status
Quiet
Tech stack
python
Domain
documentation

Research direction

Start with docs/FEATURES.md and inspect src/bmad_loop/data/settings/core.toml, policy.py, and tests/test_settings_schema.py for the existing reserved-field treatment. Document that gates.on_escalation is accepted for forward compatibility but has no effect; done means the shipped configuration surface makes this clear to operators.

Written by the indexing model from the issue text.

Description

area:config documentation P3

gates.on_escalation is a reserved no-op with zero readers, and nothing tells the operator so. A user who sets it gets the behaviour they asked for by coincidence — CRITICAL escalations pause unconditionally — and has no way to discover the setting is inert.

Current state (verified on main at 254f203)

  • Declared at policy.py:65 (on_escalation: str = "pause"), parsed at policy.py:727.
  • Zero readers. grep -rn "on_escalation" src returns exactly those two lines.
  • Absent from src/bmad_loop/data/settings/core.toml — and that absence is deliberate and test-sanctioned, not an invariant violation: tests/test_settings_schema.py:93 lists ("gates", "on_escalation") in HIDDEN, which test_every_policy_field_is_covered_by_exactly_one_spec consults to waive the "every policy field needs a spec" assertion. The exemption comment already says "CRITICAL escalations always pause; field reserved".
  • No mention anywhere under docs/.

So the codebase knows the field is reserved. The operator does not — there is no rendered surface that says so.

Field evidence

The 0.9.0 reporter in #337 had gates.on_escalation = pause set and observed pausing behaviour, which matched. It matched by coincidence: pause is hardcoded. Nothing in the run, the docs, or validate would have told them otherwise if they had set anything else.

Why it is being filed now

This was recorded as correction (c) on the #337 field report and routed to #334 for a doc fix — #334's own filing brief said "Note the dead on_escalation field for a doc fix here too". #334 shipped as PR #339 (the review.on_status_contradiction gate) without touching it, and closed completed. Filing it standalone so it is tracked rather than dropped with its former parent.

Two shapes

  1. Doc note (smaller): say in docs/FEATURES.md — and/or as a core.toml entry marked reserved/disabled — that the field is accepted for forward compatibility and currently has no effect. If it gets a core.toml entry, the HIDDEN exemption comes out in the same change.
  2. A reader: give it real semantics. Only worth it if there is a second escalation disposition worth having; today there is not, and a doc note is the honest fix.

Either way the acceptance test is the same: an operator reading the shipped configuration surface can tell the field does nothing.

Dominant language
Python
Stars
137
Forks
60
Avg merge
2d 13h
Merged PRs (30d)
45

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from bmad-code-org/bmad-loop

All issues in bmad-code-org/bmad-loop

Similar issues

More Python issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.