gate-evm-tools 1.0.27 → 1.0.31

package/docs/delivery-safe.md

@@ -0,0 +1,72 @@
+# Official Safe 1.4.1 delivery
+
+The supported adapter is `safe-1.4.1-call-only/v1`: the published ordinary Safe
+singleton and SafeProxy, with either a single CALL or DELEGATECALL to the official
+MultiSendCallOnly containing only CALL entries. SafeL2, modules, ordinary MultiSend,
+arbitrary delegatecall and nested Safe execution are unsupported. Reviewed runtime
+hashes are code-owned; caller-provided hashes cannot add implementations.
+
+The developer delivers this optional target policy in the existing `config.yaml`.
+It is included in the captured release inputs, with no production business override:
+
+```yaml
+production:
+  environment: prod
+  finality: { confirmations: 1 }
+  openzeppelin: { manifestDir: .openzeppelin }
+  safe:
+    adapter: safe-1.4.1-call-only/v1
+    multiSendCallOnly: '0x<deployed official MultiSendCallOnly address>'
+    safeTxGas: '500000'
+    submitterPolicy: { kind: any }
+```
+
+Safe address is the current original plan executor. After final plan preparation,
+the host retains READY, exits the project simulation, and starts a separate static
+worker. Only that worker receives the observation provider and durable store. It
+checks the actual proxy/singleton/batch identities and nonce at one canonical block
+and freezes the current contiguous external segment, complete Safe envelope,
+transaction IDs, EIP-712 hash, explicit finality and zero-refund policy. It never
+allocates a future segment's nonce. Existing published bindings are immutable;
+consumed nonces require reconciliation of the original hash, not rebasing.
+
+Pure renderers perform zero provider, signer or broadcast calls. JSON and Markdown
+contain the full plan and frozen Safe payload, with signatures left for external
+collection. An unprepared current Safe segment reports `preparation-required` and
+still exports the complete ordinary plan. Later segments await preparation when
+executable. The existing host export boundary separately revalidates completed
+progress using readonly RPC; this is distinct from pure rendering.
+
+Reconciliation requires an explicit original outer transaction hash. The collector
+strictly checks all execTransaction fields, ABI canonicality, packed CALL lengths,
+values and complete range coverage. Signatures may vary. The outer sender can be a
+distinct relayer under the sealed any-relayer policy. Base gas/gas price are zero,
+gas token/refund receiver are zero addresses, and actual payment must be zero.
+Exactly the expected SafeTxHash ExecutionSuccess, canonical inclusion and finality
+are required. ExecutionFailure never advances, even when receipt status is one.
+One verified Safe batch is committed atomically to its exact inner indices. The
+EOA duplicate-hash rule is unchanged, and only a complete finalized prefix allows
+the original operator continuation. Successful calls do not replace business
+assertions or production finalization.
+
+The finite evidence collector supports Geth 1.15.11 prestateTracer plus its default
+opcode trace. It requests its own fixed options for the same hash, checks full
+address-keyed transaction-time code and proxy slot zero, binds proxy pc 28 SLOAD /
+pc 94 DELEGATECALL and singleton/batch call frames, and tracks CALL versus
+DELEGATECALL storage context. Missing, malformed, incomplete, oversized or
+unavailable evidence is refused. No VERSION/block-end identity fallback exists.
+Type-4 authorization transactions and delegation-designator assets are unsupported.
+The client's declared version is a compatibility gate, not remote binary attestation;
+ordinary configured-RPC trust applies. The host limits both options and response
+size and retains its request/scope/effect guards.
+
+Local acceptance uses the already prepared official native Geth 1.15.11 source
+build, dev mode with Prague enabled, and vendored official Safe artifacts. Set
+`GATE_SAFE_GETH_ACCEPTANCE=1` for `node --test test/delivery-safe-geth.test.mjs` after
+starting the pinned isolated fixture at 127.0.0.1:19545. The fixture retains its
+own deployment state under `/tmp/gate-r5-20261023-implementation`; it never clears
+historic accepted chains. The gated suite covers real owners/signatures, value,
+relayers, batch failures, extra calls, same-block fake switch/restore, later-index
+execution, reentry/slot-zero refusal, malformed provider evidence and original
+operator continuation. Local confirmations/finalized tags do not prove production
+consensus finality. R6 owns the final frozen-version packaged lifecycle.

package/docs/delivery-setup.md

