Add FlowChain real-value pilot goal pack

docs/agent-goals/flowchain-real-value-pilot/README.md

@@ -0,0 +1,103 @@
+# FlowChain Real-Value Pilot Goal Pack
+
+Status: copy-ready `/goal` prompts for a capped real-value bridge pilot.
+
+Last updated: 2026-05-14.
+
+## Target
+
+Build the missing path between the current local/product FlowChain testnet and a
+capped real-value pilot that can be exercised by the project owner with a tiny
+amount on Base public network chain ID `8453`.
+
+This goal pack is for implementation, deployment tooling, operator checks, and
+emergency controls. It does not claim broad public readiness.
+
+## Current Baseline
+
+Current `main` already has:
+
+- local/private product testnet package;
+- `npm run flowchain:product-e2e`;
+- local chain runtime, token launch, DEX pool/liquidity/swap smoke;
+- wallet signing and product transaction schemas;
+- control-plane API, explorer/workbench surfaces, and bridge local-credit smoke;
+- second-computer local verification.
+
+Current long-loop agents are also working in these worktrees:
+
+- `E:\FlowMemory\flowmemory-chain`
+- `E:\FlowMemory\flowmemory-crypto`
+- `E:\FlowMemory\flowmemory-indexer`
+- `E:\FlowMemory\flowmemory-dashboard`
+- `E:\FlowMemory\flowmemory-bridge-full`
+- `E:\FlowMemory\flowmemory-contracts`
+- `E:\FlowMemory\flowmemory-review`
+- `E:\FlowMemory\flowmemory-hardware`
+- `E:\FlowMemory\flowmemory-research`
+- `E:\FlowMemory\flowmemory-hq-review-loop`
+
+Real-value pilot agents must inspect those worktrees before coding and reuse
+their completed work where practical. Do not rebuild duplicate systems.
+
+## Final Stop Condition
+
+The pilot is complete only when all of these pass from `main`:
+
+```powershell
+npm run flowchain:l1-e2e
+npm run flowchain:real-value-pilot:e2e
+```
+
+`flowchain:real-value-pilot:e2e` must prove:
+
+1. Base chain ID `8453` is verified before any live transaction path.
+2. A deployed lockbox address is loaded from local ignored config, not hardcoded
+   into public docs as a blanket endorsement.
+3. Per-deposit and total pilot caps are enforced on-chain.
+4. A pause path blocks new deposits while preserving recovery/release flows.
+5. A tiny supported-asset deposit can be observed from Base public network.
+6. The relayer derives a deterministic bridge observation and credit.
+7. The local FlowChain runtime credits the matching local account once.
+8. Replay of the same Base event is rejected or idempotent with evidence.
+9. Withdrawal intent/release path is implemented for the pilot mode.
+10. Operator can stop the bridge, revoke authority, export evidence, and recover
+    from restart.
+11. Dashboard/API show exact live/degraded/error state.
+12. No private key, seed phrase, mnemonic, RPC credential, API key, or webhook is
+    committed, logged, exported, or returned from public local routes.
+
+## Local Secret Boundary
+
+Agents may add `.env.example`, config schemas, and scripts that read local
+environment variables. They must not commit real keys or RPC credentials.
+
+Required local env names should be explicit and scoped, for example:
+
+```text
+FLOWCHAIN_BASE8453_RPC_URL
+FLOWCHAIN_BASE8453_DEPLOYER_PRIVATE_KEY
+FLOWCHAIN_BASE8453_LOCKBOX_ADDRESS
+FLOWCHAIN_PILOT_MAX_DEPOSIT_WEI
+FLOWCHAIN_PILOT_TOTAL_CAP_WEI
+FLOWCHAIN_PILOT_OPERATOR_ACK
+```
+
+## Prompt Files
+
+- `pilot-hq.md`
+- `pilot-contracts.md`
+- `pilot-bridge-relayer.md`
+- `pilot-chain-runtime.md`
+- `pilot-wallet-operator.md`
+- `pilot-control-plane-dashboard.md`
+- `pilot-ops-installer.md`
+
+## Launcher
+
+```powershell
+cd E:\FlowMemory\flowchain-release
+powershell -ExecutionPolicy Bypass -File .\infra\scripts\launch-flowchain-real-value-pilot-agents.ps1
+```
+
+Run with `-DryRun` first when checking worktree paths.

docs/agent-goals/flowchain-real-value-pilot/pilot-bridge-relayer.md

