teddy-cli 0.1.17.dev1415__tar.gz → 0.1.17.dev1418__tar.gz

{teddy_cli-0.1.17.dev1415 → teddy_cli-0.1.17.dev1418}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: teddy-cli
-Version: 0.1.17.dev1415
+Version: 0.1.17.dev1418
 Summary: The local-first, test-driven agentic engineering harness. Because you should own the means of development.
 Author: Raphael Atteritano
 License: AGPL-3.0-only

{teddy_cli-0.1.17.dev1415 → teddy_cli-0.1.17.dev1418}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "teddy-cli"
-version = "0.1.17.dev1415"
+version = "0.1.17.dev1418"
 description = "The local-first, test-driven agentic engineering harness. Because you should own the means of development."
 readme = "README.md"
 keywords = [

{teddy_cli-0.1.17.dev1415 → teddy_cli-0.1.17.dev1418}/src/teddy_executor/resources/MRP.md

@@ -56,7 +56,7 @@ Every EXECUTE action runs in a fresh subshell rooted at the project root (CWD).
 
 ### Information Gathering Workflow
 
-If you are missing information critical to your immediate goal, gather it efficiently without getting sidetracked. You can chain multiple discovery actions in one turn. Discover locally via `EXECUTE` (`git grep`) and externally via `RESEARCH`. Never rely on search snippets; always `READ` target URLs. For opaque sources (JavaScript-rendered pages, PDFs, binary formats) where `READ` fails or yields unusable content, `CREATE` and `EXECUTE` a minimal extraction script to inspect the raw data or API. If static reading leaves behavioral ambiguity, validate assumptions via a minimal spike in `spikes/`. Check flags with `[tool] --help` before running complex CLI commands.
+If you are missing information critical to your immediate goal, gather it efficiently without getting sidetracked. You can chain multiple discovery actions in one turn. Discover locally via `EXECUTE` (`git grep`) and externally via `RESEARCH`. Never rely on search snippets; always `READ` target URLs. For opaque sources (JavaScript-rendered pages, PDFs, binary formats) where `READ` fails or yields unusable content, `CREATE` and `EXECUTE` a minimal extraction script to inspect the raw data or API. If static reading leaves behavioral ambiguity, validate assumptions via a minimal spike in `spikes/`. Check flags with `[tool] --help` before running complex CLI commands. To read CI logs, use `make logs RUN=<run-id>` for all failed steps, or `make logs RUN=<run-id> STEP="<step-name>"` for one step.
 
 ### Version Control
 
@@ -64,10 +64,10 @@ The entire commit cycle (test, stage, commit) MUST occur in a dedicated Version
 
 1. Pre-conditions: Clean up temporary files. If recurring script, test, or tool detritus appears, do not just delete it manually: update `.gitignore` or configure the script to write outside tracked directories. If unsure of changes, inspect via `EXECUTE git add . && git diff HEAD`.
 2. Commit Message: Use Conventional Commits `"<type>(<scope>): <description>"` in double quotes (imperative mood; plain text without backticks, quotes, or `$`; append `!` for breaking changes) on a single line.
-3. Execution: Run `make commit "<type>(<scope>): <description>"`. This stages all local changes (`git add .`) and runs Git's local hooks before committing.
+3. Execution: Run `make commit MSG="<type>(<scope>): <description>"`. This stages all local changes (`git add .`) and runs Git's local hooks before committing.
 4. Post-conditions: All tests MUST pass: the post-commit hook reverts automatically on failure and cannot be bypassed.
 5. Push at Conclusion: In the Conclusion phase, if a remote is configured, run `make push`.
-6. CI Monitoring: If remote CI is configured and a push occurred, run `make ci-watch` to monitor workflow runs and to inspect results: use `make logs <run-id>` (or `make logs <run-id> '<step-name>'`) for full logs.
+6. CI Monitoring: If remote CI is configured and a push occurred, run `make ci-watch` to monitor workflow runs. If needed inspect details using `make logs`.
 
 ### Standardized Plan Types
 

{teddy_cli-0.1.17.dev1415 → teddy_cli-0.1.17.dev1418}/src/teddy_executor/resources/config/prompts/debugger.md

@@ -14,7 +14,7 @@ Follow these phases and steps in order. Keep track of your progress in your Stat
 1. **Case File Check:**
    If a Case File was not provided in the initial context, CREATE one following the case file template and path conventions.
 2. **Context and History Gathering:**
-   Use EXECUTE `git grep`, EXECUTE `git log`, READ, and RESEARCH to understand the codebase, recent changes, and identify the last known green CI run or commit. For historical CI failures, do not try to read the entire log: extract failed step logs by executing `make logs [ID]` (for all failed steps) or `make logs [ID] "[STEP_NAME]"` (for a specific step).
+   Use EXECUTE `git grep`, EXECUTE `git log`, READ, and RESEARCH to understand the codebase, recent changes, and identify the last known green CI run or commit. For historical CI failures pull the failed step logs.
 3. **Diagnostic MRE and Platform Check:**
    Trigger the symptom: if an existing command, test, or CI failure exists, execute it to observe the failure live. If the bug is reported verbally or without an existing test, write a targeted probe script in `spikes/debug/{scope-slug}/` to trigger the symptom.
 
@@ -26,7 +26,7 @@ Follow these phases and steps in order. Keep track of your progress in your Stat
    - **Probe file:**
      consolidate diagnostic logic into the single shell entry point `spikes/debug/probe.sh` following the Makefile template pattern. Output must be written to `spikes/debug/probe_output.txt` for artifact upload, using the single-file Heredoc pattern.
    - **Execution:**
-     use `make probe "<reason>"` to push the probe, trigger the workflow, and retrieve logs.
+     use `make probe REASON="<reason>"` to push the probe, trigger the workflow, and retrieve logs.
 
 ### Investigation
 **Goal:** Peel back internal layers to resolve discrepancies and update the Causal Model.

{teddy_cli-0.1.17.dev1415 → teddy_cli-0.1.17.dev1418}/src/teddy_executor/resources/templates/ARCHITECTURE.md

@@ -14,13 +14,13 @@ This section defines foundational engineering practices. Each entry MUST be a sp
 - **Runtime Contract Assertions:** Enforce Design-by-Contract with native `assert condition, "message"` for pre/post-conditions and invariants (strippable via `python -O`); never custom exceptions for contract checks.
 - **Dependency Injection:** Constructor injection mandate; forbid Service Locator and global containers.
 - **Centralized Configuration:** Config file location, prohibition of magic numbers.
-- **Continuous Integration & Remote Diagnostics:** Parallel CI jobs: 1) Blocking OS matrix test suite. 2) Non-blocking (`continue-on-error: true`) quality checks running fast formatters, linters, security scanners, type checkers, and repository-wide structural checks. Platform-specific and CI-only issues are investigated via the Remote Probing Protocol (`make probe '<reason>'`). See [docs/templates/ci.md](docs/templates/ci.md).
+- **Continuous Integration & Remote Diagnostics:** Parallel CI jobs: 1) Blocking OS matrix test suite. 2) Non-blocking (`continue-on-error: true`) quality checks running fast formatters, linters, security scanners, type checkers, and repository-wide structural checks. Platform-specific and CI-only issues are investigated via the Remote Probing Protocol (`make probe REASON="<reason>"`). See [docs/templates/ci.md](docs/templates/ci.md).
 - **Local Quality Gates (Pre-commit & Post-commit):** Local pre-commit hooks MUST stay fast, checking only staged files (formatters, secret detection, merge conflict markers). Heavy, false-positive-prone checks run non-blocking in CI. The full test suite runs via the post-commit hook (`.githooks/post-commit.py`) as an unskippable safety net, reverting automatically on failure. See [docs/templates/pre-commit.md](docs/templates/pre-commit.md).
 - **Diagnostic Instrumentation:** High-value diagnostics MUST use zero-cost language-native dead-code elimination (e.g. `if __debug__:`) and Composition Root toggles; mid-logic environment checks are forbidden.
 - **Experimental Code:** The `spikes/` directory is reserved for rapid, isolated experimentation (`debug/`, `prototypes/`, `showcases/`) and is explicitly excluded from all quality gates (linters, type checkers, test suites).
 - **Directory Conventions:**
   `docs/architecture/BOUNDARY/LAYER/TYPE/name.md` -> Source path: `src/{pkg}/BOUNDARY/LAYER/TYPE/name.ext` -> Test path: `tests/suites/TEST_TYPE/BOUNDARY/LAYER/TYPE/test_name.ext`