@@ -0,0 +1,146 @@
+# Core 项目的按需部署接入
+
+`gate-delivery` 只接受已完成生成的 `gateflow-evm-core@1` / `profile: core` 项目。
+它不迁移 full/旧模板，不复制 workflow 源码，也不管理项目的 RPC 网络目录。
+正常的 `compile`、`test`、`typecheck`、`clean` 在接入前后均不需要 `config.yaml`、钱包或外部 RPC。
+
+## 本地接入
+
+创建 JSON 选项文件，例如：
+
+```json
+{
+  "workspaceRoot": "/absolute/workspace",
+  "projectRoot": "contracts",
+  "toolPackage": "/absolute/build/gate-evm-tools-1.0.29.tgz",
+  "targets": [
+    {
+      "network": "sepolia",
+      "environment": "dev",
+      "finality": { "confirmations": 1 },
+      "create2": {
+        "scheme": "evm",
+        "factory": "0x1111111111111111111111111111111111111111"
+      }
+    }
+  ]
+}
+```
+
+工厂地址只是格式示例，应填写项目实际设施地址。`create2`、
+`uups: { placeholderImplementation }` 和 `multicall: { controlledMulticall }`
+都可省略；call/view/check 类项目无需部署设施。提供设施配置时，setup 和 `loadDeliveryTarget` 均校验其地址为非零 EVM 地址。
+`loadDeliveryTarget` 保留 YAML 中的额外人工字段，不采用 setup 选项的严格字段白名单。具体操作需要哪些设施由执行输入验证决定。
+
+```sh
+gate-delivery inspect --options delivery-options.json
+gate-delivery setup --options delivery-options.json
+```
+
+`inspect` 是只读诊断。`setup` 完成冲突预检后，仅补充缺失的选中目标配置、
+缺失的 `contractInfo.json`（内容为 `{}`）和所需的开发依赖声明。
+已有 YAML 注释、其他目标、自定义字段、业务代码、注册表、Git 元数据和生成器 marker 均保留。
+已有值与明确请求冲突、路径包含 symlink、模板不受支持时，在写入前拒绝。
+
+依赖未就绪时返回 `dependencies_pending`，CLI 退出码为 `2`；不会安装依赖或添加失败的插件 import。
+用户在目标项目显式安装依赖后再次运行 setup，才会把
+`import "gate-evm-tools/delivery-hardhat";` 放在其他 import 之前。
+重复 setup 不改写已满足要求的文件。退出码 `0` / `ready` 只表示接入完成，
+不表示 source 已验证、RPC 已连接、部署获准或合约已部署。`setup_pending` 是 inspect 发现仍有配置修改待完成。
+
+当前未发布的 API 应使用显式本地构建 tarball：在 GateTool 仓库运行 `npm run build` 和
+`npm pack --pack-destination /absolute/build`，并把 tarball 绝对路径写入 `toolPackage`。
+该字段可省略，但仅有 `gate-evm-tools@1.0.29` 版本号不能证明 API 已存在；诊断会检查本地 exports。
+如 package.json 已声明另一来源，先显式调整该依赖，不会静默覆盖人工声明。
+
+验证的 core 工具链是 Hardhat `2.26.3`、ethers `6.15.0`、hardhat-ethers `3.1.0`、
+TypeScript `5.9.3`、ts-node `10.9.2`。按需声明 OZ hardhat-upgrades `3.9.1`、
+upgrades-core `1.44.2`、contracts `5.4.0`；业务 Solidity 源码引用 contracts-upgradeable 时才声明 `5.4.0`。
+诊断检查实际本地包、delivery exports 和本地 npm 依赖树，不把祖先目录的依赖当作本项目就绪。
+不添加 toolbox、zkSync、Foundry、patch-package 或 postinstall 补丁。
+
+网络仍只定义在项目 `hardhat.config.ts`。接入读取静态 const/default-export 对象中的选中网络，
+支持字面 URL、`process.env.NAME`、`||` 和 `??`；动态计算的选中网络需要人工改为可验证的静态定义。业务依赖扫描遵循静态 `paths.sources`（默认 `contracts`），且只读取项目内目录。
+诊断只输出 network、chainId 和 rpcConfigured，不输出解析后的 RPC URL。
+可通过项目生成器或手工增加网络，无需发布 GateTool。
+
+## 公共 API
+
+- `gate-evm-tools/delivery-setup`：`inspectDeliveryProject(options)`、`setupDeliveryProject(options)`、
+  `readProjectNetworkSnapshots(root, aliases, env?)`、`loadDeliveryTarget(root, network, environment?)`、
+  `configureDeliveryEnvironment({ root, env?, argv? })`。
+- `gate-evm-tools/delivery-protocol`：`parseDeliveryRequest(input)`、
+  `validateDeliveryRpc(input, selectedProjectSnapshot, loadProvider)` 及请求类型。
+- `gate-evm-tools/delivery-hardhat`：项目配置的薄插件入口，带 Hardhat ethers/upgrades 类型扩展。
+- `gate-evm-tools/delivery-policy`：不加载 OZ 的共享 manifest 策略。
+
+`readProjectNetworkSnapshots` 提供给本地 provider 装配使用，包含解析后的 URL，
+不要把它写入交付文件或日志。`validateDeliveryRpc` 首先校验请求语法，之后才调用
+注入的 `loadProvider(snapshot)`；provider 的 `request({ method: "eth_chainId", params: [] })`
+必须返回与项目快照一致的真实 chain ID。RPC 失败或链 ID 不符直接拒绝，没有备用网络。
+
+## 显式 runtime 请求协议
+
+```json
+{
+  "version": 1,
+  "environment": "dev",
+  "purpose": "dev-execution",
+  "mode": "simulate",
+  "network": "sepolia",
+  "sourceRef": {
+    "path": "handoff/task-1/handoff.md",
+    "taskId": "task-1",
+    "planKey": "rollout",
+    "rev": 1
+  },
+  "devSigner": "0x2222222222222222222222222222222222222222"
+}
+```
+
+所有字段严格校验，不存在默认 execute。environment、purpose、mode 必须是字符串，不接受数组或对象的隐式转换。
+sourceRef.path 必须是 workspace-relative POSIX 路径，releaseRef.path 必须是 project-relative POSIX 路径；
+ID、network alias 和路径禁止 traversal/prototype 名称。
+
+| purpose | environment | mode | 额外约束 |
+| --- | --- | --- | --- |
+| dev-execution | dev | simulate / execute / reconcile / verify | devSigner；禁止 operator |
+| prod-qualification | prod | simulate / verify | operator；simulate 必需 fork `{ blockNumber, blockHash, readOnly: true }`；verify 不带 fork/releaseRef，只读、不广播 |
+| prod-execution | prod | simulate / execute / export-calldata / reconcile / verify | operator；必需 releaseRef `{ path, releaseId, inputsHash }` |
+
+`inputsHash` 是 64 位小写 hex，不含 `0x`。fork blockNumber 是非负安全整数；只有 simulate 可带 fork。
+qualification verify 不需要伪造 fork 或 releaseRef，不接受 execute/export-calldata/reconcile；具体只读 verification orchestration 在后续阶段实现。
+所有 signer/operator 地址只是请求约束，不是授权证明。业务 owner 留在冻结 source 的业务参数中，
+不会从 devSigner/operator 推导，也不接受 `businessOwner` 或参数覆盖字段。
+不支持 `admin_release`、旧 SuperTask 字段、`mergeCommit`、`parameterOverrides`、`authorized: true`。
+
+这一步只定义语法、路由和 RPC 一致性验证；canonical source 文件内容核验、输入冻结、prod host 授权、
+执行/finalize/export CLI 在后续交付阶段实现。这里没有把新请求转译给旧 `workflow/run.ts`。
+
+## Manifest 与普通开发命令
+
+插件只有在显式设置 `GATE_DELIVERY_CONTEXT`（上述请求的 JSON）时读取选中目标。
+它在任何 OZ import 之前设置 `MANIFEST_DEFAULT_DIR` 和 `GATE_WORKFLOW_TARGET`；
+`prod` 必须使用 `.openzeppelin`，`dev` 必须使用隔离目录（默认 `.openzeppelin.dev`）。
+两种环境可以使用同一 chain ID。每个 runtime target 应使用全新子进程；继承的目录/目标冲突、
+不同的 Hardhat config/tsconfig、网络路由冲突或已提前加载 OZ 均拒绝。
+所有重复 CLI 参数和对应环境变量都会逐一核对，不能用 CLI 掩盖继承的冲突值。
+无显式 network selector 时读取项目的静态 `defaultNetwork`；插件还会在 HRE 初始化时核对实际
+`hre.network.name`、project root 和 configFile，拒绝 config extender 改写后的不一致。
+只有 simulate 可一致地选择本地 hardhat；该例外不会覆盖显式 selector 冲突或错误的默认网络。
+
+没有 delivery context 时不读取 YAML。插件启用 OZ 原生 storageLayout 和 canonical ERC1967Proxy
+依赖编译，不重写 compiler、optimizer、viaIR、artifact/cache 路径，也不读取钱包。
+旧 workflow 配置入口仅接受 local/development/production，拒绝 dev/prod；新协议通过独立 loader 只接受 dev/prod。
+共享 manifest/preparation 策略支持两套环境名称，但不会将新环境转换为旧 workflow 请求。
+
+真实本地验收：`npm run test:delivery:core`。测试需要相邻的 `EvmHardhatCli` checkout 已构建。该测试生成全新 core、安装本地 tarball、
+编译临时 UUPS 合约并验证 canonical prepare，确认重复 setup 稳定及删除 YAML 后普通命令正常；
+它不发布 npm 包，也不连接真实链。
+
+The read-only [`delivery-source` API](delivery-source.md) binds actual confined handoff tasks and canonical definitions before RPC validation. It is separate from setup, lifecycle persistence and host authorization.
+
+Owned multi-target input qualification is available through
+`gate-evm-tools/delivery-aggregate`; see [aggregate lifecycle and API](delivery-aggregate.md).
+
+Node 最低版本为 22.13.0（node:sqlite）；本次本地组合使用 Node 24.3.0 / npm 11.4.2。