@@ -0,0 +1,62 @@
+/goal You are the FlowChain Real-Value Pilot Bridge Relayer agent.
+
+Worktree: E:\FlowMemory\flowmemory-live-bridge
+Branch: agent/real-value-pilot-bridge
+
+Goal: implement the relayer path that observes a tiny capped deposit on Base public network chain ID `8453`, derives a deterministic bridge credit, applies it to local FlowChain exactly once, and supports pilot withdrawal/release evidence.
+
+Inspect first:
+- current `services/bridge-relayer`;
+- E:\FlowMemory\flowmemory-bridge-full active bridge-testnet work;
+- E:\FlowMemory\flowmemory-live-contracts if it exists;
+- current runtime bridge-credit handoff shape.
+
+Allowed folders:
+- services/bridge-relayer/
+- fixtures/bridge/
+- schemas/flowmemory/bridge*.json
+- infra/scripts/bridge-*.ps1
+- infra/scripts/flowchain-real-value*.ps1
+- docs/bridge/
+- docs/agent-runs/real-value-pilot-bridge/
+
+Forbidden folders:
+- contracts/ except generated ABI fixture or read-only docs coordination
+- crates/ except read-only handoff review
+- apps/dashboard/
+- crypto/ secret internals
+- hardware/
+
+Create and maintain:
+- docs/agent-runs/real-value-pilot-bridge/PLAN.md
+- docs/agent-runs/real-value-pilot-bridge/CHECKLIST.md
+- docs/agent-runs/real-value-pilot-bridge/EXPERIMENTS.md
+- docs/agent-runs/real-value-pilot-bridge/NOTES.md
+
+Quantitative acceptance:
+1. `npm test --prefix services/bridge-relayer` passes.
+2. Existing `npm run bridge:local-credit:smoke` passes.
+3. New mock pilot E2E passes without external RPC.
+4. New Base public-network observer verifies `eth_chainId == 0x2105`.
+5. Observer rejects wrong chain IDs and unapproved contract addresses.
+6. Observer supports confirmation depth configuration.
+7. Deposit observation writes deterministic observation, credit, and evidence files.
+8. Duplicate deposit event replay is rejected or idempotent with explicit evidence.
+9. Credit handoff applies to local runtime exactly once.
+10. Withdrawal intent/release evidence path exists for pilot mode.
+11. Script prints exact next operator command after every step.
+12. No private key, seed phrase, mnemonic, RPC credential, API key, or webhook appears in committed fixtures, logs, exports, or API payloads.
+13. `npm run flowchain:real-value-pilot:e2e` includes this bridge path.
+14. `npm run flowchain:product-e2e` still passes or the breakage is assigned.
+
+Feedback loop:
+- Run bridge tests.
+- Run mock pilot E2E.
+- Run wrong-chain negative tests.
+- Run local-credit smoke.
+- Run product E2E.
+
+PR output:
+- Include exact commands for mock mode and live observer mode.
+- Include env vars required.
+- Include failure/retry/replay behavior.

docs/agent-goals/flowchain-real-value-pilot/pilot-chain-runtime.md

@@ -0,0 +1,54 @@
+/goal You are the FlowChain Real-Value Pilot Chain Runtime agent.
+
+Worktree: E:\FlowMemory\flowmemory-live-chain
+Branch: agent/real-value-pilot-chain
+
+Goal: make the local FlowChain runtime consume real-value pilot bridge credits deterministically and expose receipts/state required by the relayer, control plane, and dashboard.
+
+Inspect first:
+- current `crates/flowmemory-devnet`;
+- E:\FlowMemory\flowmemory-chain active long-loop work;
+- bridge handoff files from bridge relayer worktrees.
+
+Allowed folders:
+- crates/flowmemory-devnet/
+- devnet/
+- infra/scripts/flowchain-*.ps1
+- docs/agent-runs/real-value-pilot-chain/
+- local runtime docs under docs/
+
+Forbidden folders:
+- contracts/
+- services/bridge-relayer/
+- apps/dashboard/
+- crypto/ secret internals
+- hardware/
+
+Create and maintain:
+- docs/agent-runs/real-value-pilot-chain/PLAN.md
+- docs/agent-runs/real-value-pilot-chain/CHECKLIST.md
+- docs/agent-runs/real-value-pilot-chain/EXPERIMENTS.md
+- docs/agent-runs/real-value-pilot-chain/NOTES.md
+
+Quantitative acceptance:
+1. `cargo test --manifest-path crates/flowmemory-devnet/Cargo.toml` passes.
+2. Runtime supports bridge-credit asset/account mapping for the pilot.
+3. Bridge credits are included in blocks exactly once.
+4. Replay of the same credit is rejected or idempotent with evidence.
+5. Runtime exposes receipt by id and by Base event reference.
+6. Restart preserves bridge credit, local balance, token, DEX, and receipt state.
+7. Export/import preserves deterministic roots for pilot state.
+8. Multi-node/local-network smoke remains passing or is updated.
+9. `npm run flowchain:real-value-pilot:e2e` exercises runtime credit.
+10. `npm run flowchain:product-e2e` still passes.
+
+Feedback loop:
+- Run focused Rust tests.
+- Run cargo test.
+- Run network smoke if available.
+- Run pilot E2E and product E2E.
+
+PR output:
+- Include state/receipt shape.
+- Include exact commands run.
+- Include remaining integration blockers.

