# v0.4.13 — Built-in Default Agent Pack

v0.4.13 makes agent topology reusable even when a target repository has never had a `.harness/` directory. The package now ships a built-in `aeh:default` topology and `aeh init` creates a small project overlay that extends it instead of copying the entire agent catalog.

## Why a built-in pack

A project should not have to maintain a large agent JSON file merely to obtain sensible engineering roles. At the same time, defaults must not become immutable framework magic. The topology therefore uses explicit layer composition:

```jsonc
{
  "version": 1,
  "extends": ["aeh:default"],
  "agents": {},
  "routing": [],
  "remove": { "agents": [] }
}
```

The effective topology is deterministic and inspectable through `aeh agents compile`, `aeh agents check`, `aeh agents list`, `aeh agents show`, and `aeh agents route`.

## Default agents

The built-in pack deliberately includes cross-project engineering roles rather than copying every project-specific Pawra role.

### Control and discovery

- `lead` — orchestration, intent ownership and final semantic acceptance (`@brain`, Luna via Codex).
- `planner` — read-only decomposition and dependency planning (`@workhorse`, Muse in shipped `balanced` default; `@brain` only in explicit opt-in `economy`/`maximum-quality`).
- `spec-manager` — formal requirement authoring before freeze (`@workhorse`, Muse in shipped `balanced` default; `@brain` only in explicit opt-in `economy`/`maximum-quality`).
- `oracle` — read-only diagnosis and exception classification (`@brain`).
- `explorer` — cheap repository discovery (`@workhorse`, Muse).
- `librarian` — authoritative documentation/research support (`@workhorse`, Muse).

### Implementers

- `implementation-worker` — generic fallback.
- `backend-implementer`
- `frontend-implementer`
- `data-implementer`
- `mobile-implementer`
- `test-implementer`
- `docs-implementer`
- `ops-implementer`
- `quality-implementer` — focused review-debt remediation.
- `senior-implementer` — stronger `@brain` remediation.

### Reviewers

- `code-quality-reviewer`
- `requirements-reviewer`
- `architecture-reviewer`
- `security-reviewer`
- `api-reviewer`
- `backend-reviewer`
- `frontend-reviewer`
- `data-reviewer`
- `mobile-reviewer`
- `test-reviewer`
- `docs-reviewer`
- `ops-reviewer`

### Validation

- `validator`
- `integration-validator`
- `e2e-validator`

Agents that are tightly coupled to one external workflow are intentionally not universal defaults. In particular, `openspec-manager` is redundant with the Harness SDD/QuickContract normative layer, while `github-manager` would make generic engineering execution depend on a GitHub-specific write surface. Projects may add either as ordinary local agents when appropriate.

## Model defaults

The pack preserves the brain/workhorse hierarchy:

```jsonc
"models": {
  "brain": {
    "runtime": "codex",
    "provider": "openai",
    "model": "gpt-6-luna",
    "variant": "xhigh"
  },
  "workhorse": {
    "runtime": "opencode",
    "provider": "opencode-go",
    "model": "muse-spark-1.3-contributor"
  },
  "structured-assessor": {
    "runtime": "codex",
    "provider": "openai",
    "model": "gpt-6-luna",
    "variant": "xhigh"
  }
}
```

Changing an alias once changes every inherited agent that uses it.

### Partial model-routing migration (owner-approved)

Shipped default is `balanced` (`activeProfile: "balanced"` in
`presets/agents/default.jsonc`). Profile routing is DETERMINISTIC:
`resolveAgentTopology` merges the selected profile overlay onto the base agents
(fail-closed on unknown profile/agent/model) with no model inference.

| Lane | `balanced` (shipped default, owner-approved) |
| --- | --- |
| planner, spec-manager, explorer, librarian, implementer, normal reviewer (`cross-cutting`), repairer | Muse Spark 1.3 Contributor via OpenCode Go (`runtime opencode`, `provider opencode-go`, `model muse-spark-1.3-contributor`) |
| lead, operation-supervisor, high-assurance reviewer (`high-assurance`), difficult-diagnosis escalation (`senior`/`diagnosis`/`replan` stages pin `@brain`), explicit provider fallback | GPT-6 Luna via Codex (`runtime codex`, `provider openai`, `model gpt-6-luna`, `variant xhigh`) |
| semantic-assessor (`@structured-assessor`, fail-closed, never falls back) | GPT-6 Luna via Codex, certified Codex-channel only (see certification note below) |

