Rename input-file flags from --path to --input-path

[johnjosephhorton]

What

--path/--out were overloaded: on some commands they mean write output here, on others read this input file (question import, respondent import, answer import, twin-results import, twin-experiment approve/export-plan/validate, agent-list inspect, the *-import report commands, context add/set, raw add, agent-material add/import, ...).

Every input-file flag is now --input-path (dest input_path). Output flags (--path/--out) are unchanged. The result is an invariant that holds by construction: any --path/--out is an output; any --input-path is a read.

Why

1. Clarity — an agent or user can now tell from the flag alone whether a command writes or reads.
2. Enables the output-root guardrail — the planned "contain all writes under zwill_work/" resolver can rebase every --path/--out without a fragile per-flag input/output classification. This rename is the prerequisite that makes that resolver correct by construction.

Doing it now, before external users, means no compatibility burden — a clean break.

Scope

• Parser: 25 input subcommands → --input-path.
• Handlers: 26 input handlers across ~11 modules now read args.input_path; output handlers untouched (124 args.path reads remain, all outputs).
• Internal callers: functions that synthesize a Namespace to call an import handler (twin-study run, import-results-dir, import-plan-results, the pew-demo workflow, the delegating practitioner-report imports, the internal rank-results-import) now pass input_path=.
• User-facing guidance: every next_steps/hint string that tells the user to run an input command was updated — otherwise the tool would print a command that now errors.
• Docs/tests: guides, skills, README, SPEC, example scripts, and the test suite.

Behavior change

zwill question import --survey demo --path q.jsonl now errors:

zwill question import: error: the following arguments are required: --input-path

Use --input-path. No deprecated alias.

Testing

• pytest — 242 passed.
• ruff check zwill/ tests/ clean.
• Live smoke: --path rejected on input commands, --input-path works end-to-end; example scripts (which run real CLI flows) pass.
• Repo-wide scan confirms zero remaining input-command --path references (outside historical workdir/ snapshots).

🤖 Generated with Claude Code

[greptile-apps]

Greptile Summary

This PR renames all input-file CLI flags from --path to --input-path (dest input_path) across 25 subcommands, establishing a clear invariant: --path/--out always means an output file write, and --input-path always means an input file read. The rename touches parsers, handlers, internal Namespace synthesizers, user-facing hint strings, tests, examples, and docs.

• Parser: 25 add_argument(\"--path\", ...) calls on input subcommands replaced with add_argument(\"--input-path\", ...); 124 existing output --path flags are unchanged.
• Handlers & internal callers: All 26 import/inspect/add handler functions updated to read args.input_path; every synthetic argparse.Namespace(path=...) call that targeted an input command updated to input_path=.
• Docs and tests: next_steps hint strings, guides, example scripts, README, SPEC, and pytest tests all updated; the PR description confirms 242 tests pass and ruff is clean.

Confidence Score: 5/5

This is a clean mechanical rename with no behavioral changes — all 25 input-command parsers, 26 handler functions, internal Namespace synthesizers, hint strings, tests, and docs were updated consistently.

The rename is applied exhaustively: every input-command parser definition, every handler that reads the flag, every internal argparse.Namespace(...) call that targets an import handler, and every user-facing hint string were all updated. Output-only --path flags are correctly left untouched. No missed cases were found across the 39 changed files.

No files require special attention. The most complex delegation chains (practitioner_reports.py delegating through cmd_twin_benchmark_practitioner_report_import, twin_validation_commands.py and probability_commands.py re-using the same delegate) all correctly propagate args.input_path.

Important Files Changed

Filename	Overview
zwill/cli_parser.py	Core parser change: 25 input-command --path arguments renamed to --input-path; all output-only --path arguments left intact.
zwill/result_commands.py	cmd_twin_results_import and cmd_rank_results_import both updated to args.input_path; output args.path references in export/retry commands unchanged.
zwill/practitioner_reports.py	Import handlers and two internal argparse.Namespace(input_path=...) synthesizers updated; output args.path references in render/export commands unchanged.
zwill/twin_experiments.py	approve, export-plan, and validate handlers switched to args.input_path; import-plan-results Namespace synthesizer updated; hint strings all updated.
zwill/workflow_commands.py	Five internal argparse.Namespace(input_path=...) synthesizers updated in the pew-demo workflow; correct.
zwill/survey_commands.py	cmd_question_import, cmd_respondent_import, cmd_answer_import, cmd_raw_add, cmd_agent_material_import, and helper functions markdown_from_args/material_markdown_from_args all updated.
zwill/twin_approaches.py	markdown_from_note_args (defensive getattr) and cmd_twin_approach_add updated; next_steps hint updated.
tests/test_cli_workflows.py	All test argparse.Namespace calls and run_cli invocations updated to use input_path= / --input-path.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[User runs CLI command] --> B{Flag type?}
    B -->|--input-path| C[Input command\ne.g. import / inspect / add]
    B -->|--path or --out| D[Output command\ne.g. export / run / render]
    C --> E[Handler reads args.input_path\nopens file for reading]
    D --> F[Handler reads args.path\nwrites file to disk]
    E --> G[Internally synthesized Namespace\nuses input_path= keyword]
    F --> H[Internally synthesized Namespace\nuses path= keyword]
    G --> I[Result: invariant by construction\nany --path/--out is always an output\nany --input-path is always a read]
    H --> I

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
flowchart TD
    A[User runs CLI command] --> B{Flag type?}
    B -->|--input-path| C[Input command\ne.g. import / inspect / add]
    B -->|--path or --out| D[Output command\ne.g. export / run / render]
    C --> E[Handler reads args.input_path\nopens file for reading]
    D --> F[Handler reads args.path\nwrites file to disk]
    E --> G[Internally synthesized Namespace\nuses input_path= keyword]
    F --> H[Internally synthesized Namespace\nuses path= keyword]
    G --> I[Result: invariant by construction\nany --path/--out is always an output\nany --input-path is always a read]
    H --> I

Loading

_{Reviews (1): Last reviewed commit: "Rename input-file flags from --path to -..." | Re-trigger Greptile}