# v0.4.14 — Selective MCPs, Skills and Issue/Worktree Delivery

v0.4.14 extends the built-in agent pack with a least-privilege MCP catalog, reusable engineering skills, two additional OMO-derived generic roles, and an opt-in deterministic delivery bridge from sealed SDD to GitHub and Paseo.

## Design rules

1. MCPs are capabilities, not authorities. Deterministic validators and sealed normative artifacts still outrank agent/tool output.
2. MCPs are granted per logical agent. A configured server is not automatically exposed to every agent.
3. GitHub writes for the SDD delivery lifecycle are performed by deterministic Harness code, not by an LLM with a broad GitHub MCP token.
4. The local sealed SDD + TaskContract remain normative. The GitHub issue is a delivery mirror by default.
5. One task maps to one resumable delivery record and, when enabled, one issue-linked branch/worktree workspace.

## OMO Slim built-in agent mapping

The default pack was reviewed against the generic OMO Slim agents rather than only Pawra's custom roles.

| OMO capability | Harness decision | Reason |
| --- | --- | --- |
| orchestrator | `lead` | Already the Harness control-plane role. |
| oracle | `oracle` | Same escalation/root-cause niche. |
| librarian | `librarian` | Useful cross-project documentation/research role. |
| explorer | `explorer` | Useful low-cost repository discovery role. |
| designer | `designer` | Added as a read-only UI/UX reviewer with selective browser/docs MCP access. |
| fixer | `quality-implementer` | No duplicate agent; quality remediation already covers the bounded fixer niche. |
| observer | optional overlay | Not default until a project explicitly configures a multimodal/vision model and input contract. |
| council | Harness `councils` abstraction | Kept as topology data rather than duplicating it as a normal logical agent. |

The Pawra-specific `openspec-manager` remains excluded because the Harness owns SDD/QuickContract. `github-manager` is now included, but only as a **read-only coordination/triage agent**; deterministic delivery code performs issue/branch writes.

## MCP inventory and decisions

### Default catalog

The initialized project template defines four servers. Tool schemas are injected only for agents that request the corresponding MCP name.

### `context7` — enabled, selective

Use for current library/framework documentation. Assigned to `librarian` and selected implementers/reviewers where external API/version knowledge is useful.

Why default: high reuse across stacks and a narrower purpose than generic web search.

### `playwright` — enabled, selective

Use for exploratory/stateful browser inspection by `designer` and `e2e-validator`.

The deterministic Playwright validator remains the acceptance authority. MCP browser interaction does not turn manual exploratory output into a gate.

### `github` — enabled server, read-only agent surface

Uses the official GitHub MCP server with scoped toolsets and `GITHUB_READ_ONLY=1`. Only `github-manager` receives the MCP by default.

The server token comes from environment expansion; no GitHub token is stored in topology, generated runtime or delivery state.

### `sentry` — catalogued but disabled

Useful for production-error/trace investigation in projects that use Sentry. It is not universal and should be enabled only when a project has an operational Sentry dependency.

## MCPs deliberately not defaulted

### grep.app / external code search

Pawra uses `grep_app` heavily and OMO Slim often grants it to `librarian`. It remains worth supporting as a project overlay, but the generic Harness does not assume one external code-search service or server implementation.

### codegraph / codemap MCPs

Not a default because Graphify already supplies the Harness structural code graph. A second structural graph would create competing structural truth unless a project deliberately chooses it as an adapter.

### filesystem MCP

Not useful as a generic default: runtimes already have repository/file tools and the Harness has explicit read/write permissions. Adding another filesystem surface increases capability without adding a distinct evidence source.

### security-scanning MCPs

OpenGrep and Trivy already run as deterministic validators. Security MCP wrappers can be useful for exploration, but they should not replace the CLI evidence used by gates.

### database/Kubernetes/cloud-provider MCPs

Potentially valuable project overlays, but too privileged and stack-specific for the universal pack. Prefer read-only modes and narrow toolsets where supported.

## Future MCP experiments

Good candidates for targeted evals rather than immediate defaults:

- production observability: Sentry plus OpenTelemetry-aware investigation;
- issue/project systems: GitLab, Jira/Linear when a repository actually uses them;
- self-hosted web/document retrieval for organizations that require data locality;
- read-only database schema/query MCPs for data-heavy systems;
- Kubernetes/cloud inventory MCPs in read-only mode for ops repositories;
- dependency-source lookup analogous to OMO `clonedeps`, measured against ordinary package/source checkout workflows.

Any candidate should be evaluated on task success, token/context overhead, latency, stale-data risk and permission surface before promotion to the default pack.

## Skills added to the Harness

These are Harness-native, general-purpose policies rather than copies of Pawra/OMO prompt text:

