# KORA v0.2.1-alpha Contributor Path Audit

Date: 2026-05-07

## Current Branch Base

| Item | Value |
|---|---|
| Base branch | `origin/task135_release_evidence_crosslinks` |
| Base commit | `7a4936ff28da19cf0bc641b0b2439f40b747d04b` |
| Audit branch | `task136_contributor_path_audit` |
| Public release baseline | `v0.2.0-alpha` |
| Release URL | `https://github.com/Krako-Labs/KORA/releases/tag/v0.2.0-alpha` |

## Audit Scope

Reviewed first-time contributor entry points and project-governance files:

- `README.md`
- `docs/README.md`
- `experiments/README.md`
- `CHANGELOG.md`
- `CONTRIBUTING.md`
- `SECURITY.md`
- `CODE_OF_CONDUCT.md`
- `GOVERNANCE.md`
- `LICENSE`
- `.github/ISSUE_TEMPLATE/`
- `.github/pull_request_template.md`
- `.github/workflows/ci.yml`
- `docs/good_first_issues.md`
- `pyproject.toml`
- `scripts/release_smoke.sh`
- tests and examples directories
- `python3 -m kora examples list`

## Present Contributor Docs

KORA already has the core public contributor surface:

- `CONTRIBUTING.md`: local setup, first verification commands, branch/PR workflow, contribution rules.
- `SECURITY.md`: security concern reporting guidance and scope.
- `CODE_OF_CONDUCT.md`: expected behavior, unacceptable behavior, reporting concerns, scope.
- `GOVERNANCE.md`: architectural invariants and change-control philosophy.
- `LICENSE`: Apache-2.0 license.
- `.github/pull_request_template.md`: summary, change type, verification, scope check, reviewer notes.
- `.github/ISSUE_TEMPLATE/bug_report.md`: reproducibility and verification context.
- `.github/ISSUE_TEMPLATE/docs_improvement.md`: small docs improvement template.
- `.github/ISSUE_TEMPLATE/feature_discussion.md`: public surface and deterministic-first checks before implementation.
- `.github/ISSUE_TEMPLATE/good_first_issue.md`: small contributor-friendly task template.
- `.github/ISSUE_TEMPLATE/community-task.md`, `content-review.md`, and `partner-lead.md`: claim-sensitive community and external-facing coordination templates.
- `.github/workflows/ci.yml`: CI runs editable install, release smoke, and pytest on PRs to `main`.
- `docs/good_first_issues.md`: contributor-friendly backlog that maintainers can convert to issues.

## Missing Contributor Docs

No top-level contributor file is absent. The gap is polish and alignment, not missing existence.

Missing or incomplete contributor-path details:

- `CONTRIBUTING.md` still says KORA is at `v0.1.0-alpha`, while public docs now point to `v0.2.0-alpha`.
- `SECURITY.md` says to contact maintainers through the repository owner, but does not provide a concrete security contact path or GitHub Security Advisory path.
- `CONTRIBUTING.md` does not link directly to `SECURITY.md`, `CODE_OF_CONDUCT.md`, `GOVERNANCE.md`, `docs/README.md`, `docs/good_first_issues.md`, or the current benchmark evidence path.
- PR and issue templates are present, but `CONTRIBUTING.md` does not explicitly route contributors to the templates.
- Good-first-issue backlog exists, but the repository still depends on maintainers to convert candidates into GitHub issues.
- Governance exists at both `GOVERNANCE.md` and `docs/GOVERNANCE.md`; duplication should be kept in sync or made intentionally canonical.

## Findings By Severity

### Blocker

No blocker was found. A first-time contributor can understand the project, install it locally, run tests, run examples, find the license, find governance expectations, and open an issue or PR using existing templates.

### High

1. `CONTRIBUTING.md` has stale release status.
   - It states KORA is currently at `v0.1.0-alpha`.
   - Impact: contributors may trust the contributor guide less than the README/changelog.
   - Recommended fix: update contributor status to the current published prerelease and link `CHANGELOG.md`.

2. Security reporting guidance is present but not concrete enough.
   - It tells reporters to contact maintainers through the repository owner.
   - Impact: sensitive reports may be delayed or opened publicly if the reporter cannot find the intended private channel.
   - Recommended fix: add the preferred private reporting path, or explicitly route to GitHub private vulnerability reporting if enabled.

### Medium

1. Contributor flow is split across several files without a compact path.
   - README links contributor files, but `CONTRIBUTING.md` does not provide a single map to docs index, security, governance, code of conduct, claim registry, templates, and good-first-issue backlog.
   - Recommended fix: add a short "Contributor path" section to `CONTRIBUTING.md`.

2. Good-first-issue material exists but is not yet fully operationalized.
   - `docs/good_first_issues.md` lists candidates and `.github/ISSUE_TEMPLATE/good_first_issue.md` exists.
   - Recommended fix: convert a small set of candidates into GitHub issues and keep the backlog as the source for future issue creation.

