agentic-engineering-harness 0.6.8 → 0.6.9

package/skills/engineering-workflow/SKILL.md

@@ -44,7 +44,11 @@ Inside a managed Paseo lead, long deterministic workflows must be started detach
 - 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.
+The start command must return promptly with an `operationId`. Report that identifier and the meaningful starting phase to the user, then allow the current lead turn to end if there is no additional semantic work to do. The controller durably registers the initiating managed lead as a completion target. When the operation becomes `SUCCEEDED`, `FAILED` or `CANCELLED`, AEH sends that lead an `[AEH_OPERATION_COMPLETED]` follow-up so it can consume the durable result and finish the original user request.
+
+Do **not** keep the lead alive by repeatedly calling `aeh operation status` or `aeh_operation_status`. Those are explicit diagnostics/manual-recovery surfaces. 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; cancellation also follows the completion-callback path after cleanup.
+
+When `[AEH_OPERATION_COMPLETED]` arrives, treat it as an internal continuation event, not a new user task. Do not create another AUDIT/RUN. Read the existing operation state and cited report/result artifact, then complete the original user-facing response.
 
 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.
 
@@ -89,10 +93,12 @@ Do not invoke sudo or silently install unmanaged host prerequisites.
 
 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.
+3. AEH runs deterministic validators, classifies failures, dispatches the materialized reviewers with that evidence, waits for the complete reviewer barrier, deduplicates findings and calculates quality debt.
+4. The lead is allowed to finish its initiating conversational turn while step 3 continues. It must not infer that the AUDIT ended merely because its own turn ended or because some reviewers have replied.
+5. Only after the controller reaches terminal operation state does it send `[AEH_OPERATION_COMPLETED]` back to the initiating lead. The lead then reads the persisted AuditReport and completes the original user-facing audit response.
+6. Validator failures remain evidence; do not reinterpret them as PASS.
+7. Persisted reports under `.harness/audits/` and `.harness/operations/` are durable input for later remediation and recovery.
+8. AUDIT never implements fixes. A later "fix these" is a new CHANGE using the AuditReport as evidence.
 
 ## Issue-driven CHANGE path
 
@@ -115,6 +121,7 @@ For a CHANGE classified QUICK:
 2. `aeh quick validate <id>`.
 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.
+5. The lead may end its current turn after the detached operation starts; AEH's completion callback will reactivate it after the full run/review/delivery state machine is terminal.
 
 ## SPEC path — OpenSpec authoring
 
@@ -130,17 +137,20 @@ The lead must not write proposal/spec/design/tasks/Gherkin itself.
 
 If OpenSpec cannot express a true product decision without guessing, return `REQUIRES_PRODUCT_DECISION`; otherwise author and validate autonomously.
 
-## Operation observation
+## Operation observation and recovery
+
+Durable operation state remains authoritative, but normal managed-lead continuation is callback-driven rather than polling-driven:
 
-Use durable operation state for progress rather than narrating terminal silence:
+- `[AEH_OPERATION_COMPLETED]` -> normal wake-up/continuation after terminal state;
+- `aeh operation status <id>` -> explicit diagnostic controller status/phase/result/error;
+- `aeh paseo agents --operation <id>` -> manual inspection of real LLM participants and their roles/phases;
+- `aeh operation wait <id>` -> synchronous non-interactive/recovery boundary only.
 
