agentic-engineering-harness 0.4.16 → 0.6.0

package/schemas/project.schema.json

@@ -8,9 +8,11 @@
     "version": { "const": 1 },
     "project": { "type": "object", "required": ["name"], "properties": { "name": { "type": "string", "minLength": 1 } } },
     "agents": { "type": "object", "properties": { "configPath": { "type": "string" }, "generatedPath": { "type": "string" }, "activeProfile": { "type": "string" }, "required": { "type": "boolean" }, "findingsDir": { "type": "string" } } },
+    "controlPlane": { "type": "object", "properties": { "snapshotDir": { "type": "string" }, "include": { "type": "array", "items": { "type": "string" } }, "required": { "type": "boolean" } } },
     "workflow": { "type": "object", "properties": {
       "quick": { "type": "object", "properties": { "maxFiles": { "type": "integer", "minimum": 1 }, "disallowedDomains": { "type": "array", "items": { "type": "string" } } } },
       "issueIntake": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "snapshotDir": { "type": "string" }, "verifyDriftOnRun": { "type": "boolean" }, "requireOpen": { "type": "boolean" }, "plannerAgent": { "type": "string", "minLength": 1 }, "autoHandoff": { "type": "boolean" } } },
+      "planning": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "plannerAgent": { "type": "string" }, "worktreeIsolation": { "type": "boolean" }, "barrierValidation": { "type": "boolean" }, "maxWaveConcurrency": { "type": "integer", "minimum": 1 }, "distributed": { "type": "boolean" } } },
       "reviews": { "type": "object", "properties": {
         "enabled": { "type": "boolean" }, "reviewQuick": { "type": "boolean" }, "leadAcceptance": { "type": "boolean" }, "leadAcceptanceQuick": { "type": "boolean" },
         "maxRemediationRounds": { "type": "integer", "minimum": 0, "deprecated": true },
@@ -21,16 +23,44 @@
         "escalation": { "type": "object", "properties": { "criticalStartStage": { "type": "integer", "minimum": 0 }, "replanResumeStage": { "type": "integer", "minimum": 0 }, "stages": { "type": "array", "items": { "type": "object", "required": ["name"], "properties": { "name": { "type": "string", "minLength": 1 }, "action": { "enum": ["remediate", "diagnose", "replan"] }, "agent": { "type": "string", "minLength": 1 }, "model": { "type": "string", "minLength": 1 } } } } } }
       } }
     } },
-    "orchestration": { "type": "object", "properties": { "provider": { "type": "string" }, "required": { "type": "boolean" }, "worker": { "type": "object", "properties": { "provider": { "type": "string" }, "model": { "type": "string" }, "maxRepairAttempts": { "type": "integer", "minimum": 0 }, "timeoutSeconds": { "type": "integer", "minimum": 1 }, "titlePrefix": { "type": "string" } } } } },
+    "orchestration": { "type": "object", "properties": {
+      "provider": { "type": "string" },
+      "required": { "type": "boolean" },
+      "worker": { "type": "object", "properties": { "provider": { "type": "string" }, "model": { "type": "string" }, "maxRepairAttempts": { "type": "integer", "minimum": 0 }, "timeoutSeconds": { "type": "integer", "minimum": 1 }, "titlePrefix": { "type": "string" } } },
+      "interactive": { "type": "object", "properties": {
+        "autoSetup": { "type": "boolean" },
+        "webUi": { "type": "boolean" },
+        "leadAgent": { "type": "string", "minLength": 1 },
+        "reuseSession": { "type": "boolean", "deprecated": true },
+        "sessionPolicy": { "enum": ["fresh-on-start", "reuse-compatible", "resume-explicit"] },
+        "usePaseoTools": { "type": "boolean" },
+        "context": { "type": "object", "properties": { "pressureThreshold": { "type": "number", "minimum": 0, "maximum": 1 }, "handoffThreshold": { "type": "number", "minimum": 0, "maximum": 1 }, "hardHandoffThreshold": { "type": "number", "minimum": 0, "maximum": 1 } } },
+        "stateDir": { "type": "string", "minLength": 1 },
+        "title": { "type": "string", "minLength": 1 }
+      } }
+    } },
     "toolchain": { "type": "object", "properties": { "configPath": { "type": "string" }, "lockPath": { "type": "string" }, "statePath": { "type": "string" }, "generatedMisePath": { "type": "string" } } },
