[Parked pending adopter evidence] Support user-defined execution phases

Summary

Allow callers to define custom execution phases (e.g. plan, critique, reflect, summarize) with their own token budgets and candidate-scope preferences, while keeping the four built-in phases as defaults.

Why this matters

The phase-specific budget is contextweaver's core differentiator, but real agent loops increasingly have more than four phases (planner/critic loops, reflection steps, sub-agent handoffs). Today Phase is a closed str Enum, so a planner step must masquerade as route or answer, inheriting the wrong budget and scope preferences. Opening the phase vocabulary makes the library fit modern agent architectures without forking.

Current evidence

• src/contextweaver/types.py:45-51 — Phase(str, Enum) with exactly four members.
• src/contextweaver/config.py — ContextBudget keyed by these phases.
• src/contextweaver/context/memory_types.py — PHASE_SCOPE_PREFERENCES constants are keyed by the same four phases.
• docs/concepts.md and README document the 4-phase loop as the model.

External context

Agent frameworks (LangGraph nodes, CrewAI task stages, OpenAI Agents SDK handoffs) model arbitrary named stages; a context compiler that only knows four stage names creates an impedance mismatch at integration boundaries.

Proposed implementation

1. Design decision first: either (a) widen APIs to accept Phase | str with a registry of PhaseSpec(name, budget, scope_preferences, kind_priorities), or (b) keep Phase for built-ins and add ContextManager.register_phase(PhaseSpec). Prefer (b): explicit registry, no enum changes.
2. Add PhaseSpec dataclass (budget default, scope preference, optional kind-priority overrides) in config.py or a new small module respecting the ≤300-line rule.
3. Thread custom phases through ContextBudget, context/candidates.py (scope selection), context/build.py, and the build/build_sync signatures (phase: Phase | str).
4. Keep serialization stable: phases serialize as strings already (str Enum), so to_dict paths mostly work; verify schema impact (_schema_gen.py enum handling).
5. CLI: replay --phase should accept registered custom phase names.

AI-agent execution notes

• Inspect first: types.py, config.py, context/candidates.py, context/build.py, context/memory_types.py, _schema_gen.py (enum → JSON Schema), tests/test_manager.py, tests/test_config.py.
• Edge cases: unknown phase name → ConfigError; custom phase with no budget → documented default; PHASE_SCOPE_PREFERENCES fallback for unregistered phases.
• Do not reorder pipeline stages; do not change defaults for the four built-in phases (byte-stable outputs for existing tests).

Acceptance criteria

• A registered custom phase can be passed to build_sync(phase="plan", ...) and receives its own budget and scope preference.
• All existing 4-phase behavior is byte-identical (regression tests pass unchanged).
• Unknown/unregistered phase names raise ConfigError with the available names listed.
• Schemas (schemas/, docs/schemas/v0/) regenerate cleanly and CI schemas-check passes.

Test plan

New tests/test_config.py/tests/test_manager.py cases (registration, budgets, scope fallback, error path); serde round-trip with a custom phase; CLI replay test with a custom phase; full make ci.

Documentation plan

docs/concepts.md Phase section, docs/quickstart.md advanced snippet, AGENTS.md key-types note, CHANGELOG.md.

Migration and compatibility notes

Additive. Built-in enum stays; existing payloads unaffected. If option (a) is chosen instead, audit all Phase isinstance checks before widening — flag any behavioral change in the PR.

Risks and tradeoffs

Widening a closed enum risks stringly-typed sprawl; the registry approach contains it. Custom phases increase the test matrix — document that built-ins remain the supported happy path. Alternative: keep enum closed and document "map your stages onto the four phases" (rejected: real adopter friction).

Suggested labels

product, architecture, developer-experience

Start by reading src/contextweaver/types.py, config.py, context/candidates.py, context/build.py, context/memory_types.py, and _schema_gen.py, then inspect tests/test_manager.py and tests/test_config.py. The design choice between a registry and widened APIs must be resolved first; done means custom phases work without changing built-in outputs, schemas and CLI behavior remain valid, and the listed regression and CI checks pass.