package/docs/delivery-source.md

@@ -0,0 +1,67 @@
+# Actual handoff source binding
+
+`gate-evm-tools/delivery-source` is a read-only API for the new template delivery protocol. It reads the actual workspace handoff using the vendored canonical `gateflow-plan/v2` codec. It does not load HRE, a provider, a signer, or SmartFlowAI, and does not persist lifecycle state or grant execution authority.
+
+```ts
+import { readDeliverySource, validateDeliverySourceRpc } from 'gate-evm-tools/delivery-source';
+
+const source = readDeliverySource({
+  workspaceRoot: '/absolute/workspace',
+  projectRoot: 'contracts/vault', // workspace-relative; '.' is supported
+  sourceRoots: ['qualify-mainnet'], // upstream selection owned by caller policy
+  request, // DeliveryRequest from delivery-protocol
+});
+
+// If RPC validation is needed, this wrapper checks actual source first.
+const bound = await validateDeliverySourceRpc(options, selectedNetworkSnapshot, loadProvider);
+```
+
+`request.sourceRef.path` is workspace-relative. The reference identifies the **invocation task** using taskId, planKey and rev. The selected task's deployment projectRoot must exactly equal the configured workspace-relative projectRoot. Its environment, targetNetwork, allowedActions and exact releaseRef must match the request. The project must carry the supported completed core-template marker. A disabled or cancelled invocation is refused.
+
+Purpose is bound to task steps:
+
+| Purpose | Steps |
+| --- | --- |
+| dev-execution | deploy, check-code |
+| prod-qualification | deploy-test |
+| prod-execution | release-prepare, release-execute, release-verify |
+
+The Task 4 protocol still controls legal modes: dev reconcile is valid; qualification verify needs neither fork nor releaseRef; qualification simulate requires a pinned read-only fork. Source binding adds the actual task's allowedActions constraint. The release reference's path remains **project-relative**; source checking does not read or validate release package contents.
+
+Traversal, symlinks, hardlinks, nonregular files, missing/invalid handoffs, incorrect task identity/revision and route/ref mismatches fail before the wrapper invokes `loadProvider`. The file is opened without following a final symlink, and its identity and modification metadata are checked across the read. Parsing and projections use the same observed text. Subsequent lifecycle operations must revalidate against their freeze policy; this is not a filesystem lock.
+
+## Definition identity
+
+`sourceRoots` is separate from the invocation reference. The caller's trusted selection policy chooses upstream roots; the canonical projector includes their dependency closure and refuses any generated release-prepare/release-execute/release-verify root or dependency. Qualification tasks may be upstream. Selected deployment contracts belonging to another projectRoot are rejected, including those found only through dependencies. Generic source tasks remain available for dependency closure.
+
+The returned recursively immutable binding contains:
+
+- `request` and `invocation` (lane and complete parsed task).
+- `sourceDefinition`, `sourceDefinitionBytes` and SHA-256 `sourceDefinitionHash`.
+- For prod execution, `prodTaskGraph`, `prodTaskGraphBytes` and `prodTaskGraphHash`: all matching-release tasks for the selected project, across target networks, with full dependency closure and full releaseRef data.
+- `observation.path` and raw file SHA-256 for audit observation only.
+
+Definition bytes bind schema/taskId/flow, chosen roots, planKey/rev/lane, selected relative task order, used lane state/skill/step IDs, and objective/acceptance/dependsOn/step/scope/parameters/expectedArtifacts/allowedChanges. They exclude presentation, tools, progress and unrelated tasks. Thus ordinary progress updates change the observation hash without changing the upstream definition hash; an updated rev still binds when semantics return to their prior value.
+
+The later lifecycle must construct `inputsHash` from sourceDefinitionHash plus operation/parameter/artifact/script/config/executor bindings. It must keep the production task graph hash independent of inputsHash, because production task definitions contain releaseRef.inputsHash. **Neither the raw handoff hash nor prodTaskGraphHash is an inputsHash substitute.**
+
+The wrapper verifies source constraints; it does not replace host approval, root selection/freeze policy, revision adoption, progress ordering, release sealing, or release package checks. No runtime actor information is inserted into portable task definitions.
+
+`parseCanonicalPlan(text)` and `projectCanonicalDefinitions(text, { roots, mode: 'upstream' | 'full' })` also expose the canonical read-only surface. The projector reparses text rather than accepting a mutable parsed snapshot. Full mode permits complete independent prod projections. Canonical JSON uses sorted mapping keys and preserves prototype-named own metadata as data.
+
+## Vendor provenance and build
+
+The checked-in files are under `runtime/vendor/plan-codec`: a standalone CJS bundle, `.d.cts` declarations and provenance manifest. SmartFlowAI's `scripts/build-plan-codec.mjs` produces them from committed sources using its existing esbuild. The manifest records the actual commit, relevant source SHA-256s, schema/definition contract, version, builder version and artifact hashes. Its recorded source commit continues to be valid after unrelated SmartFlow commits; `--verify` uses that commit, not current HEAD.
+
+Maintainer refresh, from a SmartFlowAI checkout with the corresponding committed sources:
+
+```sh
+node scripts/build-plan-codec.mjs --out ../EvmGateTools/runtime/vendor/plan-codec
+node scripts/build-plan-codec.mjs --out ../EvmGateTools/runtime/vendor/plan-codec --verify
+```
+
+After reviewing the rebuilt artifact, explicitly update `runtime/delivery/codec-pin.ts` with its manifest SHA-256 and sourceCommit, and copy the canonical `definition-golden.json` and `evm-cases.json` into `test/fixtures/plan-codec`. The pin is a reviewed repository/package integrity anchor; changing all trusted package code is outside its threat boundary.
+
+`npm run build` compiles TypeScript, runs `scripts/stage-plan-codec.mjs` to verify the pinned manifest and both artifact digests, copies them into `dist-runtime/vendor/plan-codec`, verifies staged bytes, and only then writes runtime identity. Normal builds never fetch or rebuild/re-pin canonical sources. Runtime source entry points verify the same pin and artifact hashes before loading the codec. The compiled pin binds the manifest to runtime identity; the staged CJS bundle is also hashed directly.
+
+Both vendor locations are included by existing npm package file rules. Pack tests extract an isolated tarball and read actual source plus shared complete-object/exact-byte golden fixtures with no SmartFlow checkout and no installed dependencies. Tampering with bundle, declarations or provenance fails in runtime and staging checks. Tracked `dist-runtime` files must accompany source changes.

