# v0.3.0-alpha Publish Readiness

## Goal

Record the Persona Harness npm alpha release that external testers can install without local path or tarball friction.

This started as a readiness record and now records the `0.3.0-alpha.2` publish result.

## Release Message

Persona Harness `v0.3.0-alpha.2`:

> Java/Spring backend Clean Code workflow pilot for OpenCode.

The alpha is for external tester feedback on install friction, OpenCode plugin connection, backend planning workflow, generated code shape, Gradle behavior, and workflow evidence.

It is not a stable product release.

## Package Name

Package name: `persona-harness`

Original registry check before the package name existed:

```bash
npm view persona-harness version
```

Observed result on 2026-06-21:

```text
E404 Not Found
```

Interpretation: the package name was not published in the public npm registry at the time of the original check.

Current registry state after `0.3.0-alpha.2` publish:

```bash
npm dist-tag ls persona-harness
```

Observed result on 2026-06-21:

```text
alpha: 0.3.0-alpha.2
latest: 0.3.0-alpha.2
```

## Version

Current package version: `0.3.0-alpha.2`

Reason:

- `0.2.1` was the local/tarball support posture.
- v0.3.0 added project intake, workflow plan artifacts, policy overlay, workflow report lifecycle, and external tester pilot docs.
- `alpha.1` was published but still printed the old implementation-first `ph init` guidance.
- `alpha.2` carries the plan-first init output, default backend/programming scope, malformed config diagnostics, and bearshell timeout behavior needed for external tester use.

## License

License: `Apache-2.0`

The repository includes a root `LICENSE` file containing the Apache License 2.0 text. This makes the alpha install easier for external testers and avoids the previous `UNLICENSED` publish-readiness blocker.

## Dist Tag Strategy

Use `alpha` for explicit tester installs, and keep `latest` synchronized to the current alpha build during this alpha pilot.

Dry-run command:

```bash
npm publish --dry-run --tag alpha
```

Real publish command used after explicit approval:

```bash
npm publish --tag alpha
npm dist-tag add persona-harness@0.3.0-alpha.2 latest
```

This is not a stable support claim. The temporary `latest` sync exists because stale default installs are worse than clearly documented alpha installs while the package is already public.

## Alpha Install Flow

After alpha publish, testers should install with:

```bash
npm install -g opencode-ai
opencode auth login
npm install -D persona-harness@alpha
npx ph init
npx ph intake --interactive
npx ph policy init
npx ph plan
```

Then run OpenCode with the accepted workflow plan:

Plan-only prompt:

```bash
opencode run --dir . --model openai/gpt-5.4-mini-fast --dangerously-skip-permissions \
  "$(npx ph plan --prompt)"
```

Implementation prompt:

```bash
opencode run --dir . --model openai/gpt-5.4-mini-fast --dangerously-skip-permissions \
  "README.md, .persona/project-profile.jsonc, .persona/policies, .persona/workflow/plan.md를 읽고, 계획이 accepted 상태인지 확인한 뒤 Java/Spring Gradle 기반으로 요구사항 전체를 구현해줘. 명령 실행은 가능하면 npx ph bearshell로 하고, 구현 후 npx ph bearshell gradle test, npx ph bearshell gradle build, 실행 가능한 Spring Boot 앱이면 npx ph bearshell --shell 'gradle bootRun --args=\"--server.port=<port>\"', HTTP happy/failure smoke를 실행하고 .persona/workflow/implementation-report.md와 .persona/workflow/review-report.md를 채워줘."
```

## Supported Alpha Scope

The alpha supports:

- Java/Spring backend Clean Code injection
- Gradle-first backend project guidance
- `ph init`
- `ph intake --interactive`
- `ph policy init`
- `ph plan`
- `ph plan --status`
- `ph plan --accept`
- `ph plan --revise`
- `ph plan --report-filled implementation`
- `ph plan --report-filled review`
- `ph history`
- `ph bearshell`
- `.persona/evidence` metadata capture
- diagnostics-only rule report
- scope and injection-value checks

