Skip to content

fix(cli): restore concise default help and manpage parity - #3943

Closed
songoow wants to merge 1 commit into
loopx-project:mainfrom
songoow:codex/cli-concise-help-manpage-parity
Closed

songoow wants to merge 1 commit into
loopx-project:mainfrom
songoow:codex/cli-concise-help-manpage-parity

Conversation

@songoow

@songoow songoow commented Sep 4, 2026 •

Copy link
Copy Markdown
Collaborator

Summary

  • examples/cli-help-manpage-smoke.py fails on main because the concise default help grew to 41 lines against its 39-line budget after feat(control-plane): add Stage 2C local authority cutover kernel #3882 put a two-line coordination-shadow --help entry on the first screen; the checked-in man/loopx.1 was also never regenerated after that change, and machine-config (feat(machine-config): add generic operator configuration surfaces #3865) was left unclassified for the manual.
  • Remove coordination-shadow from render_concise_help only. It remains in loopx commands, in its own --help, and in the manual. Classify machine-config as manpage/help-only like its sibling configure-goal, and regenerate man/loopx.1 from the canonical catalog.
  • Default-behavior disclosure: bare loopx and loopx --help no longer list coordination-shadow. The 39-line first-screen budget is kept rather than raised, because the Stage 2C file shadow is a default-off experimental admin surface. If maintainers prefer the entry on the first screen, the alternative is to raise the budget in the smoke; that is an explicit owner decision and this PR does not pre-empt it.
  • No CLI flags, outputs, or defaults change otherwise. turn.py and todo.py are untouched.

Companion baseline PRs for the other shard failures: #3942 (goal configuration catalog smoke) and #3944 (todo.py owner extraction). Each is independent and can merge in any order.

Issue Or Task

  • Closes #
  • Contributor task ID: baseline repair for the red Full Public Smokes workflow on main (shard 0)

Validation

  • python3 -m py_compile loopx/help_surface.py
  • python3 examples/cli-help-manpage-smoke.py -> cli-help-manpage-smoke ok
  • python3 scripts/render-manpage.py --check man/loopx.1 -> parity
  • bare loopx help -> 39 lines
  • python3 -m pytest tests/control_plane/test_cli_output_budget.py -q -> 21 passed (agent-facing manifest unchanged)
  • adjacent cli-control-plane-command-modularization and cli-bootstrap-rollout-helper smokes -> ok
  • loopx canary premerge --from-git-diff --git-diff-base <official main> -> 2/2 selected checks passed, 0 manual holds
  • git diff --check clean; commit carries the DCO trailer

Type of Change

  • Bug fix
  • Documentation update

LoopX Area

  • Public docs or presentation surface (README, protocols, dashboard)

Technical Direction

  • Core control-plane hardening

  • Target base branch: main

  • Direction tracker or promotion unit: Full Public Smokes baseline

Boundary Checklist

  • I did not commit .loopx/, .codex/goals/, live ACTIVE_GOAL_STATE.md, credentials, private benchmark traces, verifier output, raw agent sessions, internal document links, or local machine paths.
  • I did not duplicate maintainer-owned benchmark work unless a maintainer split out a public issue for it.
  • I kept the change scoped to the linked issue/task.
  • Every commit includes a DCO Signed-off-by trailer (git commit -s).

`examples/cli-help-manpage-smoke.py` went red on the Full Public Smokes
baseline for three help-surface drifts that all trace back to recently
merged commands:

- loopx-project#3882 added a two-line `loopx coordination-shadow --help` entry to the
  bare `loopx` / `loopx --help` first screen, pushing the concise help to 41
  lines against the smoke's 39-line concise-default budget. The command is
  a default-off, experimental Stage 2C admin surface, so it does not belong
  on the first screen. Drop it from `render_concise_help`; it stays listed
  under "Daily operator commands" in `loopx commands` and in the manual, so
  the agent-facing output-budget classification is unchanged.
- loopx-project#3865 registered the top-level `machine-config` command without
  classifying it for the manual. Add it to `MANPAGE_COMMAND_HELP_ONLY`,
  matching its Goal-scoped sibling `configure-goal`.
- The checked-in `man/loopx.1` was never regenerated after loopx-project#3882 added
  `coordination-shadow` to the command catalog. Regenerate it with
  `scripts/render-manpage.py --output man/loopx.1`.

Default-behavior disclosure: the bare `loopx` / `loopx --help` first screen
no longer lists `loopx coordination-shadow --help` (back to 39 lines). The
grouped reference (`loopx commands`) and the manual page are unchanged in
membership; the manual gains the catalog row it was already missing. The
39-line budget was not raised.

Validation:
- PATH with system bash first: python3 examples/cli-help-manpage-smoke.py
  -> cli-help-manpage-smoke ok
- python3 examples/cli-control-plane-command-modularization-smoke.py -> ok
- python3 examples/cli-bootstrap-rollout-helper-command-modularization-smoke.py -> ok
- python3 -m pytest tests/control_plane/test_cli_output_budget.py -q -> 21 passed

Signed-off-by: song <liusongstep@gmail.com>
(cherry picked from commit 053bd1c795f889724d93dd22c4b97cb793eba906)
@songoow

songoow commented Sep 4, 2026

Copy link
Copy Markdown
Collaborator Author

Closing to keep the review queue small. The 39-line first-screen breach can only be resolved by an owner decision (drop coordination-shadow from the concise help, as this branch does, or raise the smoke budget), so it should not sit in the queue as a contributor PR. The manpage regeneration and machine-config classification are folded into the same branch (codex/cli-concise-help-manpage-parity) and can be reopened or cherry-picked if maintainers want this path.

@songoow songoow closed this Sep 4, 2026
@songoow
songoow deleted the codex/cli-concise-help-manpage-parity branch September 16, 2026 05:54
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant