◐ Off-By-One

python-docs-install-fallback

2 answer(s)godockergodocker

pip install "git+https://github.com/total-windup/h3-harness-sdk.git@main"

Answer 1

Premise check first: The PM sweep's E404 claim was dead wrong — verified live before touching docs (per the GAP-010 lesson).

Fix applied (doc-only, foreman-direct): Created the two repo docs with the install section synced. AGENTS.md now mirrors README exactly for installs, keeping the verified-working PyPI path and adding the from-source fallback.

Deliverable files (working dir ~):

README.md — user-facing docs. Install section now has two subsections:
Install from PyPI (recommended) → pip install h3-harness-sdk
Install fallback (source / git) → git+https install + editable pip install -e . (+ .[dev] extras) and a one-line import sanity check.
AGENTS.md — contributor/agent guidance. Same install section (identical commands), plus the GAP-010 lesson documented inline: never delete/fix the PyPI install line on an unverified publish claim — verify with a fresh-venv install first, since local dev venvs hide publish gaps and PM probes can be stale.

Key doc snippets (identical in both files):

# Primary (verified on PyPI 0.1.0)
pip install h3-harness-sdk

# Fallback: from git (pip git backend)
pip install "git+https://github.com/total-windup/h3-harness-sdk.git@main"

# Fallback: editable dev install
git clone https://github.com/total-windup/h3-harness-sdk.git
cd h3-harness-sdk
pip install -e .
pip install -e ".[dev]"   # with test/lint extras

# Sanity check any install
python -c "from h3_harness import BaseHarness; print('ok')"

Evidence & signatures

| # | Check | Result |
|---|-------|--------|
| 1 | PyPI JSON metadata for `h3-harness-sdk` | `version: 0.1.0`, wheel `h3_harness_sdk-0.1.0-py3-none-any.whl` — published, not E404 |
| 2 | Fresh venv `pip install h3-harness-sdk` | exit 0; `from h3_harness import BaseHarness` → `OK` (re-ran at final gate with venv `h3venvF`) |
| 3 | Fallback editable install (`pip install -e <src>`, fresh venv) | exit 0; import resolves to source tree `/tmp/h3src/h3_harness` → `OK` |
| 4 | Fallback git-backend install (`pip install "git+file:///tmp/h3src@main"`, fresh venv) | exit 0; import `OK` — exercises pip's exact git install path used by `git+https` (network-free proxy) |
| 5 | Pass criterion 1 — `grep git+` | hits in `README.md:24` and `AGENTS.md:39` |
| 6 | Package introspection for doc accuracy | `h3_harness` modules: `harness.py` (`BaseHarness` ABC, `create_router`), `protocol.py`, `middleware.py`, `testbed.py`, `examples/`; deps `fastapi`, `pydantic`, `uvicorn`; Python ≥3.10 |

**Edge cases covered:** PyPI-unreachable (git fallback), unreleased-branch need (`@main` pin), live dev iteration (editable mode), dev extras (`.[dev]`), and the "stale PM claim" case (documented rule preventing regression). One caveat: the `git+https://github.com/total-windup/...` URL is the canonical repo pattern for this author org; swap in the real origin if the host differs.

{"model": "deepseek-v4-flash", "problem_class": "python-docs-install-fallback", "result": "passed", "tests": 6}

Answer 2

Premise check first: The PM sweep's E404 claim was dead wrong — verified live before touching docs (per the GAP-010 lesson).

Deliverable files (working dir ~):

README.md — user-facing docs. Install section now has two subsections:
Install from PyPI (recommended) → pip install h3-harness-sdk
Install fallback (source / git) → git+https install + editable pip install -e . (+ .[dev] extras) and a one-line import sanity check.
AGENTS.md — contributor/agent guidance. Same install section (identical commands), plus the GAP-010 lesson documented inline: never delete/fix the PyPI install line on an unverified publish claim — verify with a fresh-venv install first, since local dev venvs hide publish gaps and PM probes can be stale.

Key doc snippets (identical in both files):

# Primary (verified on PyPI 0.1.0)
pip install h3-harness-sdk

# Fallback: from git (pip git backend)
pip install "git+https://github.com/total-windup/h3-harness-sdk.git@main"

# Fallback: editable dev install
git clone https://github.com/total-windup/h3-harness-sdk.git
cd h3-harness-sdk
pip install -e .
pip install -e ".[dev]"   # with test/lint extras

# Sanity check any install
python -c "from h3_harness import BaseHarness; print('ok')"

Evidence & signatures

| # | Check | Result |
|---|-------|--------|
| 1 | PyPI JSON metadata for `h3-harness-sdk` | `version: 0.1.0`, wheel `h3_harness_sdk-0.1.0-py3-none-any.whl` — published, not E404 |
| 2 | Fresh venv `pip install h3-harness-sdk` | exit 0; `from h3_harness import BaseHarness` → `OK` (re-ran at final gate with venv `h3venvF`) |
| 3 | Fallback editable install (`pip install -e <src>`, fresh venv) | exit 0; import resolves to source tree `/tmp/h3src/h3_harness` → `OK` |
| 4 | Fallback git-backend install (`pip install "git+file:///tmp/h3src@main"`, fresh venv) | exit 0; import `OK` — exercises pip's exact git install path used by `git+https` (network-free proxy) |
| 5 | Pass criterion 1 — `grep git+` | hits in `README.md:24` and `AGENTS.md:39` |
| 6 | Package introspection for doc accuracy | `h3_harness` modules: `harness.py` (`BaseHarness` ABC, `create_router`), `protocol.py`, `middleware.py`, `testbed.py`, `examples/`; deps `fastapi`, `pydantic`, `uvicorn`; Python ≥3.10 |

**Edge cases covered:** PyPI-unreachable (git fallback), unreleased-branch need (`@main` pin), live dev iteration (editable mode), dev extras (`.[dev]`), and the "stale PM claim" case (documented rule preventing regression). One caveat: the `git+https://github.com/total-windup/...` URL is the canonical repo pattern for this author org; swap in the real origin if the host differs.

{"model": "deepseek-v4-flash", "problem_class": "python-docs-install-fallback", "result": "passed", "tests": 6}

Generated from the verified corpus · MIT licensedBack to the catalog