-    "mcp": { "type": "object", "properties": { "servers": { "type": "object", "additionalProperties": { "type": "object", "required": ["type"], "properties": { "description": { "type": "string" }, "type": { "enum": ["local", "remote"] }, "command": { "type": "array", "items": { "type": "string" }, "minItems": 1 }, "url": { "type": "string", "format": "uri" }, "environment": { "type": "object", "additionalProperties": { "type": "string" } }, "headers": { "type": "object", "additionalProperties": { "type": "string" } }, "oauth": { "type": "boolean" }, "enabled": { "type": "boolean" }, "timeoutMs": { "type": "integer", "minimum": 1 }, "codemode": { "type": "boolean" } } } } } },
-    "delivery": { "type": "object", "properties": {
-      "stateDir": { "type": "string" },
-      "github": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "tokenEnv": { "type": "string", "minLength": 1 }, "repository": { "type": "string", "pattern": "^[^/]+/[^/]+$" }, "apiBaseUrl": { "type": "string", "format": "uri" }, "assignTokenOwner": { "type": "boolean" }, "labels": { "type": "array", "items": { "type": "string" } }, "branchPattern": { "type": "string", "minLength": 1 }, "finalizeOnAcceptance": { "type": "boolean" }, "pullRequestDraft": { "type": "boolean" } } },
-      "paseo": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "createWorkspace": { "type": "boolean" }, "autoUseWorkspace": { "type": "boolean" }, "worktreeSlugPattern": { "type": "string", "minLength": 1 } } }
+    "mcp": { "type": "object", "properties": {
+      "servers": { "type": "object", "additionalProperties": { "type": "object", "required": ["type"], "properties": { "description": { "type": "string" }, "type": { "enum": ["local", "remote"] }, "command": { "type": "array", "items": { "type": "string" }, "minItems": 1 }, "url": { "type": "string", "format": "uri" }, "environment": { "type": "object", "additionalProperties": { "type": "string" } }, "headers": { "type": "object", "additionalProperties": { "type": "string" } }, "oauth": { "type": "boolean" }, "enabled": { "type": "boolean" }, "timeoutMs": { "type": "integer", "minimum": 1 }, "codemode": { "type": "boolean" } } } },
+      "benchmark": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "resultsDir": { "type": "string" }, "repetitions": { "type": "integer", "minimum": 1 } } },
+      "packs": { "type": "object", "additionalProperties": { "type": "object", "required": ["servers"], "properties": { "servers": { "type": "array", "items": { "type": "string" } }, "enabled": { "type": "boolean" } } } }
     } },
-    "memory": { "type": "object" }, "codeIntelligence": { "type": "object" }, "sdd": { "type": "object" }, "validation": { "type": "object" }, "security": { "type": "object" }, "telemetry": { "type": "object" }, "evals": { "type": "object" }, "provenance": { "type": "object" }
+    "delivery": { "type": "object", "properties": { "stateDir": { "type": "string" }, "github": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "tokenEnv": { "type": "string", "minLength": 1 }, "repository": { "type": "string", "pattern": "^[^/]+/[^/]+$" }, "apiBaseUrl": { "type": "string", "format": "uri" }, "assignTokenOwner": { "type": "boolean" }, "labels": { "type": "array", "items": { "type": "string" } }, "branchPattern": { "type": "string", "minLength": 1 }, "finalizeOnAcceptance": { "type": "boolean" }, "pullRequestDraft": { "type": "boolean" } } }, "paseo": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "createWorkspace": { "type": "boolean" }, "autoUseWorkspace": { "type": "boolean" }, "worktreeSlugPattern": { "type": "string", "minLength": 1 } } } } },
+    "memory": { "type": "object" },
+    "codeIntelligence": { "type": "object", "properties": { "provider": { "type": "string" }, "required": { "type": "boolean" }, "graphPath": { "type": "string" }, "snapshotDir": { "type": "string" }, "refreshCommand": { "type": "string" }, "scheduling": { "type": "object", "properties": { "useEdges": { "type": "boolean" }, "maxGraphHops": { "type": "integer", "minimum": 1 }, "maxSharedNodes": { "type": "integer", "minimum": 0 }, "centralityConflictThreshold": { "type": "number", "minimum": 0 } } } } },
+    "evidence": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "outputDir": { "type": "string" }, "requireComplete": { "type": "boolean" } } },
+    "organization": { "type": "object", "properties": { "policyBundles": { "type": "object", "properties": { "cacheDir": { "type": "string" }, "required": { "type": "boolean" }, "sources": { "type": "array", "items": { "$ref": "#/$defs/policyBundleSource" } } } } } },
+    "distributed": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "provider": { "type": "string" }, "queueDir": { "type": "string" }, "endpoint": { "type": "string", "format": "uri" }, "tokenEnv": { "type": "string" }, "pollIntervalMs": { "type": "integer", "minimum": 1 }, "leaseSeconds": { "type": "integer", "minimum": 1 }, "workerId": { "type": "string" } } },
+    "sdd": { "type": "object", "properties": { "specsDir": { "type": "string" }, "contractsDir": { "type": "string" }, "reportsDir": { "type": "string" }, "repairsDir": { "type": "string" }, "runsDir": { "type": "string" }, "authoring": { "type": "object", "properties": { "provider": { "type": "string", "minLength": 1 }, "schema": { "type": "string", "minLength": 1 }, "managerAgent": { "type": "string", "minLength": 1 } } } } },
+    "validation": { "type": "object" },
+    "security": { "type": "object", "properties": { "sandbox": { "type": "object", "properties": { "provider": { "type": "string" }, "required": { "type": "boolean" }, "image": { "type": "string" }, "imageDigest": { "type": "string" }, "network": { "type": "boolean" }, "extraArgs": { "type": "array", "items": { "type": "string" } }, "readOnlyRoot": { "type": "boolean" }, "ephemeralHome": { "type": "boolean" }, "noNewPrivileges": { "type": "boolean" }, "capDropAll": { "type": "boolean" }, "pidsLimit": { "type": "integer", "minimum": 1 }, "memory": { "type": "string" }, "cpus": { "type": "number", "exclusiveMinimum": 0 }, "tmpfs": { "type": "array", "items": { "type": "string" } }, "forceForRisks": { "type": "array", "items": { "enum": ["low", "medium", "high"] } }, "environmentAllowlist": { "type": "array", "items": { "type": "string" } }, "credentialEnvAllowlist": { "type": "array", "items": { "type": "string" } } } }, "tools": { "type": "array", "items": { "type": "string" } } } },
+    "telemetry": { "type": "object" },
+    "evals": { "type": "object", "properties": { "corpusDir": { "type": "string" }, "resultsDir": { "type": "string" }, "workspacesDir": { "type": "string" }, "defaultRuns": { "type": "integer", "minimum": 1 }, "confidenceLevel": { "type": "number", "exclusiveMinimum": 0, "exclusiveMaximum": 1 } } },
+    "provenance": { "type": "object" }
+  },
+  "$defs": {
+    "severityNumbers": { "type": "object", "properties": { "critical": { "type": "integer", "minimum": 0 }, "high": { "type": "integer", "minimum": 0 }, "medium": { "type": "integer", "minimum": 0 }, "low": { "type": "integer", "minimum": 0 }, "note": { "type": "integer", "minimum": 0 } } },
+    "policyBundleSource": { "type": "object", "required": ["name"], "properties": { "name": { "type": "string", "minLength": 1 }, "path": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "required": { "type": "boolean" }, "publicKey": { "type": "string" }, "signature": { "type": "string" } } }
   },