-- **Makefile Commands:** The `Makefile` is the canonical entry point for the version control workflow and on-demand test runs: `make test` (full suite), `make commit '<msg>'` (local commit with advisory auto-fix and unskippable post-commit test gate), `make push` (rebase and push), `make ci-watch` (CI monitoring), and `make probe '<reason>'` (Remote Probing Protocol). See [docs/templates/makefile.md](docs/templates/makefile.md).
+- **Makefile Commands:** The `Makefile` is the canonical entry point for the version control workflow and on-demand test runs: `make test` (full suite), `make commit MSG="<msg>"` (local commit with advisory auto-fix and unskippable post-commit test gate), `make push` (rebase and push), `make ci-watch` (CI monitoring), and `make probe REASON="<reason>"` (Remote Probing Protocol). See [docs/templates/makefile.md](docs/templates/makefile.md).
 
 ## Ubiquitous Language
 

{teddy_cli-0.1.17.dev1415 → teddy_cli-0.1.17.dev1418}/src/teddy_executor/resources/templates/PROJECT.md

@@ -24,7 +24,7 @@ Defines the high-level artifact lifecycle and conventions for project management
     - **Milestone 0 (bootstrapping) & Ad-hoc work (not tied to a milestone):** `00-NN-name.md` (in `docs/project/slices/`) — `00` is used as the Milestone prefix for Milestone 0 bootstrapping slices and for ad-hoc slices. Ad-hoc slices are NOT tracked in Milestone documents or the Roadmap.
 - **Archiving Policy:** When and how completed artifacts are archived or deleted.
 - **Spec Organization:** Specification documents live in a single flat directory `docs/project/specs/` and are reserved strictly for **permanent system invariants** — formats, contracts, protocols (e.g. the MRP), core data models, and non-negotiable architectural rules. Feature goals, requirements, and acceptance criteria belong in Milestone documents (`docs/project/milestones/`), not in specs.
-- **Build & Run Commands:** Document the standard commands in the project `Makefile` (see [docs/templates/makefile.md](docs/templates/makefile.md)). At minimum: `make test` (full suite), `make commit '<msg>'`, `make push`, `make ci-watch` (CI monitoring), and `make probe '<reason>'` (Remote Probing Protocol).
+- **Build & Run Commands:** Document the standard commands in the project `Makefile` (see [docs/templates/makefile.md](docs/templates/makefile.md)). At minimum: `make test` (full suite), `make commit MSG="<msg>"`, `make push`, `make ci-watch` (CI monitoring), and `make probe REASON="<reason>"` (Remote Probing Protocol).
 - **Release Process:** Document how releases are cut. At minimum: (1) **Triage** the scope (patch/minor/major) from conventional commits since the last tag; (2) write **release notes** to `docs/project/releases/v<version>.md`; (3) bump the `version` field in the project manifest; (4) present the notes and version bump at an **approval gate**; (5) **commit** (`chore(release): bump version to <version>`) and **tag** (`git tag -a v<version>`); and (6) **publish** (e.g. create a GitHub Release). Adapt the concrete commands to the project's packaging and distribution channel.
 
 ## Templates

{teddy_cli-0.1.17.dev1415 → teddy_cli-0.1.17.dev1418}/src/teddy_executor/resources/templates/ci.md

@@ -162,7 +162,7 @@ jobs:
 
 ### How to use it
 1. Create a probe script at `spikes/debug/remote_probe.sh` containing diagnostic logic.
-2. Commit and push via: `make probe 'reason for probing'`
+2. Commit and push via: `make probe REASON="reason for probing"`
 3. The Makefile will: push the probe → trigger the workflow → wait for completion → retrieve logs.
 
 ### Prerequisites

{teddy_cli-0.1.17.dev1415 → teddy_cli-0.1.17.dev1418}/src/teddy_executor/resources/templates/makefile.md

@@ -9,11 +9,18 @@ and the Debugger's Remote Probing Protocol (RPP). Below are concrete examples ad
 
 ### Commit
 ```shell
-make commit "feat(templates): add PROJECT.md template"
+make commit MSG="feat(templates): add PROJECT.md template"
 ```
 
 **What is `.PHONY`?**
