fix(deep-learning-book): reject overlapping capacity regime bands

Ninth review on PR #994 found that --underparameterized-max and
--overparameterized-min, added two commits earlier, were never checked against each
other. Reproduced, and the consequence is sharper than a silent misclassification:
with --underparameterized-max 20 --overparameterized-min 5 and a ratio of 10, the
tool reported a model ten times overparameterized as "underparameterized" and exited
0. That verdict ranks "shrink the model" FIRST rather than last, inverting the exact
double-descent correction this tool exists to apply.

Added an argparse guard rejecting under-max >= over-min with a message naming both
values (exit 2, the documented usage-error code). Equal bands are rejected too,
since they leave the near-interpolation regime unreachable.

Verified: inverted and equal bands both exit 2; a valid override still moves the
regime (--overparameterized-min 500 gives near-interpolation); defaults unchanged at
overparameterized / OVERFIT / 240.0 with smaller-model last; the other exit codes
still 1 for an action, 0 for balanced, 4 for a leaky split.

Worth noting for the two flags' own history: they were added to close a consistency
nit, and introduced this defect in doing so. A new option is new surface, and its
interaction with existing options is part of it.

Gates green: compileall, check_paths, check_frontmatter, check_dual_publish,
check_model_freshness, smoke_scripts (696 passed), derive_counters --check,
check_skill_names, check_plugin_json, book_skill_validator, and --help +
--sample --output json on all four tools.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BswsZp5zrJWFAGU6KWNA1s
This commit is contained in:
Claude
2026-08-25 20:06:05 +00:00
parent 35f5b3b6d3
commit 942e771319
@@ -242,6 +242,16 @@ def main(argv: list[str] | None = None) -> int:
"required (or use --sample)")
if args.params <= 0 or args.train_examples <= 0:
parser.error("--params and --train-examples must be positive")
if args.underparameterized_max >= args.overparameterized_min:
# Overlapping bands silently mis-class the regime, and the cost is not
# cosmetic: an overparameterized model reported as underparameterized ranks
# "shrink the model" FIRST, inverting the double-descent correction this
# tool exists to apply.
parser.error(
f"--underparameterized-max ({args.underparameterized_max}) must be less "
f"than --overparameterized-min ({args.overparameterized_min}); the bands "
"are ordered and must not overlap"
)
known = {item[0] for item in LADDER}
applied = {token.strip() for token in args.applied.split(",") if token.strip()}