`economy` and `maximum-quality` are explicit opt-in quality pins, NOT shipped
defaults (their preset descriptions state this explicitly). They intentionally
escalate planning/repair/review lanes to the Luna brain via the same canonical
DETERMINISTIC profile-overlay mechanism — pre-existing quality-escalation
semantics, not hidden defaults:
- `economy`: pins planner, spec-manager, repairer (+ lead, high-assurance
  reviewer) to `@brain`; explorer, librarian, implementer and normal reviewer
  stay on the Muse workhorse.
- `maximum-quality`: pins planner, spec-manager, normal reviewer, repairer (+
  high-assurance reviewer) to `@brain`; explorer, librarian and implementer stay
  on the Muse workhorse.
- The repo-local `certification` profile in `.harness/agents.source.jsonc` is a
  developer-only opt-in and is not shipped in `presets/agents/default.jsonc`.
- Semantic-assessor certification is Codex-channel only (`openai/gpt-6-luna`);
  Muse (`opencode-go/muse-spark-1.3-contributor`) remains uncertified for the
  `semantic-assessment` contract and fails closed with
  `SEMANTIC_ASSESSMENT_UNAVAILABLE`.

High-assurance review is routed canonically, with no role-specific branches: the preset
ships a dedicated `high-assurance-reviewer` (role `Reviewer`, specialization
`high-assurance`, execution `@brain`), the `high-risk-review` routing rule selects
`{ role: Reviewer, specializations: [high-assurance] }`, and every profile
(`economy`, `balanced`, `maximum-quality`) pins that agent to `@brain`. The normal
`default-implementation` rule selects `{ role: Reviewer, specializations: [cross-cutting] }`,
so ordinary tasks keep the workhorse reviewer while high-risk tasks carry both the
workhorse review and the Luna high-assurance review by canonical rule composition.

The canonical Semantic Assessor alias is `@structured-assessor` (kept as a distinct alias
rather than a new `@governor`/`@independent` name to preserve topology references; it
intentionally duplicates the `@brain` Codex Luna identity but remains a separate alias for
independent auditability and fail-closed certification). The superseded OpenCode-routed
Luna pairing (`runtime opencode` + `provider opencode-go` + `model gpt-6-luna`) was removed:
stale topologies fail with `UNSUPPORTED_LEGACY_ASSESSOR_ROUTING` and stale
`orchestration.worker.model` values naming MiMo fail with
`UNSUPPORTED_LEGACY_WORKER_MODEL` (see `src/core/config.ts` and `src/agents/config.ts`).
No silent compat shims exist.

Explicit provider fallback is registry-driven and observable: see
`src/agents/modelFallback.ts` (`workhorseToBrain`, `from`/`to`/`reason`),
`selectModelFallbackExecutionV1` (`src/agents/routing.ts`), the escalation path
(`src/core/run.ts` stageSelections, which tags the frozen selection), and the telemetry
fields `fallbackUsed`/`from`/`to`/`reason` on participant usage
(`participantUsageObservationV2Schema.fallback`, mapped from the canonical V1 observation).
A fallback fires ONLY on an explicit registry match; every other selection records
`fallbackUsed: false`. Semantic assessment itself never falls
back (`fallbackUsed: false` always; `SEMANTIC_ASSESSMENT_UNAVAILABLE` fail-closed).

### Codex-channel Luna is certified (requalification landed 2026-10-04)

GPT-6 Luna via Codex (`openai/gpt-6-luna`) IS certified for the Semantic Assessor
contract at `SCHEMA_BOUND_TOOL_CALL`. The S13 probe matrix had certified gpt-6-luna ONLY
via the OpenCode channel (`opencode-go/gpt-6-luna` 4/4 schema-valid); that evidence never
transferred across channels. The bounded 2026-10-04 round-1 Codex-channel probe
(`docs/evidence/model-routing/codex-structured-output-probe-2026-10-04.json`, frozen)
recorded 0 successful trials across 4 attempts: Paseo 0.9.1 rejects the draft 2020-12
`$schema` dialect at agent creation, Codex `response_format` rejects the judgment `oneOf`
union, then `propertyNames`/record maps, then non-required optional keys.

The CODEX-CHANNEL SEMANTIC ASSESSOR REQUALIFICATION resolved all four barriers without
weakening the contract (strict-mode schema reformulation: `anyOf` union with disjoint
`const` discriminators, strict `{key,value}` entries array for STACK `versions`, required
nullable suggestion, no `$schema` dialect; plus the Codex launch-path model-name repair)
and certified on round 2 (`docs/evidence/model-routing/codex-requalification-2026-10-04.json`,
report sha256 `b9e6b5b1837ffef40e9f59ef3e5aaa3e1931216e20bd4520a540f921a860983f`):
2/2 schema-valid STACK trials through the AEH production path (Paseo SDK, deny-all,
`semantic-assessment` contract), median 15085ms, schema sha256
`f6f206c204a5f13075344c1b8f29401e950d999be11ca29f3ae3e2881b9073a2`, prompt sha256
`3d78118898276107fffdc6500e50c592136cab6f4e3ef5c06ead509e297be936`, recorded in
`semanticStructuredOutputCapabilitiesV1`. Certification is scoped to that schema sha;
any schema change re-opens requalification. Fail-closed behavior is preserved for genuine
errors (capability gate, unavailability, invalid payloads); semantic assessment itself
never falls back. The round-1 probe file stays frozen as the failure record, and the
test-only `semanticPendingRequalificationStubAssessor` was deleted with certification.