-`.PHONY` is a Makefile directive that declares `commit`, `push`, `ci-watch`, `probe`, `test`, `logs`, and the internal `_preflight` gate as phony targets — they do not correspond to actual files. Without `.PHONY`, if a file named `commit` or `probe` existed in the directory (e.g., a script called `commit`), Make would see it as up-to-date and skip the target entirely. By declaring them phony, Make always runs the recipe when you call `make commit`, `make push`, `make ci-watch`, `make probe`, or `make test`.
+`.PHONY` is a Makefile directive that declares `commit`, `push`, `ci-watch`, `probe`, `test`, `logs`, `help`, and the internal `_preflight` gate as phony targets — they do not correspond to actual files. Without `.PHONY`, if a file named `commit` or `probe` existed in the directory (e.g., a script called `commit`), Make would see it as up-to-date and skip the target entirely. By declaring them phony, Make always runs the recipe when you call `make commit`, `make push`, `make ci-watch`, `make probe`, or `make test`.
+
+### Help
+```shell
+make
+```
+
+The default goal is `help`, so a bare `make` prints the target list. An unknown goal aborts with its own name instead of an "up to date" line.
 
 ### Push
 ```shell
@@ -38,7 +45,7 @@ make test
 
 ### Probe
 ```shell
-make probe "investigate windows path handling"
+make probe REASON="investigate windows path handling"
 ```
 
 **Why does `probe` need a reason?**
@@ -46,12 +53,12 @@ The Remote Probing Protocol requires a reason string because it is passed as the
 
 ### Logs
 ```shell
-make logs 12345              # extract logs for ALL failed steps
-make logs 12345 "Run tests"  # extract logs for a specific step (substring match)
+make logs RUN=12345                   # extract logs for ALL failed steps
+make logs RUN=12345 STEP="Run tests"  # extract logs for a specific step (substring match)
 ```
 
 **How does `make logs` work?**
-The first argument is the GitHub Actions run ID (as shown by `gh run list`). If invoked without a second argument, it extracts and formats logs for **all failed steps** using `gh run view --log-failed`. An optional second argument filters down to a specific step using substring matching, stripping ANSI escapes and GitHub boilerplate so you see the failure without noise. See [CI Log Extraction](#ci-log-extraction).
+The `RUN` value is the GitHub Actions run ID (as shown by `gh run list`). If `STEP` is omitted, it extracts and formats logs for **all failed steps** using `gh run view --log-failed`. An optional `STEP` value filters down to a specific step using substring matching, stripping ANSI escapes and GitHub boilerplate so you see the failure without noise. See [CI Log Extraction](#ci-log-extraction).
 
 ## Probe Script
 
@@ -84,16 +91,39 @@ EOF
 
 Always use GNU Make native features for cross-platform compatibility instead of shell-specific constructs:
 
-- **Native argument validation:** Use `$(if $(strip $(VAR)),,$(error Usage: ...))` instead of POSIX `[ -n "$$VAR" ]`. GNU Make validates parameters before spawning any shell process.
-- **Shell-less empty recipe:** Use `%: ;` to absorb extra command-line arguments. In Windows `cmd.exe`, the Unix built-in `@:` fails because `:` is reserved syntax for labels and drives. The empty recipe `%: ;` tells Make to do nothing without spawning a subshell.
-- **POSIX shell preflight:** Every POSIX recipe target (`ci-watch`, `probe`, `logs`) depends on the internal `_preflight` target, which verifies `git`, `gh`, `awk`, and `sed` before any network call. It aborts with one actionable message instead of a generic `make: *** Error 1`.
+- **Required input validation:** Reject a missing required input in a parse-time block, not in the recipe. Make runs the check while it reads the file, so it aborts before any prerequisite and before any shell process starts. See [Parse-Time Input Validation](#parse-time-input-validation).
+- **Named inputs instead of positional goals:** Pass values as `NAME="value"`, as in `make commit MSG="feat(scope): add thing"`. GNU Make treats a command-line assignment as a variable, so no word of the value can become a goal. Positional capture through `$(MAKECMDGOALS)` is forbidden, because a word that names a real target executes that target.
+- **Parse-time goal validation:** Compare `$(MAKECMDGOALS)` against a `_KNOWN_GOALS` list and abort with `$(error ...)` when a goal is unknown or when more than one goal is present. The check runs while Make reads the file, so no recipe line can run first.
+- **POSIX shell preflight:** Every POSIX recipe target (`ci-watch`, `probe`, `logs`) depends on the internal `_preflight` target, which verifies `git`, `gh`, `awk`, and `sed` before any network call. It aborts with one actionable message instead of a generic `make: *** Error 1`. A missing required input aborts at parse time, before the tool gate runs.
 - **Shell routing for Bash-only commands:** Make spawns a recipe line directly when the line carries no shell metacharacter. That direct spawn bypasses `SHELL`. On Windows it fails for Git Bash-only programs such as `sleep` and for shell builtins such as `echo`. Keep these commands inside a shell block that carries `;`, `&&`, or a variable expansion.
 - **Windows shell selection:** Set `SHELL := bash.exe` when `OS` is `Windows_NT` so multi-line shell pipelines (`ci-watch`, `probe`, `logs`) execute through Git Bash. `_preflight` also confirms that the shell is Git Bash rather than the WSL `bash.exe` shim, and it names the `SHELL=` override when it is not.
 - **Portable quoting:** Pass values with double quotes, as in `--field reason="..."`, because Windows `cmd.exe` keeps single quotes literally.
 - **ASCII-only output:** Recipe output stays ASCII, because a Windows console turns a non-ASCII dash into mojibake in captured logs.
-- **Native error suppression:** The Makefile uses Make's built-in `-` prefix (`-pre-commit run`) instead of shell-level `|| true` or `&&`/`||` chaining. Make suppresses non-zero exit codes natively before passing lines to the shell.
+- **Explicit advisory fallback:** The advisory pre-commit pass consumes its own exit code with `|| echo "<sentence>"`, so a failing run prints one plain sentence. Make's `-` prefix is forbidden here, because it prints a bare `Error 1 (ignored)` line that reads as an unexplained defect.
 - **Error transparency:** The first pre-commit pass is advisory, so its non-zero exit is ignored and auto-fixed files are re-staged. Git then runs the same hooks again during `git commit`, and that second run is the blocking local gate. A hook failure there aborts the commit. The post-commit test gate is the final safety net. `make push` runs `git pull --rebase` and `git push` without suppression, so a rebase conflict or push rejection surfaces as a non-zero exit.
 
+### Parse-Time Input Validation
+
+A required input is rejected while Make reads the file, so the check runs before any prerequisite and before any shell process starts. A recipe-level check is forbidden, because it runs after the `_preflight` prerequisite.
+
+```makefile
+ifneq ($(filter commit,$(MAKECMDGOALS)),)
+ifeq ($(strip $(MSG)),)
+$(error Usage: make commit MSG="<type>(<scope>): <description>")
+endif
+endif
+ifneq ($(filter probe,$(MAKECMDGOALS)),)
+ifeq ($(strip $(REASON)),)
+$(error Usage: make probe REASON="<reason>")
+endif
+endif
+ifneq ($(filter logs,$(MAKECMDGOALS)),)
+ifeq ($(strip $(RUN)),)
+$(error Usage: make logs RUN=<run-id> [STEP="<step-name>"])
+endif
+endif
+```
+
 ## Test Workflow
 
 ### Example
@@ -118,25 +148,21 @@ test:
 ### Example
 
 ```makefile