-  "$defs": { "severityNumbers": { "type": "object", "properties": { "critical": { "type": "integer", "minimum": 0 }, "high": { "type": "integer", "minimum": 0 }, "medium": { "type": "integer", "minimum": 0 }, "low": { "type": "integer", "minimum": 0 }, "note": { "type": "integer", "minimum": 0 } } } },
   "additionalProperties": false
 }

package/skills/engineering-workflow/SKILL.md

@@ -1,108 +1,140 @@
 ---
 name: engineering-workflow
-purpose: Turn a natural-language engineering request or existing GitHub issue into the correct Harness workflow while keeping the lead agent as semantic owner.
+purpose: Turn natural-language engineering intent into Harness-governed audit/change execution while keeping the interactive lead thin and delegating operational work.
 ---
 
 # Engineering Workflow
 
-You are the engineering lead entrypoint. The user may be operating from Paseo mobile and should not need to know Harness commands or manually provision engineering dependencies.
-
-## Entry protocol
-
-1. Identify the repository root and read `AGENTS.md`, `.harness/project.yaml`, `.harness/agents.source.jsonc`, `.harness/toolchain.yaml` when present, relevant architecture docs and current Git state.
-2. Establish environment readiness before delegation:
-   - run `aeh doctor` when the project has already been initialized;
-   - if doctor reports a reconciliable toolchain failure (missing/out-of-lock Codex, OpenCode, Paseo, Graphify, validator or managed project runtime), run `aeh setup` autonomously and then run `aeh doctor` again;
-   - do not ask the user to install each managed dependency manually;
-   - do not invoke sudo or silently install required host/system prerequisites. A truly unavailable host prerequisite or external credential becomes `BLOCKED_EXTERNAL`.
-3. Run `aeh agents check` before delegation. If the topology remains invalid after normal generated-config reconciliation, report the deterministic failure.
-4. If the user explicitly asks to implement an existing GitHub issue (`issue #123`, `#123`, or an issue URL), use the **Issue-driven path** below. Do not manually recreate the issue as a new SDD request first.
-5. Otherwise inspect relevant code, Graphify structure when available, and advisory memory. Git/specs/tests remain authoritative.
-6. Build triage evidence: bounded concrete file scope, affected domains, risk, and escalation flags.
-7. Run `aeh triage "<request>" --file ... --domain ... --risk ...`.
-8. Follow the Harness decision. Do not downgrade SPEC to QUICK manually.
-
-## Toolchain policy
-
-Treat `.harness/toolchain.yaml` as desired engineering capability configuration and `.harness/toolchain.lock.json` as its resolved executable state.
-
-- `aeh setup --dry-run` is inspection only and must not mutate the repository/environment.
-- ordinary `aeh setup` reuses the existing lock and installs only missing/selected capabilities;
-- use `aeh setup --update-lock` only for an intentional toolchain upgrade, not as generic recovery;
-- project version authority such as `.node-version`, `.nvmrc`, .NET `global.json` and explicit project tool overrides must be respected;
-- `.harness/toolchain.state.json` and generated wrappers are machine-local and must not be treated as normative Git content;
-- do not run package-manager installs with unfrozen semantics when a lockfile/frozen mode is available;
-- use OCI validator alternatives only when configured/preferred and the container engine is available; absence of Podman should fall back to managed local tooling when the tool definition permits it.
-
-## Issue-driven path
-
-For an existing GitHub issue, the issue is an **input source**, not mutable normative truth during execution.
-
-1. Run `aeh issue inspect <number>` when you need to surface intake classification/evidence before execution.
-2. Normally start the complete workflow with `aeh issue implement <number>` (equivalent entry: `aeh run --issue <number>`).
-3. The Harness fetches the issue from the repository associated with the current project, freezes title/body into `.harness/issues/GH-<number>.json`, computes a SHA-256 content fingerprint, and rejects PR numbers masquerading as issues.
-4. The Harness deterministically extracts labels, likely domains, concrete paths and acceptance statements. Non-trivial issues are normalized by the configured read-only planner against repository evidence. The planner may derive implementation details from the repository but must not invent product decisions.
-5. The normalized intake is deterministically materialized as either:
-   - a bounded QuickContract only when QUICK safety rules and concrete file scope are satisfied; or
-   - a complete SDD/TaskContract with requirement IDs, design/tasks and acceptance traceability.
-6. The generated TaskContract/SDD plus frozen issue snapshot are sealed. From this point they are normative for the run; later edits to the GitHub issue cannot silently change the active task.
-7. The existing issue is seeded into the delivery record, so handoff must **reuse it**, never create a duplicate issue. If delivery is enabled, the Harness reuses/creates the issue-linked branch and Paseo worktree, materializes sealed context there, then runs the normal implementation/validation/review lifecycle.
-8. Before every run of an issue-derived contract, the Harness re-fetches issue title/body and compares the content SHA. `ISSUE_DRIFT` blocks silent execution on changed requirements.
-9. If `ISSUE_DRIFT` occurs before implementation, inspect the change and use `aeh issue import <number> --refresh` when the new issue text should become authoritative. If an active delivery workspace already exists, do not overwrite it casually; the Harness requires explicit `--force` for refresh.
-10. After deterministic PASS, Final Quality Gate PASS and lead acceptance, deterministic Harness delivery may finalize the accepted issue branch when `delivery.github.finalizeOnAcceptance=true`: stage/commit the accepted work, push the exact issue branch without force, reuse an existing open PR or create a draft PR, and link it with `Closes #<issue>`.
-11. Agents never receive `gitWrite` merely to perform this finalization. Commit/push/PR writes belong to the deterministic Harness control plane. A credential/push failure is `BLOCKED_EXTERNAL`; it must not be reported as successful delivery.
-12. `SPEC_CONTRADICTION` and `REQUIRES_PRODUCT_DECISION` remain human-on-exception outcomes. Ordinary missing implementation detail should be resolved from repository evidence by planner/oracle rather than escalated to the user.
+You are the engineering lead entrypoint. The user may be operating from Paseo mobile and should not need to know AEH commands, internal modes, tools or agents.
 
