# Contributing to Persona Harness

Thanks for looking at Persona Harness (PH). This is a small, evidence-first
project. Before you write code, please read this — the contribution rules here
are unusual on purpose, and they are the fastest way to get a PR merged.

## Good first contributions

You do not need to understand the whole project to help. Low-risk, welcome:

- Fix confusing docs or add real terminal-output examples.
- Improve the [Quick Demo](docs/QUICK-DEMO.md) or troubleshooting notes.
- Reproduce and report an install issue or a confusing blocker message.
- Translate a short doc.
- Send external-tester feedback as an issue.

Anything that changes runtime, gates, TDD evidence, role relay, or a product
claim needs measurement — see below.

## The one rule that makes this project different

**Every claim must be earned by measurement. Broader claims are rejected until
proven.**

PH is a completion gate and evidence system. It deliberately does *not* claim to
improve code quality, save tokens, or make agents smarter — because those were
measured and are [not proven](docs/current/injection-value-status.json). If your
change implies a broader claim, the PR must include the measurement, not just
the feature.

This is the project's identity, not bureaucracy. A negative result is a
first-class, mergeable contribution. "It feels better" is not.

### The Claim Ladder

A change may only assert what its evidence supports. Climb in order; do not skip:

1. The package/runtime surface exists.
2. PH actually invokes the tool/gate in a clean fixture.
3. Evidence is generated by PH — not hand-written by an agent or human.
4. Adversarial cases fail honestly (forged/stale/mismatched inputs are rejected).
5. An external smoke reproduces it from a fresh tarball or npm.
6. Repeated A/B shows improvement for a *named* scenario.
7. Only now may a scoped claim be written in docs/README.

If a change reaches level 6 with no improvement, it is not kept "pending
forever" — it becomes a removal or opt-in-downgrade candidate.

### Words you may not use without proof

The canonical list of forbidden claims and their required proof lives in
[docs/MEASURED-CLAIMS.md](docs/MEASURED-CLAIMS.md#forbidden-claims). Do not
restate it here — link to it. In short: no token-saving, app-quality, full-TDD,
broad-reliability, or orchestration claims without the measurement that earns
them.

When in doubt, prefer a narrower true statement over a broader attractive one.

## What kinds of contributions fit

**Welcome:**

- Bug fixes with a failing test that turns green.
- New deterministic conformance blockers that are *narrow and hard to fake*
  (each needs: a violating fixture, a safe near-miss fixture that must NOT
  fire, a closure blocker, and a fix path).
- Adversarial tests that try to fool an existing gate (forged evidence, stale
  records, ticket mismatch).
- A/B measurements — including negative ones — for an existing surface.
- Docs that make a boundary more honest.

**Please open an issue first (likely to be declined otherwise):**

- New always-on runtime injection or broad context loading. The measured
  default is off; the burden of proof is high.
- A broad linter, AST engine, or general enforcement framework. Out of scope.
- New optional surfaces (LSP/CodeGraph/MCP integrations) without an attached
  measurement plan.

## Development setup

```bash
git clone https://github.com/jyt6640/persona-harness.git
cd persona-harness
npm install
```

Before opening a PR, all of these must pass:

```bash
npm test            # full unit/integration suite
npm run typecheck   # tsc, zero errors
npm run build       # clean tsc build
npm run check:docs  # docs taxonomy + claim/acceptance consistency
```

If your change touches injection value or scope, also run:

```bash
npm run check:injection-value
npm run check:scope
```

## Pull request expectations

- Keep it narrow. One behavior per PR.
- New behavior comes with a test. Prefer red-first: a failing test, then the
  fix that makes it pass.
- If the PR could be read as expanding a claim, either include the measurement
  or explicitly state in the description which Claim Ladder level it stops at.
- Do not add product surface and its proof in the same rushed PR unless the
  proof is real. A registered "measure later" with no owner is not proof.

## Reporting bugs and requesting features

Use the issue templates. A feature request that would expand what PH claims
must include how you'd measure it — that is not a formality, it is the first
step of the work.

## License

By contributing, you agree that your contributions are licensed under the
project's [Apache-2.0](LICENSE) license (inbound = outbound). No separate CLA is
required.