-commit: ARGS := $(wordlist 2,$(words $(MAKECMDGOALS)),$(MAKECMDGOALS))
-
 commit:
-	$(if $(strip $(ARGS)),,$(error Usage: make commit '<message>'))
 	git add .
-	-uv run pre-commit run
+	@uv run pre-commit run || echo "Advisory pre-commit reported issues. Auto-fixed files were re-staged and the commit continues."
 	git add .
-	git commit -m "$(ARGS)"
+	git commit -m "$(MSG)"
 
-# Empty recipe absorbs extra arguments without invoking a subshell.
-%: ;
 ```
 
 **Usage:**
-- `make commit 'feat(templates): add PROJECT.md template'`
+- `make commit MSG="feat(templates): add PROJECT.md template"`
 
-**Message-input contract:** the recipe captures the message from the extra `make` goals via `$(wordlist 2,$(words $(MAKECMDGOALS)),$(MAKECMDGOALS))`. Supported input:
+**Message-input contract:** the message arrives in the named variable `MSG`, so its words are data and never goals. Supported input:
 
-- ✅ **Single-line Conventional Commits in double quotes survive verbatim** — e.g. `make commit "feat(scope): add thing"`. Always use double quotes across all operating systems.
+- ✅ **Single-line Conventional Commits in double quotes survive verbatim** — e.g. `make commit MSG="feat(scope): add thing"`. Always use double quotes across all operating systems.
+- ✅ **`#` survives** — Make keeps the character inside a quoted command-line value, so `MSG="fix: close #42"` commits that subject.
 - ❌ **`$VAR` is swallowed or expanded** — `make` and shells expand `$(...)`/`$X`; avoid `$`.
 - ❌ **Backticks trigger command substitution** in POSIX shells when inside double quotes; avoid backticks.
 - ❌ **Multiline messages fail hard** (`unexpected EOF`).
