agentic-engineering-harness 0.8.1 → 0.8.3

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.
@@ -41,8 +50,45 @@ Budgets are role- and phase-aware. New projects default to `enforce`; `observe`
 
 Envelopes carry operation, agent, phase, budget, fragment projections, allowed retrieval IDs and a provenance hash. Large bodies are persisted as `.harness/context/<operation>/...raw`; envelopes contain references and compact content, not lifecycle authority.
 
+### Informational fast path
+
+Repository-grounded explanations use the same separation without creating an
+engineering operation. `aeh_informational_context` selects a bounded set of
+repository files and returns claims, summaries, direct repository-relative
+source refs, provenance and payload estimates. It does not write evidence,
+telemetry, operations, contracts or other `.harness` artifacts. Source bodies
+are not placed in `structuredContent` or replayed in `human`. The lead can call
+`aeh_informational_evidence` for one explicit
+`repo://...#sha256=<chunk>&file-sha256=<file>&range=<start>-<end>` reference
+when a summary is insufficient. A later bounded range can be requested by
+adding `&read=<start>-<end>` while retaining the original selected chunk and
+file identity. Retrieval verifies the whole file with a streaming hash and
+the selected chunk, retains only bounded returned bytes, and carries the
+requested excerpt once while structured metadata remains compact. Stale,
+forged, traversal and repository-escape references fail explicitly. Legacy
+range-only refs remain readable but cannot authorize a later range.
+
+Informational defaults are centralized at an 8K target, 12K soft limit and 15K
+exceptional limit, with eight source candidates, a 4KB per-source initial read
+limit and a 20KB total initial read limit. Projection and deduplication run
+before injection. Telemetry names the quantities it can actually measure:
+`rawEvidenceTokens`, `legacyPayloadTokens`, `projectedPayloadTokens`,
+`informationalPayloadTokens` and `duplicatePayloadTokensAvoided`. These are
+deterministic estimates of repository evidence and serialized payloads; they
+are not claims about actual lead-provider token usage. Source-code strings such
+as PASS/FAIL/WARN/security/uncertainty are summarized as implementation text,
+not promoted to verified runtime findings. Typed validation artifacts retain
+their separate authoritative evidence path.
+
 ## 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.3",
   "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" },

package/templates/project.yaml

@@ -202,6 +202,8 @@ context:
     default:
       inputTokens: 16000
     agents:
+      lead:
+        inputTokens: 12000
       explorer:
         inputTokens: 12000
       planner:
@@ -214,6 +216,14 @@ context:
         inputTokens: 14000
       operation-supervisor:
         inputTokens: 1500
+  informational:
+    targetTokens: 8000
+    softLimitTokens: 12000
+    exceptionalTokens: 15000
+    maxSources: 8
+    sourceSummaryTokens: 96
+    maxInitialBytesPerSource: 4000
+    maxInitialBytesTotal: 20000
   repositoryMap:
     enabled: true
     tokenBudget: 2000