# Java Backend MVP Install Guide

## Scope

Persona Harness의 현재 productized MVP는 Java/Spring backend Clean Code injection이다.

목표는 같은 요구사항에서 Gradle 기반, 계층 분리, DTO boundary, Repository boundary, Service orchestration-only backend product code shape가 더 균일하게 나오도록 Java target file에 rule context를 주입하는 것이다.

frontend, infra, multi-domain shared skill은 후속 확장 후보이며 현재 release-facing MVP 범위가 아니다.

## Requirements

- Node.js ^20.17.0 || >=22.9.0 (Node 21 unsupported)
- npm
- OpenCode terminal CLI
- OpenCode에 연결된 model/provider

Persona Harness의 CLI는 OpenCode 없이도 `.persona` planning files를 만들 수 있지만, 핵심인 plugin hook injection과 evidence capture는 OpenCode가 있어야 동작한다.

OpenCode 설치:

```bash
curl -fsSL https://opencode.ai/install | bash
```

대안 npm 설치:

```bash
npm install -g opencode-ai
```

확인:

```bash
opencode --version
opencode
```

model/provider 연결:

```bash
opencode auth login
opencode auth list
```

또는 OpenCode TUI에서:

```text
/connect
/models
```

`opencode run --model <model>`의 model 값은 `provider/model` 형식이어야 한다. 예:

```text
openai/gpt-5.4-mini-fast
```

## Local Development Install

```bash
npm install
npm run build
```

## Project Init

대상 프로젝트에서는 다음 한 줄로 Persona Harness rules와 OpenCode plugin 연결을 설치한다.

```bash
npx persona-harness init
```

설치되는 것:

- `.persona/harness.jsonc`
- `.persona/rules/`
- `.opencode/opencode.json`

복사하지 않는 것:

- `.persona/evidence/`

`.persona/evidence/`는 init template가 아니라 hook runtime evidence다. OpenCode가 README/requirements/Gradle/Java target을 실제로 읽거나 수정할 때 대상 프로젝트 안에 생성된다.

### Java/Spring guidance core와 명시적 conditional pack

기본 Java/Spring rule은 작게 유지한다. Controller→Application→Domain, Repository/persistence boundary, API DTO와 Entity 분리, constructor injection, public setter 금지, domain invariant, security fail-closed 같은 공통 경계만 기본 주입한다. JPA, 전역 exception/response contract, 특정 package tree, GWT 또는 모든 production class 직접 테스트, report/evidence/finish는 기본값이 아니다.

프로젝트가 기술이나 테스트 convention을 명시적으로 선택했을 때 `.persona/harness.jsonc`의 `backendPacks`에 pack을 적는다.

```jsonc
{
  "backendPacks": ["persistence-jdbc", "migration-flyway"]
}
```

사용 가능한 pack은 `domain-layout`, `persistence-jdbc`, `persistence-jpa`, `migration-flyway`, `error-contract-global`, `testing-direct-class`, `testing-gwt`, `workflow-evidence`다. JDBC를 선택해도 JPA나 global error/response pack은 따라오지 않으며, OAuth provider/domain/callback/state/layer/type-exception/global-scope가 미결정이면 구현을 시작하지 않고 `design-required`로 둔다. Flyway를 선택한 경우에도 적용된 migration은 수정하지 않고 새 forward-only migration만 만든다.

`workflow-evidence`는 public workflow boundary가 실제로 바뀌는 작업에서만 선택한다. guidance-only 또는 일반 product code 작업은 report/evidence/finish 산출물을 자동으로 요구하지 않는다.

기본 검증:

```bash
npm test
npm run typecheck
npm run build
npm run report:rules
```

`npm run report:rules`는 `.persona/rules` frontmatter diagnostics를 ignored output인 `.persona/evidence/phase-next/rule-diagnostics-report.md`에 남긴다. 이 report는 diagnostics-only surface이며 rule loading, rule selection, injection, test, typecheck, build를 막지 않는다.

## Package Artifact Smoke

가장 짧은 package artifact smoke commands:

```bash
npm run demo:init
npm run demo:bootstrap
npm run demo:java-mvp
```

`npm run demo:init`은 package artifact가 실제 설치 환경에서 `persona-harness init`으로 clean project를 안전하게 초기화하는지 확인한다.