package/docs/direct-package-acceptance.md

@@ -0,0 +1,20 @@
+# Direct-package template acceptance — 2026-09-09
+
+New full projects use `gate-workflow` directly through the existing npm command names. Hardhat and tests import `gate-evm-tools/runtime-config/*` and `runtime/*`; the template no longer contains `scripts/workflow` or `scripts/config` forwarding directories. Business contracts, task/custom scripts, configuration and state remain project-owned.
+
+Local artifact: `/Users/vector/gate/local-packages/direct-package/gate-evm-tools-1.1.0-local.0.tgz`. Its SHA-256 is recorded alongside it in `sha256.txt`. This preview is unpublished. The installed runtime digest is `612a6704b8bd379c97ee352a47a04402615a49c38718bc3542ca0f6252097de2`.
+
+Validation:
+
+- GateTool: 131 tests passed after rebuilding the migration utility.
+- EVM generator/template: build and all 374 tests passed, including direct commands, legacy upgrades and conflict handling.
+- Isolated full project: installed the tarball and refreshed its existing npm lockfile, then `npm ci`, 9 Hardhat tests and a two-custom-step simulation (`direct-final-2`) passed.
+- GateFlow `evm-runtime-check`: accepted the direct-package fixture and reported the matching version/digest.
+- Historical full-template baseline: migration removed 72 recognized files, updated 4 consumers, and backed up originals. All 72 backups matched the baseline. Hardhat differed only in import paths; compiler settings were unchanged. A repeated migration reported 72 current entries and made no changes.
+- Migration skill: quick validation and 89 workflow policy tests passed.
+
+Logs, migration plans, GateFlow output and tarball metadata are in the artifact directory above. The historical baseline check shares the isolated project's installed node_modules for resolution; the isolated full project itself was validated using a real frozen npm install.
+
+Migration refuses custom/unknown executable references and unsafe paths instead of deleting them. Install the approved package and update dependency/lockfile first, review `gate-workflow migrate`, then apply once. Later compatible upgrades update the exact package and existing lockfile; breaking API/config changes still need migration. Active execution bindings must stay on their original runtime build.
+
+No remote transaction broadcast, npm publication, commit/push or active SuperTask mutation was performed in this acceptance.

