[MINOR] §12: pixi.toml targets linux-64 only — limits distribution

[mvillmow]

Evidence

pixi.toml:7

Description

platforms = ["linux-64"] restricts pixi-based packaging and installation to Linux. Cross-platform support would require adding osx-arm64, osx-64, and win-64 to the platforms list.

Part of #92

[mvillmow]

Implementation Plan

I have enough context to produce the plan.

Implementation Plan

Objective

Issue #180 calls out that pixi.toml:7 declares platforms = ["linux-64"], which prevents pixi-based install and packaging on macOS (Intel + Apple Silicon) and Windows. The package itself is pure-Python (hatchling wheel of src/telemachy) with pure-Python runtime deps (pydantic, httpx, pyyaml, rich, typer), so there is no platform-specific code constraining us — the limitation is a config-only restriction. This plan expands platforms to include osx-arm64, osx-64, and win-64, regenerates pixi.lock to cover all four, and adds a matrix entry to CI so the broader platform set is continuously verified.

Approach

Decision 1 — expand platforms to all four conda-forge tier-1 targets (linux-64, osx-arm64, osx-64, win-64). Evidence: all declared [pypi-dependencies] (pydantic, pydantic-settings, httpx, pyyaml, rich, typer) and [feature.dev.pypi-dependencies] (pytest, pytest-asyncio, pytest-cov, ruff, mypy, types-PyYAML, yamllint) ship universal wheels on PyPI for these targets. python = ">=3.10" is also available on all four via conda-forge. There is no native build step (pyproject.toml uses hatchling and [tool.hatch.build.targets.wheel] packages = ["src/telemachy"] — pure Python).

Decision 2 — regenerate pixi.lock via pixi install, do NOT hand-edit. Evidence: project guardrail in CLAUDE.md reads "Never write to pixi.lock by hand; regenerate via pixi install." Lockfile currently has only the linux-64 solve; running pixi install after the platforms edit will resolve and append osx-arm64, osx-64, win-64 entries.

Decision 3 — add a matrix to .github/workflows/ci.yml so the multi-platform claim is enforced. Evidence: ci.yml:11 currently hardcodes runs-on: ubuntu-latest. Without a matrix, a regression that breaks macOS or Windows installs would not be caught. The prefix-dev/setup-pixi action supports all three runner OSes. We replace the scalar runs-on with a strategy.matrix.os over [ubuntu-latest, macos-latest, windows-latest]. To keep the existing Lint YAML files and Type-check (mypy) deterministic across OSes, we keep them in the matrix (they are pure-Python tools) and gate bash shell with shell: bash explicitly so Windows uses Git Bash for the lint/test steps. The Gitleaks installer step in secrets-scan already supports macOS/Linux but its current OS=$(uname -s | tr …) logic is Linux-only here; that job stays ubuntu-latest to avoid scope creep — gitleaks is repo-scanning, not platform-specific behaviour.

Decision 4 — classify the change under docs/backwards-compat.md. Evidence: backwards-compat.md:8-25 enumerates the public surface; platforms in pixi.toml is not in that list (it governs the dev environment, not the workflow schema, CLI, Python API, or env vars). However, the project guardrail "Workflow YAML is a public API" does not apply here — this is a development-environment widening, not a schema change. It is additive (more platforms supported), so even if treated as governed it would be a MINOR bump. Issue title already labels it [MINOR], consistent with this read.

Decision 5 — update docs/install.md to state which platforms pixi install resolves. Evidence: docs/install.md describes pixi as "the only installation path covered by CI and the test suite" but never names the supported OSes. Adding a one-line note avoids future user confusion and matches the new CI matrix.

Files to Create

None.

Files to Modify

pixi.toml

Replace the single-platform declaration at pixi.toml:7 with the four conda-forge tier-1 targets:

platforms = ["linux-64", "osx-arm64", "osx-64", "win-64"]

pixi.lock

Regenerated mechanically by pixi install after the pixi.toml change. Do NOT hand-edit. The resulting file will gain osx-arm64, osx-64, and win-64 solve entries alongside the existing linux-64 one. Commit the regenerated lockfile in the same PR.

.github/workflows/ci.yml