3. PR verification guidance is consistent but could be clearer for docs-only changes.
   - The PR template allows docs-only changes, while `CONTRIBUTING.md` emphasizes release smoke and pytest.
   - Recommended fix: clarify minimum verification expectations for docs-only, tests, examples, benchmark docs, and runtime changes.

4. Governance duplication can drift.
   - `GOVERNANCE.md` and `docs/GOVERNANCE.md` both exist.
   - Recommended fix: choose a canonical file and make the other a short pointer, or add an explicit sync note.

### Low

1. Issue template labels use spaces such as `good first issue`.
   - This may be fine if labels exist in GitHub, but label setup should be verified.

2. Contributor docs do not mention Python version as clearly as CI does.
   - `pyproject.toml` says Python `>=3.11`, while CI uses Python `3.13`.
   - Recommended fix: add a short note in `CONTRIBUTING.md`.

3. Example output expectations are scattered.
   - README lists first-run examples, and `docs/good_first_issues.md` includes tasks to explain examples.
   - Recommended fix: follow through on example explanation tasks for `hello_kora`, `retry_demo`, and offline `direct_vs_kora`.

## First-Time Contributor Questions

| Question | Assessment |
|---|---|
| Can a contributor understand what KORA is? | Yes. README and docs index explain the execution-control category and deterministic-first model. |
| Can they run tests? | Yes. `CONTRIBUTING.md`, PR template, CI, and `pyproject.toml` point to editable install, release smoke, and pytest. |
| Can they run the main examples? | Yes. README and release smoke cover CLI help, examples list, `hello_kora`, `retry_demo`, and offline `direct_vs_kora`. |
| Can they find benchmark evidence and claim boundaries? | Yes. README, docs index, experiments guide, changelog, artifact policy, and claim registry are linked. |
| Can they understand how to propose changes? | Mostly. Branch/PR workflow and templates exist; `CONTRIBUTING.md` should link them explicitly. |
| Can they find security reporting guidance? | Yes, but the private reporting path is vague. |
| Can they find license/governance expectations? | Yes. Apache-2.0 license and governance docs exist. |
| Are there good-first-issue labels/templates/docs? | Templates and backlog exist; GitHub label availability should be checked in platform setup. |
| Are there missing or stale docs that block contributors? | No blockers. The stale `v0.1.0-alpha` contributor status should be corrected next. |

## Recommended Minimum v0.2.1-alpha Contributor Docs

Minimum docs improvements before wider contributor outreach:

1. Update `CONTRIBUTING.md` current status from `v0.1.0-alpha` to current published alpha/prerelease wording.
2. Add a concise contributor path map in `CONTRIBUTING.md`:
   - setup and verification
   - issue templates
   - PR template
   - `SECURITY.md`
   - `CODE_OF_CONDUCT.md`
   - `GOVERNANCE.md`
   - `docs/README.md`
   - `docs/good_first_issues.md`
   - claim registry and benchmark evidence path
3. Clarify verification expectations by change type.
4. Make security reporting instructions concrete.
5. Convert 3-5 good-first-issue candidates into GitHub issues.
6. Decide how to keep root and docs governance files synchronized.

## Proposed Next Task Sequence

1. Task 137: polish `CONTRIBUTING.md` current status and contributor path links.
2. Task 138: tighten `SECURITY.md` reporting route and vulnerability-disclosure wording.
3. Task 139: align PR and issue templates with current verification and claim hygiene language.
4. Task 140: convert initial good-first-issue backlog items into GitHub issues.
5. Task 141: resolve or document `GOVERNANCE.md` and `docs/GOVERNANCE.md` duplication.
6. Task 142: add short expected-output notes for first-run examples.

## Do-Not-Touch Items

- Do not delete or move historical reports, EOD/SOD docs, release-prep reports, or benchmark summaries.
- Do not expand the public CLI or task surface as part of contributor polish.
- Do not change package version.
- Do not create a Git tag or GitHub Release.
- Do not commit generated benchmark JSON artifacts.
- Do not weaken deterministic-first, validation, retry, budget, or no-hidden-model-call guidance.
- Do not add broad impact claims to contributor docs.

## Claim Hygiene Note

Contributor docs should continue routing benchmark language to existing evidence docs rather than restating long release material.

If the benchmark claim is needed, use only the approved wording:

> In a reproducible 100-task deterministic-heavy benchmark workload, KORA-controlled execution avoided 80 of 100 simulated model invocations versus a naive direct baseline.

Contributor-facing docs should preserve the current non-claims:

- no 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

## Validation Commands For This Audit

```bash
python3 -m pytest
python3 -m kora --help
python3 -m kora examples list
python3 -m kora run direct_vs_kora -- --offline
```
