fix(runner): --help and unknown-flag guard for _cli_flag subcommands (issue #459)

[azalio]

Problem

python3 .map/scripts/map_step_runner.py write_review_verdict_ledger --help executed the subcommand with all-empty inputs and wrote .map/<branch>/review-verdict-ledger.{json,md} plus artifact_manifest.json instead of printing usage. The root cause: the _cli_flag helper silently ignores every flag it doesn't recognise, including --help and typos.

The same gap existed in the three other _cli_flag-based subcommands: write_implementer_readiness_review, write_prd_review, and record_prd_review_decision.

Fix

Add _cli_flags_guard(known: frozenset[str], usage: str) right after _cli_flag in the template source (templates_src/map/scripts/map_step_runner.py.jinja). The guard is called at the top of each _cli_flag-based dispatch branch, before any state-writing function is invoked:

• --help / -h anywhere in sys.argv[2:] → print usage text, sys.exit(0), no .map/ writes
• Any --foo token not in the known set → print error naming the offending flag(s), sys.exit(1), no .map/ writes
• Known flags pass through unchanged

Changes

• src/mapify_cli/templates_src/map/scripts/map_step_runner.py.jinja — new _cli_flags_guard helper + guard calls in all 4 branches
• src/mapify_cli/templates/map/scripts/map_step_runner.py — rendered output
• .map/scripts/map_step_runner.py — dev-copy rendered output
• tests/test_map_step_runner.py — 11 new subprocess tests in TestCliFlagsGuard covering all 4 subcommands: --help exits 0 with no .map/ written, unknown flags exit 1 with no state written, known flags still accepted

Test run

uv run make check   # 5555 passed, 4 skipped

Fixes #459.

---

🤖 Generated with Claude Code

https://claude.ai/code/session_01VRqTf2dJArpwNUA59afq5i

---

Generated by Claude Code

Summary by CodeRabbit

• New Features

  • Added help output for review-related command-line operations, including supported options and verdict choices.
  • Added validation that reports unrecognized command-line flags instead of silently ignoring them.

• Bug Fixes

  • Help requests and invalid flags no longer write review state before exiting.

• Tests

  • Added regression coverage for help handling, unknown flags, state protection, and recognized ledger options.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Advanced

Run ID: 6443c18b-5f20-4b46-9f0e-4592bb4bcd45

📥 Commits

Reviewing files that changed from the base of the PR and between 0b267e6 and 85367ba.

📒 Files selected for processing (4)

• .map/scripts/map_step_runner.py
• src/mapify_cli/templates/map/scripts/map_step_runner.py
• src/mapify_cli/templates_src/map/scripts/map_step_runner.py.jinja
• tests/test_map_step_runner.py

---

📝 Walkthrough

Walkthrough

The change adds shared CLI flag validation to four state-writing subcommands. Help flags now print usage and exit successfully. Unknown flags now produce an error before state-writing functions run. Regression tests cover these behaviors.

Changes

CLI flag validation

Layer / File(s)	Summary
Shared CLI guard .map/scripts/map_step_runner.py, src/mapify_cli/templates/map/scripts/map_step_runner.py, src/mapify_cli/templates_src/map/scripts/map_step_runner.py.jinja	Adds _cli_flags_guard, which handles --help and -h, and rejects unknown ---prefixed flags.
Subcommand integration and regression coverage .map/scripts/map_step_runner.py, src/mapify_cli/templates/map/scripts/map_step_runner.py, src/mapify_cli/templates_src/map/scripts/map_step_runner.py.jinja, tests/test_map_step_runner.py	Wires command-specific flag sets and usage text into four review subcommands. Tests verify help handling, unknown-flag errors, prevention of state writes, and accepted ledger flags.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Change: Bug fix · Severity of issue fixed: Medium

Suggested reviewers: yvasiyarov

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch claude/compassionate-cerf-hy3x9v

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{A rabbit guards the flags tonight
Help prints softly, clear and bright
Unknown hops meet an error gate
No ledger writes must wait
Four commands now follow the trail
And tests keep every promise hale}

_{Comment @coderabbitai help to get the list of available commands.}