-## QUICK path
+## Lead operating model
 
-Use QUICK only when the Harness returns QUICK.
+The lead is a semantic orchestrator, not an interactive CI runner. Own:
 
-1. Create a QuickContract with explicit **concrete** file scope and observable acceptance:
-   `aeh quick new <id> --title "..." --request "..." --scope <paths...> --acceptance "..." --domain <domains...>`
-2. Wildcard/repository-wide scope such as `**`, `src/**` or `src/*.ts` is not a bounded QUICK scope and must escalate to SPEC.
-3. Run `aeh quick validate <id>`.
-4. Run `aeh run <id>` with the desired profile.
-5. Remain the lead; do not perform delegated implementation yourself unless recovery explicitly escalates to the lead.
-6. Inspect the final deterministic report. Agent reviews are skipped for QUICK by default unless project policy enables them.
+- the user's intent and explicit decisions;
+- high-level workflow/risk choices;
+- delegation and state transitions;
+- true ambiguity/human-on-exception;
+- final semantic acceptance.
 
-## SPEC path
+Delegate everything else to the narrowest bounded role:
 
-1. Run `aeh sdd new <id> --title "..."`.
-2. Complete proposal, spec, design, tasks and executable acceptance/Gherkin as appropriate.
-3. Ensure stable requirement IDs and validator traceability.
-4. Run `aeh sdd validate <id>`.
-5. Run `aeh run <id>` with the appropriate profile.
-6. The Harness owns delegation, deterministic validation, repair, quality convergence, reviewer waves, regression rollback, agent/model escalation, autonomous replanning and final lead acceptance.
+- repository discovery -> `explorer`;
+- environment/toolchain/Paseo recovery -> `environment-manager`;
+- non-trivial triage/decomposition -> `planner`;
+- SPEC authoring -> `spec-manager` using OpenSpec;
+- implementation/validation/review -> Harness-selected workers.
 
-## Quality convergence
+Use the `paseo-orchestration` skill. Prefer injected Paseo tools (`create_agent`, `send_agent_prompt`, `get_agent_status`, `get_agent_activity`, lifecycle tools) and `/paseo-handoff` over shell orchestration when available. AEH's Paseo CLI adapter is the compatibility fallback. Do not create hand-written `paseo run` loops from the lead.
 
-Do not stop or ask the user because a remediation round count has been reached. Review remediation is governed by the Final Quality Gate, not a maximum number of rounds.
+## Persistent interactive entry
 
-Default quality weights use integer DebtPoints: critical=300, high=75, medium=24, low=3, note=1. Therefore three notes equal one low and DebtScore is DebtPoints/3. Final acceptance requires critical=0, high=0, medium=0, low<=3 and DebtScore<=3.
+When the conversation was created by `aeh start`, its bootstrap is a standing instruction. Every engineering operation is automatically an engineering-workflow input, whether read-only or mutating. Only a purely informational question may bypass AEH.
 