`npm run demo:bootstrap`은 init 이후 README target에서 bootstrap injection과 runtime evidence 생성이 되는지 확인한다. 설치된 named `PersonaHarnessPlugin` export를 사용하고 임시 프로젝트 안에서만 `ph bootstrap backend --runtime-injection-preview --no-developer-mcp`를 명시적으로 적용한다. 이 opt-in은 기본 `runtimeInjection` 설정을 바꾸지 않는다.

`npm run demo:java-mvp`는 package artifact가 실제 설치 환경에서도 Java Controller plugin hook, injection, model input transform, evidence 생성 경로를 재현하는지 확인한다. 마찬가지로 disposable fixture에서만 preview opt-in을 사용한다.

저장소 maintainer/reviewer가 실제 Gradle/JUnit과 workflow Finish 경계를 검증하려면 Node 20.19+, JDK 21, Gradle 9.4.0 환경에서 다음을 실행한다.

```bash
npm ci
node scripts/verify-cooperative-finish-demo.mjs
```

이 명령은 exact packed package를 disposable Java/Spring fixture에 설치하고, 먼저 `workflow-state-uninitialized` BLOCK을 확인한 다음 실제 Gradle/JUnit evidence와 `--assurance cooperative`의 `Finish status: PASS`를 확인한다. required repository CI도 같은 명령을 실행한다. 이는 trusted external authority나 production quality를 증명하지 않는다.

검증하는 것:

- `npm pack` tarball 생성
- 임시 프로젝트에 packed `persona-harness` 설치
- 설치된 `persona-harness init` 실행
- init 직후 `.persona/evidence`가 없음을 확인
- 설치된 패키지 안의 `dist/index.js`, `.persona/harness.jsonc`, `.persona/rules` 확인
- README target의 `project-bootstrap` injection 확인
- 설치된 OpenCode plugin module import
- `tool.execute.after` hook 노출과 Java Controller injection 확인
- `experimental.chat.messages.transform` hook 노출과 model input transform 확인
- 임시 프로젝트의 `.persona/evidence/phase0` evidence JSON 생성 확인

임시 프로젝트를 보존하려면:

```bash
npm run demo:java-mvp -- --keep
```

## OpenCode Plugin Connection

테스트할 Java/Spring 프로젝트에서 `persona-harness init`을 실행한다.

```bash
npx persona-harness init
```

local development 중 직접 경로를 고정해야 하면 `.opencode/opencode.json`에 빌드된 플러그인을 등록한다.

```jsonc
{
  "plugin": [
    "/absolute/path/to/persona-harness/dist/index.js"
  ]
}
```

그 Java/Spring 프로젝트에서 OpenCode를 실행한다.

```bash
opencode run --dir /path/to/java-spring-project --model openai/gpt-5.4-mini-fast \
  "$(npx ph plan --prompt)"
```

Persona Harness는 OpenCode가 README/requirements/Gradle bootstrap target 또는 Java/Spring target file을 읽거나 수정할 때 동작한다.

흐름:

```text
README / requirements / Gradle / Java target file
-> file role
-> selected rules
-> injection block
-> tool output / model input
-> .persona/evidence/phase0 JSON
```

현재 Java/Spring target role:

```text
README.md
requirements.md
build.gradle
settings.gradle
**/*Controller.java
**/*Service.java
**/*Repository.java
**/*Entity.java
**/*Request.java
**/*Response.java
**/*Exception.java
**/*Test.java
```

## Evidence

Plugin hook이 발동하면 연결한 Java/Spring 프로젝트의 configured evidence directory 아래에 JSON이 남는다. 기본값은 다음 경로다.

```text
.persona/evidence/phase0/*.json
```

각 evidence JSON은 target file, file role, selected rules, selected rule metadata, selected shared skills, injected policy count를 기록한다.

## Non-Goals

이 install guide와 `npm run demo:java-mvp` 및 `node scripts/verify-cooperative-finish-demo.mjs`는 다음을 보증하지 않는다.

- 생성된 Spring application의 품질
- 테스트 충분성
- rule compliance enforcement
- Guard/AST/linter 검증
- frontend, infra, multi-domain productization
- package name exact match

Backend product code shape uniformity가 현재 MVP 성공 기준이다.