docs/agent-goals/flowchain-real-value-pilot/pilot-contracts.md

@@ -0,0 +1,59 @@
+/goal You are the FlowChain Real-Value Pilot Contracts agent.
+
+Worktree: E:\FlowMemory\flowmemory-live-contracts
+Branch: agent/real-value-pilot-contracts
+
+Goal: build the contract side of the capped Base public-network pilot bridge. Reuse existing bridge/settlement contracts and active worktree changes where practical. Do not create a parallel bridge architecture.
+
+Inspect first:
+- current main contracts and tests;
+- E:\FlowMemory\flowmemory-contracts active long-loop work;
+- E:\FlowMemory\flowmemory-bridge-full bridge event expectations.
+
+Allowed folders:
+- contracts/
+- tests/
+- script/
+- docs/bridge/
+- docs/agent-runs/real-value-pilot-contracts/
+
+Forbidden folders:
+- crates/
+- services/
+- apps/dashboard/
+- crypto/
+- hardware/
+
+Create and maintain:
+- docs/agent-runs/real-value-pilot-contracts/PLAN.md
+- docs/agent-runs/real-value-pilot-contracts/CHECKLIST.md
+- docs/agent-runs/real-value-pilot-contracts/EXPERIMENTS.md
+- docs/agent-runs/real-value-pilot-contracts/NOTES.md
+
+Quantitative acceptance:
+1. `forge test` passes.
+2. `npm run contracts:hardening` passes.
+3. Lockbox supports chain ID `8453` deployment configuration.
+4. Contract enforces per-deposit cap and total pilot cap.
+5. Contract supports allowlisted asset(s) only.
+6. Pause blocks deposits.
+7. Authorized release/recovery path remains possible while paused.
+8. Replay protection prevents duplicate release/deposit accounting.
+9. Events contain enough deterministic data for the relayer to derive bridge observation IDs without assuming txHash/logIndex inside the contract.
+10. Dry-run deployment script exists.
+11. Broadcast deployment script requires explicit local env ack and never commits keys.
+12. Verification/source command or instructions exist.
+13. Contract docs explain owner, release authority, cap, pause, replay, and emergency assumptions.
+14. `npm run flowchain:product-e2e` still passes or the breakage is assigned.
+
+Feedback loop:
+- Run focused forge tests.
+- Run `forge test`.
+- Run `npm run contracts:hardening`.
+- Run deployment dry run against local Anvil if scripts support it.
+- Run `git diff --check`.
+
+PR output:
+- Include deployed-address handling design.
+- Include exact commands run.
+- Include remaining real-value pilot blockers.

docs/agent-goals/flowchain-real-value-pilot/pilot-control-plane-dashboard.md

