Skip to content

Aire 0.4.2 Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [x]) syntax for tracking.

Goal: Repair newly reproduced correctness gaps and systemize future audits in 0.4.2.

Architecture: Preserve existing runtime boundaries. Add installed-user smoke diagnostics to doctor and a separate repository audit runner with source-bound JSON evidence; CI consumes the same runner.

Tech Stack: Python, pytest, Typer, uv, GitHub Actions.

Spec: docs/superpowers/specs/2026-10-15-audit-loop-design.md

Global Constraints

  • Keep Python >=3.11, the four existing runtime dependencies and all public extras.
  • No new runtime dependency.
  • Retain lazy imports, release integrity gates and digital attestations.
  • QA optional CPU backends with bounded threads.

Review Focus

  • Secret values in nested/custom config fields must not appear in diagnostics.
  • Invalid explicit paths must never fall back to a different project configuration.
  • Mutating records inside a failed transform must not change the source dataset.
  • Overlapping tasks sharing one context must restore their own ambient context.
  • Interrupted audits and changed source trees must never produce a healthy report.

Task 1: Fail-closed configuration and safe inspection

Files: src/aire/core/config.py, src/aire/cli/main.py, tests/unit/test_config_boundaries.py.

Interfaces: Settings.load(...) -> Settings; Settings.safe_dict() -> dict[str, Any] feeds inspection and future diagnostics.

  • [x] Write tests for missing explicit files/directories, valid discovery, nested secrets/custom mask fields, unknown inspection selectors. Run .venv/bin/python -m pytest tests/unit/test_config_boundaries.py; Expected: reproducible failures.
  • [x] Implement explicit-path errors and recursive key-based redaction; preserve excluded provider settings and mask configured fields without importing optional packages.
  • [x] Run the same test command; Expected: all pass. Run lint on changed files and commit fix: fail closed on missing config and redact inspection secrets.

Task 2: Immutable datasets and valid sampling/splits

Files: src/aire/data/dataset.py, tests/unit/test_dataset_boundaries.py.

Interfaces: Existing Dataset API; record and lineage access returns isolated snapshots.

  • [x] Write tests for constructor/accessor/callback mutation isolation, zero fraction, conflicting/negative/nonfinite sampling and splits, record conservation and manifest counts. Run .venv/bin/python -m pytest tests/unit/test_dataset_boundaries.py; Expected: failures.
  • [x] Copy mutable boundaries, validate sampling/split inputs with structured DataError, and preserve deterministic selection and lineage.
  • [x] Run the same test command; Expected: all pass. Run lint on changed files and commit fix: preserve dataset snapshots and validate partitions.

Task 3: Context and schedule lifecycle correctness

Files: src/aire/core/context.py, src/aire/schedule/scheduler.py, tests/unit/test_context_schedule_boundaries.py.

Interfaces: Existing context manager and scheduler API; task-local context token stacks.

  • [x] Write tests for nested/overlapping context entry, successful/failed job replacement, nonfinite intervals/poll periods. Run .venv/bin/python -m pytest tests/unit/test_context_schedule_boundaries.py; Expected: failures.
  • [x] Restore context tokens per asyncio context; validate registration before mutation and remove replaced handlers; reject nonfinite timing.
  • [x] Run the same test command; Expected: all pass. Run lint on changed files and commit fix: restore nested contexts and replace scheduled handlers atomically.

Task 4: Offline diagnostics and repeatable audit evidence

Files: src/aire/cli/diagnostics.py, src/aire/cli/main.py, scripts/audit.py, tests/unit/test_diagnostics.py, tests/contract/test_audit.py, .gitignore, Makefile, .github/workflows/ci.yml.

Interfaces: doctor --smoke --output PATH emits versioned checks; run_audit(root, checks, output, timeout_seconds) -> dict writes source-bound reports. Check(name, command) defines named subprocess checks. build_checks(profile) -> list[Check] defines core/optional profiles.

  • [x] Write tests exercising real doctor generation/embedding/tool/RAG, invalid config, missing credentials, configured live credentials and report persistence. Write real subprocess audit tests for pass/fail/timeout/source drift and initially unrun states. Run .venv/bin/python -m pytest tests/unit/test_diagnostics.py tests/contract/test_audit.py; Expected: missing feature failures.
  • [x] Implement doctor diagnostics with explicit statuses, resource cleanup and safe error output. Implement runner with bounded process groups, incremental atomic reports/logs and a Git source fingerprint. Require ignored/external report paths. Integrate core CI and upload evidence; add make audit and make audit-optional without pruning optional environments.
  • [x] Run the same test command; Expected: all pass. Run lint/types, run core and optional audit profiles; Expected: healthy source-bound reports. Commit feat: add offline smoke diagnostics and reproducible repository audits.

Task 5: Release 0.4.2 with reviewed evidence

Files: Version, changelog, citation, docs home, issue template, capability/CLI/contributing/publishing/migration docs, audit record, MkDocs nav.

Interfaces: Existing scripts/release.py source gate and exact-main publication workflow.

  • [x] Update all current release metadata to 0.4.2/date 2026-10-15, document new behavior, limits and audit commands; retain historical snapshots. Record regression evidence and QA.
  • [x] Run core/optional audits, dependency audit, actionlint and fresh wheel installation. Expected: passing checks, explicit known backend warnings only.
  • [x] Commit release preparation, obtain a fresh branch review, address Important/Critical findings with RED→GREEN regressions and full suite; record all decisions.
  • [ ] Push PR, attach it, update GitHub review/audit evidence, wait for CI, merge after QA. Expected: all required jobs pass.
  • [ ] Require exact-main checks and dry-run, tag v0.4.2, verify public bytes and fresh-index installation. Expected: complete successful release; clean main/tag/source match.

The final two steps execute after this source snapshot is committed. Their completion evidence is recorded on PR #19 and the v0.4.2 release workflow; publication status is not inferred from these source checkboxes.