# KORA v0.2.1-alpha Polish Merge Readiness PR Packet

Date: 2026-05-07

## PR Title Suggestion

Polish onboarding and contributor docs for v0.2.1-alpha

## Branches

| Item | Value |
|---|---|
| Source branch | `task144_v021_polish_merge_packet` |
| Target branch | `main` |
| Public baseline | `origin/main` at `a3348864fbfbe559a2479826025c53dba42f6e98` |
| Chain tip before packet | `origin/task143_telemetry_counter_definitions` at `ac69f6e2cab3fc1584333e0ea10d1f5a16e5d975` |

## Copy-Pasteable PR Body

```md
## Summary

Polishes the public onboarding, contributor, security, governance, examples, telemetry, and benchmark-regeneration documentation path for the `v0.2.1-alpha` polish cycle.

This PR includes:

- README current-release and quickstart polish for the published `v0.2.0-alpha` prerelease.
- Docs index/navigation polish with a canonical benchmark evidence path.
- Experiments benchmark regeneration guide cleanup using the current `deterministic_heavy_v1_100` workload and `/tmp` outputs.
- Release evidence cross-links across README, changelog, docs index, experiments guide, benchmark artifact policy, and raw artifact freeze decision.
- Contributor, security, PR template, and issue template polish.
- Initial good-first issues seeded for first-time contributor work.
- Governance duplication clarification: top-level `GOVERNANCE.md` is canonical, while `docs/GOVERNANCE.md` points to it.
- First-run expected-output notes for `hello_kora`, `retry_demo`, and `direct_vs_kora -- --offline`.
- Core telemetry counter definitions linked from README and docs index.

## Linked Issues

Refs #33
Refs #34
Refs #35
Refs #36

## Validation

- `python3 -m pytest` passed, `50 passed`
- `python3 -m kora --help` passed
- `python3 -m kora examples list` passed
- `python3 -m kora run hello_kora` passed
- `python3 -m kora run retry_demo` passed
- `python3 -m kora run direct_vs_kora -- --offline` passed
- `python3 -m kora telemetry --help` passed
- `python3 -m kora telemetry --input docs/reports/sample_telemetry_input.json --json-out /tmp/kora_sample_telemetry_task144.json --md-out /tmp/kora_sample_telemetry_task144.md` passed

## Release Hygiene

- No Git tag created.
- No GitHub Release created.
- No package version update.
- No release assets uploaded.
- No raw benchmark JSON artifacts committed.

## Claim Hygiene

This PR keeps benchmark language bounded to simulated, reproducible alpha evidence and does not add unsupported production cost, real API-cost, production benchmark, full runtime-integrated benchmark, broad workload superiority, or energy reduction claims.

## Post-Merge Actions

- Run final validation from merged public `origin/main`.
- Refresh local project context after merge, if needed.
- Decide whether to close issues #33-#36 after maintainers confirm the docs fully address them.
- Clean stale Task 131-144 branches after merge.
```

## Task Chain Summary

| Task | Commit | Summary |
|---|---|---|
| 131 | `9b3300f382b6293dd31fb8083ff9530f435c0582` | Added v0.2.1-alpha polish/onboarding audit report. |
| 132 | `8449601b061d57dc0a1467be075940ec4fe5bca9` | Polished README current release, quickstart, and bounded benchmark evidence. |
| 133 | `47a54ade1d2fe67a1c92f796f08c1310bab772e2` | Polished docs index and canonical benchmark evidence path. |
| 134 | `b110aa971b34d70c29f73c799c5e705f7a8817d7` | Polished experiments benchmark regeneration guide. |
| 135 | `7a4936ff28da19cf0bc641b0b2439f40b747d04b` | Updated release evidence cross-links and stale release wording. |
| 136 | `53eb2bf58255f6f737fdf02df07512708ae6db98` | Added contributor path audit report. |
| 137 | `aa96bc54e5d7a34c8b12af2bcf29d6b249b4beb4` | Polished contributing guide for current alpha. |
| 138 | `830d661530254fdc0623d352bb009825ec470506` | Polished security reporting guidance. |
| 139 | `4f8a2d5eb7ae9626723d28e8e19592c4d8e6883c` | Aligned GitHub templates with contributor guidance. |
| 140 | `6133cbddb69de733a8b7825b096a1b0fbca1bf0a` | Seeded initial good-first issues and report. |
| 141 | `ae996271d1429a0fc2153f919063e17b708f017c` | Clarified governance documentation. |
| 142 | `f41afd4384adef839ff5192c9a7c381d277c9abe` | Documented first-run example output expectations. |
| 143 | `ac69f6e2cab3fc1584333e0ea10d1f5a16e5d975` | Defined core telemetry counters. |

