Orchestrata Ultimate › Plans › briefs › proper-install-5-4-implementation

Packet: proper-install §5.4 implementation + §5.3 staleness guard (codetools)

Source: plans/briefs/proper-install-5-4-implementation.md at 8a2cb42ad · last changed 2026-10-20 · first committed 2026-10-20 · 128 lines.

Prose pending.

Plan text

Packet: proper-install §5.4 implementation + §5.3 staleness guard (codetools)

Status: DISPATCH-READY · Repo: /home/mohamed/workspace/orchestrata.codetools (branch master) Authority: ADR-0120 (Accepted, Mohamed 2026-10-20) + the §5.3/§5.4 rulings logged in orchestrata session 272. DESIGN_WAIVER: ADR-0120 per ADR-0048 — the packet's entire scope executes the Accepted ADR and its rulings; scope beyond the deliverables below loses the waiver.

Context (measured, not assumed)

The proper install is live in codetools (00b1304, 9c583c85 in HEAD; PEP 610 editable:false). The coordinator measured the §5.4 coupling sites at HEAD:

• tests/deploy/test_atomic_promote.py — KILL_SCRIPT child: sys.path.insert(0, sys.argv[1]) then from codetools.deploy import Artifact, Pipeline; src_path (line ~51) is argv[1].
• tests/deploy/test_install.py — KILL_SCRIPT child: sys.path.insert(0, sys.argv[1]) then from codetools.deploy import install; SRC_PATH (line ~35) is argv[1].
• tests/bdd/steps_spec012_fixtures.py — KILL_SCRIPT child: same sys.path.insert(0, sys.argv[1]) pattern (Artifact/Pipeline); SRC_PATH (line ~22) is argv[1].
• tests/bdd/steps_spec012_cli.py — _CLI_SRC_PATH (line ~29) fed as extra_pythonpath to _run_version (line ~105): the "deployed release" scenario runs codetools --version against the LIVE source tree via PYTHONPATH.
• tests/bdd/test_spec_018.py — PROLOG_DIR (line ~17) = repo/src/codetools/prolog, consumed as use_module('{PROLOG_DIR / "facts.pl"}') (line ~65). The .pl files ship in the installed package.

ADR-0120 (verbatim decision): test-spawned subprocesses resolve the packages under test from the installed environment, never via sys.path/PYTHONPATH into the source tree; freshness is the runner-level staleness guard (the §5.3 ruling: versioned copy, never in-place, path never in the dev directory, hard fail when stale); production-entrypoint invocation wherever a child simulates production; -c shims stay only where the PID is structurally needed (these three kill-children qualify — keep the shim, drop only the path hack). The repoints and the staleness guard travel in the SAME packet, never alone.

Deliverables

D1 — repoint the three KILL_SCRIPT children (§5.4a, ADR-0120)

For each of tests/deploy/test_atomic_promote.py, tests/deploy/test_install.py, tests/bdd/steps_spec012_fixtures.py:

• Remove sys.path.insert(0, sys.argv[1]) from the KILL_SCRIPT; remove the now-dead src_path / SRC_PATH computation AND its Popen argument.
• INDEX-SHIFT HAZARD (measured defect class): every KILL_SCRIPT sys.argv[n] reference after argv[1] shifts down by one. Paste the FULL KILL_SCRIPT and the FULL Popen argument list in the report before and after; verify each argv index against the new argument list.
• The child imports codetools.deploy from the venv it inherits (its parent runs under the sanctioned runner; sys.executable is the venv python). Do not add any other path mechanism.
• Acceptance: grep -rn "sys.path.insert" over the three files returns NOTHING; the three modules pass via the sanctioned runner (D5).

D2 — faithful deploy in the spec-012 CLI scenario (§5.4b)

In tests/bdd/steps_spec012_cli.py, the step "that release's interpreter runs codetools --version" must run codetools --version from a release interpreter that REALLY contains the installed package — no extra_pythonpath.

• FIRST measure the release-builder step that produces CTX.cli_python/cli_cwd (paste it) and report the seam: if the builder creates a real venv, add the install step there (uv pip install <repo root> --python <release python> — uv, never bare pip); if it builds only a VERSION-file directory with no interpreter, create the venv in the scenario (the scenario is the deploy test — the install step is its premise).
• Check every other caller of _run_version before changing its signature; if extra_pythonpath becomes dead, remove it and note it.
• If the measured seam contradicts this brief's premise, STOP and report — never invent.
• Acceptance: no _CLI_SRC_PATH reference remains (delete the constant if dead); the spec-012 bdd feature tests pass via the sanctioned runner.

D3 — repoint PROLOG_DIR to the installed package (§5.4c)

