Skip to content

PROFILES.md

Latest commit

 

History

History
99 lines (79 loc) · 4.57 KB

PROFILES.md

File metadata and controls

99 lines (79 loc) · 4.57 KB
Raw

Domain Profiles

DomainProfile is the boundary between the runner's architecture and domain-specific knowledge.

The runner owns:

  • phase execution and repair loops
  • evidence arbitration
  • final acceptance as the sole success gate
  • oracle tri-state handling through VerificationReport
  • recovery handoff generation

A profile owns:

  • scaffold paths expected for the domain
  • dependency readiness and the sanctioned setup requirement
  • build oracle command recognition and compile-error parsing
  • serve or behavior probe invocation
  • invariants and deterministic repairs
  • goal capability inference and evidence vocabulary hooks

Profile UltraPlan presets are explicit opt-ins rather than a global default. UAT test0711_bs_004 exposed duplicate setup-step stagnation in preset implementation phases, so qwen27, gemma-family, and unmatched planner models currently default to none. Tier lookup and source recording still use the resolved planner model regardless of whether it came from CLI, executor-model fallback, or a named config preset. Set plan_preset = "profile" in config or pass --plan-preset profile to opt in; explicit CLI always overrides config.

Profiles must not special-case runner control flow. If a new domain needs a new lifecycle shape, extend DomainProfile first and keep the runner calling the trait.

Implementing A Profile

The compact registration workflow and pack-capability boundary are also mapped in docs/dev/extension-catalog.md.

  1. Add a profile module under src/planner/profiles/.
  2. Implement DomainProfile with defaults for anything not applicable.
  3. Add one entry to PROFILE_DESCRIPTORS in src/planner/profile_descriptor.rs.
  4. Keep dependency setup authority-gated and offline-aware.
  5. Return compile errors as CompileError so existing repair targeting, rollback, and recovery handoff paths work unchanged.
  6. Emit behavior evidence through the profile behavior probe, not by bypassing final acceptance.
  7. Add or update one row in the conformance matrix under tests/conformance/. The row must exercise the profile through the normal plan or ultra-plan runner path with fake clients and probe overrides, then pass the reusable interface-contract checkers.
  8. Add focused profile proof tests for domain-specific outputs only after the shared conformance row passes.

Do not add provider abstractions, profile-specific runner branches, or profile-specific repair loops.

External Draft Profiles

An extension root can add a first-class draft profile at profiles/<id>/manifest.toml. Select it with both --extension-root <DIR> and --profile <id>; --doctor lists its exact-byte hash. External supply never grants admission: a manifest that says admitted is forced to draft, has no capability band or pack selection, and is capped at static with profile_not_admitted.

For an admitted embedded manifest-backed profile, Issue #105 permits a single profiles/<admitted-base-id>/overlay.toml. This produces a separate draft effective profile and may only add artifacts, guidance variants, checks, and their local evidence targets. Replacement, removal, weakening, overlay chaining, and base identity mutation are rejected. Use an external draft when testing new declarations; use the compiled workflow above when seeking admission.

Operators and extenders can inspect draft/source labels and the bounded pack lifecycle in the GUI extensions guide.

Development Guardrails

New entry points and execution boundaries must be registered in tests/protection_coverage_audit.rs before they are used. Add or update the declarative protection row for the affected category, including the site predicate, required wrapper/type, and allowlist, then add a conformance pathway row when the boundary can affect runner outcomes.

This rule exists because the instruction 92 parity-hole incidents showed the same failure class recurring at opt-in call sites: compile parsers received display excerpts instead of full command output, verify commands bypassed the shared normalizer, and terminal records were missing on some exit paths. New boundaries must make those bypasses type-impossible or CI-detected.

Definition Of Done

A new profile is not complete until cargo test --test conformance passes with its matrix row. The conformance suite owns the shared runner/profile interface contracts: earned assurance, monotonic rebind, authority symmetry, detect/repair pairing, honest terminal records, oracle tri-state handling, and degradation labeling. New profiles add rows, not bespoke copies of those assertions.