## Not Supported

The alpha does not support or guarantee:

- generated app product quality certification
- rule compliance enforcement
- AST/linter/Guard behavior
- frontend productization
- infra productization
- desktop app
- TDD workflow automation
- stable API compatibility
- stable support guarantees

## Package Contents

`package.json` includes the alpha-facing docs in `files`, including:

- `README.md`
- `LICENSE`
- `dist`
- `.persona/harness.jsonc`
- `.persona/rules`
- `packages/shared-skills/skills/programming/SKILL.md`
- `packages/shared-skills/skills/programming/references/java`
- `docs/current/v0.3.0-alpha-publish-readiness.md`
- `docs/current/v0.3.0-external-tester-guide.md`
- `docs/current/v0.3.0-external-tester-feedback-template.md`
- `docs/current/v0.3.0-gradle-spring-build-guidance.md`
- `docs/current/java-backend-mvp-install-guide.md`
- `docs/current/persona-harness-detailed-usage.md`

Packaging decision: the repo keeps the full vendored shared-skills tree, but the public alpha tarball only includes the Java MVP programming reference subset. This avoids shipping inactive OMO skills, no-excuse fixtures, and frontend/infra reference material as if they were public support surfaces.

## Required Verification Before Publish

Run:

```bash
npm test
npm run typecheck
npm run build
npm run report:rules
npm run check:scope:strict
npm run check:injection-value
npm pack --dry-run
npm publish --dry-run --tag alpha
```

Expected:

- tests pass
- typecheck passes
- build passes
- rule diagnostics PASS
- strict scope diagnostics PASS
- injection value state PASS
- package metadata says `Apache-2.0`
- root `LICENSE` is included in the tarball
- `npm pack --dry-run` includes alpha tester docs
- `npm pack --dry-run` excludes inactive shared-skills and Java no-excuse fixture files
- `npm publish --dry-run --tag alpha` does not publish but confirms package metadata and tarball shape

## GitHub Actions Release Automation

`.github/workflows/release.yml` is the release path for future tagged releases.

- It verifies `npm test`, `npm run typecheck`, `npm run build`, rule diagnostics, strict scope check, injection value check, and `npm pack --dry-run`.
- It checks that a pushed release tag matches `v${package.json.version}`.
- It runs `npm publish --dry-run --access public --tag <resolved-dist-tag>` before real publish.
- Tags matching `vX.Y.Z-alpha.N` publish with npm dist-tag `alpha`, then synchronize `latest` to that same version.
- Tags matching `vX.Y.Z-beta.N` publish with npm dist-tag `beta`, then synchronize `latest` to that same version.
- Stable tags matching `vX.Y.Z` publish with npm dist-tag `latest`.
- Tag releases create GitHub release notes with `gh release create --generate-notes`.

Required GitHub repository setup:

- Preferred future setup: npm trusted publishing with GitHub Actions OIDC.
- Current fallback setup: `NPM_TOKEN` secret with granular publish permission and 2FA-compatible automation behavior.
- `id-token: write` remains enabled for npm provenance/trusted-publishing readiness.
- The version commit should be pushed before the release tag.

See also:

- `docs/current/release/github-actions-release-automation.md`
- `docs/current/release/v0.3.0-alpha.3-candidate.md`

## Known Gaps

- `0.3.0-alpha.2` is published and both `alpha` and `latest` point to it during the alpha pilot.
- GitHub Actions release automation is defined but not proven by a real tag push in this document.
- `bootJar` disabling remains the first external tester risk to watch.
- Full shared-skills productization remains deferred. The alpha package ships only the Java MVP programming reference subset.
- `latest` points at the current alpha/beta during the alpha pilot, but it does not imply a stable support contract.

## Decision

`v0.3.0-alpha.2` is the current npm alpha tester package.

Next decision is based on external tester feedback: install friction, OpenCode plugin connection, planning workflow usability, generated Java/Spring code shape, Gradle behavior, and workflow evidence quality.