agentic-engineering-harness 0.8.1 → 0.8.2

package/docs/ARCHITECTURE.md

@@ -14,6 +14,37 @@ Paseo is the reference adapter. It owns process/session/worktree/mobile control,
 
 A lead agent (reference: Codex) owns requirement interpretation, architecture, SDD and review.
 
+Conversational intent is a separate routing boundary. For a managed
+conversation, the lead is the only natural-language semantic authority. It
+translates each human turn, including negation, referents and follow-ups, into
+a compact, versioned `IntentDecisionV1`; the controller never reclassifies the
+original sentence after that decision.
+
+```text
+human turn -> Paseo lead -> IntentDecisionV1 -> selected AEH route
+                                  |                  |
+                                  |                  +-> informational / audit / change / run / status / cancel
+                                  v
+                    durable userTurnId, outcome, referents, constraints
+```
+
+The decision is descriptive, not a permission grant. Its contract contains
+`version`, `source` (`lead-semantic`, `explicit-cli` or
+`heuristic-fallback`), optional `userTurnId`, `intent`, compact
+`requestedOutcome`, effect booleans, optional continuation references,
+constraints, confidence and resolution state. AEH validates only this typed
+contract and its internal effect invariants. Unknown policy claims such as
+`skipValidation`, `allowNetwork`, `gitWrite` or `bypassProvenance` are rejected
+by strict schema validation.
+
+Explanatory repository questions use a bounded read-only context answer and do
+not create lifecycle state. Audit, change and run routes enter their existing
+deterministic contracts. The controller remains the authority for TaskContract,
+SDD/seal, scope, capabilities, permissions, validators, evidence, lifecycle,
+provenance and delivery. The retained `classifyEngineeringIntentHeuristic`
+surface is diagnostic/evaluation/fallback infrastructure only; it cannot veto a
+lead-selected route.
+
 ### 3. Implementation workers
 
 Workers (reference: OpenCode + cost-efficient model) implement frozen, scoped tasks. They have no authority to redefine acceptance.
@@ -80,6 +111,15 @@ The deterministic harness evaluates build/type/lint/tests, scope, immutable file
 
 `ContextBudgetGateway` is the single controller-owned path for bounded agent context. It retrieves, classifies, selects, deterministically projects, budgets, selectively compresses and delivers a versioned `ContextEnvelope`. Required `VERBATIM` content is never lossy-compressed or character-truncated. Raw evidence remains in an AEH artifact and is available only through an operation/agent-authorized retrieval gateway.
 