@@ -0,0 +1,56 @@
+/goal You are the FlowChain Real-Value Pilot Control-Plane/Dashboard agent.
+
+Worktree: E:\FlowMemory\flowmemory-live-control-dashboard
+Branch: agent/real-value-pilot-control-dashboard
+
+Goal: expose and render the real-value pilot bridge lifecycle end to end: Base deposit observed, local credit applied, replay/retry status, withdrawal intent/release evidence, emergency state, and exact operator next steps.
+
+Inspect first:
+- current services/control-plane and apps/dashboard;
+- E:\FlowMemory\flowmemory-indexer active long-loop work;
+- E:\FlowMemory\flowmemory-dashboard active long-loop work;
+- bridge relayer/runtimes handoff shapes.
+
+Allowed folders:
+- services/control-plane/
+- services/shared/
+- apps/dashboard/
+- schemas/flowmemory/
+- docs/agent-runs/real-value-pilot-control-dashboard/
+- control-plane/dashboard docs under docs/
+
+Forbidden folders:
+- contracts/
+- crates/
+- crypto/ secret internals
+- hardware/ implementation
+
+Create and maintain:
+- docs/agent-runs/real-value-pilot-control-dashboard/PLAN.md
+- docs/agent-runs/real-value-pilot-control-dashboard/CHECKLIST.md
+- docs/agent-runs/real-value-pilot-control-dashboard/EXPERIMENTS.md
+- docs/agent-runs/real-value-pilot-control-dashboard/NOTES.md
+
+Quantitative acceptance:
+1. `npm test --prefix services/control-plane` passes.
+2. `npm run control-plane:smoke` passes.
+3. `npm test --prefix apps/dashboard` passes.
+4. `npm run build --prefix apps/dashboard` passes.
+5. API exposes pilot status, deposit observations, credits, withdrawal intents, release evidence, cap status, pause status, retry status, and emergency status.
+6. API rejects or redacts private key, seed phrase, mnemonic, RPC credential, API key, and webhook-shaped material.
+7. Dashboard shows exact live/degraded/error state and next operator command.
+8. Dashboard labels the pilot as capped owner testing, not broad public readiness.
+9. Browser stores no private keys or RPC secrets.
+10. `npm run flowchain:real-value-pilot:e2e` verifies API and dashboard evidence.
+11. `npm run flowchain:product-e2e` still passes.
+
+Feedback loop:
+- Run control-plane tests/smoke.
+- Run dashboard tests/build.
+- Run browser verification if available.
+- Run pilot E2E and product E2E.
+
+PR output:
+- List API methods/endpoints and dashboard sections.
+- Include exact commands run.
+- Include screenshots or browser verification notes if possible.

docs/agent-goals/flowchain-real-value-pilot/pilot-hq.md

@@ -0,0 +1,55 @@
+/goal You are the FlowChain Real-Value Pilot HQ agent.
+
+Worktree: E:\FlowMemory\flowmemory-live-hq
+Branch: agent/real-value-pilot-hq
+
+Goal: coordinate the capped real-value pilot until `npm run flowchain:real-value-pilot:e2e` exists and passes on main, together with `npm run flowchain:l1-e2e`.
+
+Start by reading current main and inspecting these active worktrees for reusable work:
+- E:\FlowMemory\flowmemory-chain
+- E:\FlowMemory\flowmemory-bridge-full
+- E:\FlowMemory\flowmemory-contracts
+- E:\FlowMemory\flowmemory-crypto
+- E:\FlowMemory\flowmemory-indexer
+- E:\FlowMemory\flowmemory-dashboard
+- E:\FlowMemory\flowmemory-review
+- E:\FlowMemory\flowmemory-hq-review-loop
+
+Allowed folders:
+- docs/
+- infra/scripts/
+- package.json
+- .github/
+- README.md
+
+Forbidden folders:
+- crates/
+- contracts/
+- services/
+- crypto/
+- apps/dashboard/
+- hardware/
+
+Create and maintain:
+- docs/agent-runs/real-value-pilot-hq/PLAN.md
+- docs/agent-runs/real-value-pilot-hq/CHECKLIST.md
+- docs/agent-runs/real-value-pilot-hq/EXPERIMENTS.md
+- docs/agent-runs/real-value-pilot-hq/NOTES.md
+
+Quantitative acceptance:
+1. Create docs/FLOWCHAIN_REAL_VALUE_PILOT.md.
+2. Add or update `npm run flowchain:real-value-pilot:e2e` as the final pilot gate.
+3. The gate must fail clearly until contracts, bridge relayer, chain runtime, wallet/operator, control-plane/dashboard, and ops pieces exist.
+4. Create an integration matrix mapping every required proof to owning agent and command.
+5. Create a pilot go/no-go checklist for the project owner.
+6. Keep public-readiness claims out of docs; this is a capped owner pilot.
+7. `node infra/scripts/check-unsafe-claims.mjs` passes.
+8. `git diff --check` passes.
+9. Existing `npm run flowchain:product-e2e` remains passing, or the failure is documented with owner and next action.
+10. Open a PR with exact commands run and current blockers.
+
+Feedback loop:
+- Run `git diff --check`.
+- Run `node infra/scripts/check-unsafe-claims.mjs`.
+- Run the new pilot gate in incomplete mode if needed.
+- Run `npm run flowchain:product-e2e` before PR if practical.