FlowmemoryAI · FlowmemoryAI · May 14, 2026 · May 14, 2026
diff --git a/docs/agent-goals/flowchain-l1-long-loop/README.md b/docs/agent-goals/flowchain-l1-long-loop/README.md
@@ -0,0 +1,86 @@
+# FlowChain L1 Long-Loop Goal Pack
+
+Status: copy-ready `/goal` prompts for long-running Codex agents.
+
+Last updated: 2026-05-14.
+
+## Baseline
+
+Start from current `main`. Do not rebuild what already exists.
+
+Already implemented and verified:
+
+- local/private FlowChain product testnet package;
+- `npm run flowchain:product-e2e`;
+- local devnet runtime with product token and DEX smoke;
+- wallet signing and product transaction vectors;
+- control-plane API and product read methods;
+- dashboard/workbench product surfaces;
+- bridge local-credit handoff smoke;
+- contracts, crypto, dashboard, hardware, services, and full smoke gates;
+- second-computer verification on `FalconXtreme`.
+
+## Final Stop Condition
+
+The long-loop program is complete only when this command exists and passes from
+a clean-ish Windows checkout:
+
+```powershell
+npm run flowchain:l1-e2e
+```
+
+That command must prove:
+
+1. `npm run flowchain:product-e2e` passes.
+2. A multi-node local network smoke passes.
+3. A local wallet E2E passes for create/import/export/account switching/signing.
+4. A bridge testnet/local-credit E2E passes without real mainnet funds.
+5. The control-plane/explorer can query live node, wallet, tx, token, DEX,
+   bridge, hardware, and provenance state.
+6. The dashboard can run against the live API and show clear recovery actions.
+7. A beginner/offline second-computer bundle can be produced and smoke-tested.
+8. No public API, export, log, fixture, or dashboard payload exposes
+   private-key, seed, mnemonic, RPC credential, API key, or webhook material.
+
+## Agent Tracking Rules
+
+Each agent must create and maintain its own files under:
+
+```text
+docs/agent-runs/<agent-name>/
+```
+
+Required files:
+
+- `PLAN.md` for the current plan and stop condition.
+- `CHECKLIST.md` for measurable items, checked off as they pass.
+- `EXPERIMENTS.md` for attempts, results, and failures.
+- `NOTES.md` for concise chronological handoff notes.
+
+Each agent must keep its feedback loop tight. Prefer the smallest relevant test
+first, then the subsystem smoke, then `npm run flowchain:product-e2e`, then the
+future `npm run flowchain:l1-e2e`.
+
+## Prompt Files
+
+- `chain-network.md`
+- `wallet-crypto.md`
+- `control-plane-explorer.md`
+- `dashboard-workbench.md`
+- `bridge-testnet.md`
+- `contracts-settlement.md`
+- `installer-ops.md`
+- `hardware-signals.md`
+- `research-decisions.md`
+- `hq-review.md`
+
+## Launcher
+
+From the main checkout:
+
+```powershell
+cd E:\FlowMemory\flowchain-release
+powershell -ExecutionPolicy Bypass -File .\infra\scripts\launch-flowchain-l1-long-loop-agents.ps1
+```
+
+Use `-DryRun` first to print the windows that would be started.
diff --git a/docs/agent-goals/flowchain-l1-long-loop/bridge-testnet.md b/docs/agent-goals/flowchain-l1-long-loop/bridge-testnet.md
@@ -0,0 +1,57 @@
+/goal You are the FlowChain Bridge/Testnet long-loop agent.
+
+Worktree: E:\FlowMemory\flowmemory-bridge-full
+Branch: agent/l1-loop-bridge-testnet
+
+Baseline: bridge local-credit handoff smoke exists and product E2E proves mock bridge-credit visibility. Extend the existing bridge path. Do not create a second bridge system.
+
+Allowed folders:
+- services/bridge-relayer/
+- fixtures/bridge/
+- schemas/flowmemory/bridge*.json
+- infra/scripts/bridge-*.ps1
+- docs/agent-runs/bridge-testnet/
+- bridge docs under docs/
+
+Forbidden folders:
+- apps/dashboard/
+- crates/ except read-only handoff review
+- contracts/ except read-only event/schema review
+- crypto/ secret internals
+- production deployment files
+
+Create tracking files first:
+- docs/agent-runs/bridge-testnet/PLAN.md
+- docs/agent-runs/bridge-testnet/CHECKLIST.md
+- docs/agent-runs/bridge-testnet/EXPERIMENTS.md
+- docs/agent-runs/bridge-testnet/NOTES.md
+
+Quantitative goal: complete 10/10 checks below:
+1. `npm test --prefix services/bridge-relayer` passes.
+2. `npm run bridge:local-credit:smoke` passes.
+3. A bridge E2E command exists for mock/local Anvil/Base Sepolia test mode.
+4. Deposit observation produces deterministic bridge observation and credit IDs.
+5. Replaying the same deposit is rejected or idempotent with clear evidence.
+6. Withdrawal intent is generated for local/testnet only and is queryable by control plane.
+7. Base mainnet real-funds behavior remains blocked unless a separate production gate exists.
+8. No bridge output contains private keys, seed phrases, RPC credentials, API keys, or webhooks.
+9. Bridge state is visible through the control-plane contracts agreed with the explorer agent.
+10. `npm run flowchain:product-e2e` still passes after your changes.
+
+Implementation constraints:
+- Mock, local Anvil, and Base Sepolia are allowed.
+- Base mainnet must remain read-only/canary or blocked.
+- No custody keys or real $20 bridge path until audited production gate.
+- Keep replay protection explicit.
+
+Feedback loop:
+1. Run bridge unit tests.
+2. Run local-credit smoke.
+3. Run new bridge E2E.
+4. Run `npm run flowchain:product-e2e`.
+5. If `npm run flowchain:l1-e2e` exists, run it last.
+
+PR output:
+- State mode: mock, local Anvil, Base Sepolia, or blocked mainnet.
+- Include exact commands run.
+- Name security risks that remain.
diff --git a/docs/agent-goals/flowchain-l1-long-loop/chain-network.md b/docs/agent-goals/flowchain-l1-long-loop/chain-network.md
@@ -0,0 +1,57 @@
+/goal You are the FlowChain Chain/Network long-loop agent.
+
+Worktree: E:\FlowMemory\flowmemory-chain
+Branch: agent/l1-loop-chain-network
+
+Baseline: FlowChain Product Testnet V1 already exists and `npm run flowchain:product-e2e` has passed on main. Build on the existing Rust devnet. Do not create a replacement chain.
+
+Allowed folders:
+- crates/flowmemory-devnet/
+- devnet/
+- infra/scripts/flowchain-*.ps1 only when the script is runtime/network related
+- docs/agent-runs/chain-network/
+- runtime/network docs under docs/
+
+Forbidden folders:
+- apps/dashboard/
+- contracts/
+- crypto/
+- services/bridge-relayer/
+- unrelated docs
+
+Create tracking files first:
+- docs/agent-runs/chain-network/PLAN.md
+- docs/agent-runs/chain-network/CHECKLIST.md
+- docs/agent-runs/chain-network/EXPERIMENTS.md
+- docs/agent-runs/chain-network/NOTES.md
+
+Quantitative goal: complete 10/10 checks below and keep them checked in CHECKLIST.md:
+1. `cargo test --manifest-path crates/flowmemory-devnet/Cargo.toml` passes.
+2. A command `npm run flowchain:network-e2e` or equivalent exists.
+3. A three-node local static-peer smoke runs from scripts without manual steps.
+4. Each node produces blocks for at least 60 seconds or a bounded deterministic equivalent.
+5. At least 20 signed local transactions are accepted, included exactly once, and queryable by id.
+6. Restarting a node preserves height, latest hash, mempool state, product token state, DEX state, and bridge-credit state.
+7. Export/import preserves deterministic roots for the tested state.
+8. Peer/node status reports enough data for the control plane to show health and sync.
+9. Product transaction types still pass: transfer, token launch, mint/test funding, pool create, add liquidity, remove liquidity, swap, bridge credit.
+10. `npm run flowchain:product-e2e` still passes after your changes.
+
+Implementation constraints:
+- Keep local/testnet/no-value semantics.
+- Use existing inbox/intake, block, state, receipt, and export/import patterns.
+- Do not add tokenomics, fees, slashing, public validators, mainnet behavior, or real bridge custody.
+- Do not duplicate state models if an existing map/root/receipt type can be extended.
+
+Feedback loop:
+1. Run the smallest Rust unit test for the changed function.
+2. Run `cargo test --manifest-path crates/flowmemory-devnet/Cargo.toml`.
+3. Run the network smoke command you add.
+4. Run `npm run flowchain:product-e2e`.
+5. If `npm run flowchain:l1-e2e` exists, run it last.
+
+PR output:
+- One PR only.
+- Link the checklist.
+- State exact commands run.
+- State remaining blockers for full L1 readiness.
diff --git a/docs/agent-goals/flowchain-l1-long-loop/contracts-settlement.md b/docs/agent-goals/flowchain-l1-long-loop/contracts-settlement.md
@@ -0,0 +1,55 @@
+/goal You are the FlowChain Contracts/Settlement long-loop agent.
+
+Worktree: E:\FlowMemory\flowmemory-contracts
+Branch: agent/l1-loop-contracts-settlement
+
+Baseline: contract hardening and bridge lockbox tests already exist. Extend existing contracts and tests. Do not invent a parallel settlement system.
+
+Allowed folders:
+- contracts/
+- tests/
+- script/
+- docs/agent-runs/contracts-settlement/
+- contract/settlement docs under docs/
+
+Forbidden folders:
+- crates/
+- services/
+- apps/dashboard/
+- crypto/
+- hardware/
+
+Create tracking files first:
+- docs/agent-runs/contracts-settlement/PLAN.md
+- docs/agent-runs/contracts-settlement/CHECKLIST.md
+- docs/agent-runs/contracts-settlement/EXPERIMENTS.md
+- docs/agent-runs/contracts-settlement/NOTES.md
+
+Quantitative goal: complete 9/9 checks below:
+1. `npm run contracts:hardening` passes.
+2. `forge test` passes for all contract suites.
+3. Bridge lockbox deposit/release/replay/pause/cap tests are complete for local/testnet needs.
+4. Settlement spine emits stable events for objects consumed by bridge/control-plane.
+5. Event schemas avoid txHash/logIndex assumptions inside contracts.
+6. Dry-run deployment scripts exist for local Anvil or Base Sepolia test mode where appropriate.
+7. Mainnet deployment remains blocked behind explicit production gate docs.
+8. Contract docs name owner, authority, pause, cap, replay, and emergency assumptions.
+9. `npm run flowchain:product-e2e` still passes after your changes.
+
+Implementation constraints:
+- No tokenomics.
+- No production deployment.
+- No unaudited real-funds bridge claim.
+- Keep event/object vocabulary coordinated with bridge and control-plane agents.
+
+Feedback loop:
+1. Run focused forge test.
+2. Run `forge test`.
+3. Run `npm run contracts:hardening`.
+4. Run `npm run flowchain:product-e2e`.
+5. If `npm run flowchain:l1-e2e` exists, run it last.
+
+PR output:
+- Include exact commands run.
+- State whether event schema changed.
+- State production blockers.
diff --git a/docs/agent-goals/flowchain-l1-long-loop/control-plane-explorer.md b/docs/agent-goals/flowchain-l1-long-loop/control-plane-explorer.md
@@ -0,0 +1,59 @@
+/goal You are the FlowChain Control-Plane/Explorer long-loop agent.
+
+Worktree: E:\FlowMemory\flowmemory-indexer
+Branch: agent/l1-loop-control-plane-explorer
+
+Baseline: the control plane already serves health/state/RPC and product token/DEX/bridge reads. Extend the existing service. Do not create a second explorer backend.
+
+Allowed folders:
+- services/shared/
+- services/indexer/
+- services/verifier/
+- services/flowmemory/
+- services/control-plane/
+- schemas/flowmemory/ only for API schema coordination
+- docs/agent-runs/control-plane-explorer/
+- control-plane/indexer docs under docs/
+
+Forbidden folders:
+- crates/
+- apps/dashboard/
+- contracts/
+- crypto/ secret-handling internals
+- hardware/ implementation
+
+Create tracking files first:
+- docs/agent-runs/control-plane-explorer/PLAN.md
+- docs/agent-runs/control-plane-explorer/CHECKLIST.md
+- docs/agent-runs/control-plane-explorer/EXPERIMENTS.md
+- docs/agent-runs/control-plane-explorer/NOTES.md
+
+Quantitative goal: complete 10/10 checks below:
+1. `npm test --prefix services/control-plane` passes.
+2. `npm run control-plane:smoke` passes.
+3. API reads prefer live local node state where present and fall back to fixtures only when live state is unavailable.
+4. Explorer summary includes node status, peer status, blocks, txs, accounts, balances, tokens, pools, LP positions, swaps, bridge credits, hardware signals, and provenance counts.
+5. Transaction submit accepts only validated signed envelopes and rejects unsigned or secret-shaped requests.
+6. Bridge observation/credit reads are replay-safe and distinguish mock, Base Sepolia, local Anvil, and production-gated mainnet modes.
+7. No response route returns private key, seed, mnemonic, RPC credential, API key, or webhook-shaped text.
+8. A control-plane/explorer E2E command exists or is wired into `flowchain:l1-e2e`.
+9. Dashboard has stable API contracts for every field it needs.
+10. `npm run flowchain:product-e2e` still passes after your changes.
+
+Implementation constraints:
+- Keep a single JSON-RPC/control-plane surface.
+- Do not add public production endpoints.
+- Do not bypass existing no-secret scans.
+- Keep schemas explicit and documented.
+
+Feedback loop:
+1. Run focused service tests.
+2. Run `npm run control-plane:smoke`.
+3. Run full service tests.
+4. Run `npm run flowchain:product-e2e`.
+5. If `npm run flowchain:l1-e2e` exists, run it last.
+
+PR output:
+- List every method/endpoint added or changed.
+- Include exact commands run.
+- Name dashboard/runtime dependencies.
diff --git a/docs/agent-goals/flowchain-l1-long-loop/dashboard-workbench.md b/docs/agent-goals/flowchain-l1-long-loop/dashboard-workbench.md
@@ -0,0 +1,54 @@
+/goal You are the FlowChain Dashboard/Workbench long-loop agent.
+
+Worktree: E:\FlowMemory\flowmemory-dashboard
+Branch: agent/l1-loop-dashboard-workbench
+
+Baseline: the workbench already shows product testnet surfaces and live API status. Extend that app. Do not create another dashboard.
+
+Allowed folders:
+- apps/dashboard/
+- docs/agent-runs/dashboard-workbench/
+- dashboard/workbench docs under docs/
+
+Forbidden folders:
+- crates/
+- contracts/
+- crypto/ secret internals
+- services/ except read-only API contract review
+- hardware/ implementation
+
+Create tracking files first:
+- docs/agent-runs/dashboard-workbench/PLAN.md
+- docs/agent-runs/dashboard-workbench/CHECKLIST.md
+- docs/agent-runs/dashboard-workbench/EXPERIMENTS.md
+- docs/agent-runs/dashboard-workbench/NOTES.md
+
+Quantitative goal: complete 10/10 checks below:
+1. `npm test --prefix apps/dashboard` passes.
+2. `npm run build --prefix apps/dashboard` passes.
+3. Workbench shows live/offline state for node, API, wallet, bridge, explorer, and product flow.
+4. Workbench renders blocks, txs, accounts, balances, tokens, pools, LP positions, swaps, bridge credits, hardware signals, and provenance.
+5. Workbench has clear recovery commands when node/API are offline.
+6. Workbench never stores or asks for private keys, seed phrases, mnemonics, RPC credentials, API keys, or webhooks in browser state.
+7. Workbench can trigger only safe local/testnet actions through signed-envelope or local command guidance.
+8. A dashboard E2E or browser verification path exists for local `127.0.0.1:5173`.
+9. Mobile and desktop layouts do not overlap text or controls.
+10. `npm run flowchain:product-e2e` still passes after your changes.
+
+Implementation constraints:
+- Build operational UI, not a marketing page.
+- Keep controls dense, clear, and local/testnet labeled.
+- Do not imply production mainnet or real funds.
+- Use existing design system and app structure.
+
+Feedback loop:
+1. Run focused component/data tests.
+2. Run dashboard tests/build.
+3. Run browser verification if the dev server is available.
+4. Run `npm run flowchain:product-e2e`.
+5. If `npm run flowchain:l1-e2e` exists, run it last.
+
+PR output:
+- Include screenshots or browser verification notes when possible.
+- Include exact commands run.
+- Name API fields that are required from control plane.