- `verification-planning` — requirement -> deterministic evidence planning.
- `worktree-lifecycle` — isolated task/worktree discipline.
- `routing-normalizer` — bounded delegation-task normalization.
- `recovery-classifier` — canonical failure taxonomy and recovery selection.
- `acceptance-traceability` — criterion -> implementation -> executable evidence.
- `finding-dedup` — normalize/consolidate reviewer findings.
- `prompt-drift-audit` — topology/prompt/skill/generated-runtime consistency.
- `simplify` — reduce accidental complexity without changing observable behavior.
- `github-delivery-lifecycle` — safe issue-linked branch/worktree delivery rules.

### OMO skills not duplicated directly

- `worktrees` maps to `worktree-lifecycle`.
- `verification-planning` maps directly to the Harness-native version.
- `simplify` maps directly to the Harness-native version.
- `codemap` is largely covered by Graphify.
- `clonedeps` remains an experiment candidate rather than a default requirement.
- `deepwork` is not a core policy because the Harness already owns planning/waves/convergence and should not stack a second orchestration doctrine.
- reflection-style skills overlap the eval/review/convergence loop; add only if eval evidence shows a gap.

Framework-specific Pawra skills (EF Core, Expo, Storybook, etc.) remain project overlays.

## Per-agent MCP projection

`AgentDefinition.mcps` now affects runtime configuration. For OpenCode direct/Podman execution the Harness builds an `OPENCODE_CONFIG_CONTENT` that:

- includes only MCP server definitions selected by the logical agent;
- explicitly disables configured-but-unselected MCP tool namespaces;
- keeps existing file/shell/network/skill permissions;
- allows project/host-supplied MCP names when the topology assigns a name not present in the Harness catalog.

This prevents a large GitHub/browser MCP schema from entering every worker context.

## SDD -> GitHub -> Paseo delivery

Delivery is disabled by default.

```yaml
delivery:
  stateDir: .harness/delivery
  github:
    enabled: true
    tokenEnv: GH_TOKEN
    assignTokenOwner: true
    labels: []
    branchPattern: feature/gh-{issue}-{slug}
  paseo:
    enabled: true
    createWorkspace: true
    autoUseWorkspace: true
    worktreeSlugPattern: gh-{issue}-{slug}
```

### Lifecycle

1. `aeh sdd new CHANGE-123 --title "..."`
   - captures the current Git branch into `TaskContract.git.originatingBranch` when available;
   - creates only local SDD/TaskContract artifacts; no remote writes.
2. complete the proposal/spec/design/tasks/Gherkin and TaskContract;
3. `aeh sdd validate CHANGE-123`;
4. `aeh seal CHANGE-123`;
5. `aeh sdd handoff CHANGE-123`;
   - rejects incomplete traceability;
   - rejects unresolved template `TODO` markers;
   - verifies the seal when `validation.requireSeal` is enabled;
   - reads the GitHub token from environment only;
   - creates one GitHub issue and persists its ID immediately;
   - creates `feature/gh-<issue>-<slug>` from the captured originating branch;
   - creates a Paseo `worktree` workspace using `checkout-branch`;
   - persists `.harness/delivery/<task>.json` after each successful phase.
6. `aeh run CHANGE-123`
   - when `delivery.paseo.autoUseWorkspace` is enabled, all Paseo implementation/review/repair sessions use `--workspace <id>` for that delivery record.

## Resumability

The delivery record is a small state machine:

```text
initialized
  -> issue-created
  -> branch-created
  -> workspace-created
  -> ready
```

Remote writes are checkpointed. If a later step fails, rerunning `aeh sdd handoff` reuses recorded issue/branch state instead of intentionally creating duplicates.

No credential is serialized into this record.

## Source-of-truth rule

Unlike Pawra's current OpenSpec workflow, v0.4.14 does **not** promote the GitHub issue to normative truth. The issue body explicitly says it is a delivery mirror. This preserves the Harness trust hierarchy:

```text
sealed local SDD/TaskContract > issue mirror > agent memory/summaries
```

A project that wants issue-canonical semantics should implement that as an explicit project/organization policy rather than silently changing the generic default.

## Paseo workspace semantics

For an issue-backed branch the Harness uses Paseo's worktree workspace mode and checkout-existing-branch flow. The resulting workspace ID is persisted and reused by worker and routed-agent Paseo launches.

This keeps one task isolated from the request-time checkout and prevents implementation/review/repair from drifting across unrelated working trees.

## Security notes

- GitHub delivery token: environment only; never written to config/state/generated topology.
- GitHub MCP: read-only by default and assigned only to `github-manager`.
- GitHub delivery writes: deterministic REST code, not LLM MCP calls.
- branch base: captured originating branch; never guessed from a later checkout when available.
- no force-push/rebase/amend is part of delivery recovery.
- MCPs remain optional capabilities and do not bypass deterministic acceptance gates.
