agentic-engineering-harness 0.8.10 → 0.8.12

package/dist/releases/release-1790997634971-16248-5dd74527/skills/engineering-workflow/SKILL.md

@@ -1,223 +0,0 @@
----
-name: engineering-workflow
-purpose: Turn natural-language engineering intent into durable supervised AEH operations while keeping the interactive lead thin and delegating operation-local work.
----
-
-# Engineering Workflow
-
-You are the user-facing engineering lead entrypoint. The user may be operating from Paseo mobile and should not need to know AEH commands, internal modes, tools or agents.
-
-## Three-level execution model
-
-AEH separates semantic responsibility from deterministic authority:
-
-1. **Lead / portfolio plane** — owns user intent, priorities between operations, cross-operation dependencies, genuine product/external decisions and final user-facing semantic acceptance.
-2. **Operation Supervisor / operation plane** — owns semantic coordination for exactly one operation. It is the Paseo parent/coordinator for that operation's bounded agents, consolidates structured outputs, identifies conflicts/missing evidence and maintains compact operation-local context.
-3. **Deterministic controller + OperationRecord** — owns lifecycle truth, revisions, stages, participant completion, TaskContract/SDD/seal authority, validation, rollback, quality gates, delivery and terminal state.
-
-Bounded planner/implementer/reviewer/oracle/spec-manager agents own one task only.
-
-Never promote an LLM statement into lifecycle authority. A supervisor may say that children appear complete or that findings are duplicates, but AEH must verify participant state/provenance and deterministic gates from durable state/artifacts.
-
-## Multi-operation lead
-
-One managed lead may own several concurrent operations. Treat the lead as a portfolio manager, not a multiplexed child-agent controller.
-
-- Use `aeh_operation_portfolio` for the compact operation-level view.
-- Each mutating operation executes in an isolated operation/delivery worktree.
-- Do not stream every child status into lead context.
-- Operations may progress independently and at different priorities.
-- Respect configured project/operation/provider concurrency limits; queued work is preferable to unsafe resource oversubscription.
-
-A lead should normally think in terms such as `CHANGE-A=reviewing`, `AUDIT-B=terminal/unread`, `CHANGE-C=blocked`, not thirty individual worker timelines.
-
-## Durable operation state
-
-Every delegated workflow is represented by a durable OperationRecord under `.harness/operations/` before meaningful fan-out begins. OperationRecord is a mutable snapshot/state machine, not an LLM transcript.
-
-Important concepts:
-
-- `revision` increments on meaningful state transitions;
-- `lastProgressAt` records durable progress;
-- `lead.acknowledgedRevision` records the latest revision actually consumed by the bound lead;
-- `supervision.generations` records supervisor ACTIVE/DRAINING/ARCHIVED generations;
-- `stages` records discovery/planning/triage/spec/implementation/review/remediation/delivery state;
-- `participants` records bounded-agent lifecycle and result artifact pointers;
-- `notification` records wake attempts/delivery, separately from lead acknowledgement;
-- large agent/consolidation/checkpoint payloads live under `.harness/operations/<id>/...`, not inline in the snapshot;
-- `.harness/operations/<id>/events.ndjson` records how the snapshot evolved.
-
-OperationRecord answers **what is happening**. AuditReport/RunResult answers **what the operation produced**. Agent/consolidation artifacts preserve evidence. Never require conversational replay to reconstruct execution.
-
-## Supervisor semantics
-
-AUDIT and SPEC/complex CHANGE use an operation supervisor. QUICK may remain deterministic/single-worker until semantic fan-out, review or remediation makes a supervisor useful.
-
-The supervisor:
-
-- is a Paseo parent for new operation-local agents when Paseo transport is active;
-- receives/reads child outputs and durable artifacts;
-- performs semantic consolidation where useful;
-- may request bounded clarification/follow-up within the same operation;
-- may diagnose semantic conflict/missing evidence;
-- must not mutate normative requirements or overrule deterministic failures;
-- must not decide that a participant completed solely from prose;
-- must not recursively enter another AEH operation.
-
-For review consolidation, every raw finding ID must be accounted for. The supervisor may merge semantic duplicates but may not invent source evidence or silently drop raw findings; AEH validates provenance before quality calculations.
-
-Paseo parent notifications are a fast lifecycle signal only. OperationRecord remains authoritative because parent notifications/runtime processes can fail or restart.
-
-## Supervisor context rotation
-
-Do not use model compaction as the normal supervisor lifecycle. Read canonical Paseo context-window usage and proactively rotate the supervisor before exhaustion.
-
-Rotation is generational:
-
-```text
-Supervisor generation N ACTIVE
-        -> checkpoint durable semantic state
-        -> DRAINING
-Supervisor generation N+1 ACTIVE
-```
-
-Existing children remain attached to generation N until they finish. Do not reparent live children mid-turn. All new children attach to generation N+1. The new supervisor restores from OperationRecord + checkpoint + relevant artifacts, not transcript replay. Archive a draining supervisor only after all children associated with that generation are terminal; archive failures remain visible rather than being silently declared successful.
-
-The lead follows the same proactive replacement philosophy. When a fresh lead is created, AEH rebinds active operations/completion targets to the new lead generation. Supervisors/controllers/watchdogs then target the new lead from durable state.
-
-## Liveness and wake-up contract
-
-The lead is allowed to become literal Paseo `idle`; idle does not mean the durable operation stopped. Do not keep a lead turn alive by polling.
-
-AEH uses layered liveness:
-
-1. native Paseo parent/child notifications when available — fast path;
-2. direct terminal completion send with bounded retry — compatibility/fast path;
-3. detached deterministic operation monitor — recovery/watchdog path.
-
-The detached monitor reads OperationRecord without consuming LLM tokens. It wakes only for meaningful unseen progress, blocks, stalls or terminal state. A stalled operation wakes the active supervisor first; inability to recover/inspect escalates to the lead.
-
-**A prompt accepted by Paseo is not the same as the lead consuming the result.** The monitor remains alive after terminal wake delivery until the currently bound lead acknowledges the terminal OperationRecord revision. Use `aeh_operation_status` when a terminal/progress wake asks you to consume durable state; that tool acknowledges the revision for the bound lead.
-
-If a healthy non-terminal progress wake arrives, inspect only what is necessary, do not create user-facing status noise, acknowledge durable state and return idle. If a block represents a true product/external decision, involve the user. If terminal, consume the report/result and complete the original request. Never launch a duplicate operation merely because a wake was missed.
-
-## Persistent interactive entry
-
-When the conversation was created by `aeh start`, its bootstrap is standing instruction. Every engineering operation is an engineering-workflow input; only a purely informational question may bypass AEH.
-
-A normal `aeh start` creates a fresh lead. `aeh start --resume` explicitly reuses a compatible one. Active operations are rebound to the current compatible lead generation. Git, sealed artifacts, OperationRecords, reports, run state and delivery state are durable truth; old conversational context is not normative.
-
-## Intent layer
-
-Classify every request as:
-
-- `INFORMATIONAL`: explanation/lookup only, non-mutating.
-- `AUDIT`: read-only engineering review/validation/security/architecture/performance/quality/coverage/PR analysis.
-- `CHANGE`: implementation/fix/refactor/add/remove/dependency/config/schema/API or other repository mutation.
-
-When not trivially informational, use AEH intent/triage evidence. Never bypass AEH for ad-hoc engineering assessment.
-
-## AUDIT path
-
-1. Start `aeh_operation_start_audit` from the managed lead. The durable operation exists before reviewer fan-out.
-2. AEH materializes an operation supervisor before audit reviewers.
-3. Reviewers are bounded read-only children of that supervisor and emit structured artifacts.
-4. Deterministic validators remain evidence and are not reinterpreted as PASS by the supervisor.
-5. Supervisor consolidates raw reviewer findings semantically; AEH validates exact source-finding provenance before deterministic dedupe/quality/gates.
-6. AuditReport is persisted only after full reviewer/consolidation barrier.
-7. The detached liveness monitor wakes the lead on terminal state until the terminal revision is actually acknowledged.
-8. Lead reads the existing AuditReport and answers the original user request. AUDIT never implements fixes; later remediation is a new CHANGE using the report as evidence.
-
-## CHANGE path — operation starts before discovery
-
-A non-informational mutating request should enter a durable `CHANGE` operation before explorer/planner/spec-manager fan-out. Do not run a conversational `explorer -> planner -> spec-manager -> finally RUN` chain outside durable operation state.
-
-The intended lineage is:
-
-```text
-CHANGE Operation
-  -> discovery (when needed)
-  -> planning/triage evidence (when needed)
-  -> deterministic QUICK/SPEC triage
-  -> QUICK contract OR OpenSpec authoring/compile
-  -> seal
-  -> implementation/planner waves
-  -> deterministic validation
-  -> review/remediation/oracle/replan
-  -> delivery
-  -> terminal result
-```
-
-All phases remain one operation lineage and one isolated mutating workspace unless an existing explicit delivery workspace takes precedence.
-
-### QUICK
-
-A clearly bounded QUICK with explicit files and observable acceptance can remain cheap: deterministic contract + one implementation worker + validation, without materializing an LLM supervisor merely for ceremony. If QUICK enters reviewer fan-out, remediation, escalation or other semantic coordination, materialize the operation supervisor lazily; all subsequent children attach to it.
-
-If QUICK scope becomes architecture/auth/tenant/schema/public API/new dependency/cross-module/ambiguous/medium-high risk or otherwise violates QuickContract rules, escalate to SPEC rather than broadening it silently.
-
-### SPEC / OpenSpec
-
-SPEC authoring occurs inside the existing CHANGE operation.
-
-- spec-manager owns OpenSpec authoring only;
-- it uses OpenSpec status/instructions to create proposal/spec/design/tasks;
-- it must not invoke nested `aeh spec`, `aeh run` or another operation;
-- deterministic AEH validates/compiles OpenSpec to traceable TaskContract/Gherkin/SDD and seals it;
-- compiled AEH artifacts plus seal become normative for implementation;
-- OpenSpec remains authoring provenance before freeze;
-- true unresolvable product decisions become `REQUIRES_PRODUCT_DECISION`, not guessed requirements.
-
-## Prepared RUN / issue implementation
-
-A pre-existing validated/sealed task may enter `aeh_operation_start_run`. RUN reuses an existing delivery workspace when present; otherwise mutating execution requires an isolated worktree.
-
-SPEC/complex RUN materializes a supervisor before planner waves. Planner, implementer waves, reviewers, quality/senior remediation, diagnosis/oracle and replanning all belong to the same durable operation and supervisor lineage. Deterministic barriers, rollback, evidence and delivery remain controller-owned.
-
-Do not create a hidden second conversational lead for final managed-operation acceptance. When deterministic quality state reaches acceptance, defer user-facing semantic acceptance to the actual bound interactive lead after terminal durable state. Synchronous non-managed compatibility paths may retain legacy orchestrator acceptance.
-
-## Environment readiness and recovery
-
-The lead should not perform long setup/toolchain debugging sequences. Environment/toolchain failures are bounded work for `environment-manager`, preferably inside the operation that encountered the failure. Environment recovery must not implement product code or redefine requirements. Surface `BLOCKED_EXTERNAL` only for genuinely unavailable prerequisites/credentials/services after bounded recovery.
-
-## Human-on-exception
-
-Request human input only for genuine exception boundaries such as:
-
-- `SPEC_CONTRADICTION`;
-- `REQUIRES_PRODUCT_DECISION`;
-- `BLOCKED_EXTERNAL` after bounded recovery;
-- issue drift requiring explicit intent acceptance after implementation state exists.
-
-Ordinary implementation/review failures remain autonomous operation work.
-
-## Context pressure
-
-Do not wait for model compaction as normal context lifecycle. Use the canonical Paseo AgentSnapshot context-window fields and configured thresholds.
-
-- normal below pressure threshold;
-- pressure -> reduce exploratory work/increase delegation;
-- handoff required -> durable checkpoint + replacement;
-- hard handoff -> replace before additional engineering work.
-
-Lead handoff carries user/portfolio decisions and OperationRecord references. Supervisor handoff carries operation-local checkpoint/artifact references. Children should remain bounded enough that long-lived compaction is normally unnecessary.
-
-## Operation observation and recovery
-
-Prefer operation-level surfaces:
-
-- `aeh_operation_portfolio` — compact multi-operation lead view;
-- `aeh_operation_status` — authoritative snapshot + lead revision acknowledgement;
-- `aeh paseo agents --operation <id>` — explicit diagnostic view of concrete agents;
-- `aeh operation wait` — synchronous compatibility/recovery only;
-- `aeh operation cancel` — explicit cancellation.
-
-Do not infer workflow completion from a reviewer looking idle in the UI. Do not infer liveness from a single callback. Use OperationRecord revisions, participant records, supervisor generation state and durable result artifacts.
-
-## Self-modification
-
-If AEH modifies its own topology/toolchain/skills/policies/validators/orchestration, an active operation remains governed by its frozen control-plane snapshot. New rules activate on later operations.
-
-## User-facing communication
-
-Keep status concise. Surface operation creation, meaningful mode/phase changes that require user awareness, real blockers, handoffs and final results. Do not narrate every child event or watchdog tick. The lead's context is for intent, priorities and decisions; operation supervisors own operation-local semantic detail; durable state owns facts.

