Skip to content

feat(cli): plan headroom check and one-key artifact note - #1148

Merged
Birfy merged 3 commits into
mainfrom
agent/1113-plan-headroom-artifact-shape
Nov 17, 2026
Merged

Birfy merged 3 commits into
mainfrom
agent/1113-plan-headroom-artifact-shape

Conversation

@HugoXK

@HugoXK HugoXK commented Nov 17, 2026

Copy link
Copy Markdown
Collaborator

Fixes #1113.

What changed

plan catches two avoidable spends before they are paid for; a plain plan
still sends nothing.

  • --baseline-sample N (opt-in) scores the seed artifact on the first N tasks
    before the run is quoted, and prints the sample's own cost first (baseline sample: scoring the seed on up to N task(s) costs N agent call(s) (~$X)). A
    seed at or above --saturation (default 0.90) prints no headroom,
    withholds the paid quote — the plan: ... up to N agent calls line and the
    next: step — prints refused: no headroom ... and exits 1. --force
    quotes the run anyway but keeps ready: false plus the reason in the
    payload: force buys the estimate, not a different verdict, so a host
    following ready cannot auto-start a run the plan says has nothing to
    learn. --json carries the sample as baseline (sample, score, saturation,
    headroom) and ready: false on a refusal.
  • A one-line artifact-shape note when the strategy declares exactly one key
    (SingleSlot, a one-category KeyedRules, a one-file FileTree): every
    worker proposal targets that key, contradicting pairs collapse to one
    candidate, so n_workers is best-of-N selection, not merging, and the note
    names the fix (several keys, several files, AppendRules). Content-addressed
    strategies stay quiet, and so does a bundle that installs the reflective
    merge pair or an aggregator_factory (plan: the best-of-N selection warning fires for gepa, whose Pareto pool does not collapse proposals #1039). The pilot report card prints
    the same sentence once (notes, including --dry-run), from the one shared
    helper.

Quiet pins, so the note cannot over-fire: test_plain_plan_still_samples_nothing,
test_a_multi_key_artifact_says_nothing_about_merging,
test_the_pilot_card_is_quiet_on_a_multi_key_artifact, plus the existing
test_plan_says_when_workers_buy_selection_rather_than_merging and
test_plan_selection_warning_quiet_for_an_aggregator_factory
(tests/test_integrations.py), unchanged.

evolve is unchanged; no model or network call without the flag.

Verification at the tip

Tip SHA: 724d647

Ran:

  • red at main e42d400e (live main at open), clean tree plus only the new
    test file -> 10 failed, 3 passed in 7.98s (failing set byte-identical at
    00b46e1e, 10 failed, 3 passed in 16.24s); every flag-dependent row
    dies at argv level (agentdescent: error: unrecognized arguments: --baseline-sample 4 -> SystemExit: 2), the one-key note row on the
    shared helper's sentence, the pilot row on assert 0 == 1 (no note at
    main); the 3 passing rows are the pins that must not move.
  • pytest -q tests/test_plan_headroom_shape.py -> pass (13 passed)
  • pytest -q tests/test_plan_headroom_shape.py tests/test_plan_text_output.py tests/test_plan_probe.py -> pass (37 passed)
  • pytest -q tests/test_integrations.py tests/test_pilot.py tests/test_plan_error_output.py tests/test_strategy.py tests/test_tree_strategy.py -> pass (160 passed, 2 skipped, 1 failed: test_the_launcher_install_writes_ignores_a_shadowing_cwd — stale shared-venv launcher on this host, reproduced on pristine d4b66cfa)
  • python -m tools.gen_api_docs --check -> pass (docs/api.md is up to date)
  • python -m tools.changelog_fragments check -> pass (65 changelog fragment(s) OK)
    Not run:
  • pytest -q (full) -> 22 failed, 7673 passed, 61 skipped, 10 errors on this host (no Docker, HOME/TMPDIR not redirected, stale shared-venv launcher); the 11 apply/backup files re-run under a redirected HOME -> 69 passed, test_wheel_smoke -> 7 passed; CI at this tip is authoritative.
  • mkdocs build --strict -> mkdocs not installed on this host; docs/start.md is prose only; the build check covers it.

Review fixes at this tip

  • --saturation is validated only when --baseline-sample is present, so a
    plain plan --saturation 0 is inert instead of exit 2, and an out-of-range
    value with a sample is an input error. Rows:
    test_a_saturation_without_a_sample_changes_nothing,
    test_an_out_of_range_saturation_is_an_input_error.
  • A forced quote keeps ready: false in --json. Row:
    test_a_forced_json_plan_still_says_not_ready.

Written-by: AgentDescent Dev-1
Bot: AgentDescent Dev-1

@HugoXK HugoXK added enhancement New feature or request area:evolve The evolve loop: evolution, async_evolve, aggregator, population, policies, strategies area:cli The agentdescent command line (cli.py, doctor, plan/evolve/status/apply) agent-pr Pull request opened by an agent labels Nov 17, 2026
@HugoXK
HugoXK requested a review from Birfy November 17, 2026 04:34
@HugoXK HugoXK removed the agent-pr Pull request opened by an agent label Nov 17, 2026
@Birfy

Birfy commented Nov 17, 2026

Copy link
Copy Markdown
Collaborator

Review (Birfy)

Tip SHA: 724d647
Ran:

  • .github/scripts/risk_gate.py --pr 1148 → T3 (573 lines / 6 files; size cap over T2)
  • pytest -q tests/test_plan_headroom_shape.py tests/test_plan_text_output.py tests/test_plan_probe.py tests/test_integrations.py tests/test_pilot.py tests/test_plan_error_output.py tests/test_strategy.py tests/test_tree_strategy.py → 195 passed, 5 skipped at this tip
  • the new test file against main (e42d400) → 10 failed, 3 passed; the 3 passing rows are the quiet pins (plain plan samples nothing; a multi-key plan and a multi-key pilot card stay silent)
  • python -m tools.changelog_fragments check → 65 changelog fragment(s) OK
  • python -m tools.gen_api_docs --check → docs/api.md is up to date
  • CI at this tip → required checks green (build, test 3.9–3.13); otel-wire SUCCESS; deploy skipped; risk tier and reviewed tip are report-only SUCCESS
    Not run:
  • Full offline suite locally — the CI test matrix is the line
  • mkdocs build --strict locally — docs/start.md is prose only; the CI build job is green at this tip
  • Ark real-model run — no model path changed; --baseline-sample is opt-in and the new tests exercise it against a local stub
    Findings:
  • none
    Verdict: PASS

@Birfy
Birfy merged commit b5390c2 into main Nov 17, 2026
10 checks passed
@Birfy
Birfy deleted the agent/1113-plan-headroom-artifact-shape branch November 17, 2026 10:25
HugoXK added a commit that referenced this pull request Nov 18, 2026
Forward-merge after #1138/#1140/#1139/#1147/#1148/#1151/#1152 landed.
#1148 rewrites agentdescent/pilot.py, the file this branch patches; the
auto-merge keeps both the per-seed _next_actions branch and the
notes/strategy card addition, and the focused set is green at the
merge tree.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area:cli The agentdescent command line (cli.py, doctor, plan/evolve/status/apply) area:evolve The evolve loop: evolution, async_evolve, aggregator, population, policies, strategies enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

plan: headroom check and artifact-shape guidance before a paid run

2 participants