+Context capability requirements are scoped to the selected execution contract:
+each capability is `REQUIRED`, `OPTIONAL` or `FORBIDDEN`. Runtime and transport
+registries describe actual MCP projection surfaces independently of runtime
+names. The resolved capability object is reused for pre-materialization
+readiness, MCP injection, prompt policy and diagnostics. The coordinator and
+operation supervisor forbid repository/semantic/raw context by default, so a
+global project requirement cannot leak Serena or raw retrieval into the
+supervisory control plane.
+
 ```text
 Graphify  -> macro structural topology and advisory dependency/community signals
 Serena    -> micro semantic repository retrieval (symbol, overview, references)

package/docs/CONTEXT_EFFICIENCY.md

@@ -13,10 +13,19 @@ envelope, agent charter, frozen skills, normative contract/seal/source,
 assignment, operation projection, RepoMap, advisory memory and evidence
 references. Normative fragments remain byte-for-byte `VERBATIM`; the charter is
 not used as a single catch-all fragment. RepoMap construction is skipped when
-`context.repositoryMap.enabled` is false. Transport capabilities are carried
+the selected execution contract forbids it. Transport capabilities are carried
 into preparation so a direct Codex or hardened Podman turn never advertises a
 retrieval tool it cannot expose.
 
+Context requirements are explicit per agent: `REQUIRED`, `OPTIONAL` or
+`FORBIDDEN` for repository-map, semantic retrieval, raw retrieval and
+compression. Project-level `semanticRetrieval.required: true` is therefore
+scoped by the routed execution contract. Coordinators/supervisors default to
+`FORBIDDEN` for repository and raw semantic context; reviewers and workers may
+require Serena when their runtime/transport can actually project it. The same
+resolved capability result controls readiness, MCP injection, prompt policy
+and degradation diagnostics.
+
 ## Preservation classes
 
 - `VERBATIM`: exact normative requirements, contracts, schemas, hashes, anchors and critical diagnostics. It cannot be lossy-compressed.
@@ -43,6 +52,13 @@ Envelopes carry operation, agent, phase, budget, fragment projections, allowed r
 
 ## Runtime and troubleshooting
 
-Run `aeh doctor` after `aeh init --setup`. Context readiness reports the gateway, estimator, retrieval gateway, Serena and Headroom independently. A missing mandatory provider is a deterministic readiness failure; AEH does not silently fall back to bulk repository reads or unoptimized compression. Fix it with `aeh setup --update-lock` and rerun doctor. `--help`, `--version` and status inspection do not install tools.
+Run `aeh doctor` after `aeh init --setup`. Doctor reports the gateway,
+estimator, retrieval gateway, Serena and Headroom independently. Operation
+readiness is evaluated again after routing, against the concrete runtime and
+transport; a project-level required provider does not block a role whose
+contract forbids or does not require that capability. A required capability
+for a selected worker/reviewer fails closed before materialization; an
+optional capability records an explicit bounded fallback. `--help`,
+`--version` and status inspection do not install tools.
 
 Context telemetry emits numeric/hash-only events including `harness.context.prepare`, `project`, `compress`, `deliver` and `operation_summary`. It intentionally does not emit prompt bodies. Evaluation should compare baseline/observe and optimized/enforce with the same task, repository, model and provider, and report cost per successful operation rather than tokens removed alone.

package/docs/EVALS.md

@@ -26,3 +26,15 @@ Primary metrics:
 - elapsed time.
 
 Production bugs should be converted into permanent regression/eval cases when practical.
+
+## Semantic routing corpus
+
+`evals/corpus/intent-routing.json` is a separate lead-semantic evaluation
+corpus. It includes Spanish and English prompts, negation, mixed requests,
+finding referents, constrained follow-ups, status/cancel, prepared-run
+continuation and adversarial policy wording. Each case records an expected
+semantic route and a compact scripted `IntentDecisionV1` fixture. The mandatory
+`tests/intentRoutingCorpus.test.ts` validates the structured route/effect
+contract without invoking the heuristic classifier. A model-backed eval lane
+may compare a configured lead's decision against the prompt labels without
+making external inference a requirement of ordinary pull-request CI.

package/docs/OPERATION_SUPERVISION.md

@@ -27,6 +27,14 @@ The lead owns user intent, priorities, cross-operation dependencies, true except
 
 The operation supervisor owns semantic coordination and consolidation for one operation. It may merge semantically duplicate findings, identify conflicts and request bounded follow-up, but it cannot overrule deterministic state, validation or normative artifacts.
 
+The supervisor charter is coordination-only. Its execution contract forbids
+repository-map, Serena semantic retrieval and raw artifact retrieval, even when
+the project globally configures semantic retrieval as required. Reviewers and
+workers receive those capabilities only when their own runtime/transport
+contract resolves them as available. A capability failure is rejected before
+the candidate agent is materialized; optional capabilities produce an explicit
+degradation rather than an unmarked policy change.
+
 The controller owns lifecycle, stage transitions, participant state, seals, validators, rollback, quality gates, delivery and terminalization. `OperationRecord` is the durable source of lifecycle truth.
 
 ## OperationRecord v2
@@ -94,6 +102,12 @@ A stall targets the operation supervisor first. Missing/busy/unreachable supervi
 
 Healthy non-terminal progress wakes are internal. They should not generate chat noise.
 
+The conversational lead also has a bounded informational path. A request such
+as “explain how validation works” is answered from a small read-only repository
+context and creates no OperationRecord, TaskContract, reviewer, report or
+delivery artifact. A request to find defects, assess safety/correctness or
+report problems remains an AUDIT and follows the supervised lifecycle.
+
 ## Supervisor context generations
 
 Supervisors are proactively replaced rather than compacted as their canonical Paseo context approaches the configured handoff threshold.

package/docs/PASEO.md

@@ -43,6 +43,28 @@ aeh paseo agents --operation <operation-id> --phase review
 
 Synchronous `aeh audit` / `aeh run` remain valid compatibility entrypoints for non-interactive automation.
 
+The conversational lead is the semantic authority for translating each human
+turn into a typed, versioned `IntentDecisionV1`. It resolves the requested
+outcome, negation, referents, constraints and follow-ups, then selects the
+corresponding route. AEH does not re-interpret the original sentence after
+that decision. The deterministic controller validates only the structured
+decision and remains authoritative for contracts, capabilities, permissions,
+validators, evidence, lifecycle, provenance and delivery.
+
+Each decision is bound to the originating `userTurnId` when available and is
+stored with the operation's durable intent state (or the deterministic
+session's compact turn record). This lets lead rotation recover operation and
+finding references without replaying the old model conversation. An unresolved
+mutating referent is rejected by the route contract until the lead resolves it;
+the controller never guesses a target from the human text.
+
+Explanations and orientation use the bounded `aeh_informational_context` tool
+and do not create an operation. Defect discovery, correctness/safety judgments
+and formal review use the AUDIT start tool; mixed requests preserve the lead's
+explicit semantic decision. A heuristic classifier remains available for the
+`aeh intent` diagnostic/evaluation surface and explicitly marked compatibility
+fallbacks only; disagreement cannot veto a lead decision.
+
 ## SDK-first control plane
 
 AEH uses Paseo's published TypeScript client package, `@getpaseo/client`, as the primary control surface for agent creation, follow-up turns, status lookup and directory queries. Paseo currently documents that package as public but **not yet a stable public SDK**, so AEH deliberately resolves the copy bundled with the active `@getpaseo/cli` installation first instead of independently selecting a client version.
@@ -92,15 +114,27 @@ command: <exact Node executable>
 args: [<exact dist/main.js>, operation, mcp]
 ```
 