package/docs/external-infrastructure-acceptance.md

@@ -0,0 +1,33 @@
+# External infrastructure template acceptance
+
+The full template no longer ships Multicall3.sol or UUPSPlaceholder.sol. GateTool queries deployed Multicall authority with a packaged ABI. New proxy deployment steps identify the same business implementation in contract and firstUpgrade.contract; the old placeholder identifier remains supported without loading that artifact.
+
+No project proxy Solidity entry remains. registerWorkflowDependencyCompiler adds the canonical OpenZeppelin ERC1967Proxy source name to Hardhat compilation through the project subtask API. Project compiler settings remain authoritative. No infrastructure addresses, salts, deployments or existing project source files were changed by this template update.
+
+Pending versions: GateTool 1.0.28, EVM generator 2.1.23 (^1.0.28 dependency), GateFlow 4.2.2. The template capability workflow.external-infrastructure.v1 selects the new integrity checks; historical templates retain their source/artifact checks. Upgrade GateFlow and workflow skills before using this template in a task. The migration helper does not delete existing infrastructure source automatically.
+
+Validation:
+- GateTool: 135 tests passed.
+- EVM generator: final full run 374 tests passed, including source-level deployment and upgrade lifecycle regression.
+- GateFlow: 34 tests passed; CLI build passed.
+- ai-workflows: 89 policy tests passed; migration skill validation passed. Initialization accepted the real new fixture without either infrastructure source.
+- Local 1.0.28 tarball installed into an isolated full project, npm ci succeeded, clean Hardhat compilation and 9 tests passed without the two source files.
+- OpenZeppelin proxy bytecode and deployedBytecode were byte-for-byte identical when compiling with and without the two infrastructure sources. Final fixture was cleaned and rebuilt without them.
+- GateFlow accepted the real compiled project with the new capability, actual installed runtime and proxy artifact.
+- Direct dependency compilation without any proxy import source passed 9 Hardhat tests and zkSync compilation (9 sources). EVM proxy bytecode and deployedBytecode matched the original import-based compilation exactly.
+
+Local tarball: /Users/vector/gate/local-packages/external-infrastructure/gate-evm-tools-1.0.28.tgz. Final direct OpenZeppelin compilation logs use /tmp/direct-oz-* and are archived beside the tarball; earlier logs use /tmp/external-infra-*; the isolated project is /Users/vector/gate/local-packages/direct-package/full-runtime-check.
+
+No broadcast, npm publication, commit or push performed. Existing execution bindings cannot resume under a changed runtime digest; use the original runtime to finish those tasks.
+
+## New-workflow package acceptance
+
+Both gate-evm-tools-1.0.28.tgz and gate-evm-hardhat-foundry-2.1.23.tgz were built and inspected. The generator tarball contains none of the three removed Solidity files. The GateTool tarball contains the compiled authority ABI and dependency compiler adapter.
+
+Installed the generator tarball in an isolated directory, generated a fresh project, installed the local GateTool tarball and ran npm ci with lifecycle scripts enabled. The retained OpenZeppelin patch applied successfully. Nine Hardhat tests, EVM compilation, zkSync compilation, and static validation of a normal task created from the example passed. The reserved _examples/counter-rollout path is not accepted as a static-validation deployment ID; copy the example to a normal task ID before validating it.
+
+GateFlow: 34 tests passed again, and frontend/server/CLI/Electron code builds passed after restoring dependencies from the existing Bun lockfile. The built CLI accepted the fresh generated project. Updated the bundled Universal workflow as well as ai-workflows so new tasks no longer require removed source files. This run did not produce a desktop installer or replace the installed application.
+
+ai-workflows: 89 tests passed, all 62 workflow YAML files parsed, initialization and migration skills validated. Acceptance scope is the new workflow only.
+
+Artifacts and release-removal-* logs are in /Users/vector/gate/local-packages/external-infrastructure; SHA256SUMS records both tarballs. The fresh project is release-removal-check/project under that directory. No publication, push or remote transaction broadcast was performed.

