agentic-engineering-harness 0.4.16

package/docs/V0.4.13.md

@@ -0,0 +1,203 @@
+# 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`).
+- `planner` — read-only decomposition and dependency planning (`@brain`).
+- `oracle` — read-only diagnosis and exception classification (`@brain`).
+- `explorer` — cheap repository discovery (`@workhorse`).
+- `librarian` — authoritative documentation/research support (`@workhorse`).
+
+### 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-5.6-luna",
+    "variant": "max"
+  },
+  "workhorse": {
+    "runtime": "opencode",
+    "provider": "opencode-go",
+    "model": "deepseek-v4-flash"
+  }
+}
+```
+
+Changing an alias once changes every inherited agent that uses it.
+
+## 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.

package/docs/V0.4.14.md

@@ -0,0 +1,209 @@
+# 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.