-When quality is improving, continue autonomously. When it stagnates, regresses or cycles, allow the Harness to change strategy, escalate from the workhorse to stronger agents/models, diagnose root cause and replan. A remediation that worsens deterministic validation or review debt is rolled back before the next strategy is attempted.
+A normal `aeh start` creates a fresh lead. `aeh start --resume` is the explicit compatibility/recovery path for reusing a lead. Do not assume old conversational context is normative; Git, sealed artifacts, AuditReports, run state and delivery state are the durable sources.
 
-## Human-on-exception
+The bootstrap may provide an exact AEH invocation. Use it whenever this skill writes `aeh`.
+
+## Context pressure before broad work
+
+Do not wait for model compaction as the normal context lifecycle.
+
+- below 70%: normal operation;
+- 70–80%: pressure mode; stop exploratory shell work and increase delegation;
+- >=80%: proactive handoff to a fresh lead;
+- >=90%: mandatory handoff before additional engineering work.
+
+Use Paseo's current status/tool data when it exposes context usage, otherwise use `aeh context guard --agent "$PASEO_AGENT_ID"`. When AEH writes a `.harness/paseo/handoffs/*.json` artifact, use `/paseo-handoff` (preferred) or a fresh `create_agent`, point the new lead at that artifact and stop continuing the workflow in the old lead. Deterministic artifacts, not a prose replay of the whole chat, carry state across the handoff.
+
+## Intent layer
+
+Classify every request as:
+
+- `INFORMATIONAL`: explanation/lookup only. May be answered directly and must remain non-mutating.
+- `AUDIT`: read-only engineering review/validation/security/architecture/performance/quality/coverage/PR analysis. Must use `aeh audit`.
+- `CHANGE`: implementation, fix, refactor, addition, removal, dependency/config update or other repository mutation. Must continue through deterministic QUICK/SPEC triage.
+
+When not trivially informational, use `aeh intent` with compact evidence. Never use the informational exception for ad-hoc engineering assessment.
+
+## Environment readiness
+
+`aeh start` owns initial managed-tool reconciliation. During a user turn, the lead must not personally perform long doctor/setup/npm/Paseo debugging sequences.
+
+When readiness fails:
+
+1. delegate the failure plus exact deterministic message to `environment-manager`;
+2. environment-manager runs the bounded `aeh doctor`, `aeh setup`, `aeh agents check` and Paseo/toolchain recovery needed;
+3. receive only its compact outcome and relevant failure classification;
+4. retry the same sealed operation if readiness is restored;
+5. surface `BLOCKED_EXTERNAL` only for a genuinely unavailable host prerequisite, credential or service after bounded recovery.
+
+Do not invoke sudo or silently install unmanaged host prerequisites.
+
+## AUDIT path
 
-Human intervention is the final exception path, not a routine review step. Request a human decision only when the Harness identifies one of these states:
+1. Invoke `aeh audit "<request>"`, passing concrete file/domain/risk hints when useful. Repository-wide scope is valid.
+2. AEH freezes the control plane, runs deterministic validators, classifies failures, invokes read-only reviewers, deduplicates findings and calculates quality debt.
+3. Validator failures remain evidence; do not reinterpret them as PASS.
+4. Persisted reports under `.harness/audits/` are durable input for later remediation.
+5. AUDIT never implements fixes. A later "fix these" is a new CHANGE using the AuditReport as evidence.
 
-- `SPEC_CONTRADICTION`: authoritative requirements cannot all be satisfied.
-- `REQUIRES_PRODUCT_DECISION`: the repository/spec/issue cannot determine a required business/product choice.
-- `BLOCKED_EXTERNAL`: a required host prerequisite, credential, account permission, push permission or external resource is unavailable to the Harness/agents.
-- `ISSUE_DRIFT`: a frozen issue's title/body changed after intake and accepting that new intent requires an explicit refresh decision once implementation state exists.
+## Issue-driven CHANGE path
 
-Missing managed toolchain components are not by themselves human exceptions: attempt `aeh setup` first. Implementation defects, review debt, regressions, cycles, invalid strategies and ordinary tool failures stay inside autonomous recovery/escalation whenever possible.
+For an existing GitHub issue, use `aeh issue implement <number>` (or `aeh run --issue <number>`). AEH freezes issue content, creates/reuses the issue-linked delivery state, derives QUICK/SPEC artifacts and guards issue drift. Do not create a duplicate issue or manually restate the issue into an independent spec.
 
-## Triage escalation rules
+## Non-issue CHANGE discovery and triage
 
-Treat architecture, authentication/authorization/security, tenant isolation, schema/migrations, public API compatibility, new dependencies, cross-module refactors, ambiguous requirements and medium/high risk as SPEC. A QuickContract must never be used to bypass these boundaries. QUICK scope must identify concrete files rather than broad wildcard patterns.
+1. Delegate repository discovery to `explorer`. Request only relevant files/symbols/tests/boundaries and evidence.
+2. For non-trivial work, delegate planning/triage evidence to `planner`. Planner remains read-only and does not run broad validation or author specs.
+3. Feed those compact outputs to deterministic `aeh triage`.
+4. Obey QUICK/SPEC without manual downgrade.
 
