Phase Create — conversational phase registration (ADR-0038)

You turn a phase idea into a registered, advisor-selectable pipeline phase. All
validation, collision-checking, scaffolding, and index rebuilding live in
evolve phases create — your job is to design a good spec, call the command,
and self-correct from its JSON envelope. Never write .evolve/phases/ or
agents/ files directly; the command is the only sanctioned writer.

What a phase IS here

A phase is pure declarative config: a phase.json descriptor (the contract)
plus a persona markdown (the prompt). No executable code. User phases are
always optional:true, kind:"llm", and can never displace the
build→audit→ship spine — the same gates and policies apply to every phase.

Stage 1 — Interview (one question at a time)

Establish, in order:

1. Purpose — one sentence: what does the phase produce? (becomes description)
2. Archetype — plan (decides/scopes before build) or evaluate (verifies
   after build). User phases are never build/control.
3. Goal types — which cycles is it for? categories: subset of
   bugfix | feature | refactor | security | performance | release | docs.
4. Trigger — the objective signal that should make the advisor SELECT it
   (becomes when_to_use, ≤140 chars, and ideally a routing.insert_when
   condition on a real signal like scout.goal_type or build.diff_loc).
5. Report shape — 2–3 required ## section headings for its report
   (classify.require_sections); evaluate phases should opt into a verdict
   (verdict_on_pass: "PASS") and, when they do, into the failure-signal
   contract (require_failure_context: true, ADR-0039): a FAIL/WARN verdict
   sentinel must then carry failure: {class, defects[], evidence_paths[]} —
   the contract gate teaches the exact line and re-dispatches on omission.
6. writes_source? — does it write files into the worktree? (true ⇒ sandbox
   role-gate; most evaluate phases are read-only.)
7. Position — after which phase? (empty = the pre-audit slot.)

Skip questions the user's request already answers. Check the existing catalog
first — evolve phases list (or .evolve/phase-inventory.json) — and tell the
user when an existing phase already covers the need (SELECT over MINT applies
to humans too).

Stage 2 — Synthesize

Draft the phase.json (kebab-case name; optional:true; kind:"llm"; the
metadata trio description / when_to_use / categories; typed
inputs/outputs incl. signals; classify; routing; after) and a persona
markdown. Model the persona on agents/evolve-bug-reproduction.md: frontmatter
(name/description/model/tools/output-format), pipeline-position diagram,
numbered workflow, an Output Contract section naming the required headings,
and an anti-Goodhart note. Show both to the user for approval before
registering.

Stage 3 — Register and self-correct

evolve phases create --spec - <<'SPEC'
{ ...the phase.json... }
SPEC

Pass the persona with --persona <file> (write it to a temp file first;
only one input may use stdin). The command prints ONE JSON envelope to stdout:

• {"ok":true, "artifact":…, "required_sections":[…], "emits_verdict":…, "inventory_rebuilt":true} — done. Report the derived contract to the user
  and note the advisor can SELECT the phase from the next cycle start.
• {"ok":false, "errors":[…], "warnings":[…], "hint":…} (exit 2) — fix every
  listed error in the spec and re-run. At most 3 correction passes; if
  still failing, show the user the errors verbatim and stop.

Treat warnings as advice worth fixing (unknown category, missing
require_sections) but not blockers.

Mint promotion

To persist a good ephemeral mint from a routing plan, pass the mint JSON
(plus a name) instead of a spec:

evolve phases create --mint - <<'MINT'
{"name":"context-condense","prompt":"<persona>","tier":"balanced","writes_source":false}
MINT

The prompt becomes the persona body; tier becomes the model. Flesh out the
generated spec (categories, when_to_use, classify) afterwards via the normal
interview if the mint should become a first-class catalog citizen.

Plugin distribution

A phase created here lands in .evolve/phases/ (project-local). To ship
phases as a plugin bundle: put the same <name>/phase.json dirs in any
directory and add it to the colon-separated paths.phase_roots field in
.evolve/policy.json. Left-most root wins on name collision; built-ins always
win. Details: docs/architecture/phase-plugin-system.md.