In tests/bdd/test_spec_018.py: PROLOG_DIR = Path(codetools.__file__).resolve().parent / "prolog" (the exact COLLECT_PL precedent from tests/prolog/test_parity_base_id.py). First verify the .pl files ship in the installed artifact (ls .venv/lib/*/site-packages/codetools/prolog/ — paste the listing). Acceptance: the module passes; no parents[2] / "src" reference remains in it.

D4 — the §5.3 staleness guard (new)

New module src/codetools/testing/staleness_guard.py + startup wiring in scripts/run_tests_parallel.py + tests tests/testing/test_staleness_guard.py. Mirror the import_shadow.py pattern (pure stdlib path arithmetic, never imports the packages it guards, docstring with the incident + ruling + remediation):

• Behavior: at sanctioned-runner startup, hard-fail when the installed codetools copy differs from src/codetools — content comparison (hash every .py file in both trees, compare as a set of relpath→hash); refuse with a named remediation line (the measured correct command — uv sync --dev --no-editable) when the installed distribution is missing or stale. Never a warning-only path, never a skip switch.
• Locate the installed distribution WITHOUT importing codetools (e.g. importlib.metadata.distribution("codetools") files/direct_url.json), and locate the repo root from __file__ the way import_shadow.py does. Reuse import_shadow's helpers where they fit; do not duplicate them.
• Measure and report: wall-ms of hashing src/codetools and of hashing the installed tree (verbatim). Decide conftest wiring on the number: wire tests/conftest.py (alongside _guard_import_shadow) ONLY if the measured per-session cost is ≤200 ms; otherwise runner-only and report the number for the coordinator's adjudication.
• Interaction notes: an EDITABLE install is the existing canary's failure mode (9c583c85) — the staleness guard assumes the proper install and documents the interplay in its docstring; do not reimplement editable detection.
• Tests (real, no mocks, RUL-002): build real tmp trees (a fake src/codetools tree and a fake installed tree) and exercise the compare function: stale pair → fail with the remediation in the message; fresh pair → pass; missing installed distribution → fail. Plus a wiring test proving the runner's startup path calls the check (use the runner's real dry-run/help seam if one exists — measure what scripts/run_tests_parallel.py exposes and report it). Coverage ≥90% per file.
• Acceptance: PYTEST_DEBUG_TEMPROOT=/var/tmp .venv/bin/python scripts/run_tests_parallel.py tests/testing/ -j 8 green; the guard fires on a deliberately-stale probe you build (report the probe and its output verbatim), and is silent on the real tree.

D5 — verification lanes (verbatim outputs in the report)

PYTEST_DEBUG_TEMPROOT=/var/tmp .venv/bin/python scripts/run_tests_parallel.py tests/deploy/ -j 8
PYTEST_DEBUG_TEMPROOT=/var/tmp .venv/bin/python scripts/run_tests_parallel.py tests/bdd/ -j 8
PYTEST_DEBUG_TEMPROOT=/var/tmp .venv/bin/python scripts/run_tests_parallel.py tests/testing/ -j 8

No pytest-xdist ever. No full-tree runs.

Fence

ALLOWED (the only files you may write):

• tests/deploy/test_atomic_promote.py · tests/deploy/test_install.py
• tests/bdd/steps_spec012_fixtures.py · tests/bdd/steps_spec012_cli.py · tests/bdd/test_spec_018.py
• scripts/run_tests_parallel.py · src/codetools/testing/staleness_guard.py (new)
• tests/testing/test_staleness_guard.py (new) · tests/conftest.py (ONLY the D4 conftest wiring, if the ≤200 ms measurement allows it)

FORBIDDEN (named): src/codetools/review/** (the REV-3 lane is ACTIVE — gates.py is dirty), src/codetools/cli_version.py, pyproject.toml, uv.lock, deploy/**, tests/review/**, anything not in the allowlist. FOREIGN DIRT — do not touch, do not stage, do not "fix": src/codetools/review/gates.py (M), tests/review/test_review_ruff_lookup.py (??), plans/ast-*.json (M), kimi-export-*.md (??), plans/*.warmcache (??).

Conduct

• RUL-037: no python -c / heredoc file writes; edit files through your file tools only.
• Measure before editing (L19); paste verbatim outputs for every claim (L2); no false attribution (L11); no codemod scripts.
• Do NOT commit anything — the coordinator verifies and commits with explicit pathspecs.
• Do not run any test twice against the same code state (RUL-032); do not touch the forbidden files for any reason, including "cleanup".
• Report ends with: git status of the allowlist files, the D4 measurements, and the D5 lane outputs.

Related

• Plans
• Orchestrata Ultimate — project index
• Workflow
• Tasks