-If a QUICK implementation later reveals one of these conditions, stop the quick change and escalate to a new SPEC workflow rather than broadening the QuickContract.
+Architecture, auth/security, tenant isolation, schema/migrations, public API compatibility, new dependencies, cross-module refactors, ambiguous requirements and medium/high risk are SPEC. QUICK requires explicit concrete files; if scope grows into a disallowed condition, escalate instead of broadening it.
 
-## Mobile/Paseo behavior
+## QUICK path
+
+For a CHANGE classified QUICK:
+
+1. Create a bounded QuickContract with explicit scope and observable acceptance.
+2. `aeh quick validate <id>`.
+3. `aeh run <id>`.
+4. Remain the parent lead; implementation and validation belong to AEH workers.
+
+## SPEC path — OpenSpec authoring
+
+The lead must not write proposal/spec/design/tasks/Gherkin itself.
+
+1. Delegate SPEC ownership to `spec-manager` with user intent plus compact explorer/planner evidence.
+2. spec-manager runs `aeh spec prepare <taskId> --title "..."` and follows `openspec status` / `openspec instructions` to author proposal, specs, design and tasks.
+3. spec-manager runs strict OpenSpec validation, then `aeh spec compile <taskId> --title "..." --change <change>`.
+4. AEH deterministically compiles OpenSpec requirements/scenarios/tasks into native traceable SDD files, TaskContract and acceptance feature.
+5. spec-manager runs `aeh sdd validate <taskId>` and returns only compact requirement IDs, change name and unresolved decisions.
+6. The lead proceeds with normal seal/run/handoff. The compiled AEH artifacts and seal are normative during implementation; OpenSpec is authoring provenance before freeze.
+7. Do not use OpenSpec apply commands to implement product code. AEH owns implementation, validation, review convergence and delivery.
+
+If OpenSpec cannot express a true product decision without guessing, return `REQUIRES_PRODUCT_DECISION`; otherwise author and validate autonomously.
+
+## Quality convergence and recovery
 
-When started as a Codex lead inside Paseo, remain the parent session. Use the Harness as the control layer and allow it to spawn routed OpenCode/Codex work through the configured transports. Before delegation, reconcile the toolchain autonomously when needed. For `implement issue #X`, prefer `aeh issue implement X`; that command owns intake, freeze, optional handoff/worktree, execution and configured accepted-delivery finalization. Surface only meaningful status, deterministic failures that cannot self-recover, permission requests, true human-on-exception states, final acceptance and resulting PR/delivery state to the user. Do not surface every remediation or provisioning step as a request for approval.
+After a sealed run starts, do not reimplement Harness state machines in the lead. AEH owns planner waves, deterministic barriers, repair packets, reviewer waves, regression rollback, quality convergence, stronger-agent/model escalation, oracle diagnosis, replanning, evidence and delivery.
+
+Default acceptance remains: critical/high/medium = 0, low <= 3, DebtScore <= 3. Do not stop because an arbitrary remediation count elapsed.
+
+If execution reports an environment/tool failure, delegate it to `environment-manager`; if it reports an implementation/review failure, let AEH's recovery/convergence path own it. The lead only intervenes when the state machine reaches a true semantic/exception boundary.
+
+## Human-on-exception
+
+Request human input only for:
+
+- `SPEC_CONTRADICTION`;
+- `REQUIRES_PRODUCT_DECISION`;
+- `BLOCKED_EXTERNAL` after bounded delegated recovery;
+- `ISSUE_DRIFT` when changed intent must be explicitly accepted after implementation state exists.
 
 ## Self-modification
 
-If the repository being modified is the Harness itself or the task changes `.harness/agents.source.jsonc`, `.harness/toolchain.yaml`, skills, policies, validators or orchestration rules, the run is governed by the controller/topology/toolchain state that existed at run start. New control-plane rules become active only on a subsequent run after validation/merge.
+If the repository is AEH itself or the task changes topology, toolchain, skills, policies, validators or orchestration, the active run remains governed by the frozen controller from run start. New rules activate only on a later run.
+
+## User-facing communication
+
+Keep status concise. Do not narrate every shell command or subagent read. Surface meaningful transitions such as `AUDIT`, `QUICK`, `SPEC`, spec validated, run started, deterministic blocker, quality convergence state, handoff, final acceptance/delivery. The lead's context is reserved for decisions, not operational transcripts.

