Phase 7.5 — Code Quality Remediation and Patch Release (v1.1.0a3)

[gparadis]

Phase: 7.5
Status: active
Branch: feature/ws3-phase7.5-code-quality
Roadmap: ROADMAP.md → Phase 7.5
Target release: v1.1.0a3

---

Goal

Clear the code-quality debt that is currently blocking meaningful CI signal, fix a
confirmed runtime bug shipped in v1.1.0a2, and cut a patch release — so that
Phase 8 starts from a codebase where automated checks actually mean something.

Why now

Phase 8 (Embedded Agent Capabilities) rests on the premise that ws3 can cheaply
validate model output against real package state. Two things undermine that
premise today:

1. ws3 contains 25 F821 undefined names. One is a confirmed NameError
   (Bug: NameError from 'rel_opertors' typo in forest.py condition parser #93). Phase 8's explain_exception capability validates that referenced
   symbols exist — building that check on a codebase with undefined names is
   self-defeating.
2. CI provides no signal at all. The Lint and Type Check job is permanently
   red (1808 errors, identical on main and every branch), and test, docs,
   and build are all downstream of it, so they never run (CI: lint job permanently red (1808 pre-existing flake8 errors) blocks all other checks #94). Phase 8 is a
   test-heavy phase and needs a working pipeline from day one.

Cheap to fix now. Expensive to fix once Phase 8 code is layered on top.

Scope

• Fix the rel_opertors NameError in ws3/forest.py with a regression test
• Mechanical lint remediation (whitespace classes — no semantic change)
• Individual triage of genuine defect classes: F821, F841, E722, F401
• Restructure CI so a lint failure cannot silently disable every other check
• Bump to v1.1.0a3, update CHANGELOG.md, publish

Out of scope

• Any Phase 8 work (embedded agents, fresh-agent-core)
• Stylistic reformatting beyond what lint requires
• Type-annotation expansion (Phase 2 territory)
• Refactoring for its own sake — this phase fixes defects and unblocks CI, nothing more

Child tasks

• Task 7.5.1 — Fix rel_opertors NameError (Bug: NameError from 'rel_opertors' typo in forest.py condition parser #93)
• Task 7.5.2 — Lint stage 1: mechanical whitespace remediation
• Task 7.5.3 — Lint stage 2: triage genuine defects
• Task 7.5.4 — CI restructure so lint does not gate all jobs (CI: lint job permanently red (1808 pre-existing flake8 errors) blocks all other checks #94)
• Task 7.5.5 — Release v1.1.0a3

Acceptance criteria

• flake8 ws3/ --max-line-length=100 --exclude=__pycache__ reports zero errors
• No F821 undefined names remain
• python -m pytest passes, with a regression test covering the _period <= path
• CI runs test, docs, and build even when lint fails
• All CI jobs green on the phase PR
• ws3.__version__ == '1.1.0a3' and CHANGELOG.md records the release
• v1.1.0a3 published to PyPI

Verification

flake8 ws3/ --max-line-length=100 --exclude=__pycache__ --statistics
python -m pytest
python -m build
sphinx-build -b html docs/source _build/html
python -c "import ws3; assert ws3.__version__ == '1.1.0a3'"

Closeout

• All child issues closed with evidence
• ROADMAP.md and CHANGELOG.md synchronized
• PR merged to main
• v1.1.0a3 tagged and published
• This issue closed only after the PR merges