The commits are present in the expected order on top of `origin/main`.

## Changed File Summary

- `README.md`: current release section, quickstart commands, expected first-run output notes, benchmark evidence/non-claims, telemetry counter link, contributor/security/governance links.
- `docs/README.md`: docs navigation, current benchmark evidence path, contributor links, telemetry counter link, document status labels.
- `experiments/README.md`: current `deterministic_heavy_v1_100` workload, `/tmp` regeneration commands, artifact policy, claim boundary.
- `CHANGELOG.md`: updated `v0.2.0-alpha` status to published prerelease and added release evidence links.
- `CONTRIBUTING.md`: current alpha status, contributor path map, verification guidance by change type, claim and local-path hygiene.
- `SECURITY.md`: alpha-stage security reporting guidance, private reporting route, public/private issue boundary, artifact/release hygiene.
- `docs/GOVERNANCE.md`: converted duplicate governance copy into a pointer to canonical root `GOVERNANCE.md`.
- `.github/ISSUE_TEMPLATE/*` and `.github/pull_request_template.md`: aligned templates with verification, security, release, local-path, and claim hygiene.
- `docs/telemetry-and-observability.md`: added current public telemetry/demo/benchmark counter definitions.
- `docs/reports/*`: added onboarding audit, contributor path audit, good-first-issue seeding report, and this merge readiness packet; updated stale release wording notes.

## Branch-Chain Integrity Findings

- Current branch was created from `origin/task143_telemetry_counter_definitions`.
- `HEAD` before this packet matched `origin/task143_telemetry_counter_definitions`.
- `origin/main` baseline is `a3348864fbfbe559a2479826025c53dba42f6e98`.
- Task 131-143 commits are present in order.
- `pyproject.toml` is unchanged relative to `origin/main`.
- No package metadata files are changed.
- No workflow, release asset, or distribution artifact paths are changed.
- No new tag points at the chain tip; the existing `v0.2.0-alpha` tag remains present.

## Validation Summary

All validation was run from the Task 144 worktree:

| Command | Result |
|---|---|
| `python3 -m pytest` | Passed, `50 passed` |
| `python3 -m kora --help` | Passed |
| `python3 -m kora examples list` | Passed |
| `python3 -m kora run hello_kora` | Passed |
| `python3 -m kora run retry_demo` | Passed |
| `python3 -m kora run direct_vs_kora -- --offline` | Passed |
| `python3 -m kora telemetry --help` | Passed |
| `python3 -m kora telemetry --input docs/reports/sample_telemetry_input.json --json-out /tmp/kora_sample_telemetry_task144.json --md-out /tmp/kora_sample_telemetry_task144.md` | Passed |

## Linked Issues

- #33 `Docs: explain the hello_kora example`
- #34 `Docs: explain the retry_demo example`
- #35 `Docs: clarify direct_vs_kora offline mode`
- #36 `Docs: define core telemetry counters`

## Hygiene Summary

Claim hygiene:

- No unsupported production cost reduction proof.
- No real API-cost reduction proof.
- No production benchmark proof.
- No full runtime-integrated benchmark evidence.
- No broad workload superiority proof.
- No energy reduction evidence.

Local path hygiene:

- Public changed docs/templates were scanned for machine-local absolute paths.
- The Task 131 audit report was minimally scrubbed during this packet because it still contained explicit machine-local absolute paths.
- After the scrub, no prohibited local absolute path references remain in changed public docs/templates.

Release hygiene:

- No Git tag created.
- No GitHub Release created.
- No package version updated.
- No release assets uploaded.
- No raw benchmark JSON artifacts committed.

## Post-Merge Required Actions

1. Run final validation from merged public `origin/main`.
2. Refresh local project context after merge, if needed.
3. Decide whether to close issues #33-#36 after confirming the merged docs satisfy maintainer expectations.
4. Clean stale Task 131-144 branches after merge.
