gates.on_escalation is a reserved no-op with zero readers — document it or give it a reader
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
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 atpolicy.py:727. - Zero readers.
grep -rn "on_escalation" srcreturns 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:93lists("gates", "on_escalation")inHIDDEN, whichtest_every_policy_field_is_covered_by_exactly_one_specconsults 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
- Doc note (smaller): say in
docs/FEATURES.md— and/or as acore.tomlentry marked reserved/disabled — that the field is accepted for forward compatibility and currently has no effect. If it gets acore.tomlentry, theHIDDENexemption comes out in the same change. - 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
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from bmad-code-org/bmad-loop
-
area:adapters enhancement good first issue P3
Difficulty 2/5 1-3 hours Newbie friendliness 76/100
bmad-code-org/bmad-loop#780 · 2 comments ·
-
area:engine bug P3
Difficulty 2/5 1-3 hours Newbie friendliness 84/100
bmad-code-org/bmad-loop#723 ·
-
Re-cut test_merge_stray_dirt_escalates_with_clear_message to pin the hazard-first refusal lead-in Openarea:engine bug P3
Difficulty 2/5 1-3 hours Newbie friendliness 87/100
bmad-code-org/bmad-loop#683 ·
-
area:adapters area:psmux bug P4
Difficulty 2/5 1-3 hours Newbie friendliness 76/100
bmad-code-org/bmad-loop#673 · 7 comments · 1 reaction ·
-
area:tui enhancement P4
Difficulty 2/5 1-3 hours Newbie friendliness 76/100
bmad-code-org/bmad-loop#666 · 1 comment · 1 reaction ·
All issues in bmad-code-org/bmad-loop
Similar issues
-
Difficulty 2/5 1-3 hours Newbie friendliness 88/100
-
Difficulty 2/5 1-3 hours Newbie friendliness 82/100
-
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
-
enhancement
Difficulty 2/5 1-3 hours Newbie friendliness 72/100
-
Difficulty 2/5 1-3 hours Newbie friendliness 74/100