agentic-engineering-harness 0.5.1 → 0.6.1

package/dist/workers/paseo.js.map

@@ -1 +1 @@
-{"version":3,"file":"paseo.js","sourceRoot":"","sources":["../../src/workers/paseo.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"paseo.js","sourceRoot":"","sources":["../../src/workers/paseo.ts"],"names":[],"mappings":"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"}

package/docs/PASEO.md

@@ -1,9 +1,92 @@
 # Paseo Integration
 
-Paseo is the default orchestration control plane because an existing lead agent can spawn an OpenCode subagent in the same workspace and keep controlling it remotely.
+Paseo is AEH's default interactive orchestration surface. The integration separates **Paseo communication/session lifecycle** from **AEH deterministic workflow ownership**.
 
-The executor uses the scriptable flow `paseo run --background --quiet`, `paseo wait`, `paseo logs`, and `paseo send` for repairs. When the lead itself is a Paseo agent, Paseo supplies parent/workspace defaults automatically.
+## SDK-first control plane
 
-The lead remains responsible for architecture and final semantic review. Paseo is an execution/control primitive, not the source of engineering truth.
+AEH uses the official TypeScript SDK, `@getpaseo/client`, as the primary control surface for agent creation, follow-up turns, status lookup and directory queries. The SDK is resolved directly when available and otherwise from the managed `@getpaseo/cli` installation. Paseo CLI already ships the matching client package, so AEH does not independently pin a second Paseo SDK version.
 
-For a directly container-isolated worker, configure `orchestration.provider: podman`. This trades Paseo child-session visibility for stronger process isolation. Advanced setups can instead configure a Paseo custom provider binary/wrapper around a containerized OpenCode CLI.
+The CLI remains responsible for daemon bootstrap/recovery and is retained as a compatibility fallback when the SDK cannot be resolved or connected:
+
+```text
+AEH
+├── daemon/bootstrap/recovery -> Paseo CLI
+└── normal agent lifecycle    -> @getpaseo/client
+```
+
+Set `AEH_PASEO_FORCE_CLI=1` only when the compatibility path is deliberately required. `PASEO_DAEMON_URL` overrides the default SDK endpoint `ws://127.0.0.1:6767/ws`; `PASEO_DAEMON_PASSWORD` supplies daemon authentication when configured.
+
+A system-prompt-only idle agent is an SDK-only invariant. If the SDK is unavailable, AEH refuses to degrade that lead creation into a CLI user turn because doing so would expose the bootstrap as conversational input.
+
+## Conversational lead
+
+`aeh start` creates the lead as an idle Paseo agent. The AEH bootstrap is passed through the SDK's `systemPrompt`; it is no longer sent as the first user message and there is no synthetic `AEH READY` turn.
+
+The bootstrap is intentionally thin. `AGENTS.md`, `.harness/skills/engineering-workflow/SKILL.md`, and the resolved AEH agent topology are authoritative for roles, charters, permissions and delegation. This avoids duplicating a role map inside every Paseo conversation and prevents prompt/configuration drift.
+
+When the lead is running inside Paseo and Paseo exposes its orchestration tools, it may still use the native/MCP conversational surface and `/paseo-handoff`. Deterministic Harness-owned work, however, is created externally by AEH through the SDK.
+
+## Independent AEH agents
+
+AEH-managed workers are created without the Paseo SDK `parent` option. A worker may be placed in a delivery workspace, but workspace placement does not establish parentage. This makes each worker a top-level Paseo agent rather than a child whose lifecycle belongs to the current lead conversation.
+
+Workflow ownership is represented by labels instead:
+
+```text
+aeh.project=<project>
+aeh.kind=lead|worker
+aeh.role=<logical-agent>
+aeh.task=<task-id>        # workers
+aeh.profile=<profile>     # when selected
+aeh.generation=<n>        # leads
+```
+
+The shared Paseo runtime exposes list/inspect primitives over those labels. This lets AEH determine which logical agent is active for a task without scraping assistant prose or relying on parent/child nesting. The same labels survive lead context rotation, so a fresh lead can correlate existing workers with durable AEH run state.
+
+### Observe active agents
+
+Use the top-level AEH command to inspect the live Paseo directory. The project label is applied automatically; filters are additive:
+
+```bash
+aeh paseo agents
+aeh paseo agents --status working
+aeh paseo agents --kind worker --role backend-implementer
+aeh paseo agents --task TASK-123 --json
+```
+
+The tabular view reports status, logical role, task, kind, stable Paseo agent ID and title. `--json` returns the same normalized fields plus the complete AEH label set. This is the preferred way to answer which AEH agent is currently working without depending on Paseo parent/subagent nesting.
+
+## Runtime consolidation
+
+Lead startup, `PaseoWorkerExecutor`, and generic `agentPrompt` execution all use the same managed Paseo runtime. That runtime owns SDK-first create/run/probe/list behavior and the CLI fallback. Individual worker paths should not add new hand-written `paseo run/send/wait/logs` loops.
+
+Structured output is passed through the SDK `outputSchema` field. The compatibility CLI path continues to negotiate `--output-schema` and background capabilities dynamically.
+
+## Session policy
+
+Default:
+
+```yaml
+orchestration:
+  interactive:
+    sessionPolicy: fresh-on-start
+```
+
+```bash
+aeh start          # fresh idle lead
+aeh start --resume # explicit compatible reuse
+```
+
+Workspaces and durable AEH state remain reusable even though normal conversational context starts clean.
+
+## Context rotation
+
+Default pressure policy is 70/80/90 percent. `aeh context guard` consumes a context ratio only when Paseo exposes a usable field; AEH does not guess.
+
+At the handoff threshold it writes a deterministic `.harness/paseo/handoffs/*.json` artifact. From a managed Paseo lead it also creates the replacement lead automatically and bootstraps it from the handoff artifact and referenced sealed/run/audit/delivery state. Workers remain independent top-level agents associated through AEH labels and durable task/run state rather than lead parentage.
+
+## Trust boundary
+
+Paseo owns communication, process and session lifecycle. It is not normative engineering truth. AEH TaskContracts, seals, deterministic reports, evidence graphs and quality gates continue to decide acceptance.
+
+For stronger direct process isolation configure Podman sandboxing where appropriate; Paseo orchestration and worker sandboxing remain separate policy axes.

package/docs/PUBLISHING.md

@@ -2,41 +2,62 @@
 
 The package name is `agentic-engineering-harness` and the public CLI commands are `aeh` and `engineering-harness`.
 
-The repository is prepared for npm Trusted Publishing through GitHub Actions OIDC. No long-lived npm publish token is stored in the repository workflow.
+`package.json` is the single source of truth for the AEH version. Runtime CLI version output imports that package metadata; source files and CI must not maintain separate hard-coded version strings.
 
 ## Preflight
 
-Before any publication:
+Every release candidate must pass:
 
 ```bash
 npm run release:check
 ```
 
-This must pass typecheck, tests, build and `npm pack --dry-run`.
+This runs typecheck, the complete test suite, build and `npm pack --dry-run`.
 
-Check whether the desired package name already exists:
+## Automatic releases from `main`
 
-```bash
-npm view agentic-engineering-harness version
+`.github/workflows/publish.yml` is the single npm publishing workflow. A push to `main` starts an idempotent release pipeline unless the repository variable below is set:
+
+```text
+AEH_AUTO_PUBLISH=false
 ```
 
-An npm `E404` means the name is not currently published. If another owner controls the name, choose a scoped package name before publishing rather than changing package identity after adoption.
+The workflow performs the following steps:
 
-## One-time first publication
+1. installs dependencies with `npm ci`;
+2. checks whether the current `package.json` version is already present on npm;
+3. if the current version is unpublished, it publishes that exact version first;
+4. otherwise it derives the next semantic version from commits since the latest `v*` tag:
+   - a breaking Conventional Commit (`type!:` or `BREAKING CHANGE:`) -> major;
+   - `feat:` -> minor;
+   - every other change -> patch;
+5. synchronizes `package.json` and `package-lock.json` with `npm version --no-git-tag-version`;
+6. runs `npm run release:check` on the exact candidate;
+7. commits the version metadata as `chore(release): vX.Y.Z [skip ci]` and creates the matching Git tag;
+8. publishes the package to npm with provenance;
+9. creates the GitHub Release for the tag.
 
-npm Trusted Publisher configuration requires an npm package to exist first. The first release therefore needs one deliberate maintainer-authenticated publish.
+The release commit/tag is pushed with GitHub's repository token. GitHub does not recursively trigger ordinary push workflows for pushes created with that `GITHUB_TOKEN`, so the version commit does not create an infinite publish loop.
 
-From a clean checkout of the exact release commit:
+The repository must allow the workflow identity to write the release metadata commit/tag. If branch rules forbid direct writes to `main`, grant the GitHub Actions identity the appropriate bypass/write permission or set `AEH_AUTO_PUBLISH=false` until the repository rule is adjusted. Source validation remains independent of publication.
 
-```bash
-npm login
-npm run release:check
-npm publish --access public
+## Manual release control
+
+`publish-npm` also supports `workflow_dispatch`. The `bump` input can be:
+
+```text
+auto     # Conventional Commit-derived bump
+current  # publish current version only if it is not already published
+patch
+minor
+major
 ```
 
-Complete the npm account's required 2FA/interactive authentication. Do not create a persistent automation token solely for this bootstrap.
+Manual dispatch is useful for retrying an external npm/OIDC failure or deliberately overriding the automatic bump classification. A `current` retry is also able to recreate a missing GitHub Release when the npm version and matching Git tag already exist; it will not fabricate a missing tag for an already-published package.
 
-After the first package exists, open the package settings on npmjs.com and configure a Trusted Publisher with:
+## npm authentication
+
+The preferred steady-state path is npm Trusted Publishing with GitHub Actions OIDC. Configure the npm package Trusted Publisher with:
 
 ```text
 Provider: GitHub Actions
@@ -46,39 +67,21 @@ Workflow filename: publish.yml
 Allowed action: npm publish
 ```
 
-The workflow file lives at `.github/workflows/publish.yml`; npm expects only the filename in the Trusted Publisher configuration.
-
-For the strongest steady-state posture, after the OIDC flow has been proven once, disallow traditional publish tokens for the package and retain 2FA on the maintainer account.
+The workflow grants `id-token: write`, which is required for OIDC. Modern npm clients can exchange the GitHub OIDC identity for short-lived publish authorization, avoiding a long-lived npm write token.
 
-## Steady-state release
+For bootstrap or compatibility, the workflow also accepts an optional GitHub Actions secret named `NPM_TOKEN`. If present, it is exported only for the `npm publish` step. Once Trusted Publishing is verified, prefer removing the long-lived token.
 
-1. Change `package.json` to the intended semantic version.
-2. Ensure the CLI dispatcher reports the same version.
-3. Merge only after CI `release:check` passes.
-4. Create/publish a GitHub Release tagged exactly:
+If the package has never been published and npm does not permit Trusted Publisher configuration before first publication, perform one maintainer-authenticated bootstrap publish, then configure the Trusted Publisher above. The automatic workflow will subsequently see that version as published and continue normal semantic versioning.
 
-```text
-v<package.json version>
-```
-
-For example:
-
-```text
-v0.4.16
-```
+## Version policy
 
-5. The `publish-npm` workflow will:
-   - check out the release commit;
-   - use Node 24 on a GitHub-hosted runner;
-   - verify that the release tag exactly matches `package.json`;
-   - run `npm run release:check` again;
-   - execute `npm publish` using npm Trusted Publishing/OIDC.
+The repository currently starts this release line at `0.6.1`. After that, normal merges do not require a human to edit the version manually. The release workflow owns the release metadata bump.
 
-If the tag/version check fails, no publish is attempted.
+If a PR intentionally changes the package version to a version that is not yet on npm, that repository version wins: the next `main` publication ships it before any further automatic increment. This makes explicit release corrections and recovery deterministic.
 
 ## What enters the npm tarball
 
-The `files` allowlist in `package.json` publishes only:
+The `files` allowlist in `package.json` publishes:
 
 ```text
 dist/
@@ -92,7 +95,7 @@ docs/
 
 plus npm-required package metadata such as `package.json`, README and LICENSE.
 
-This is why CI runs `npm pack --dry-run`: bootstrap templates, default agents, skills and toolchain schemas are runtime assets for `aeh init`, not merely repository documentation.
+Packaged `skills/` and core `policies/` are runtime control-plane assets. `aeh init`, `aeh setup`, and `aeh start` reconcile those package assets into the consumer repository's `.harness` directory. `.harness/managed-assets.json` is versioned project state: it records hashes so missing or untouched files can be restored/upgraded, retired untouched assets can be removed, and project-local modifications remain protected as overrides.
 
 ## Consumer installation
 
@@ -103,8 +106,14 @@ npm install --save-dev agentic-engineering-harness
 npm exec aeh -- init --setup
 ```
 
-AEH should not be imported into the product runtime merely to use the engineering workflow.
+After the repository has been initialized, a normal:
+
+```bash
+npm exec aeh -- start
+```
+
+reconciles managed Harness assets before loading the agent topology and starting Paseo.
 
 ## Failure policy
 
-Publication is a delivery operation, not an engineering-quality gate. A registry/OIDC/permission failure must not cause the source commit to be rewritten or force-pushed. Fix the external publishing configuration and re-run/recreate the release process as appropriate while preserving the already-validated source commit.
+A registry/OIDC/permission failure is an external delivery failure, not a reason to rewrite validated engineering history. The release workflow is retry-safe: if the version commit/tag exists but npm publication failed, a manual rerun with `current` will attempt the same unpublished version rather than incrementing it again. If npm publication succeeded but GitHub Release creation failed, a `current` rerun can repair the release from the existing matching tag.

package/docs/V0.5.2.md

@@ -0,0 +1,180 @@
+# v0.5.2 — Harness-governed engineering audits
+
+v0.5.2 closes the read-only escape that existed in v0.5.1. A request no longer bypasses AEH merely because it does not mutate files. The interactive entrypoint now distinguishes a purely informational question from a read-only engineering operation.
+
+## Intent model
+
+Every conversational request is classified at the top level as:
+
+```text
+prompt
+  |
+  v
+engineering intent
+  |-- INFORMATIONAL -> direct answer, no mutation
+  |-- AUDIT         -> Harness read-only audit pipeline
+  `-- CHANGE        -> deterministic QUICK | SPEC triage
+```
+
+`AUDIT` is deliberately not a subtype of QUICK. A repository-wide review is valid audit scope even though it would be invalid QUICK scope, and it does not need artificial SDD artifacts merely to run a code review.
+
+Examples:
+
+```text
+"What does src/core/run.ts do?"
+  -> INFORMATIONAL
+
+"review the repo and validate the code for improvements"
+  -> AUDIT
+
+"find bugs and security risks"
+  -> AUDIT
+
+"review this module and fix every bug you find"
+  -> CHANGE -> QUICK | SPEC
+```
+
+The public classifier is:
+
+```bash
+aeh intent "review the repo and validate the code for improvements"
+```
+
+## Audit workflow
+
+Run an audit explicitly with:
+
+```bash
+aeh audit "review the repo and validate the code for improvements"
+```
+
+Optional hints include repeated `--file`, `--domain`, `--reviewer` and `--risk low|medium|high` values.
+
+The pipeline is:
+
+```text
+AUDIT request
+   |
+   v
+worktree checkpoint
+   |
+   v
+transient TaskContract + SHA-256 seal
+   |
+   v
+hard-frozen control plane
+   |
+   v
+configured deterministic validators
+   |
+   v
+failure classification
+   |
+   v
+read-only reviewer wave
+   |
+   v
+finding normalization + deduplication
+   |
+   v
+severity counts + DebtScore + Quality Gate evaluation
+   |
+   v
+AuditReport
+```
+
+Reviewer sessions are clamped to `write=deny`, `gitWrite=deny` and `delegate=deny`. The worktree is also checkpointed before the audit and rolled back afterward, so an accidental tracked mutation by a reviewer or tool does not survive. Any dirty paths that existed before the audit are restored to their exact prior contents.
+
+The transient contract and seal make the audit compatible with the same direct, Paseo and supported Podman execution boundaries used elsewhere in AEH.
+
+## Deterministic failures are evidence
+
+The lead must not silently reinterpret a failing validator as harmless environment noise. Audit reports classify failed checks when possible as:
+
+```text
+ASSERTION_FAILURE
+ENVIRONMENT_FAILURE
+SANDBOX_DENIAL
+MISSING_DEPENDENCY
+TOOL_FAILURE
+```
+
+For example:
+
+```text
+spawnSync git EPERM: operation not permitted
+  -> SANDBOX_DENIAL
+```
+
+That classification does not pretend the affected test passed. The audit remains `DEGRADED` and `productionSafe=false` when a deterministic failure prevents establishing correctness.
+
+## AuditReport
+
+Reports are machine-readable local artifacts:
+
+```text
+.harness/audits/<auditId>.json
+.harness/audits/latest.json
+```
+
+An AuditReport contains:
+
+- frozen controller SHA;
+- audited commit/base ref and pre-existing dirty paths;
+- deterministic checks plus failure classes;
+- reviewer sessions;
+- normalized/deduplicated findings;
+- severity counts;
+- integer DebtPoints and displayed DebtScore;
+- Final Quality Gate evaluation;
+- conservative `productionSafe` status;
+- any paths restored by the read-only rollback boundary.
+
+Audit artifacts are generated state and are gitignored by `aeh init`.
+
+## Audit to remediation
+
+AUDIT itself does not edit files or auto-remediate. If the user later says:
+
+```text
+fix these
+fix all findings
+implement the audit recommendations
+```
+
+the persistent lead reads `.harness/audits/latest.json` and the referenced report, reuses the normalized findings as evidence for a new `CHANGE`, and performs normal deterministic change triage.
+
+```text
+AuditReport
+    |
+    v
+new CHANGE request
+    |
+    v
+QUICK | SPEC
+    |
+    v
+sealed implementation workflow
+```
+
+The audit result does not override safety policy. Security, architecture, schema, public API, cross-module or otherwise unsafe findings still force SPEC when normal change triage requires it.
+
+## Paseo behavior
+
+`aeh start` now writes bootstrap version 2. Existing v0.5.1 lead sessions are intentionally incompatible and are recreated/replaced on the next start so the old broad read-only bypass cannot persist.
+
+The standing interactive invariant is now:
+
+> Every engineering operation must enter through the Harness, whether read-only or mutating. Only purely informational questions may bypass AEH.
+
+Consequently this prompt:
+
+```text
+review the repo and validate the code for improvements
+```
+
+must route to `aeh audit`; the lead must not answer that it skipped AEH because the work is read-only.
+
+## Control-plane freeze
+
+Self-hosted AEH snapshots now explicitly include `src/audit` and `src/paseo` in the controller trust boundary. Audit policy and the interactive routing code therefore cannot modify themselves and take effect inside the same active audit/run; changes govern only a later invocation after validation.

package/docs/V0.6.md

@@ -0,0 +1,148 @@
+# v0.6 — Orchestration & Context Architecture
+
+v0.6 changes the interactive model from a persistent lead that personally performs setup, discovery and specification authoring into a thin semantic orchestrator backed by bounded agents and durable Harness state.
+
+## Thin lead
+
+The interactive lead owns user intent, high-level routing, true ambiguity and final semantic acceptance. It delegates operational work:
+
+```text
+User
+  |
+  v
+AEH Lead
+  |-- explorer              repository discovery
+  |-- environment-manager   doctor/setup/Paseo recovery
+  |-- planner               decomposition + triage evidence
+  |-- spec-manager          OpenSpec authoring
+  `-- AEH                  implementation/validation/review/delivery
+```
+
+The lead should receive compact structured outcomes instead of retaining raw shell logs, full source files or long environment-repair transcripts.
+
+## Paseo-native orchestration first
+
+When the current Paseo agent exposes its orchestration tools, the lead prefers `create_agent`, `send_agent_prompt`, `get_agent_status`, `get_agent_activity` and lifecycle controls, and uses `/paseo-handoff` for responsibility transfer. `/paseo-committee` and `/paseo-advisor` may provide advisory reasoning but never override deterministic AEH gates.
+
+AEH still contains a CLI-based Paseo adapter because an external Node control-plane process cannot invoke tools local to the conversational agent. That adapter is now a compatibility fallback rather than the lead's normal orchestration mechanism.
+
+The fallback negotiates the installed Paseo surface at runtime with `paseo --version` and help output. It does not assume `--quiet`, JSON output or daemon JSON support. This specifically avoids the failure mode where an older Paseo such as 0.3.1 rejects a flag expected by a newer CLI.
+
+Recoverable daemon states such as stale PID, unreachable daemon or connection refused are stopped/restarted and verified before lead/worker launch.
+
+## Fresh lead sessions
+
+`aeh start` now creates a fresh lead by default:
+
+```bash
+aeh start
+```
+
+Explicit reuse is:
+
+```bash
+aeh start --resume
+```
+
+This prevents a new invocation from inheriting stale conversational assumptions, obsolete bootstrap instructions or unnecessary historical context. Durable Git/TaskContract/seal/run/audit/delivery state remains reusable even when the conversation is fresh.
+
+## Context pressure and automatic lead rotation
+
+Default policy:
+
+```text
+<70%     normal
+70-80%   PRESSURE: stop exploratory work and increase delegation
+>=80%    HANDOFF_REQUIRED: write handoff and rotate to a fresh lead
+>=90%    HARD_HANDOFF: no further engineering work in the old lead
+```
+
+The public check is:
+
+```bash
+aeh context guard --agent "$PASEO_AGENT_ID"
+```
+
+When Paseo exposes a usable context ratio and the guard runs inside a managed Paseo lead, AEH writes:
+
+```text
+.harness/paseo/handoffs/lead-<timestamp>.json
+```
+
+and automatically creates a fresh lead. The artifact records prior/new lead IDs, context usage, branch, latest run/audit/delivery references, and an optional semantic brief. The fresh lead is bootstrapped from this deterministic artifact and its referenced sealed state. Normal compaction-and-continue is not the preferred path once the handoff threshold is crossed.
+
+If the installed Paseo version does not expose a stable context ratio, AEH returns `UNKNOWN`; it does not fabricate token usage. Fresh-on-start and delegation-first behavior still reduce accumulation.
+
+## OpenSpec as SPEC authoring backend
+
+For non-QUICK changes, the lead no longer writes proposal/spec/design/tasks itself. `spec-manager` owns SPEC authoring with OpenSpec.
+
+```text
+CHANGE
+  |
+  v
+SPEC
+  |
+  v
+spec-manager
+  |
+  |-- aeh spec prepare
+  |-- openspec status / instructions
+  |-- proposal/specs/design/tasks
+  |-- openspec validate --strict
+  `-- aeh spec compile
+          |
+          v
+      AEH proposal/spec/design/tasks/Gherkin
+      + TaskContract
+      + stable requirement IDs
+      + validator traceability
+          |
+          v
+         seal
+```
+
+Commands:
+
+```bash
+aeh spec prepare READABILITY-001 --title "Improve readability"
+aeh spec compile READABILITY-001 --title "Improve readability"
+aeh sdd validate READABILITY-001
+aeh seal READABILITY-001
+aeh run READABILITY-001
+```
+
+OpenSpec is an **authoring source before freeze**. The compiled native AEH SDD/TaskContract and seal remain normative during implementation. OpenSpec apply commands do not replace AEH's worker, validation, review-convergence or delivery lifecycle.
+
+The compiler records `authoring.provider=openspec`, change name and SHA-256 provenance. It maps OpenSpec `### Requirement:` / `#### Scenario:` content into stable AEH requirement IDs and Gherkin acceptance. Refactor/tooling changes without a delta spec receive an explicit behavior-preservation requirement.
+
+A requirement validator may not be invented. AEH uses configured deterministic validators first, otherwise derives a project test/typecheck/build command from known project metadata. If it cannot establish executable requirement evidence, SPEC compilation fails instead of emitting a phantom validator.
+
+## Built-in orchestration preset
+
+New projects extend:
+
+```jsonc
+{
+  "extends": ["aeh:orchestration"]
+}
+```
+
+This extends `aeh:default`, makes lead/planner delegation-first, and adds:
+
+- `environment-manager`;
+- `spec-manager`.
+
+OpenSpec is included in the declarative toolchain and automatically selected when `sdd.authoring.provider: openspec` is active.
+
+## Trust boundary
+
+The authority order remains unchanged:
+
+1. user intent / true product decisions;
+2. sealed compiled AEH SDD + TaskContract;
+3. deterministic validators/evidence;
+4. quality/review gates;
+5. LLM summaries and advisory tools.
+
+Paseo skills improve communication and lifecycle control; they do not become gate authority. OpenSpec improves specification authoring; it does not become mutable execution truth after the AEH seal.