@@ -169,7 +195,7 @@ The pushed RUN's own conclusion is authoritative: it already folds in `continue-
 - **all green / non-blocking** → PASSED → **exit 0**.
 - **job-less base** → NOT green: a base run that exists but carries zero jobs (an invalid-workflow failure) is treated as an unknown base and fails safe (block).
 
-When any step fails — blocking or not — the target prints the failing step's name and its run id, then that step's log details (ANSI/timestamp-stripped and indented), bounded to `DETAIL_LINES` lines (default 50), and points to `make logs <run-id> "<step-name>"` for the full step log when needed.
+When any step fails — blocking or not — the target prints the failing step's name and its run id, then that step's log details (ANSI/timestamp-stripped and indented), bounded to `DETAIL_LINES` lines (default 50), and points to `make logs RUN=<run-id> STEP="<step-name>"` for the full step log when needed.
 
 Attribution is deterministic: SHA → run → run-level + per-job conclusion (never "the latest run").
 
@@ -229,8 +255,8 @@ ci-watch: _preflight
 	  if [ -n "$$NEWSTEPS" ]; then \
 	    echo "$$WF: failing step(s): $$NEWSTEPS (run $$NEW)"; \
 	    gh run view "$$NEW" --log-failed 2>/dev/null | awk -F'\t' '{ l=$$3; p=index(l,"Z "); if(p>0)l=substr(l,p+2); gsub(/\x1B\[[0-9;]*[a-zA-Z]/,"",l); gsub(/\^\[\[[0-9;]*[a-zA-Z]/,"",l); if(l ~ /^##\[group\]/ || l ~ /^##\[endgroup\]/) next; gsub(/^##\[error\]/,"Error: ",l); print l }' | tail -n $(DETAIL_LINES) | sed 's/^/    /'; \
-	    echo "  view all failed logs: make logs $$NEW"; \
-	    echo "  view specific step:   make logs $$NEW \"<step-name>\""; \
+	    echo "  view all failed logs: make logs RUN=$$NEW"; \
+	    echo "  view specific step:   make logs RUN=$$NEW STEP=\"<step-name>\""; \
 	  fi; \
 	  if [ "$$NEWCONC" = "success" ]; then \
 	    if [ -n "$$NEWFAIL" ]; then \
@@ -294,11 +320,9 @@ ci-watch: _preflight
 ### Example
 
 ```makefile
-probe: REASON := $(wordlist 2,$(words $(MAKECMDGOALS)),$(MAKECMDGOALS))
 probe: _preflight
 
 probe:
-	$(if $(strip $(REASON)),,$(error Usage: make probe '<reason>'))
 	git add -f spikes/debug/probe.sh
 	git commit -m "debug: probe" --no-verify --allow-empty
 	git push
@@ -321,7 +345,7 @@ probe:
 	cat spikes/debug/probe_output.txt 2>/dev/null || echo "(no output file)"
 ```
 
-**Usage:** `make probe 'investigate windows path handling'`
+**Usage:** `make probe REASON="investigate windows path handling"`
 
 `make probe` resolves the dispatched run by the pushed SHA inside a bounded retry loop. It reuses `RETRY_POLLS` and `RETRY_SLEEP` from the CI watch section. The dispatch, the run resolution, the watch, and the download stay in one shell block, because a metacharacter-free line would bypass the recipe shell on Windows. The target rejects the probe with a stderr reason when no run registers for that SHA, so a stale run can never be mistaken for the new probe.
 