-- `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.
+If a completion callback is known to have failed, inspect the `.harness/operations/<id>.completion.json` sidecar and Paseo traces, then recover by reading the terminal operation/report directly. Do not launch a duplicate operation solely because the callback failed.
 
 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.
 
-Paseo lifecycle/provider/context integration decisions are recorded under `.harness/telemetry/paseo.ndjson`; normal telemetry/OTLP receives the same events when enabled. Use these traces to distinguish SDK-native paths, negotiated fallbacks and intentional public-SDK parity gaps rather than inferring behavior from terminal output.
+Paseo lifecycle/provider/context/integration decisions are recorded under `.harness/telemetry/paseo.ndjson`; normal telemetry/OTLP receives the same events when enabled. Use these traces to distinguish SDK-native paths, reviewer turn-barrier evidence, completion callback delivery, negotiated fallbacks and intentional public-SDK parity gaps rather than inferring behavior from terminal output.
 
 ## Quality convergence and recovery
 
@@ -165,4 +175,4 @@ If the repository is AEH itself or the task changes topology, toolchain, skills,
 
 ## User-facing communication
 
-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.
+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. For a detached operation, one start acknowledgement is normally enough; do not emit a stream of status polls. When the completion callback arrives, provide the actual consolidated result. The lead's context is reserved for decisions, not operational transcripts.

package/skills/paseo-orchestration/SKILL.md

@@ -33,6 +33,21 @@ When the AEH control MCP server (`aeh operation mcp`) is injected, use its tools
 
 These MCP tools call the same persistent detached operation controller/policy code as the CLI. They do not create a controller LLM agent. If the AEH MCP server is not injected, `aeh operation start/status/cancel` and `aeh context guard` are short compatibility surfaces; do not replace them with long synchronous `aeh audit`/`aeh run` from the conversational lead.
 
+## Detached operation completion
+
+Managed AUDIT/RUN operations are callback-driven. When `aeh_operation_start_audit` or `aeh_operation_start_run` succeeds, the deterministic controller durably records the initiating managed lead as the completion target. The lead may end its current conversational turn while reviewers/workers continue independently.
+
+Do **not** repeatedly poll `aeh_operation_status` in the normal path. When the operation reaches `SUCCEEDED`, `FAILED` or `CANCELLED`, AEH sends an `[AEH_OPERATION_COMPLETED]` follow-up to the same lead. Treat that message as an internal continuation of the still-pending user request:
+
+- do not start a duplicate AUDIT/RUN;
+- inspect the existing operation record and the durable report/result artifact named by the callback;
+- finish the original user-facing request from those durable results;
+- use `aeh_operation_status` only for explicit diagnostics, manual inspection, or recovery when callback delivery is known to have failed.
+
+Callback delivery state is persisted separately from the engineering result. A failed callback must never rewrite a successful engineering operation as failed. Relevant integration traces are `harness.paseo.operation.callback.registered`, `.target`, `.sent`, `.failed`, and `.disabled`.
+
+This wake-up mechanism is intentionally independent of Paseo parent/child ownership. AEH reviewers/workers remain top-level agents so a lead rotation does not terminate them.
+
 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.
 
 ## SDK-first lifecycle
@@ -45,6 +60,8 @@ AEH should use the public `@getpaseo/client` surface first for semantic operatio
 - agent subscriptions for event-driven completion, with subscribe-before-refetch race closure;
 - provider snapshot/model/diagnostic APIs for early configuration failures.
 
+For a continued/reused agent turn, capture the last assistant response **before** dispatch. An `idle` snapshot is not sufficient proof that the new turn finished: accept it only after a real active-turn transition or assistant output that differs from the pre-dispatch baseline. Metadata-only subscription updates are not turn activity.
+
 The CLI remains a compatibility/parity-gap surface, not a parallel source of truth. Two intentional external-controller CLI uses currently remain for Paseo 0.3.1:
 
 1. operation workspace creation requiring `--isolation local` plus user-visible `--title`, which the public SDK create contract does not yet expose with equivalent parity;
@@ -60,9 +77,9 @@ Use `aeh paseo agents --operation <id>` (or Paseo's corresponding directory/stat
 
 ## Observability
 
-AEH persists integration decisions under `.harness/telemetry/paseo.ndjson` even when remote OTLP export is disabled. Relevant events include provider preflight, agent snapshot/context source, lifecycle transport, event-driven wait, SDK-to-CLI fallback, intentional workspace CLI use and cleanup CLI use. When normal Harness telemetry is enabled the same events also flow through the standard telemetry/OTLP path.
+AEH persists integration decisions under `.harness/telemetry/paseo.ndjson` even when remote OTLP export is disabled. Relevant events include provider preflight, agent snapshot/context source, lifecycle transport, event-driven wait, resumed-turn baseline, detached-operation callback delivery, SDK-to-CLI fallback, intentional workspace CLI use and cleanup CLI use. When normal Harness telemetry is enabled the same events also flow through the standard telemetry/OTLP path.
 
-A trace should answer: which transport was used, which source supplied state, whether a fallback was intentional or exceptional, why it happened, and which operation/agent/provider/model was affected.
+A trace should answer: which transport was used, which source supplied state, whether a fallback was intentional or exceptional, why it happened, which operation/agent/provider/model was affected, and whether completion notification reached the initiating lead.
 
 ## Lead discipline