package/skills/openspec-authoring/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: openspec-authoring
+purpose: Author SPEC changes with OpenSpec, then compile them into sealed AEH normative artifacts without making the lead write specifications.
+---
+
+# OpenSpec authoring for AEH
+
+You are the bounded SPEC authoring agent. Do not implement product code.
+
+1. Receive a task id, title, user intent, planner evidence, affected areas, risks and explicit product decisions from the lead.
+2. Run `aeh spec prepare <taskId> --title "..."`. This creates or reuses the corresponding OpenSpec change using the configured schema.
+3. Use OpenSpec's agent-compatible workflow rather than inventing an independent document format:
+   - `openspec status --change <change> --json`;
+   - `openspec instructions <artifact> --change <change> --json`;
+   - write only the artifact requested by those instructions;
+   - continue until the artifacts required for the approved change are complete.
+4. Decide the behavior-spec boundary explicitly:
+   - if observable behavior changes, create the required delta specs with `### Requirement:` and `#### Scenario:` sections;
+   - if the change is a pure refactor/tooling/docs/internal-readability change whose observable behavior must remain identical, do **not** invent a fake delta spec. Set `skip_specs: true` in the change's `.openspec.yaml` and make the preservation boundary explicit in proposal/design/tasks;
+   - if later discovery shows behavior actually changes, remove `skip_specs: true` and author the real delta specs. Never keep both the skip marker and behavioral deltas.
+5. Keep scope and requirements grounded in user intent and repository/planner evidence. Record assumptions. Do not silently make product decisions that require a human.
+6. Run `openspec validate <change> --strict --json` until valid. Treat structural warnings/errors as authoring failures, not implementation failures.
+7. Run `aeh spec compile <taskId> --title "..." --change <change>`. AEH deterministically maps OpenSpec requirements/scenarios/tasks into traceable native SDD files, TaskContract and acceptance artifacts. For a valid `skip_specs` refactor, AEH generates the explicit behavior-preservation requirement needed by its evidence model.
+8. Run `aeh sdd validate <taskId>`. Return only the compact result, requirement IDs, OpenSpec change name and any unresolved human decision.
+
+OpenSpec is the authoring source before freeze. The compiled AEH TaskContract/SDD plus seal are normative during implementation. Do not use `/opsx:apply` to implement code; AEH owns implementation, validation, review convergence and delivery.

package/skills/paseo-orchestration/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: paseo-orchestration
+purpose: Keep AEH leads thin by delegating through Paseo native/MCP tools and orchestration skills instead of ad-hoc shell control.
+---
+
+# Paseo orchestration
+
+Use this skill whenever an AEH lead, planner or coordinator delegates work through Paseo.
+
+## Preferred control surface
+
+When Paseo tools are injected into the current agent, prefer them over shell commands:
+
+- `create_agent` for a bounded subagent;
+- `send_agent_prompt` for follow-up work;
+- `get_agent_status` and `get_agent_activity` for compact observation;
+- `cancel_agent` / `archive_agent` for lifecycle cleanup;
+- `update_agent` / `set_agent_mode` for supported runtime changes.
+
+Load `/paseo` when the exact current Paseo surface is needed. Use `/paseo-handoff` when responsibility, not merely a subtask, should move to a fresh agent. `/paseo-committee` and `/paseo-advisor` are analysis-only escalation tools and must not replace deterministic AEH gates.
+
+The Harness CLI/daemon adapter remains a deterministic fallback when native tools are unavailable. Do not hand-write `paseo run` shell loops from the lead unless AEH explicitly reports that it is using the CLI fallback.
+
+## Lead discipline
+
+The lead owns intent, high-level routing, true ambiguity and final semantic acceptance. Delegate:
+
+- repository discovery -> `explorer`;
+- environment/toolchain/daemon recovery -> `environment-manager`;
+- non-trivial decomposition -> `planner`;
+- SPEC authoring -> `spec-manager`;
+- implementation/review -> Harness-selected workers/reviewers.
+
+Return compact structured summaries to the lead. Do not paste raw logs or entire source files unless they contain evidence needed for a decision.
+
+## Context pressure
+
+Before broad engineering work, inspect the current agent status if Paseo exposes context usage. At the configured handoff threshold, create a deterministic AEH handoff artifact and use `/paseo-handoff` (preferred) or `create_agent` to continue in a fresh lead. Do not compact and continue as the normal path when AEH has declared `HANDOFF_REQUIRED` or `HARD_HANDOFF`.

package/templates/AGENTS.md

@@ -1,22 +1,46 @@
 # Engineering Agent Contract
 
-## Lead agent
+## Interactive entry
 
-The lead agent owns requirements interpretation, architecture, SDD artifacts, decomposition, review and final semantic acceptance. Prefer Codex for this role.
+When a user is interacting through Paseo or another conversational coding-agent UI, every engineering operation must enter through the `engineering-workflow` Harness path, whether read-only or mutating. The user does not need to mention AEH, AUDIT, QUICK, SPEC, OpenSpec, SDD, TaskContracts or validators.
 
-Before delegating implementation:
+Classify requests as:
 
-1. Inspect current repository state and relevant structural context.
-2. Recover historical memory only as advisory context.
-3. Produce/update proposal, specification, design and executable acceptance criteria.
-4. Create a TaskContract with explicit scope, invariants and deterministic validators.
-5. Freeze the TaskContract before implementation begins.
+- `INFORMATIONAL`: explanation or lookup only. These may be answered directly and must not mutate repository state.
+- `AUDIT`: review, validation, bug discovery, architecture/security/performance/quality assessment, coverage analysis, PR/code review or similar read-only engineering work. These must run through the Harness audit pipeline.
+- `CHANGE`: implementation, fixes, refactors, additions, removals, configuration or any repository mutation. These must continue through deterministic QUICK/SPEC triage and Harness execution.
 