package/docs/network-runtime-acceptance.md

@@ -0,0 +1,18 @@
+# Network/RPC extraction — local acceptance
+
+The full-template Hardhat configuration now calls GateTool's compiled runtime-config exports. RPC parsing and zksyncSolcPath retain compatibility shims. Standard networks and fork validation live in networks.ts; project-provided Hardhat APIs register the solc adapter, without loading an HRE from inside config helpers.
+
+The Hardhat config went from 401 to 90 lines. Its Solidity and zkSolc sections were compared byte-for-byte and are unchanged. Overlay projects retain old compiler versions/settings/overrides and merge only helper integration. Per-network `overrides` shallow-merge named network fields; other networks keep their defaults. Manifest/plugin/env/account loading order stays in the project.
+
+Validation:
+
+- GateTool: 128 tests passed, including differential comparison of all 36 network entries against the original config under fallback, Base RPC and fork environments; overrides and compiler preservation; fork parameter rejection; project-owned compiler hook registration.
+- Template generator: build and all 372 tests passed, including legacy upgrade and packaged config preservation.
+- Generated isolated project: installed the local tarball, completed npm ci, passed 9 Hardhat tests and a two-custom-step no-broadcast workflow simulation. Installed runtime identity matches the build.
+- Migration utility: 72 baseline workflow/helper files replaced; repeated apply is a no-op; hardhat.config.ts remains byte-for-byte unchanged by the migration utility.
+- GateFlow: 32 readiness/context/integrity/RPC tests passed; the built CLI accepted the new installed runtime.
+- Migration skill: 9 policy tests and skill validation passed. The skill now describes helper-based network migration while preserving old compiler settings.
+
+The template generator's legacy upgrader also recognizes packaged network config/RPC shims and preserves them rather than injecting old inline logic. Historical upgrade coverage keeps an explicit old-config fixture. The template source tests read network/adapter implementation from the installed package, while separate installed-package integration verifies the real Hardhat boundary.
+
+Local artifact and logs: `/Users/vector/gate/local-packages/network-extraction/`. This is a new local build of `1.1.0-local.0` with a distinct runtime digest/tarball hash; the earlier workflow-extraction artifact is retained. Existing execution bindings must not be reused with this different build. No npm publication, commit/push, live SuperTask change or remote transaction broadcast.

