# Minimal External Tester Guide This guide is the smallest path to hand Persona Harness to one alpha tester. It checks the product workflow rail surface only. It is not generated app quality certification, eval proof, PH superiority evidence, or AST/linter/enforcement. ## 1. Install Current Candidate Use the tester-facing release-candidate dist-tag: ```bash mkdir -p /tmp/persona-harness-next-check cd /tmp/persona-harness-next-check npm init -y npm install -D persona-harness@next ``` For the current candidate line, `next` is the tester-facing dist-tag. As of 2026-06-30, `next=0.4.0-rc.2`, while `alpha=0.3.9-alpha.8` and `latest=0.3.9-alpha.8`. Record dist-tags before treating default install as current: ```bash npm view persona-harness@next version gitHead dist.shasum --json npm dist-tag ls persona-harness ``` ## 2. Initialize And Check Readiness Use the backend default path: ```bash npx ph init --default backend npx ph doctor ``` Expected: - `.persona/` and `.opencode/` are present. - `ph doctor` reports runtime readiness. - Any WARN should be copied into feedback instead of treated as hidden success. ## 3. Try Idea-First Workflow This path does not require OpenCode, model tokens, A/B eval, or app generation. To reduce command-count friction, copy this whole block first: Current-head caution: the less-script-heavy Windows operator run archived at `/Users/yongtae/Desktop/persona-harness-artifacts/archive/2026-06-24-desktop-persona-runs/less-script-heavy-windows-operator-exec-20260629-203000` was BLOCKED before model. It installed current tarball `0.4.0-rc.1` and init/doctor/bootstrap passed, but Korean preservation failed even with `Get-Content -LiteralPath idea-utf8.txt -Raw -Encoding UTF8 | npx ph workflow draft --stdin`, and this guide's `workflow approve requirements`, `workflow split`, and `workflow next` commands did not match the installed CLI surface in that run. Treat this copy block as needing correction/reverification before reuse for Windows operator validation. Current-head follow-up `e688d39 fix(cli): guard lossy Windows stdin and pack stale dist` addresses the two blockers found there: unrecoverable question-mark-only Korean loss such as `??? ? ? API ???` is rejected before requirements are written, and `prepack: npm run build` prevents stale `dist` in local `npm pack` tarballs. The published `0.4.0-rc.1 @next` package may not include this until a future release, so reverify with the intended package before treating this block as a Windows validation route. Retry note: the current-head `e688d39` Windows operator retry archived at `/Users/yongtae/Desktop/persona-harness-artifacts/archive/2026-06-24-desktop-persona-runs/current-head-e688d39-windows-operator-retry-20260629-204500` confirmed the packaging/current-command-surface and lossy-stdin guards, and the no-token workflow preflight passed. It still did not reach implementation finish: OpenCode hit a malformed duplicated `.persona/policies` path / `external_directory` auto-reject before app output, no `src` or Gradle files were generated, reports stayed template, and finish exited 1. Treat this guide as product-surface preflight only until the implementation entry/context path is reverified. Current-head follow-up `a307ac0 fix(cli): guide README-absent workflow entry` reduces that entry ambiguity for future packages. In README-absent workspaces, `workflow implement`, `workflow continue`, and `plan --implement` now point to repo-relative source-of-truth files: `.persona/project-profile.jsonc`, `.persona/policies/overlay.jsonc`, `.persona/workflow/plan.md`, and the current ticket / requirements source. README-present projects still keep README chunk guidance. This is guidance, not a guarantee that a model will follow through. Retry note: the current-head `a307ac0` Windows operator retry archived at `/Users/yongtae/Desktop/persona-harness-artifacts/archive/2026-06-24-desktop-persona-runs/current-head-a307ac0-windows-operator-retry-20260629-212905/RESULT.md` confirmed preflight progress: command surface, lossy stdin rejection, Korean preservation, no-token workflow/closure preflight, and README-absent guidance were observed. It still did not reach implementation finish. OpenCode read `.persona/policies/overlay.jsonc`, but no app output or `src` / Gradle files were generated; reports were filled and `step-1` was archived anyway, then final finish exited 1 on `STACK_MISMATCH` plus pending `step-2/3/4`. Treat this guide as preflight/product-surface only until report/archive integrity before final finish is reverified. Current-head follow-up `8660ef3 fix(cli): guard ticket archive on closure blockers` keeps `plan --report-filled` as a report marker, not a product-quality gate. `workflow archive ` now refuses to move work to history while non-ticket closure blockers such as `verification-unknown`, `evidence-missing`, `report-coverage-missing`, or stack/verification/report blockers remain. Pending-ticket/history-repair blockers are not archive blockers. If reports are marked filled but no app/evidence/verification exists, archive exits 1 and leaves the backlog/work ticket pending. Retry note: the current-head `8660ef3` Windows operator retry archived at `/Users/yongtae/Desktop/persona-harness-artifacts/archive/2026-06-24-desktop-persona-runs/current-head-8660ef3-windows-operator-retry-20260629-221043/RESULT.md` is INTEGRITY-PASS/PARTIAL. Fresh tarball preflight passed, no-app/no-evidence `workflow archive step-1` exited 1, blockers included `verification-unknown`, `implementation-report-missing`, and `review-report-missing`, and `workflow next` kept `step-1` current. After OpenCode generated a minimal Java/Spring/Gradle skeleton and evidence made verification passed, `step-1` moved to history. Final finish still exited 1 because `step-2`, `step-3`, and `step-4` remained pending, with backend-shape WARNs remaining. Treat this as product usability smoke only, not eval/A-B evidence or generated app quality certification. Current-head follow-up `0784135 fix(cli): block controller repository closure` adds the first scoped hard convention blocker. Existing observer signal `controller.repository-dependency` now becomes closure blocker `architecture-controller-repository-direct-dependency` only for ready Java/Spring service-layer profiles with typed Controller, Repository, file, and dependency evidence. `workflow check`, `workflow closure next --json`, `workflow continue`, `workflow finish implement`, and `workflow archive ` surface/block it consistently and tell the agent to route the Controller through a Service layer. Compliant Controller -> Service -> Repository paths have no architecture blocker. Other backend-shape WARNs remain report-only; this is not broad architecture enforcement or generated app quality certification. GUARD Phase 0-3 package-surface smoke PASS was first recorded from a fresh local tarball before publication. Source HEAD was `7fda771f74008f42082c3a85377262c8fc7ccf5f`; archive: `/Users/yongtae/Desktop/persona-harness-artifacts/archive/2026-06-24-desktop-persona-runs/current-head-7fda771-guard-package-surface-smoke-20260630-001558`. The current installable candidate for those commits is `0.4.0-rc.2` under `@next`. Phase 0 adds opt-in `.persona/harness.jsonc` `enforce.executeVerification: true` direct verification for the supported Java/Spring/Gradle slice: fake agent-written passed evidence fails, PH-run `gradlew test`/JUnit success passes, and JUnit failure blocks. Phase 1 adds `report|warn|block` convention levels while keeping Controller -> Repository as the scoped hard blocker. Phase 2 is warning-only write guard fallback, not hard enforcement. Phase 3 aligns check/closure/continue/write-warning through the convention registry. Current HEAD through `1c304e4` routes closure blockers through structured registry metadata and adds BYO `.persona/conventions/*.yml` ast-grep convention preview for simple YAML metadata; unsafe or low-precision rules must not hard-block, `warn`/`report` remain non-hard-blocking, and missing `sg`/`ast-grep` skips with a warning instead of faking a pass. Current-tarball smoke passed BYO observe/check/closure/continue/finish/archive alignment, including `observe --json` ast-grep findings for `controller.persistence-import`. This is package-surface/product enforcement evidence only, not eval/A-B proof or generated app quality certification. ```powershell mkdir persona-harness-next-check cd persona-harness-next-check npm init -y npm install -D persona-harness@next npx ph init --default backend npx ph doctor npx ph bootstrap backend $idea = @' TODO 웹 서비스 만들래 '@ $idea | npx ph workflow draft --stdin npx ph workflow approve requirements npx ph workflow split .persona/workflow/requirements/backlog.md npx ph workflow next npx ph workflow continue npx ph workflow check ``` On Windows, prefer direct PowerShell or a here-string like the block above for Korean input. A `cmd /c` wrapper can turn Korean text into `?` before Persona Harness receives stdin, so avoid wrapper/automation layers until the direct PowerShell path works. A dedicated CLI wrapper command is deferred until this copy block still proves insufficient for a real tester. If you prefer to step through manually: ```bash printf 'TODO 웹 서비스 만들래\n' | npx ph workflow draft --stdin npx ph workflow approve requirements npx ph workflow split .persona/workflow/requirements/backlog.md npx ph workflow next npx ph workflow continue npx ph workflow check ``` Expected: - `workflow draft --stdin` creates a reviewable requirements draft. - `approve`, `split`, and `next` move the draft into a pending ticket. - `workflow continue` preserves the pending ticket/card/context and next action in the top ticket block. - `workflow check` may WARN because implementation, reports, evidence, or tickets are still pending. That WARN is expected; do not claim completion while it is pending. ## 4. Current Smoke Evidence The no-token idea-first happy-path smoke passed: - input: `TODO 웹 서비스 만들래` - path: `workflow draft --stdin` -> approve -> split -> next -> continue -> check - result: pending ticket/card/context and next action were preserved - expected WARN: implementation/report/ticket work remained pending - no A/B eval, model run, OpenCode implementation, or generated-app quality check was performed Follow-up local/SSH proxy smoke was helpful: - local proxy on a local working-tree tarball and SSH remote on a current local tarball both carried init/doctor/bootstrap -> draft/approve/split/next/continue/check through the no-token idea-first path - `workflow continue` preserved pending `req-1` task-card context, next command/action, archive candidate, and no-completion guidance - the smoke started from local working-tree tarball `b4e3424`; the repo moved to `e562f17` while the smoke was running, so this is not current released or registry package proof Registry-alpha remote was not counted as helpful: - commands passed, but `workflow continue` did not show task-card context - Windows Korean input was mojibake Windows Korean stdin needs an explicit UTF-8 path on legacy PowerShell: - affected commands: `workflow draft --stdin`, `workflow capture --stdin` - root cause: stdin was decoded as UTF-8 only, so Windows cmd/PowerShell/SSH CP949/EUC-KR pipe input could mojibake - `dd1e68f` fix shape: raw buffer decode, UTF-8 first, then Windows Korean candidates (`windows-949`, `euc-kr`, `ks_c_5601-1987`) when replacement characters appear - additional current-head guard `002359c`: if Windows PowerShell 5.x has already read a UTF-8 no-BOM file as ANSI/CP949 and replaced characters with `?`, `workflow draft --stdin` / `workflow capture --stdin` now fail nonzero instead of writing corrupted requirements; already-lossy text cannot be reconstructed by the CLI - current-head guard `e688d39`: pure question-mark replacement text such as `??? ? ? API ???` is also rejected before writing requirements - preferred Windows file-pipe form: ```powershell Get-Content -LiteralPath -Raw -Encoding UTF8 | npx ph workflow draft --stdin Get-Content -LiteralPath -Raw -Encoding UTF8 | npx ph workflow capture --stdin ``` - verification reported by CLI: focused encoding tests, full tests, build, UTF-8/CP949 pipe smoke, and `npm run smoke:product-mvp` - this does not repair already broken artifacts and is product-surface corruption prevention only, not eval/A-B evidence, PH superiority proof, or generated app quality certification Alpha6 registry smoke confirmed the direct Windows PowerShell path on a D-drive workspace: - install: `npm install -D persona-harness@alpha` - installed: `persona-harness@0.3.9-alpha.6` - path: init/default backend -> doctor -> bootstrap -> draft/approve/split/next/continue/check - Korean `TODO 웹 서비스 만들래` was preserved in `workflow next` title and `workflow continue` task-card context - `workflow continue` and `workflow check` showed the post-build closure path in pending/template state - expected WARN remained because reports/evidence/tickets were still pending This closes the alpha6 product workflow surface cycle. It is still product surface smoke only, not eval/model/OpenCode/A-B evidence, PH superiority proof, or generated app quality certification. Related product-surface updates: - `8d3605b test(cli): add product MVP smoke` - `6d29d91 fix(cli): surface ticket context in workflow continue` - `a69583d docs: record product rail smoke updates` - `dd1e68f fix(cli): decode Windows Korean stdin` - `d9dcd0a fix(cli): guide post-build workflow closure` - `df2f15b docs: record alpha6 registry smoke pass` ## 5. Send Feedback Send only what helps the next product step: - whether this helped - whether the difference was unclear - the command where you got stuck - the relevant output lines - your OS, Node/npm versions, and installed Persona Harness version Do not report this guide as proof that Persona Harness improves generated app quality or beats a baseline. It only checks whether the workflow rail is usable enough for a first tester conversation.