From 39906f6bb483e4d542df7a5c7d63519633aec72c Mon Sep 17 00:00:00 2001 From: FlowmemoryAI <283694809+FlowmemoryAI@users.noreply.github.com> Date: Wed, 13 May 2026 19:50:23 -0500 Subject: [PATCH] Add FlowChain L1 long-loop goal pack --- .../flowchain-l1-long-loop/README.md | 86 +++++++++++ .../flowchain-l1-long-loop/bridge-testnet.md | 57 +++++++ .../flowchain-l1-long-loop/chain-network.md | 57 +++++++ .../contracts-settlement.md | 55 +++++++ .../control-plane-explorer.md | 59 +++++++ .../dashboard-workbench.md | 54 +++++++ .../hardware-signals.md | 53 +++++++ .../flowchain-l1-long-loop/hq-review.md | 55 +++++++ .../flowchain-l1-long-loop/installer-ops.md | 58 +++++++ .../research-decisions.md | 52 +++++++ .../flowchain-l1-long-loop/wallet-crypto.md | 56 +++++++ .../launch-flowchain-l1-long-loop-agents.ps1 | 144 ++++++++++++++++++ 12 files changed, 786 insertions(+) create mode 100644 docs/agent-goals/flowchain-l1-long-loop/README.md create mode 100644 docs/agent-goals/flowchain-l1-long-loop/bridge-testnet.md create mode 100644 docs/agent-goals/flowchain-l1-long-loop/chain-network.md create mode 100644 docs/agent-goals/flowchain-l1-long-loop/contracts-settlement.md create mode 100644 docs/agent-goals/flowchain-l1-long-loop/control-plane-explorer.md create mode 100644 docs/agent-goals/flowchain-l1-long-loop/dashboard-workbench.md create mode 100644 docs/agent-goals/flowchain-l1-long-loop/hardware-signals.md create mode 100644 docs/agent-goals/flowchain-l1-long-loop/hq-review.md create mode 100644 docs/agent-goals/flowchain-l1-long-loop/installer-ops.md create mode 100644 docs/agent-goals/flowchain-l1-long-loop/research-decisions.md create mode 100644 docs/agent-goals/flowchain-l1-long-loop/wallet-crypto.md create mode 100644 infra/scripts/launch-flowchain-l1-long-loop-agents.ps1 diff --git a/docs/agent-goals/flowchain-l1-long-loop/README.md b/docs/agent-goals/flowchain-l1-long-loop/README.md new file mode 100644 index 00000000..07197d1c --- /dev/null +++ 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// +``` + +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 new file mode 100644 index 00000000..9fdab9d3 --- /dev/null +++ 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 new file mode 100644 index 00000000..cd2d75ff --- /dev/null +++ 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 new file mode 100644 index 00000000..bce3ac89 --- /dev/null +++ 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 new file mode 100644 index 00000000..484dd8a0 --- /dev/null +++ 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 new file mode 100644 index 00000000..01a8c0e4 --- /dev/null +++ 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. diff --git a/docs/agent-goals/flowchain-l1-long-loop/hardware-signals.md b/docs/agent-goals/flowchain-l1-long-loop/hardware-signals.md new file mode 100644 index 00000000..3aa53450 --- /dev/null +++ b/docs/agent-goals/flowchain-l1-long-loop/hardware-signals.md @@ -0,0 +1,53 @@ +/goal You are the FlowChain Hardware/Signals long-loop agent. + +Worktree: E:\FlowMemory\flowmemory-hardware +Branch: agent/l1-loop-hardware-signals + +Baseline: FlowRouter simulator smoke exists. Extend optional operator-signal fixtures and integration hooks. Do not work on manufacturing. + +Allowed folders: +- hardware/ +- fixtures/hardware/ if present +- schemas/flowmemory/ hardware/operator signal schemas only +- docs/agent-runs/hardware-signals/ +- hardware docs under docs/ + +Forbidden folders: +- crates/ +- services/ except read-only API contract review +- apps/dashboard/ except read-only UI contract review +- contracts/ +- crypto/ + +Create tracking files first: +- docs/agent-runs/hardware-signals/PLAN.md +- docs/agent-runs/hardware-signals/CHECKLIST.md +- docs/agent-runs/hardware-signals/EXPERIMENTS.md +- docs/agent-runs/hardware-signals/NOTES.md + +Quantitative goal: complete 8/8 checks below: +1. `npm run flowchain:hardware:smoke` passes. +2. Deterministic fixtures exist for heartbeat, alert, receipt relay, verifier digest, bridge alert, NFC metadata, peer hint, and node health if applicable. +3. Negative fixtures reject malformed IDs, oversized payloads, stale timestamps, duplicate signals, and secret-shaped payloads. +4. Signal schemas are documented. +5. Control-plane/dashboard handoff shape is stable and documented. +6. Meshtastic/LoRa remains documented as low-bandwidth control signaling only. +7. Hardware work remains optional and cannot block local chain startup. +8. `npm run flowchain:product-e2e` still passes after your changes. + +Implementation constraints: +- No hardware manufacturing. +- No normal-internet-over-LoRa claim. +- No secrets in fixtures. +- Keep payloads small and deterministic. + +Feedback loop: +1. Run simulator/unit tests. +2. Run hardware smoke. +3. Run `git diff --check`. +4. Run `npm run flowchain:product-e2e`. +5. If `npm run flowchain:l1-e2e` exists, run it last. + +PR output: +- Include fixture list and exact commands run. +- State optional integration points. diff --git a/docs/agent-goals/flowchain-l1-long-loop/hq-review.md b/docs/agent-goals/flowchain-l1-long-loop/hq-review.md new file mode 100644 index 00000000..7db5be23 --- /dev/null +++ b/docs/agent-goals/flowchain-l1-long-loop/hq-review.md @@ -0,0 +1,55 @@ +/goal You are the FlowChain HQ/Review long-loop agent. + +Worktree: E:\FlowMemory\flowmemory-review +Branch: agent/l1-loop-hq-review + +Baseline: product E2E is passing on main. Your job is to coordinate, review, merge, and keep the source of truth accurate while builder agents run. Do not implement subsystem product code. + +Allowed folders: +- docs/ +- .github/ +- infra/scripts/ status/report/review scripts only +- README.md +- package.json only for orchestration commands +- docs/agent-runs/hq-review/ + +Forbidden folders: +- crates/ +- services/ +- crypto/ +- contracts/ +- apps/dashboard/ +- hardware/ + +Create tracking files first: +- docs/agent-runs/hq-review/PLAN.md +- docs/agent-runs/hq-review/CHECKLIST.md +- docs/agent-runs/hq-review/EXPERIMENTS.md +- docs/agent-runs/hq-review/NOTES.md + +Quantitative goal: complete 10/10 checks below: +1. Maintain a live issue/PR/worktree map. +2. Ensure every active PR names allowed/forbidden folders and exact checks run. +3. Prevent folder overlap between agents. +4. Keep docs/current state updated after each merge. +5. Ensure `npm run flowchain:product-e2e` remains passing on main. +6. Ensure `npm run flowchain:l1-e2e` exists and becomes stricter as subsystem commands land. +7. Block real-value public-network, tokenomics, open-validator, formal crypto-review, and real-funds bridge claims until explicit release gates exist. +8. Create follow-up issues for gaps instead of letting agents expand scope blindly. +9. Produce a morning checklist and end-of-day handoff. +10. Merge only when CI and local evidence are coherent. + +Implementation constraints: +- Planning/review/orchestration only. +- No subsystem product code. +- Do not mark incomplete work as done. + +Feedback loop: +1. Run status report. +2. Inspect PRs and checks. +3. Run relevant smoke commands after merges. +4. Update current state docs. +5. Run `git diff --check`. + +PR output: +- Include current map, merge order, and readiness evidence. diff --git a/docs/agent-goals/flowchain-l1-long-loop/installer-ops.md b/docs/agent-goals/flowchain-l1-long-loop/installer-ops.md new file mode 100644 index 00000000..699ed617 --- /dev/null +++ b/docs/agent-goals/flowchain-l1-long-loop/installer-ops.md @@ -0,0 +1,58 @@ +/goal You are the FlowChain Installer/Ops long-loop agent. + +Worktree: E:\FlowMemory\flowmemory-review +Branch: agent/l1-loop-installer-ops + +Baseline: second-computer setup works when the repo is present, and product E2E passed on `FalconXtreme`. Build the beginner/offline install path and final orchestration gate. Do not build protocol features. + +Allowed folders: +- infra/scripts/ +- docs/ +- .github/ +- README.md +- package.json +- docs/agent-runs/installer-ops/ + +Forbidden folders: +- crates/ +- services/ +- crypto/ +- contracts/ +- apps/dashboard/ +- hardware/ + +Create tracking files first: +- docs/agent-runs/installer-ops/PLAN.md +- docs/agent-runs/installer-ops/CHECKLIST.md +- docs/agent-runs/installer-ops/EXPERIMENTS.md +- docs/agent-runs/installer-ops/NOTES.md + +Quantitative goal: complete 10/10 checks below: +1. `npm run flowchain:l1-e2e` exists. +2. `flowchain:l1-e2e` runs product E2E plus all available subsystem E2E commands and fails clearly for missing ones. +3. One script creates an offline second-computer bundle without `.git`, `node_modules`, `target`, secrets, or local vaults. +4. One script installs/verifies prerequisites and runs the local package from that bundle. +5. Setup docs include a no-GitHub-login/offline-bundle path. +6. Setup docs include the authenticated private-repo path. +7. Troubleshooting docs cover offline node/API, Windows Cargo target locks, port conflicts, GitHub auth failures, and missing Build Tools. +8. The final local URLs and restart commands are printed by scripts. +9. `git diff --check` passes. +10. `npm run flowchain:product-e2e` still passes after your changes. + +Implementation constraints: +- Docs/scripts only. +- No product protocol implementation. +- No secret collection. +- No production claims. + +Feedback loop: +1. Run PowerShell syntax checks for changed scripts. +2. Run dry-run/offline-bundle creation. +3. Run `git diff --check`. +4. Run `npm run flowchain:product-e2e`. +5. If subsystem commands exist, run `npm run flowchain:l1-e2e`. + +PR output: +- Include exact setup command for non-technical second-computer use. +- Include exact commands run. +- List missing subsystem E2E commands. diff --git a/docs/agent-goals/flowchain-l1-long-loop/research-decisions.md b/docs/agent-goals/flowchain-l1-long-loop/research-decisions.md new file mode 100644 index 00000000..b38707ab --- /dev/null +++ b/docs/agent-goals/flowchain-l1-long-loop/research-decisions.md @@ -0,0 +1,52 @@ +/goal You are the FlowChain Research/Decisions long-loop agent. + +Worktree: E:\FlowMemory\flowmemory-research +Branch: agent/l1-loop-research-decisions + +Baseline: the project has a local/product testnet. Your job is to lock decisions that keep builders coherent. Do not implement product code. + +Allowed folders: +- research/ +- docs/DECISIONS/ +- docs/agent-runs/research-decisions/ +- research architecture docs under docs/ + +Forbidden folders: +- crates/ +- services/ +- apps/dashboard/ +- contracts/ +- crypto/ +- hardware/ + +Create tracking files first: +- docs/agent-runs/research-decisions/PLAN.md +- docs/agent-runs/research-decisions/CHECKLIST.md +- docs/agent-runs/research-decisions/EXPERIMENTS.md +- docs/agent-runs/research-decisions/NOTES.md + +Quantitative goal: complete 8/8 decision records: +1. Local consensus and fork-choice direction for the next private testnet. +2. Transaction envelope and account model boundary. +3. State storage, state-root, export/import, and pruning policy. +4. Wallet/key custody boundary for local/testnet and production-gated future. +5. Bridge security model for mock, local Anvil, Base Sepolia, and blocked mainnet. +6. Explorer/control-plane source-of-truth policy. +7. Hardware signal boundary and low-bandwidth assumptions. +8. Production gate checklist before public validators, mainnet, tokenomics, audited crypto, or real-funds bridge. + +Implementation constraints: +- Decisions must distinguish implemented, planned, and blocked. +- Cite current repo files where possible. +- Do not authorize production deployment. +- Do not create speculative tokenomics. + +Feedback loop: +1. Read current docs and issues. +2. Draft one decision record at a time. +3. Run `git diff --check`. +4. Run docs link/path checks if available. + +PR output: +- Include a decision summary table. +- Name builder issues unblocked by each decision. diff --git a/docs/agent-goals/flowchain-l1-long-loop/wallet-crypto.md b/docs/agent-goals/flowchain-l1-long-loop/wallet-crypto.md new file mode 100644 index 00000000..3834b897 --- /dev/null +++ b/docs/agent-goals/flowchain-l1-long-loop/wallet-crypto.md @@ -0,0 +1,56 @@ +/goal You are the FlowChain Wallet/Crypto long-loop agent. + +Worktree: E:\FlowMemory\flowmemory-crypto +Branch: agent/l1-loop-wallet-crypto + +Baseline: product transaction schemas and wallet product smoke already exist. Extend them. Do not create a second wallet system. + +Allowed folders: +- crypto/ +- schemas/flowmemory/ +- fixtures/crypto/ if present +- docs/agent-runs/wallet-crypto/ +- wallet/crypto docs under docs/ + +Forbidden folders: +- crates/ +- services/ +- apps/dashboard/ +- contracts/ +- hardware/ + +Create tracking files first: +- docs/agent-runs/wallet-crypto/PLAN.md +- docs/agent-runs/wallet-crypto/CHECKLIST.md +- docs/agent-runs/wallet-crypto/EXPERIMENTS.md +- docs/agent-runs/wallet-crypto/NOTES.md + +Quantitative goal: complete 10/10 checks below: +1. `npm test --prefix crypto` passes. +2. `npm run wallet:product-smoke --prefix crypto` passes. +3. A wallet E2E command exists and passes from root or crypto package. +4. The wallet can create, unlock, export public metadata, import test metadata, rotate local accounts, and list accounts. +5. The wallet can sign every current product transaction type. +6. The verifier rejects replay, wrong chain id, wrong signer role, mutated payload, malformed public key, duplicate nonce, and expired or missing envelope fields. +7. Test vectors include positive and negative cases for transfer, token launch, pool create, add/remove liquidity, swap, bridge credit ack, withdrawal intent, node/operator signal, and network join authorization if supported. +8. No exported public metadata contains private key, seed, mnemonic, RPC credential, API key, or webhook-shaped text. +9. Runtime/control-plane consumers can validate envelopes without importing secret-handling code. +10. `npm run flowchain:product-e2e` still passes after your changes. + +Implementation constraints: +- Use existing crypto helpers and schemas. +- Keep secrets local and ignored. +- Keep this testnet/local until a separate audit gate exists. +- Do not implement tokenomics or production custody. + +Feedback loop: +1. Run focused crypto tests. +2. Run wallet smoke. +3. Run schema/vector validation. +4. Run `npm run flowchain:product-e2e`. +5. If `npm run flowchain:l1-e2e` exists, run it last. + +PR output: +- Document schema/version changes. +- Include exact commands run. +- Name any runtime/control-plane integration contract that changed. diff --git a/infra/scripts/launch-flowchain-l1-long-loop-agents.ps1 b/infra/scripts/launch-flowchain-l1-long-loop-agents.ps1 new file mode 100644 index 00000000..c11eaf39 --- /dev/null +++ b/infra/scripts/launch-flowchain-l1-long-loop-agents.ps1 @@ -0,0 +1,144 @@ +param( + [switch] $DryRun, + [switch] $NoBranchPrepare +) + +$ErrorActionPreference = "Stop" +Set-StrictMode -Version Latest + +$repoRoot = (& git rev-parse --show-toplevel).Trim() +if ([string]::IsNullOrWhiteSpace($repoRoot)) { + throw "Run this script inside the FlowMemory repository." +} + +$promptRoot = Join-Path $repoRoot "docs\agent-goals\flowchain-l1-long-loop" + +$agents = @( + @{ + Name = "chain-network" + Worktree = "E:\FlowMemory\flowmemory-chain" + Branch = "agent/l1-loop-chain-network" + Prompt = "chain-network.md" + }, + @{ + Name = "wallet-crypto" + Worktree = "E:\FlowMemory\flowmemory-crypto" + Branch = "agent/l1-loop-wallet-crypto" + Prompt = "wallet-crypto.md" + }, + @{ + Name = "control-plane-explorer" + Worktree = "E:\FlowMemory\flowmemory-indexer" + Branch = "agent/l1-loop-control-plane-explorer" + Prompt = "control-plane-explorer.md" + }, + @{ + Name = "dashboard-workbench" + Worktree = "E:\FlowMemory\flowmemory-dashboard" + Branch = "agent/l1-loop-dashboard-workbench" + Prompt = "dashboard-workbench.md" + }, + @{ + Name = "bridge-testnet" + Worktree = "E:\FlowMemory\flowmemory-bridge-full" + Branch = "agent/l1-loop-bridge-testnet" + Prompt = "bridge-testnet.md" + }, + @{ + Name = "contracts-settlement" + Worktree = "E:\FlowMemory\flowmemory-contracts" + Branch = "agent/l1-loop-contracts-settlement" + Prompt = "contracts-settlement.md" + }, + @{ + Name = "installer-ops" + Worktree = "E:\FlowMemory\flowmemory-review" + Branch = "agent/l1-loop-installer-ops" + Prompt = "installer-ops.md" + }, + @{ + Name = "hardware-signals" + Worktree = "E:\FlowMemory\flowmemory-hardware" + Branch = "agent/l1-loop-hardware-signals" + Prompt = "hardware-signals.md" + }, + @{ + Name = "research-decisions" + Worktree = "E:\FlowMemory\flowmemory-research" + Branch = "agent/l1-loop-research-decisions" + Prompt = "research-decisions.md" + } +) + +function Invoke-Git { + param( + [Parameter(Mandatory = $true)] + [string] $WorkingDirectory, + + [Parameter(Mandatory = $true)] + [string[]] $Arguments + ) + + & git -C $WorkingDirectory @Arguments + if ($LASTEXITCODE -ne 0) { + throw "git $($Arguments -join ' ') failed in $WorkingDirectory" + } +} + +function Test-DirtyWorktree { + param([Parameter(Mandatory = $true)][string] $Path) + + $status = & git -C $Path status --short + if ($LASTEXITCODE -ne 0) { + throw "Could not inspect worktree: $Path" + } + return [bool] $status +} + +Write-Host "Fetching origin/main..." +Invoke-Git -WorkingDirectory $repoRoot -Arguments @("fetch", "origin", "main") + +foreach ($agent in $agents) { + $worktree = $agent.Worktree + $branch = $agent.Branch + $promptPath = Join-Path $promptRoot $agent.Prompt + + if (-not (Test-Path -LiteralPath $promptPath)) { + throw "Missing prompt file: $promptPath" + } + + if (-not (Test-Path -LiteralPath $worktree)) { + throw "Missing worktree: $worktree" + } + + if (-not $NoBranchPrepare) { + if (Test-DirtyWorktree -Path $worktree) { + Write-Warning "Skipping branch switch for dirty worktree: $worktree" + } + else { + Write-Host "Preparing $($agent.Name): $branch from origin/main" + if (-not $DryRun) { + Invoke-Git -WorkingDirectory $worktree -Arguments @("switch", "-C", $branch, "origin/main") + } + } + } + + $command = @" +`$prompt = Get-Content -Raw -LiteralPath "$promptPath" +Set-Location -LiteralPath "$worktree" +codex --cd "$worktree" -s danger-full-access -a never `$prompt +"@ + + Write-Host "Launching $($agent.Name) in $worktree" + if (-not $DryRun) { + Start-Process powershell.exe -ArgumentList @( + "-NoExit", + "-ExecutionPolicy", + "Bypass", + "-Command", + $command + ) + } +} + +Write-Host "FlowChain L1 long-loop agent launch complete."