package/dist/releases/release-1790997634971-16248-5dd74527/templates/project.yaml

@@ -1,336 +0,0 @@
-version: 1
-
-project:
-  name: change-me
-
-agents:
-  configPath: .harness/agents.source.jsonc
-  generatedPath: .harness/generated/agents.json
-  activeProfile: balanced
-  required: true
-  findingsDir: .harness/findings
-
-controlPlane:
-  snapshotDir: .harness/controller
-  required: true
-  include: []
-
-workflow:
-  issueIntake:
-    enabled: true
-    snapshotDir: .harness/issues
-    verifyDriftOnRun: true
-    requireOpen: true
-    plannerAgent: planner
-    autoHandoff: true
-  planning:
-    enabled: true
-    plannerAgent: planner
-    worktreeIsolation: true
-    barrierValidation: true
-    maxWaveConcurrency: 4
-    distributed: false
-  reviews:
-    enabled: true
-    leadAcceptance: true
-    quality:
-      severityPoints:
-        critical: 300
-        high: 75
-        medium: 24
-        low: 3
-        note: 1
-    convergence:
-      minimumDebtPointImprovement: 3
-      stagnationWindow: 2
-      cycleDetection: true
-      regressionDetection: true
-    finalQualityGate:
-      maxBySeverity:
-        critical: 0
-        high: 0
-        medium: 0
-        low: 3
-      maxDebtPoints: 9
-    escalation:
-      criticalStartStage: 2
-      replanResumeStage: 2
-      stages:
-        - name: normal
-          action: remediate
-        - name: quality
-          action: remediate
-          role: Implementer
-        - name: senior
-          action: remediate
-          role: Implementer
-          model: "@brain"
-        - name: diagnosis
-          action: diagnose
-          role: Reviewer
-          model: "@brain"
-        - name: replan
-          action: replan
-          role: Planner
-          model: "@brain"
-
-orchestration:
-  provider: paseo
-  required: false
-  worker:
-    provider: opencode
-    maxRepairAttempts: 2
-  operations:
-    liveness:
-      hardDeadlineMs: 28800000
-      progressLeaseMs: 900000
-      stallWindowMs: 900000
-      providerTurnDeadlineMs: 1800000
-      defaultToolDeadlineMs: 1800000
-      maxNoProgressRenewals: 2
-      maxParticipantRestarts: 2
-      maxLocalRetriesPerFailure: 1
-      softBudgetThreshold: 0.8
-    economicEnvelope:
-      initialProviderTurns: 8
-      supervisorProviderTurns: 12
-      hardProviderTurns: 16
-      maxLocalRetries: 1
-      maxParticipantRestarts: 2
-      softThreshold: 0.8
-  interactive:
-    autoSetup: true
-    webUi: true
-    leadAgent: lead
-    sessionPolicy: fresh-on-start
-    usePaseoTools: true
-    stateDir: .harness/paseo
-    title: AEH Lead
-    context:
-      pressureThreshold: 0.70
-      handoffThreshold: 0.80
-      hardHandoffThreshold: 0.90
-
-toolchain:
-  configPath: .harness/toolchain.yaml
-  lockPath: .harness/toolchain.lock.json
-  statePath: .harness/toolchain.state.json
-  generatedMisePath: .config/mise/conf.d/aeh.toml
-
-mcp:
-  servers:
-    context7:
-      description: Current library/framework documentation lookup.
-      type: remote
-      url: https://mcp.context7.com/mcp
-      oauth: false
-      enabled: true
-    playwright:
-      description: Browser exploration and stateful UI validation; prefer deterministic Playwright tests when they are sufficient.
-      type: local
-      command: [npx, -y, "@playwright/mcp@0.0.78"]
-      enabled: true
-      timeoutMs: 30000
-    github:
-      description: Official GitHub MCP server in read-only mode for repository/issue/PR/action triage. Deterministic Harness delivery owns writes.
-      type: local
-      command: [podman, run, -i, --rm, -e, GITHUB_PERSONAL_ACCESS_TOKEN, -e, GITHUB_TOOLSETS, -e, GITHUB_READ_ONLY, ghcr.io/github/github-mcp-server]
-      environment:
-        GITHUB_PERSONAL_ACCESS_TOKEN: "{env:GITHUB_TOKEN}"
-        GITHUB_TOOLSETS: repos,issues,pull_requests,actions
-        GITHUB_READ_ONLY: "1"
-      enabled: true
-      timeoutMs: 30000
-    sentry:
-      description: Optional production-error and trace investigation via Sentry's remote MCP.
-      type: remote
-      url: https://mcp.sentry.dev/mcp
-      enabled: false
-      timeoutMs: 10000
-  benchmark:
-    enabled: false
-    resultsDir: .harness/mcp-benchmarks
-    repetitions: 3
-  packs:
-    research:
-      servers: [context7]
-      enabled: true
-    browser:
-      servers: [playwright, context7]
-      enabled: true
-    github-readonly:
-      servers: [github]
-      enabled: true
-    observability:
-      servers: [sentry]
-      enabled: false
-
-delivery:
-  stateDir: .harness/delivery
-  github:
-    enabled: false
-    allowedActions: []
-    tokenEnv: GH_TOKEN
-    assignTokenOwner: true
-    labels: []
-    branchPattern: feature/gh-{issue}-{slug}
-    finalizeOnAcceptance: true
-    pullRequestDraft: true
-  paseo:
-    enabled: false
-    createWorkspace: true
-    autoUseWorkspace: true
-    worktreeSlugPattern: gh-{issue}-{slug}
-
-memory:
-  provider: engram
-  required: false
-  benchmark:
-    casesDir: memory-benchmarks
-    resultsDir: .harness/memory-benchmarks
-    providers: []
-
-codeIntelligence:
-  provider: graphify
-  required: false
-  graphPath: graphify-out/graph.json
-  snapshotDir: .harness/graphify
-  scheduling:
-    useEdges: true
-    maxGraphHops: 1
-    maxSharedNodes: 0
-    centralityConflictThreshold: 0.35
-
-context:
-  mode: enforce
-  budgets:
-    default:
-      inputTokens: 16000
-    agents:
-      lead:
-        inputTokens: 12000
-      explorer:
-        inputTokens: 12000
-      planner:
-        inputTokens: 10000
-      spec-manager:
-        inputTokens: 18000
-      implementer:
-        inputTokens: 24000
-      reviewer:
-        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
-    maxGraphHops: 2
-  semanticRetrieval:
-    provider: serena
-    required: true
-    editing: false
-  compression:
-    provider: headroom
-    required: true
-    minTokens: 2000
-    reversible: true
-  retrieval:
-    maxRequestsPerTurn: 8
-    maxTokensPerRequest: 6000
-    maxTotalTokensPerTurn: 20000
-  outputPolicy:
-    enabled: true
-
-evidence:
-  enabled: true
-  outputDir: .harness/evidence
-  requireComplete: true
-
-organization:
-  policyBundles:
-    cacheDir: .harness/policy-bundles
-    required: false
-    sources: []
-
-distributed:
-  enabled: false
-  provider: filesystem
-  queueDir: .harness/distributed
-  pollIntervalMs: 1000
-  leaseSeconds: 1800
-
-sdd:
-  specsDir: specs
-  contractsDir: .harness/contracts
-  reportsDir: .harness/reports
-  repairsDir: .harness/repairs
-  runsDir: .harness/runs
-  authoring:
-    provider: openspec
-    schema: spec-driven
-    managerAgent: spec-manager
-
-validation:
-  baseRef: main
-  requireSeal: true
-  frozenPaths:
-    - .harness/contracts/**
-    - .harness/seals/**
-    - tests/acceptance/frozen/**
-  commands: []
-  validators: []
-  providers: []
-  opa:
-    enabled: false
-    policyDirs:
-      - .harness/policies/core
-
-security:
-  sandbox:
-    provider: podman
-    required: false
-    readOnlyRoot: true
-    ephemeralHome: true
-    noNewPrivileges: true
-    capDropAll: true
-    pidsLimit: 512
-    forceForRisks: []
-    environmentAllowlist: []
-    credentialEnvAllowlist: []
-  tools:
-    - opengrep
-    - trivy
-
-telemetry:
-  enabled: true
-  required: false
-  localEventsFile: .harness/telemetry/events.ndjson
-  localMetricsFile: .harness/telemetry/metrics.ndjson
-  exporter: none
-  serviceName: engineering-harness-consumer
-
-evals:
-  corpusDir: evals/corpus
-  resultsDir: .harness/evals/results
-  workspacesDir: .harness/evals/workspaces
-  defaultRuns: 5
-  confidenceLevel: 0.95
-  fullStack:
-    enabled: false
-    required: false
-    strictSupplyChain: false
-
-provenance:
-  outputDir: .harness/provenance
-  buildType: https://github.com/JamesMorales04/agentic-engineering-harness/v0.6
-  # Set artifact to the normalized root-relative packed artifact when any
-  # provenance, SBOM, or signing requirement is enabled.
-  # artifact: dist/agentic-engineering-harness.tgz