@@ -332,27 +356,23 @@ The Debugger's Reproduction phase needs to read CI logs without drowning in the
 ### Example
 
 ```makefile
-logs: LOGS_RUN := $(word 2,$(MAKECMDGOALS))
-logs: LOGS_STEP := $(wordlist 3,99,$(MAKECMDGOALS))
+logs: _preflight
 
 logs:
-	$(if $(strip $(LOGS_RUN)),,$(error Usage: make logs <run-id> ["<step-name>"]))
-	@if [ -z "$(LOGS_STEP)" ]; then \
-	  gh run view "$(LOGS_RUN)" --log-failed 2>/dev/null | awk -F'\t' '{ if(j!=$$1||s!=$$2){j=$$1;s=$$2;print "\n["j" > "s"]"} l=$$3; p=index(l,"Z "); if(p>0)l=substr(l,p+2); gsub(/\x1B\[[0-9;]*[a-zA-Z]/,"",l); gsub(/\^\[\[[0-9;]*[a-zA-Z]/,"",l); if(l ~ /^##\[group\]Run /){k=1;next} if(k && l ~ /^##\[endgroup\]/){k=0;next} if(k)next; if(l ~ /^##\[group\]/ || l ~ /^##\[endgroup\]/)next; gsub(/^##\[error\]/,"Error: ",l); print l }'; \
+	@if [ -z "$(STEP)" ]; then \
+	  gh run view "$(RUN)" --log-failed 2>/dev/null | awk -F'\t' '{ if(j!=$$1||s!=$$2){j=$$1;s=$$2;print "\n["j" > "s"]"} l=$$3; p=index(l,"Z "); if(p>0)l=substr(l,p+2); gsub(/\x1B\[[0-9;]*[a-zA-Z]/,"",l); gsub(/\^\[\[[0-9;]*[a-zA-Z]/,"",l); if(l ~ /^##\[group\]Run /){k=1;next} if(k && l ~ /^##\[endgroup\]/){k=0;next} if(k)next; if(l ~ /^##\[group\]/ || l ~ /^##\[endgroup\]/)next; gsub(/^##\[error\]/,"Error: ",l); print l }'; \
 	else \
-	  gh run view "$(LOGS_RUN)" --log 2>/dev/null | awk -F'\t' -v step="$(LOGS_STEP)" 'index($$2, step) > 0 { if(j!=$$1||s!=$$2){j=$$1;s=$$2;print "\n["j" > "s"]"} l=$$3; p=index(l,"Z "); if(p>0)l=substr(l,p+2); gsub(/\x1B\[[0-9;]*[a-zA-Z]/,"",l); gsub(/\^\[\[[0-9;]*[a-zA-Z]/,"",l); if(l ~ /^##\[group\]Run /){k=1;next} if(k && l ~ /^##\[endgroup\]/){k=0;next} if(k)next; if(l ~ /^##\[group\]/ || l ~ /^##\[endgroup\]/)next; gsub(/^##\[error\]/, "Error: ", l); print l }'; \
+	  gh run view "$(RUN)" --log 2>/dev/null | awk -F'\t' -v step="$(STEP)" 'index($$2, step) > 0 { if(j!=$$1||s!=$$2){j=$$1;s=$$2;print "\n["j" > "s"]"} l=$$3; p=index(l,"Z "); if(p>0)l=substr(l,p+2); gsub(/\x1B\[[0-9;]*[a-zA-Z]/,"",l); gsub(/\^\[\[[0-9;]*[a-zA-Z]/,"",l); if(l ~ /^##\[group\]Run /){k=1;next} if(k && l ~ /^##\[endgroup\]/){k=0;next} if(k)next; if(l ~ /^##\[group\]/ || l ~ /^##\[endgroup\]/)next; gsub(/^##\[error\]/, "Error: ", l); print l }'; \
 	fi
 
-# Empty recipe absorbs extra arguments without invoking a subshell.
-%: ;
 ```
 
 **Usage:**
-- `make logs 12345` — extract logs for ALL failed steps from run `12345`.
-- `make logs 12345 "Run tests"` — extract logs for a specific step (substring match) from run `12345`.
+- `make logs RUN=12345` — extract logs for ALL failed steps from run `12345`.
+- `make logs RUN=12345 STEP="Run tests"` — extract logs for a specific step (substring match) from run `12345`.
 
 **How it works:**
-- `$(word 2,$(MAKECMDGOALS))` takes the run ID and `$(wordlist 3,99,$(MAKECMDGOALS))` captures any optional step name.
+- `RUN` carries the run ID and `STEP` carries the optional step name. Both arrive as command-line variables, so neither can become a goal.
 - When no step name is provided, `gh run view --log-failed` is used so only failed steps are fetched and printed with `[job > step]` headers.
 - When a step name is supplied, `index($2, step) > 0` performs substring matching against column 2.
 - Timestamps and ANSI escapes are stripped, and `##[error]` lines are prefixed with `Error: `.