-Only four MCP tools are preapproved:
+The control MCP is preapproved only for these bounded tools:
 
 ```text
+aeh_informational_context
 aeh_operation_start_audit
 aeh_operation_start_run
+aeh_operation_start_change
+aeh_operation_digest
 aeh_operation_status
+aeh_operation_ack
+aeh_operation_portfolio
 aeh_operation_cancel
+aeh_context_status
 ```
 
+`aeh_informational_context` is read-only and accepts a lead-produced
+`IntentDecisionV1` whose route is INFORMATIONAL. AEH validates the decision's
+effects without scanning the human request. The lead is never given Serena through this control surface;
+Serena is projected only to a routed worker/reviewer whose resolved capability
+contract permits it.
+
 Paseo's `toolPolicy.preapproved` is scoped to those exact MCP server/tool identities; native shell/edit tools are not broadened by this configuration. If the AEH invocation cannot be parsed as a safe command vector, MCP injection is skipped rather than evaluating shell syntax, and the short `aeh operation ...` CLI surface remains the fallback.
 
 The lead bootstrap version is incremented when this managed-session contract changes, so explicit resume cannot silently reuse an older lead that lacks the current operation-control surface.

package/docs/VALIDATION.md

@@ -2,6 +2,14 @@
 
 LLM output is an untrusted proposal. Acceptance is based on executable evidence.
 
+## User-facing evidence discipline
+
+Operation completion messages distinguish durable operation results, audit or
+validation reports, control-plane context and inference. A failed or blocked
+operation with no result artifact, AuditReport or findings is not evidence that
+the repository was inspected. The lead must state the blocker and keep any
+pre-existing context separate from operation-produced claims.
+
 ## Capability registry
 
 The normative unit of validation is a capability. TaskContracts should prefer:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentic-engineering-harness",