package/docs/plans/2026-09-09-workflow-extraction.md

@@ -0,0 +1,16 @@
+# Packaged workflow extraction
+
+Scope: Move the full template workflow into GateTool, retaining existing project commands, data paths and business hooks. No npm publication or blockchain broadcast. Local tarball installation is the acceptance source. Existing proxy-check changes are preserved.
+
+- [x] Record template baseline and GateFlow callers.
+- [x] Package runtime implementations with explicit project runtime resolution and public type/module entrypoints.
+- [x] Preserve old script paths through thin compatibility shims; resolve internal child entrypoints from the installed package.
+- [x] Add runtime version compatibility guards for resumable executions without rewriting old state.
+- [x] Build and pack locally; install the tarball into an isolated full-template fixture.
+- [x] Run configuration, checks, execution/retry/custom-step and template/GateFlow compatibility tests without broadcasting.
+- [x] Provide a migration plan/apply tool that only replaces unchanged known template files, preserving custom files and running task records.
+- [x] Document supported upgrades, limitations, validation results, and rollback.
+
+Non-goals: npm publication, moving business contracts or data into node_modules, implementation vanity-policy changes, modifying live SuperTask execution state.
+
+Acceptance: `docs/workflow-runtime-acceptance.md`. Tests use packaged source fixtures plus a separately installed compiled-runtime project. No remote EVM or zkSync transaction was broadcast.

package/docs/superpowers/plans/2026-07-22-manifest-bootstrap-transaction.md