### Known limitation: Muse is not certified for semantic assessment

Muse (`opencode-go/muse-spark-1.3-contributor`) is intentionally NOT certified for the
Semantic Assessor contract (`SCHEMA_BOUND_TOOL_CALL` required,
`src/semantic/structuredOutput.ts` + `src/semantic/assessment.ts`). Failed Muse
qualification evidence is preserved out-of-tree and frozen (gitignored):
`/tmp/aeh-muse-probe` and `.harness/evidence/campaigns/model-routing-migration-generation.json`.
Do not reinterpret that evidence as certification.

Requalification path (bounded, evidence-first): run a bounded real-provider probe of Muse
against the canonical `semantic-assessment` JSON Schema through the provider-enforced
structured-output channel (same matrix as `docs/evidence/s13/structured-output-probe.json`),
record trials/failures/medianMs plus the probe report sha256 in
`semanticStructuredOutputCapabilitiesV1`, and only then add
`opencode-go/muse-spark-1.3-contributor` at `SCHEMA_BOUND_TOOL_CALL` or higher. Until that
lands, any topology resolving the assessor to Muse fails closed with
`SEMANTIC_ASSESSMENT_UNAVAILABLE` and no silent fallback is performed.

## Four composition operations

### 1. Use the defaults unchanged

```jsonc
{
  "version": 1,
  "extends": ["aeh:default"]
}
```

### 2. Add an agent

```jsonc
{
  "version": 1,
  "extends": ["aeh:default"],
  "agents": {
    "payments-implementer": {
      "role": "implementer",
      "domains": ["payments"],
      "execution": { "model": "@workhorse" },
      "permissions": {
        "read": "allow",
        "write": "allow",
        "shell": "allow"
      },
      "outputContract": "implementer"
    }
  },
  "routing": [
    {
      "id": "payments",
      "priority": 90,
      "when": { "intent": "implement", "domains": ["payments"] },
      "use": "payments-implementer"
    }
  ]
}
```

### 3. Partially override a default agent/model

Local definitions merge onto inherited definitions, so the project only specifies what changes:

```jsonc
{
  "version": 1,
  "extends": ["aeh:default"],
  "models": {
    "workhorse": { "model": "another-model" }
  },
  "agents": {
    "backend-implementer": {
      "temperature": 0.05,
      "description": "Project-specific backend charter"
    }
  }
}
```

Nested `execution`, `permissions`, runtime `capabilities`, and model `options` are merged rather than replacing the entire parent object. A routing rule with an existing `id` replaces that inherited rule.

### 4. Remove defaults

`remove` accepts minimatch patterns:

```jsonc
{
  "version": 1,
  "extends": ["aeh:default"],
  "remove": {
    "agents": ["mobile-*", "ops-reviewer"],
    "routing": ["mobile"]
  }
}
```

Removing an agent also removes references to it from inherited routing/recovery/council membership. The effective topology is validated after composition, so remaining references to removed models/runtimes or incomplete newly-added definitions still fail deterministically.

## Multiple layers

`extends` is ordered. Later bases override earlier bases, then the current project layer is applied:

```jsonc
{
  "version": 1,
  "extends": [
    "aeh:default",
    "../company/agents.jsonc"
  ]
}
```

Relative extension paths are resolved relative to the file declaring them. Circular extension chains are rejected.

## Agent charters are executable context

The `description` field is now propagated into `AgentExecutionSelection` and prepended to routed agent prompts. It is therefore a concise role charter rather than decorative metadata. Permissions and deterministic output contracts remain the enforcement boundary; the charter explains the specialist's engineering responsibility inside that boundary.

## Self-hosting / dogfooding

The Harness repository itself now contains:

```text
.harness/
├── project.yaml
└── agents.source.jsonc
```

Its topology extends `aeh:default` and adds a repository-specific `harness-reviewer`. Runtime artifacts such as generated topology, runs, reports, findings, seals and provenance remain ignored by Git.

This makes the Harness its own reference project without duplicating the built-in catalog.
