# v0.3.1-alpha Roadmap

Planning date: 2026-05-07

Current public HEAD reviewed: `8deb36d85b20fad56ef39f1a7250a5b0a5c1a51c`

Current released version: `v0.3.0-alpha`

Release/tag target HEAD: `078de0777178f8b233877f126a4ed844247da7d7`

Release URL: https://github.com/Krako-Labs/KORA/releases/tag/v0.3.0-alpha

Purpose: candidate roadmap for `v0.3.1-alpha`. This document is planning-only and does not change runtime behavior, release state, package version, generated artifacts, or claim boundaries.

## v0.3.0-alpha Baseline

`v0.3.0-alpha` established a bounded, reviewer-facing evidence path:

- Runtime evidence architecture design.
- Initial runtime-path benchmark harness.
- Runtime benchmark JSON output path.
- Markdown evidence packet/report generator.
- Telemetry-connected summary path.
- Reviewer-facing reproduction guide.
- Release-readiness checklist.
- Docs cross-link audit.
- Public claim-boundary review.
- Draft changelog entry.
- Release validation packet.
- Release approval checkpoint.
- Git tag and GitHub prerelease.
- Post-release EOD/SOD docs.
- SOD HEAD wording clarification.
- Post-release cleanup plan.

Release state remains:

- `v0.3.0-alpha` is published as a GitHub prerelease.
- Release assets: none.
- Raw benchmark artifacts uploaded: none.
- Package version remains `0.1.0a0`.

## Safe Current Claim

> KORA reduced model invocations by 80% in a reproducible deterministic-heavy benchmark workload.

## Explicit Non-Claims

KORA does not currently claim:

- production cost reduction proof
- real API-cost reduction proof
- production benchmark proof
- full runtime-integrated benchmark evidence yet
- broad workload superiority proof
- energy reduction evidence
- formal government validation
- signed partner validation unless actually signed and documented
- guaranteed adoption or funding

## v0.3.1-alpha Planning Goal

Improve evidence breadth, reviewer usability, and next-step implementation clarity without overclaiming.

The `v0.3.1-alpha` work should extend the non-production benchmark scaffold and reviewer-facing reproducibility path while preserving the bounded v0.3.0-alpha evidence path and artifact policy.

## Proposed Workstreams

### 1. Broader Workload Design

- Add at least one new non-production benchmark workload family.
- Keep deterministic and fallback/model-candidate counters explicit.
- Document workload purpose, routing expectations, and limitations.
- Avoid broad workload superiority claims.

### 2. Evidence Hardening

- Strengthen report generation and evidence packet consistency.
- Consider a CI-safe smoke test for report generation if current tests do not already cover the critical path.
- Keep generated JSON, Markdown, and telemetry outputs in `/tmp` or user-provided ignored paths.
- Ensure generated artifacts remain out of git.

### 3. Reviewer Onboarding

- Create a compact reviewer quickstart.
- Clarify commands, expected outputs, safe claim wording, and explicit non-claims.
- Support external reviewer reproduction without raw artifact uploads.
- Preserve no-network and no-API-key requirements for the default reproduction path.

### 4. Telemetry and Report Polish

- Improve telemetry summary readability.
- Verify report sections remain stable across runs.
- Keep runtime counters and telemetry counters aligned across JSON, Markdown, and CLI summaries.
- Preserve offline/no-network/no-API requirements.

### 5. Future Cleanup Execution

- Use the [`v0.3.0-alpha post-release cleanup plan`](../reports/v0.3.0-alpha-post-release-cleanup-plan.md) as the cleanup source.
- Do not delete worktrees or branches in planning tasks.
- Actual deletion requires explicit approval with exact paths and branch names.
- Reconfirm clean status, merge status, and unpushed commits before any approved cleanup execution.

## Candidate Task Sequence

Task A: broader workload design doc.

Task B: add second CI-safe benchmark workload scaffold.

Task C: add or extend tests for workload/report consistency.

Task D: reviewer quickstart doc.

Task E: `v0.3.1-alpha` validation packet.

## Acceptance Criteria for v0.3.1-alpha

- `python3 -m pytest` passes.
- `python3 -m kora run direct_vs_kora -- --offline` passes.
- `python3 -m kora run runtime_integrated_benchmark -- --offline` passes.
- Any additional workload implemented has clear counters and documented limitations.
- Generated artifacts remain in `/tmp` or user-provided ignored paths.
- Claim boundaries are preserved.
- No production/API-cost/energy claims are introduced.
- No broad workload superiority claim is introduced.
- No release assets or raw benchmark artifacts are uploaded without explicit approval.

## Risk Table

| Risk | Why it matters | Mitigation |
|---|---|---|
| Overclaiming | Evidence remains bounded and non-production. | Keep safe claim wording and explicit non-claims in every reviewer-facing artifact. |
| Benchmark too narrow | A single deterministic-heavy workload can be mistaken for broad evidence. | Add broader workload design before adding public claims. |
| Generated artifacts mistaken for official assets | Reproducible `/tmp` outputs can look release-like if copied into public channels. | Keep generated artifacts out of git and out of release assets unless explicitly approved. |
| Cleanup deletes useful branches | Older task branches may preserve validation or follow-up context. | Use approval-gated cleanup and review unmerged branches before removal. |
| Reviewer confusion around tag target vs current public HEAD | The release tag target differs from later post-release documentation commits. | State release/tag target HEAD and current public HEAD separately in reviewer docs. |

## Recommended Next Task

Recommended next task: create a broader workload design doc or create an external reviewer quickstart.

Do not execute cleanup unless explicitly approved. Do not create additional tags, GitHub Releases, release assets, raw benchmark artifact uploads, or package version changes without explicit approval.
