agentic-engineering-harness 0.6.4 → 0.6.5

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "agentic-engineering-harness",
-  "version": "0.6.4",
+  "version": "0.6.5",
   "description": "OSS-first engineering harness for deterministic, spec-driven, issue-driven, audit-governed and orchestration-first multi-agent software delivery.",
   "type": "module",
   "bin": {
-    "engineering-harness": "./dist/entry.js",
-    "aeh": "./dist/entry.js"
+    "engineering-harness": "./dist/main.js",
+    "aeh": "./dist/main.js"
   },
   "files": [
     "dist",
@@ -17,8 +17,10 @@
     "docs"
   ],
   "scripts": {
-    "build": "tsc -p tsconfig.json",
-    "dev": "tsx src/entry.ts",
+    "clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",
+    "build": "npm run clean && tsc -p tsconfig.json",
+    "prepare": "npm run build",
+    "dev": "tsx src/main.ts",
     "test": "vitest run",
     "test:watch": "vitest",
     "typecheck": "tsc -p tsconfig.json --noEmit",

package/skills/engineering-workflow/SKILL.md

@@ -25,16 +25,29 @@ Delegate everything else to the narrowest bounded role:
 - SPEC authoring -> `spec-manager` using OpenSpec;
 - implementation/validation/review -> Harness-selected workers.
 
-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.
+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` for bounded conversational delegation. For deterministic multi-agent AEH workflows, use the first-class operation controller rather than holding the lead inside a long shell process. AEH's Paseo CLI adapter is a compatibility fallback; do not create hand-written `paseo run` loops from the lead.
+
+The AEH operation controller is deterministic infrastructure, not an LLM agent. Do not create a fake controller/session merely to make it visible in Paseo. Real LLM participants are materialized as independent top-level Paseo agents and are correlated through AEH operation/task labels.
 
 ## Persistent interactive entry
 
 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.
 
-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.
+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, operation state, run state and delivery state are the durable sources.
 
 The bootstrap may provide an exact AEH invocation. Use it whenever this skill writes `aeh`.
 
+## Interactive operation boundary
+
+Inside a managed Paseo lead, long deterministic workflows must be started detached:
+
+- audit: `aeh operation start audit "<request>" ...`
+- sealed task execution: `aeh operation start run <taskId> ...`
+
+The start command must return promptly with an `operationId`. Report that identifier and the meaningful phase to the user instead of waiting in an interactive shell. Observe with `aeh operation status <operationId>` and, when useful, `aeh paseo agents --operation <operationId>`. Use `aeh operation wait` only when synchronous waiting is explicitly required by a non-interactive caller or bounded recovery flow. Cancel with `aeh operation cancel <operationId>` when the user requests cancellation.
+
+Direct synchronous commands such as `aeh audit` and `aeh run` remain valid non-interactive/compatibility entrypoints, but a conversational Paseo lead should not use them for a long-running operation when the detached controller is available.
+
 ## Context pressure before broad work
 
 Do not wait for model compaction as the normal context lifecycle.
@@ -44,14 +57,14 @@ Do not wait for model compaction as the normal context lifecycle.
 - >=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.
+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. Detached AEH operations and their top-level worker agents survive lead rotation.
 
 ## 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`.
+- `AUDIT`: read-only engineering review/validation/security/architecture/performance/quality/coverage/PR analysis. Must use the Harness audit path.
 - `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.
@@ -72,15 +85,16 @@ Do not invoke sudo or silently install unmanaged host prerequisites.
 
 ## AUDIT path
 
-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.
+1. From an interactive Paseo lead, invoke `aeh operation start audit "<request>"`, passing concrete file/domain/risk/reviewer hints when useful. Repository-wide scope is valid. A non-interactive caller may use synchronous `aeh audit`.
+2. AEH freezes the control plane and materializes the selected read-only reviewers as visible Paseo agents before deterministic validation begins. The agents remain idle until validator evidence is ready.
+3. AEH runs deterministic validators, classifies failures, dispatches the materialized reviewers with that evidence, deduplicates findings and calculates quality debt.
+4. Validator failures remain evidence; do not reinterpret them as PASS.
+5. Persisted reports under `.harness/audits/` and `.harness/operations/` are durable input for later remediation and recovery.
+6. AUDIT never implements fixes. A later "fix these" is a new CHANGE using the AuditReport as evidence.
 
 ## Issue-driven CHANGE path
 
-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.
+For an existing GitHub issue, use the issue intake flow to freeze and derive the task. `aeh issue implement <number>` remains a synchronous compatibility shortcut. From an interactive lead, once the resulting QuickContract/TaskContract is validated and sealed, execute it through `aeh operation start run <taskId>`. AEH guards issue drift and reuses the issue-linked delivery state. Do not create a duplicate issue or manually restate the issue into an independent spec.
 
 ## Non-issue CHANGE discovery and triage
 
@@ -97,8 +111,8 @@ 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.
+3. From an interactive lead, start `aeh operation start run <id>`; use synchronous `aeh run <id>` only for non-interactive compatibility.
+4. Remain the semantic parent lead; implementation, validation and review belong to AEH workers and the deterministic controller.
 
 ## SPEC path — OpenSpec authoring
 
@@ -109,14 +123,24 @@ The lead must not write proposal/spec/design/tasks/Gherkin itself.
 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.
+6. The lead proceeds with normal seal/handoff, then starts `aeh operation start run <taskId>` when interactive. 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.
 
+## Operation observation
+
+Use durable operation state for progress rather than narrating terminal silence:
+
+- `aeh operation status <id>` -> controller status/phase/result/error;
+- `aeh paseo agents --operation <id>` -> real LLM participants and their roles/phases;
+- `aeh operation wait <id>` -> synchronous boundary only when necessary.
+
+Paseo workspaces used for operation grouping are local orchestration containers and do not imply Git branch/worktree delivery. Delivery workspaces remain a separate isolation decision and take precedence for workers when present.
+
 ## Quality convergence and recovery
 
-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.
+After a sealed operation 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.
 
@@ -133,8 +157,8 @@ Request human input only for:
 
 ## Self-modification
 
-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.
+If the repository is AEH itself or the task changes topology, toolchain, skills, policies, validators or orchestration, the active operation remains governed by the frozen controller from operation start. New rules activate only on a later operation.
 
 ## 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.
+Keep status concise. Do not narrate every shell command or subagent read. Surface meaningful transitions such as operation started, `AUDIT`, `QUICK`, `SPEC`, spec validated, deterministic blocker, quality convergence state, handoff, final acceptance/delivery. A useful update names the operation id and phase and, when relevant, the visible worker roles. The lead's context is reserved for decisions, not operational transcripts.

package/skills/paseo-orchestration/SKILL.md

@@ -9,7 +9,7 @@ Use this skill whenever an AEH lead, planner or coordinator delegates work throu
 
 ## Preferred control surface
 
-When Paseo tools are injected into the current agent, prefer them over shell commands:
+When Paseo tools are injected into the current agent, prefer them over shell commands for bounded conversational delegation:
 
 - `create_agent` for a bounded subagent;
 - `send_agent_prompt` for follow-up work;
@@ -17,9 +17,24 @@ When Paseo tools are injected into the current agent, prefer them over shell com
 - `cancel_agent` / `archive_agent` for lifecycle cleanup;
 - `update_agent` / `set_agent_mode` for supported runtime changes.
 
+When the optional AEH operation MCP server (`aeh operation mcp`) is injected, use its tools for long deterministic Harness workflows:
+
+- `aeh_operation_start_audit`;
+- `aeh_operation_start_run`;
+- `aeh_operation_status`;
+- `aeh_operation_cancel`.
+
+These MCP tools call the same persistent detached operation controller as the CLI. They do not create a controller LLM agent. If the AEH MCP server is not injected, `aeh operation start/status/cancel` is the short non-blocking compatibility surface; do not replace it with a long synchronous `aeh audit`/`aeh run` from the conversational lead.
+
 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.
+The Harness CLI/daemon adapter remains a deterministic compatibility path when native tools/SDK are unavailable. Do not hand-write `paseo run` shell loops from the lead unless AEH explicitly reports that it is using the CLI fallback.
+
+## Visible execution graph
+
+Real planner/reviewer/implementer/oracle sessions should be top-level Paseo agents labeled with their AEH operation/task/role. The deterministic operation controller remains outside the agent graph. Operation-local Paseo workspaces are grouping containers; delivery worktree workspaces are a separate Git-isolation concern.
+
+Use `aeh paseo agents --operation <id>` (or Paseo's corresponding directory/status tools) to observe real participants without scraping terminal output.
 
 ## Lead discipline
 
@@ -35,4 +50,4 @@ Return compact structured summaries to the lead. Do not paste raw logs or entire
 
 ## 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`.
+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. Detached operations and their top-level workers remain valid across lead rotation. Do not compact and continue as the normal path when AEH has declared `HANDOFF_REQUIRED` or `HARD_HANDOFF`.

package/templates/AGENTS.md

@@ -14,7 +14,7 @@ Do not use the informational exception for an ad-hoc engineering review. `aeh st
 
 ## 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.
+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, implementation or a long-running controller shell.
 
 Delegate by default:
 
@@ -24,18 +24,20 @@ Delegate by default:
 - 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.
+Prefer Paseo's injected orchestration tools and `/paseo-handoff` for bounded conversational delegation. Long deterministic AUDIT/RUN workflows use the detached AEH operation controller. The controller is deterministic infrastructure, not an LLM agent; real planner/reviewer/worker sessions appear independently in Paseo and are correlated by AEH operation/task labels.
 
 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`.
+3. Interactive AUDIT -> `aeh operation start audit "<request>"`; use `aeh operation status <id>` and `aeh paseo agents --operation <id>` for progress. Synchronous `aeh audit` remains a non-interactive compatibility path.
 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.
+5. QUICK -> bounded QuickContract; interactive execution -> `aeh operation start run <taskId>`.
+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; interactive execution then uses `aeh operation start run <taskId>`.
 7. Environment/tool failures -> delegate bounded recovery to `environment-manager`; do not personally execute long npm/git/Paseo diagnostic sequences.
 
+Operation-local Paseo workspaces are only UI/execution grouping. They do not imply a Git branch/worktree; delivery isolation remains a separate policy. Detached operations and their top-level agents survive lead context rotation.
+
 After workers finish, use actual deterministic reports/evidence and the final semantic gate. Never accept work solely from a worker summary.
 
 ## Worker agent
@@ -55,7 +57,7 @@ If the plan conflicts with reality, report the blocker instead of silently redes
 ## Source-of-truth order
 
 1. Current Git-versioned code and schemas.
-2. Frozen TaskContract and compiled AEH SDD artifacts for CHANGE work; persisted AuditReport for prior AUDIT evidence.
+2. Frozen TaskContract and compiled AEH SDD artifacts for CHANGE work; persisted AuditReport and operation record 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.