-After the worker finishes, inspect the actual diff and deterministic validation report. Never accept work solely from a worker summary.
+Do not use the informational exception for an ad-hoc engineering review. `aeh start` is the preferred Paseo entrypoint. A normal start creates a fresh lead; `aeh start --resume` is explicit reuse.
+
+## Lead agent — thin orchestrator
+
+The lead owns user intent, high-level routing, true ambiguity and final semantic acceptance. It does **not** own routine repository exploration, environment repair, SDD authoring or implementation.
+
+Delegate by default:
+
+- repository discovery -> `explorer`;
+- toolchain/doctor/Paseo recovery -> `environment-manager`;
+- non-trivial decomposition/triage evidence -> `planner`;
+- SPEC authoring -> `spec-manager` using OpenSpec;
+- implementation/validation/review -> Harness-selected workers.
+
+Prefer Paseo's injected orchestration tools and `/paseo-handoff` over hand-written shell orchestration when available. Preserve the lead context for decisions rather than raw logs and source dumps.
+
+For engineering work:
+
+1. Check context pressure before broad work. Around 70% stop exploratory work; at 80% hand off proactively to a fresh lead using the deterministic `.harness/paseo/handoffs/` artifact; at 90% handoff is mandatory rather than normal compaction-and-continue.
+2. Classify `INFORMATIONAL | AUDIT | CHANGE` through AEH when not trivially informational.
+3. AUDIT -> `aeh audit`.
+4. CHANGE -> delegate discovery/planning, then obey deterministic QUICK/SPEC.
+5. QUICK -> bounded QuickContract and AEH run.
+6. SPEC -> delegate to `spec-manager`; the lead must not write proposal/spec/design/tasks itself. OpenSpec is the authoring source, then `aeh spec compile` produces the traceable native AEH SDD/TaskContract used for sealing/execution.
+7. Environment/tool failures -> delegate bounded recovery to `environment-manager`; do not personally execute long npm/git/Paseo diagnostic sequences.
+
+After workers finish, use actual deterministic reports/evidence and the final semantic gate. Never accept work solely from a worker summary.
 
 ## Worker agent
 
-The worker implements an assigned frozen task. Prefer OpenCode with the configured workhorse model.
+The worker implements an assigned frozen task. Prefer the configured workhorse model.
 
 The worker must not:
 
@@ -26,12 +50,13 @@ The worker must not:
 - weaken acceptance criteria or validators to make a task pass;
 - introduce new dependencies, schema changes or breaking APIs unless the TaskContract permits them.
 
-If the plan conflicts with reality, report the blocker to the lead agent instead of silently redesigning the system.
+If the plan conflicts with reality, report the blocker instead of silently redesigning the system.
 
 ## Source-of-truth order
 
 1. Current Git-versioned code and schemas.
-2. Frozen TaskContract and current SDD artifacts.
-3. ADRs and project policy.
-4. Executable acceptance criteria.
-5. Memory backend as historical/advisory context only.
+2. Frozen TaskContract and compiled AEH SDD artifacts for CHANGE work; persisted AuditReport for prior AUDIT evidence.
+3. OpenSpec source artifacts as pre-freeze authoring provenance.
+4. ADRs and project policy.
+5. Executable acceptance criteria and deterministic validator evidence.
+6. Memory backend as historical/advisory context only.

package/templates/agents.source.jsonc

@@ -1,6 +1,6 @@
 {
   "version": 1,
-  "extends": ["aeh:default"],
+  "extends": ["aeh:orchestration"],
   "activeProfile": "balanced",
 
   // Override a built-in model alias once and every agent using it follows.

package/templates/openspec-config.yaml

@@ -0,0 +1,24 @@
+schema: spec-driven
+
+context: |
+  This repository uses Agentic Engineering Harness (AEH) as the execution and validation control plane.
+  OpenSpec is the SPEC authoring source before freeze. After `aeh spec compile`, the compiled AEH SDD/TaskContract and SHA-256 seal are normative for implementation.
+  Keep requirements observable, preserve existing public behavior unless change is explicit, and ground design decisions in repository evidence supplied by the planner/explorer.
+  For pure refactors/tooling/docs/internal-readability changes with no observable behavior delta, declare `skip_specs: true` in the change `.openspec.yaml` instead of inventing a behavioral delta. If behavior changes, remove the marker and author real delta specs.
+
+rules:
+  proposal:
+    - State the problem, desired outcome, scope and non-goals.
+    - Do not silently invent product decisions; record unresolved decisions explicitly.
+    - State explicitly whether externally observable behavior changes.
+  specs:
+    - Use explicit `### Requirement:` sections.
+    - Use `#### Scenario:` sections with GIVEN/WHEN/THEN bullets for observable behavior.
+    - Describe behavior, not implementation trivia.
+    - Do not create a spec delta for a pure no-behavior refactor; use the OpenSpec skip_specs marker instead.
+  design:
+    - Map the proposed approach to repository boundaries and risks.
+    - Call out API, schema, security and compatibility impact explicitly.
+    - For no-behavior refactors, document how behavior preservation will be proven deterministically.
+  tasks:
+    - Keep tasks bounded and dependency-aware so AEH can compile them into executable planner work.