@@ -0,0 +1,50 @@
+# Manifest Bootstrap and Transaction Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Make bare gate-tool manifest commands route to the intended release-stage directory before OpenZeppelin loads and recover the exact manifest after any failed sync.
+
+**Architecture:** A dependency-free bin bootstrap validates CLI/environment routing before dynamically importing the compiled command tree. A focused manifest transaction utility owns confinement, locking, byte snapshots, atomic writes, rollback, hashes, and audit reports around `forceImport`.
+
+**Tech Stack:** Node.js ESM, TypeScript, OpenZeppelin upgrades-core, Node test runner.
+
+---
+
+### Task 1: Pre-import manifest bootstrap
+
+**Files:**
+- Create: `bin/manifest-bootstrap.js`
+- Modify: `bin/cli.js`
+- Create: `test/manifest-bootstrap.test.mjs`
+- Modify: `package.json`
+
+- [ ] Write failing tests for `bscDev`, `bscProd`, local, explicit custom directories, environment conflicts, ambiguous mutating networks, traversal, and symlink escape.
+- [ ] Add a module-load-order test proving the environment is set before a simulated upgrades-core import observes it.
+- [ ] Run the focused tests and confirm missing bootstrap behavior.
+- [ ] Implement strict argv parsing and confinement, invoke it before `import('../dist/index.js')`, then re-run tests.
+
+### Task 2: Transactional sync
+
+**Files:**
+- Create: `src/utils/manifestTransaction.ts`
+- Modify: `src/core/syncUpgradeJson.ts`
+- Create: `test/manifest-transaction.test.mjs`
+
+- [ ] Write failing tests for success hashes, concurrent lock rejection, exact-byte rollback, new-file removal, atomic replacement, and symlink rejection.
+- [ ] Implement a dedicated gate-tool lock, snapshots, atomic write helper, rollback, and JSON audit report.
+- [ ] Wrap `forceImport`, manifest validation, and tx-hash enrichment in the transaction and expose report/hash fields in the result.
+- [ ] Run focused and full tests.
+
+### Task 3: Packaging, docs, and integration
+
+**Files:**
+- Modify: `src/core/BytecodeChecker.ts` or its import to use canonical casing
+- Modify: `README.md`
+- Modify: `package.json`
+- Modify: `package-lock.json`
+- Verify: `dist/**`
+
+- [ ] Add tests that package metadata runs the Node suite and includes bootstrap files.
+- [ ] Correct the existing filename/import casing mismatch so Linux and case-sensitive builds agree.
+- [ ] Document conventional routing, explicit custom `MANIFEST_DEFAULT_DIR`, fail-closed behavior, transaction reports, and full-workflow usage.
+- [ ] Bump gate-tool to `1.0.21`, build `dist`, run all tests, and perform a bare CLI fixture integration check.

package/docs/superpowers/plans/2026-07-22-manifest-review-remediation.md

@@ -0,0 +1,49 @@
+# Manifest Review Remediation Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Close the reviewed rollback, writer-serialization, CLI bootstrap, local-network, and report-collision gaps without weakening fail-closed manifest routing.
+
+**Architecture:** Resolve OpenZeppelin's canonical and fallback manifest paths together, confine and lock them by the canonical path, snapshot both exact byte streams, reject dual-file ambiguity, and restore both names exactly on failure. Reuse the same lock around every `sync` and `validate` mutation; emit a per-manifest report path. Treat OpenZeppelin development manifests outside the repository as unsupported for mutating commands.
+
+**Tech Stack:** Node.js ESM, TypeScript, OpenZeppelin upgrades-core, Node test runner.
+
+---
+
+### Task 1: Bootstrap aliases and local fail-closed behavior
+
+**Files:**
+- Modify: `test/manifest-bootstrap.test.mjs`
+- Modify: `bin/manifest-bootstrap.js`
+- Modify: `README.md`
+
+- [ ] Add a failing load-order test for `-n bscDev`.
+- [ ] Change the local-network expectation to an explicit unsupported error and confirm RED.
+- [ ] Parse `--network` and `-n` before command imports; reject local manifest mutations with an actionable error.
+- [ ] Re-run the focused bootstrap tests.
+
+### Task 2: Canonical/fallback transaction and shared writers
+
+**Files:**
+- Modify: `test/manifest-transaction.test.mjs`
+- Modify: `src/utils/openzeppelin.ts`
+- Modify: `src/utils/manifestTransaction.ts`
+- Modify: `src/core/syncUpgradeJson.ts`
+- Modify: `src/core/validateAndGenerateCalldata.ts`
+
+- [ ] Add failing tests for fallback rename rollback, dual-file ambiguity, temporary exact restore, and a shared lock blocking a concurrent writer.
+- [ ] Expose both OpenZeppelin manifest paths.
+- [ ] Implement a canonical lock plus exact two-path snapshots/restoration.
+- [ ] Wrap persistent and temporary `validate` mutations with the shared protocol.
+- [ ] Require sync success to leave one canonical regular file and emit a distinct per-manifest report.
+- [ ] Re-run focused tests after each behavior.
+
+### Task 3: Packaging and verification
+
+**Files:**
+- Modify: `README.md`
+- Verify: `dist/**`
+
+- [ ] Document fallback restoration, shared writer locking, local rejection, and returned report paths.
+- [ ] Build `dist`, run the complete test suite, and run `npm pack --dry-run` with the isolated cache.
+- [ ] Inspect the diff and commit the remediation.