Add an OS matrix to the lint-and-test job (currently ci.yml:10-11). Replace:

  lint-and-test:
    name: Lint & Test
    runs-on: ubuntu-latest

with:

  lint-and-test:
    name: Lint & Test (${{ matrix.os }})
    runs-on: ${{ matrix.os }}
    strategy:
      fail-fast: false
      matrix:
        os: [ubuntu-latest, macos-latest, windows-latest]
    defaults:
      run:
        shell: bash

The defaults.run.shell: bash ensures Windows uses Git Bash so the existing pixi run … step bodies (pixi run ruff check src tests, etc.) execute identically across all three runners. The secrets-scan job (ci.yml:36-58) is left as ubuntu-latest — its Gitleaks installer is hand-rolled around uname and is out of scope for this issue.

docs/install.md

Append one line under "1. pixi (development; recommended)" (current block ends at docs/install.md:19):

The `pixi` solve covers `linux-64`, `osx-arm64`, `osx-64`, and `win-64`;
all four are exercised in CI.

CHANGELOG.md

Add an entry under the current Unreleased section's ### Changed (or create the section if absent):

- pixi: expand `platforms` to `linux-64`, `osx-arm64`, `osx-64`, `win-64`
  so contributors and operators on macOS and Windows can run
  `pixi install` (#180).

docs/license-audit.md

No re-audit required: this change adds no new runtime dependencies and bumps no existing one — only the platforms array changes. The CLAUDE.md guardrail ("re-run the license audit when adding or major-bumping a runtime dependency") does not trigger.

Implementation Order

1. Edit pixi.toml:7 to add the three new platforms.
2. Run pixi install locally to regenerate pixi.lock with the new solves. If any pypi dep fails to resolve on a target (unlikely for our pure-Python stack but possible if a transitive sdist lacks a wheel), stop and pin the offending dep or open a sub-issue rather than dropping a platform silently.
3. Edit .github/workflows/ci.yml to add the OS matrix as described above.
4. Edit docs/install.md to mention the four supported platforms.
5. Add the CHANGELOG.md entry under Unreleased / Changed.
6. Run pixi run ruff check src tests, pixi run yamllint ., pixi run mypy src/telemachy --ignore-missing-imports, and pixi run pytest --cov-fail-under=75 locally on linux-64 to confirm nothing regressed.
7. Push branch, open PR referencing [MINOR] §12: pixi.toml targets linux-64 only — limits distribution #180 and Epic: Strict audit 2026-04-28 — ProjectTelemachy #92, watch the CI matrix turn green on all three OS runners.

Verification

Acceptance criterion: "Cross-platform support would require adding osx-arm64, osx-64, and win-64 to the platforms list."

# Acceptance criterion 1: pixi.toml declares all four platforms
python -c "import tomllib, pathlib; p = tomllib.loads(pathlib.Path('pixi.toml').read_text()); assert set(p['workspace']['platforms']) == {'linux-64','osx-arm64','osx-64','win-64'}, p['workspace']['platforms']; print('OK')"

# Acceptance criterion 2: pixi.lock contains a solved environment for each platform
pixi install      # regenerates lockfile if drifted; exits 0 only if all four platforms solve
grep -E "^(  |    )- platform: " pixi.lock | sort -u   # expect four entries

# Acceptance criterion 3: existing test suite still passes on linux-64
pixi run pytest --tb=short -q --cov=telemachy --cov-fail-under=75

# Acceptance criterion 4: CI matrix runs on macOS + Windows (verified by GitHub Actions on the PR)
# Confirmed by green checks for: "Lint & Test (ubuntu-latest)", "Lint & Test (macos-latest)", "Lint & Test (windows-latest)"
gh pr checks --watch

Skills Used

• docs-search (consulted via direct grep against docs/ and CLAUDE.md to confirm install-doc surface and the no-hand-edit-pixi.lock guardrail).
• hephaestus:verification (informs the per-criterion runnable-command discipline used in the Verification section).
• hephaestus:systematic-debugging (applied to confirm via repo evidence — pyproject.toml's hatchling wheel target and pure-Python dep list — that no native build step blocks cross-platform support before proposing the config-only fix).
• No marketplace skill entries were resolvable from the prepended Prior Learnings block (the marketplace file was not accessible); the plan therefore relies on in-repo evidence and project guardrails in CLAUDE.md / docs/backwards-compat.md.

Changes from review

N/A — initial plan.

---

Final review verdict (from strict review loop)

Now I have the full context to review the plan. Let me analyze it against all rubric dimensions.

---

Review: Issue #180 — pixi.toml Cross-Platform Support

Dimension 1: Requirements Alignment

The issue has one concrete acceptance criterion: "Cross-platform support would require adding osx-arm64, osx-64, and win-64 to the platforms list." The plan directly addresses this in pixi.toml:7. The plan also adds CI matrix coverage, docs updates, and CHANGELOG — all additive, none of which contradicts the stated criterion. The scope expansion (CI matrix, docs) is reasonable and coherent with the issue's intent.

No silently dropped criteria. The criterion is fully addressed.

Dimension 2: Plan Completeness

The plan covers:

• Design: Decision rationale for all four major choices (platform selection, lock regeneration, CI matrix, versioning classification). Well-evidenced.
• Implementation: Specific edits named with file:line for pixi.toml, ci.yml, docs/install.md, CHANGELOG.md.
• Tests/Verification: Four acceptance criteria with runnable commands.
• Rollback: Implicit — since pixi.lock is regenerated by command and pixi.toml is a trivial single-line change, rollback is a revert. Not explicitly called out but low risk.

Minor gap: The plan acknowledges in Learnings that no audit of src/telemachy/ for Linux-only code paths (os.uname, path separators, temp file handling) was performed. This is flagged in Learnings but not included as a plan step. For a CLI tool, this is low-risk but the plan says "low risk for a CLI tool, but reviewer should do a quick grep." The implementer is instructed to trust the reviewer rather than having the grep in the plan steps. This is a minor omission.

Dimension 3: Concreteness

• pixi.toml:7 — specific line cited.
• ci.yml:10-11 — specific lines cited with before/after YAML shown verbatim.
• docs/install.md:19 — specific line cited with exact text to append.
• CHANGELOG.md — exact entry text provided.
• Implementation order is numbered and actionable.

One vagueness: The plan says to edit ci.yml by replacing the lint-and-test job header, but the full updated YAML for the entire job is not shown. The before/after for the header is clear, but the defaults.run.shell: bash placement is shown inline in the replacement snippet without confirming where it lands relative to steps:. This is navigable but not perfectly self-contained for the implementer.

Dimension 4: Risk Surface

The plan addresses risks:

• Lock regeneration guardrail cited (CLAUDE.md).
• Gitleaks job left at ubuntu-latest with rationale (uname-based installer, out of scope).
• Windows shell: bash caveats noted in Learnings.
• No schema or API surface changes.

Gap acknowledged but not mitigated: The Learnings section notes that macos-latest/windows-latest CI runners are unverified with this action. However, prefix-dev/setup-pixi explicitly lists Linux/macOS/Windows support in its README, and this is a well-known action. The plan treats this correctly as low-risk.

Minor risk not called out: pixi.lock will grow substantially (3x entries). Some CI systems cache the lockfile; the cache: true on setup-pixi means the cache key may need to include the new platform entries. This is handled automatically by pixi's cache keying but not mentioned.

Dimension 5: Verification Plan

Four acceptance criteria, each with a runnable command:

1. Python one-liner verifying the TOML platforms set — concrete and runnable.
2. pixi install + grep on lockfile — concrete and runnable.
3. pixi run pytest with coverage flag — concrete and runnable.
4. gh pr checks --watch for CI matrix — concrete, though externally dependent.

All four map directly to the issue's stated criterion. Strong.

Dimension 6: Stage Handoff

The plan is self-contained: specific before/after YAML, exact text for docs/changelog, numbered order, and the key decision (Gitleaks stays on ubuntu-latest) is recorded with reasoning. An implementer can execute without re-deriving anything.

Minor gap: Decision 4 (backwards-compat classification) is concluded as "no version bump needed." The plan correctly reasons that platforms is not in the public surface (backwards-compat.md:8-25), and the issue title already says [MINOR]. However, the plan says "even if treated as governed it would be a MINOR bump" but then says no bump is needed. This is slightly contradictory but ultimately correct — the platforms key is dev environment, not schema, so no bump is warranted.

---

Software Engineering Principles

P1 — KISS

The solution is minimal: one config line change + lock regeneration + CI matrix expansion + two doc edits. No new abstractions, no new code. No finding.

P2 — YAGNI

All plan steps map directly to the issue's requirements. The CI matrix is directly required to validate the claim. The docs/install.md and CHANGELOG.md updates are standard hygiene required by project conventions (CLAUDE.md guardrails). No finding.

P3 — TDD

This is a configuration/infra change, not a code change. The "tests" are the CI matrix runs and the acceptance criterion commands. No production code is written, so TDD does not apply in the classical sense. The plan correctly relies on CI to verify. Not applicable.

P4 — DRY

No code duplication introduced. defaults.run.shell: bash is set once at job level. No finding.

P5 — SOLID

No new code. Not applicable.

P6 — Modularity

The Gitleaks job is kept separate from lint-and-test — this is correct SRP. No finding.

P7 — POLA

The defaults.run.shell: bash for Windows is the right default behavior — least surprise for contributors who expect bash behavior. Keeping Gitleaks on ubuntu-latest without changing its name would be slightly surprising (CI shows three green Lint & Test jobs and one ubuntu-only secrets-scan) but this is cosmetic and the plan explains the rationale. No finding.

---

Summary of Findings

Critical: None.

Major: None.

Minor:

1. The plan does not include a plan step to grep src/telemachy/ for Linux-only code paths (only mentioned in Learnings as "reviewer should do a quick grep"). This is risk acknowledged but not mitigated in the plan steps themselves.
2. The full updated ci.yml job YAML is not shown — only the header replacement. The defaults.run.shell: bash placement relative to steps: is inferrable but not shown explicitly. Marginal implementer risk.
3. Decision 4 slightly contradicts itself ("even if treated as governed it would be MINOR bump" → "no bump needed") without cleanly resolving the tension. Not a material problem since the conclusion is correct.

All three are minor. The plan is well-evidenced, concrete, and addresses the single acceptance criterion directly. The Learnings section demonstrates intellectual honesty about unverified assumptions without blocking the plan. The verification section is unusually strong for a plan-level review.

Grade: B
Verdict: GO

---

Generated by Claude Code Planner (strict review loop)

[mvillmow]

🔍 Plan Review

Now I have the full context to review the plan. Let me analyze it against all rubric dimensions.

---

Review: Issue #180 — pixi.toml Cross-Platform Support

Dimension 1: Requirements Alignment

The issue has one concrete acceptance criterion: "Cross-platform support would require adding osx-arm64, osx-64, and win-64 to the platforms list." The plan directly addresses this in pixi.toml:7. The plan also adds CI matrix coverage, docs updates, and CHANGELOG — all additive, none of which contradicts the stated criterion. The scope expansion (CI matrix, docs) is reasonable and coherent with the issue's intent.

No silently dropped criteria. The criterion is fully addressed.

Dimension 2: Plan Completeness

The plan covers:

• Design: Decision rationale for all four major choices (platform selection, lock regeneration, CI matrix, versioning classification). Well-evidenced.
• Implementation: Specific edits named with file:line for pixi.toml, ci.yml, docs/install.md, CHANGELOG.md.
• Tests/Verification: Four acceptance criteria with runnable commands.
• Rollback: Implicit — since pixi.lock is regenerated by command and pixi.toml is a trivial single-line change, rollback is a revert. Not explicitly called out but low risk.

Minor gap: The plan acknowledges in Learnings that no audit of src/telemachy/ for Linux-only code paths (os.uname, path separators, temp file handling) was performed. This is flagged in Learnings but not included as a plan step. For a CLI tool, this is low-risk but the plan says "low risk for a CLI tool, but reviewer should do a quick grep." The implementer is instructed to trust the reviewer rather than having the grep in the plan steps. This is a minor omission.

Dimension 3: Concreteness

• pixi.toml:7 — specific line cited.
• ci.yml:10-11 — specific lines cited with before/after YAML shown verbatim.
• docs/install.md:19 — specific line cited with exact text to append.
• CHANGELOG.md — exact entry text provided.
• Implementation order is numbered and actionable.

One vagueness: The plan says to edit ci.yml by replacing the lint-and-test job header, but the full updated YAML for the entire job is not shown. The before/after for the header is clear, but the defaults.run.shell: bash placement is shown inline in the replacement snippet without confirming where it lands relative to steps:. This is navigable but not perfectly self-contained for the implementer.

Dimension 4: Risk Surface

The plan addresses risks:

• Lock regeneration guardrail cited (CLAUDE.md).
• Gitleaks job left at ubuntu-latest with rationale (uname-based installer, out of scope).
• Windows shell: bash caveats noted in Learnings.
• No schema or API surface changes.

Gap acknowledged but not mitigated: The Learnings section notes that macos-latest/windows-latest CI runners are unverified with this action. However, prefix-dev/setup-pixi explicitly lists Linux/macOS/Windows support in its README, and this is a well-known action. The plan treats this correctly as low-risk.

Minor risk not called out: pixi.lock will grow substantially (3x entries). Some CI systems cache the lockfile; the cache: true on setup-pixi means the cache key may need to include the new platform entries. This is handled automatically by pixi's cache keying but not mentioned.

Dimension 5: Verification Plan

Four acceptance criteria, each with a runnable command:

1. Python one-liner verifying the TOML platforms set — concrete and runnable.
2. pixi install + grep on lockfile — concrete and runnable.
3. pixi run pytest with coverage flag — concrete and runnable.
4. gh pr checks --watch for CI matrix — concrete, though externally dependent.

All four map directly to the issue's stated criterion. Strong.

Dimension 6: Stage Handoff

The plan is self-contained: specific before/after YAML, exact text for docs/changelog, numbered order, and the key decision (Gitleaks stays on ubuntu-latest) is recorded with reasoning. An implementer can execute without re-deriving anything.

Minor gap: Decision 4 (backwards-compat classification) is concluded as "no version bump needed." The plan correctly reasons that platforms is not in the public surface (backwards-compat.md:8-25), and the issue title already says [MINOR]. However, the plan says "even if treated as governed it would be a MINOR bump" but then says no bump is needed. This is slightly contradictory but ultimately correct — the platforms key is dev environment, not schema, so no bump is warranted.

---

Software Engineering Principles

P1 — KISS

The solution is minimal: one config line change + lock regeneration + CI matrix expansion + two doc edits. No new abstractions, no new code. No finding.

P2 — YAGNI

All plan steps map directly to the issue's requirements. The CI matrix is directly required to validate the claim. The docs/install.md and CHANGELOG.md updates are standard hygiene required by project conventions (CLAUDE.md guardrails). No finding.

P3 — TDD

This is a configuration/infra change, not a code change. The "tests" are the CI matrix runs and the acceptance criterion commands. No production code is written, so TDD does not apply in the classical sense. The plan correctly relies on CI to verify. Not applicable.

P4 — DRY

No code duplication introduced. defaults.run.shell: bash is set once at job level. No finding.

P5 — SOLID

No new code. Not applicable.

P6 — Modularity

The Gitleaks job is kept separate from lint-and-test — this is correct SRP. No finding.

P7 — POLA

The defaults.run.shell: bash for Windows is the right default behavior — least surprise for contributors who expect bash behavior. Keeping Gitleaks on ubuntu-latest without changing its name would be slightly surprising (CI shows three green Lint & Test jobs and one ubuntu-only secrets-scan) but this is cosmetic and the plan explains the rationale. No finding.

---

Summary of Findings

Critical: None.

Major: None.

Minor:

1. The plan does not include a plan step to grep src/telemachy/ for Linux-only code paths (only mentioned in Learnings as "reviewer should do a quick grep"). This is risk acknowledged but not mitigated in the plan steps themselves.
2. The full updated ci.yml job YAML is not shown — only the header replacement. The defaults.run.shell: bash placement relative to steps: is inferrable but not shown explicitly. Marginal implementer risk.
3. Decision 4 slightly contradicts itself ("even if treated as governed it would be MINOR bump" → "no bump needed") without cleanly resolving the tension. Not a material problem since the conclusion is correct.

All three are minor. The plan is well-evidenced, concrete, and addresses the single acceptance criterion directly. The Learnings section demonstrates intellectual honesty about unverified assumptions without blocking the plan. The verification section is unusually strong for a plan-level review.

Grade: B
Verdict: GO