-  "version": "0.8.1",
+  "version": "0.8.2",
   "description": "OSS-first engineering harness for deterministic, spec-driven, issue-driven, audit-governed and orchestration-first multi-agent software delivery.",
   "type": "module",
   "bin": {

package/presets/agents/default.jsonc

@@ -3,15 +3,15 @@
   "activeProfile": "balanced",
   "skillRoots": [".harness/skills", ".agents/skills", ".opencode/skills"],
   "runtimes": {
-    "codex": { "adapter": "codex", "paseoProvider": "codex", "command": "codex", "capabilities": { "nativeAgent": false, "nativeAgentViaPaseo": false, "modelSelection": true, "variantSelection": true, "sessions": true } },
-    "opencode": { "adapter": "opencode", "paseoProvider": "opencode", "command": "opencode", "capabilities": { "nativeAgent": true, "nativeAgentViaPaseo": false, "modelSelection": true, "variantSelection": true, "sessions": true, "structuredOutput": true } }
+    "codex": { "adapter": "codex", "paseoProvider": "codex", "command": "codex", "capabilities": { "nativeAgent": false, "nativeAgentViaPaseo": false, "modelSelection": true, "variantSelection": true, "sessions": true, "mcp": true, "stdioMcp": true, "localMcp": true, "nativeToolProjection": true } },
+    "opencode": { "adapter": "opencode", "paseoProvider": "opencode", "command": "opencode", "capabilities": { "nativeAgent": true, "nativeAgentViaPaseo": false, "modelSelection": true, "variantSelection": true, "sessions": true, "structuredOutput": true, "mcp": true, "stdioMcp": true, "localMcp": true, "runtimeConfigInjection": true, "nativeToolProjection": true } }
   },
   "models": {
     "brain": { "runtime": "codex", "provider": "openai", "model": "gpt-5.6-luna", "variant": "max" },
     "workhorse": { "runtime": "opencode", "provider": "opencode-go", "model": "deepseek-v4-flash" }
   },
   "agents": {
-    "lead": { "role": "orchestrator", "domains": ["*"], "description": "Own intent, decomposition, dependency ordering, risk decisions and final semantic acceptance. Delegate repository work to the narrowest specialist; do not perform implementation edits. Preserve sealed requirements and use human-on-exception only when the answer cannot be derived from repository evidence or normative artifacts.", "execution": { "model": "@brain" }, "skills": ["engineering-workflow", "lead-engineer", "verification-planning", "worktree-lifecycle"], "permissions": { "read": "allow", "write": "deny", "shell": "allow", "network": "ask", "delegate": "allow", "review": "allow", "validate": "deny", "gitWrite": "deny" }, "outputContract": "orchestrator" },
+    "lead": { "role": "orchestrator", "domains": ["*"], "description": "Own intent, decomposition, dependency ordering, risk decisions and final semantic acceptance. Delegate repository work to the narrowest specialist; do not perform implementation edits. Preserve sealed requirements and use human-on-exception only when the answer cannot be derived from repository evidence or normative artifacts.", "execution": { "model": "@brain" }, "contextRequirements": { "repositoryMap": "FORBIDDEN", "semanticRetrieval": "FORBIDDEN", "rawRetrieval": "FORBIDDEN" }, "skills": ["engineering-workflow", "lead-engineer", "verification-planning", "worktree-lifecycle"], "permissions": { "read": "allow", "write": "deny", "shell": "allow", "network": "ask", "delegate": "allow", "review": "allow", "validate": "deny", "gitWrite": "deny" }, "outputContract": "orchestrator" },
     "planner": { "role": "planner", "domains": ["*"], "description": "Produce bounded delegation plans from requirements, changed areas, dependencies, findings and validation evidence. Remain read-only, identify parallelizable work, required reviewers and validation gates, and never silently change normative scope.", "execution": { "model": "@brain" }, "skills": ["routing-normalizer", "verification-planning", "acceptance-traceability"], "permissions": { "read": "allow", "write": "deny", "shell": "allow", "network": "deny", "delegate": "allow", "review": "allow", "validate": "deny", "gitWrite": "deny" }, "outputContract": "planner" },
     "oracle": { "role": "escalation", "domains": ["*"], "description": "Diagnose persistent, ambiguous, cycling or cross-cutting failures using repository evidence and sealed requirements. Distinguish implementation defects from spec contradictions, missing product decisions and unavailable external resources. Do not edit files.", "execution": { "model": "@brain" }, "skills": ["recovery-classifier", "simplify"], "permissions": { "read": "allow", "write": "deny", "shell": "allow", "network": "ask", "delegate": "deny", "review": "allow", "validate": "allow", "gitWrite": "deny" }, "outputContract": "recovery" },
     "explorer": { "role": "explorer", "domains": ["*"], "description": "Perform fast repository discovery: locate relevant files, symbols, tests, ownership boundaries and nearby patterns. Return evidence and paths rather than speculative redesigns. Remain read-only.", "execution": { "model": "@workhorse" }, "permissions": { "read": "allow", "write": "deny", "shell": "allow", "network": "deny", "delegate": "deny", "review": "deny", "validate": "deny", "gitWrite": "deny" } },

package/presets/agents/orchestration.jsonc

@@ -22,6 +22,7 @@
       "domains": ["*"],
       "description": "Own operation-local semantic coordination, delegation, consolidation, conflict detection and evidence gaps for exactly one durable AEH operation.",
       "execution": { "model": "@brain" },
+      "contextRequirements": { "repositoryMap": "FORBIDDEN", "semanticRetrieval": "FORBIDDEN", "rawRetrieval": "FORBIDDEN", "compression": "OPTIONAL" },
       "temperature": 0.1,
       "skills": [],
       "permissions": { "read": "allow", "write": "deny", "shell": "allow", "network": "deny", "delegate": "allow", "review": "allow", "validate": "deny", "gitWrite": "deny" },