From 23ef139adef26c7c0ac48ff462660f55f47bbec5 Mon Sep 17 00:00:00 2001 From: FlowmemoryAI <283694809+FlowmemoryAI@users.noreply.github.com> Date: Wed, 13 May 2026 00:44:04 -0500 Subject: [PATCH 1/5] Build FlowMemory HQ program manager OS --- .github/ISSUE_TEMPLATE/bug.yml | 66 ++++++- .github/ISSUE_TEMPLATE/feature.yml | 53 ++++- .github/ISSUE_TEMPLATE/hardware.yml | 65 ++++++- .github/ISSUE_TEMPLATE/research.yml | 62 +++++- .github/ISSUE_TEMPLATE/security.yml | 57 +++++- .github/pull_request_template.md | 10 + .github/workflows/ci.yml | 6 + AGENTS.md | 9 + README.md | 55 +++++- docs/AGENT_PROMPTS.md | 289 ++++++++++++++++++++++++++++ docs/AGENT_ROLES.md | 36 ++++ docs/ARCHITECTURE.md | 205 ++++++++++++++------ docs/CURRENT_STATE.md | 119 ++++++++---- docs/DAILY_HQ_RUNBOOK.md | 125 ++++++++++++ docs/DECISIONS/README.md | 58 +++++- docs/FLOWMEMORY_HQ_CONTEXT.md | 5 +- docs/ISSUE_BACKLOG.md | 132 +++++++++++++ docs/PROJECT_CHARTER.md | 5 +- docs/PR_PROCESS.md | 121 ++++++++++++ docs/ROADMAP.md | 153 +++++++++++---- docs/START_HERE.md | 4 + infra/scripts/status-report.ps1 | 78 ++++++++ 22 files changed, 1542 insertions(+), 171 deletions(-) create mode 100644 docs/AGENT_PROMPTS.md create mode 100644 docs/DAILY_HQ_RUNBOOK.md create mode 100644 docs/ISSUE_BACKLOG.md create mode 100644 docs/PR_PROCESS.md create mode 100644 infra/scripts/status-report.ps1 diff --git a/.github/ISSUE_TEMPLATE/bug.yml b/.github/ISSUE_TEMPLATE/bug.yml index 6b58c7c9..c6a06927 100644 --- a/.github/ISSUE_TEMPLATE/bug.yml +++ b/.github/ISSUE_TEMPLATE/bug.yml @@ -4,6 +4,10 @@ title: "[Bug]: " labels: - bug body: + - type: markdown + attributes: + value: | + Keep the report scoped. Do not include live secrets, private keys, seed phrases, RPC credentials, or exploitable private details. - type: textarea id: summary attributes: @@ -26,16 +30,66 @@ body: validations: required: true - type: textarea - id: reproduction + id: evidence attributes: - label: Reproduction Or Evidence + label: Evidence Or Reproduction description: Steps, logs, screenshots, file references, or reasoning. validations: required: false - type: textarea - id: scope + id: allowed_folders attributes: - label: Suspected Scope - description: Which area or directory is likely affected? + label: Allowed Folders + description: Which folders may be edited to fix this? + placeholder: | + - docs/ + - .github/ validations: - required: false + required: true + - type: textarea + id: forbidden_folders + attributes: + label: Forbidden Folders + description: Which folders must not be edited for this bug? + placeholder: | + - contracts/ + - services/ + - apps/ + validations: + required: true + - type: textarea + id: acceptance_criteria + attributes: + label: Acceptance Criteria + description: What must be true before this can close? + placeholder: | + - The stale statement is removed. + - The relevant docs agree with GitHub source of truth. + - Checks pass. + validations: + required: true + - type: dropdown + id: risk_level + attributes: + label: Risk Level + options: + - Low + - Medium + - High + validations: + required: true + - type: dropdown + id: recommended_agent_worktree + attributes: + label: Recommended Agent / Worktree + options: + - 'Review / maintenance - E:\FlowMemory\flowmemory-review' + - 'Protocol contracts - E:\FlowMemory\flowmemory-contracts' + - 'Services indexer/verifier - E:\FlowMemory\flowmemory-indexer' + - 'Apps dashboard/explorer - E:\FlowMemory\flowmemory-dashboard' + - 'Hardware - E:\FlowMemory\flowmemory-hardware' + - 'Research - E:\FlowMemory\flowmemory-research' + - 'Crypto - E:\FlowMemory\flowmemory-crypto' + - 'Chain/devnet research - E:\FlowMemory\flowmemory-chain' + validations: + required: true diff --git a/.github/ISSUE_TEMPLATE/feature.yml b/.github/ISSUE_TEMPLATE/feature.yml index cde35cf8..012ea1fd 100644 --- a/.github/ISSUE_TEMPLATE/feature.yml +++ b/.github/ISSUE_TEMPLATE/feature.yml @@ -2,7 +2,7 @@ name: Feature description: Propose a FlowMemory product, protocol, service, app, or infra feature. title: "[Feature]: " labels: - - feature + - enhancement body: - type: markdown attributes: @@ -16,17 +16,60 @@ body: validations: required: true - type: textarea - id: scope + id: allowed_folders attributes: - label: Scope + label: Allowed Folders description: Which directories, systems, or interfaces are in scope? + placeholder: | + - contracts/ + - tests/ validations: required: true - type: textarea - id: boundaries + id: forbidden_folders attributes: - label: Boundaries + label: Forbidden Folders description: What is explicitly out of scope? + placeholder: | + - apps/ + - services/ + - production deployment config + validations: + required: true + - type: textarea + id: acceptance_criteria + attributes: + label: Acceptance Criteria + description: What must be true before this can close? + placeholder: | + - The implementation stays inside the allowed folders. + - Relevant docs are updated. + - Tests or checks are documented. + validations: + required: true + - type: dropdown + id: risk_level + attributes: + label: Risk Level + options: + - Low + - Medium + - High + validations: + required: true + - type: dropdown + id: recommended_agent_worktree + attributes: + label: Recommended Agent / Worktree + options: + - 'Review / maintenance - E:\FlowMemory\flowmemory-review' + - 'Protocol contracts - E:\FlowMemory\flowmemory-contracts' + - 'Services indexer/verifier - E:\FlowMemory\flowmemory-indexer' + - 'Apps dashboard/explorer - E:\FlowMemory\flowmemory-dashboard' + - 'Hardware - E:\FlowMemory\flowmemory-hardware' + - 'Research - E:\FlowMemory\flowmemory-research' + - 'Crypto - E:\FlowMemory\flowmemory-crypto' + - 'Chain/devnet research - E:\FlowMemory\flowmemory-chain' validations: required: true - type: textarea diff --git a/.github/ISSUE_TEMPLATE/hardware.yml b/.github/ISSUE_TEMPLATE/hardware.yml index ccb2f8df..d4b066ba 100644 --- a/.github/ISSUE_TEMPLATE/hardware.yml +++ b/.github/ISSUE_TEMPLATE/hardware.yml @@ -2,12 +2,12 @@ name: Hardware description: Track FlowRouter, Meshtastic, LoRa, enclosure, or field-test work. title: "[Hardware]: " labels: - - hardware + - documentation body: - type: markdown attributes: value: | - Meshtastic and LoRa are low-bandwidth control signaling paths. Do not assume normal internet bandwidth. + Meshtastic and LoRa are low-bandwidth control signaling paths. Do not assume normal internet bandwidth or production readiness. - type: textarea id: objective attributes: @@ -16,23 +16,70 @@ body: validations: required: true - type: textarea - id: components + id: allowed_folders attributes: - label: Components - description: Devices, radios, sensors, enclosure parts, boards, or power systems involved. + label: Allowed Folders + description: Which hardware/docs folders may be edited? + placeholder: | + - hardware/ + - docs/ARCHITECTURE.md + - docs/SECURITY_MODEL.md validations: - required: false + required: true + - type: textarea + id: forbidden_folders + attributes: + label: Forbidden Folders + description: Which folders or work types must not be touched? + placeholder: | + - contracts/ + - services/ + - apps/ + - production firmware + - deployment config + validations: + required: true - type: textarea id: constraints attributes: label: Constraints - description: Bandwidth, power, size, thermal, safety, field, or manufacturing constraints. + description: Bandwidth, power, size, thermal, safety, field, manufacturing, or regulatory constraints. + validations: + required: true + - type: textarea + id: acceptance_criteria + attributes: + label: Acceptance Criteria + description: What must be true before this can close? + placeholder: | + - Low-bandwidth limits are explicit. + - Safety or field risks are named. + - No production hardware commitment is implied. + validations: + required: true + - type: dropdown + id: risk_level + attributes: + label: Risk Level + options: + - Low + - Medium + - High + validations: + required: true + - type: dropdown + id: recommended_agent_worktree + attributes: + label: Recommended Agent / Worktree + options: + - 'Hardware - E:\FlowMemory\flowmemory-hardware' + - 'Review / maintenance - E:\FlowMemory\flowmemory-review' validations: required: true - type: textarea id: validation attributes: - label: Validation - description: How should this be tested or field-validated? + label: Tests Or Validation + description: How should this be tested, reviewed, or field-validated? validations: required: false diff --git a/.github/ISSUE_TEMPLATE/research.yml b/.github/ISSUE_TEMPLATE/research.yml index 2e5f623d..3b6a8331 100644 --- a/.github/ISSUE_TEMPLATE/research.yml +++ b/.github/ISSUE_TEMPLATE/research.yml @@ -2,12 +2,12 @@ name: Research description: Track AI memory, neural geometry, protocol, reliability, or appchain/L1 research. title: "[Research]: " labels: - - research + - documentation body: - type: markdown attributes: value: | - Use this for research questions, hypotheses, experiments, and literature notes. + Use this for research questions, hypotheses, experiments, and literature notes. Mark unknowns as unknowns. - type: textarea id: question attributes: @@ -15,20 +15,68 @@ body: description: What are we trying to learn? validations: required: true + - type: textarea + id: allowed_folders + attributes: + label: Allowed Folders + description: Which folders may be edited? + placeholder: | + - research/ + - docs/DECISIONS/ + - docs/ARCHITECTURE.md + validations: + required: true + - type: textarea + id: forbidden_folders + attributes: + label: Forbidden Folders + description: Which folders or claims are out of scope? + placeholder: | + - contracts/ + - services/ + - apps/ + - production deployment plans + validations: + required: true - type: textarea id: context attributes: label: Context - description: What project context or prior work matters? + description: What project context, prior work, or source material matters? validations: required: true - type: textarea - id: method + id: acceptance_criteria attributes: - label: Proposed Method - description: How should the research be conducted? + label: Acceptance Criteria + description: What must be true before this can close? + placeholder: | + - Hypotheses are separated from accepted decisions. + - Unknowns are listed. + - Follow-up implementation issues are separate. validations: - required: false + required: true + - type: dropdown + id: risk_level + attributes: + label: Risk Level + options: + - Low + - Medium + - High + validations: + required: true + - type: dropdown + id: recommended_agent_worktree + attributes: + label: Recommended Agent / Worktree + options: + - 'Research - E:\FlowMemory\flowmemory-research' + - 'Review / maintenance - E:\FlowMemory\flowmemory-review' + - 'Crypto - E:\FlowMemory\flowmemory-crypto' + - 'Chain/devnet research - E:\FlowMemory\flowmemory-chain' + validations: + required: true - type: textarea id: output attributes: diff --git a/.github/ISSUE_TEMPLATE/security.yml b/.github/ISSUE_TEMPLATE/security.yml index b31f5822..7b051ff1 100644 --- a/.github/ISSUE_TEMPLATE/security.yml +++ b/.github/ISSUE_TEMPLATE/security.yml @@ -2,7 +2,7 @@ name: Security description: Report or track protocol, service, hardware, crypto, or operational security work. title: "[Security]: " labels: - - security + - documentation body: - type: markdown attributes: @@ -30,6 +30,27 @@ body: description: What is the security concern? validations: required: true + - type: textarea + id: allowed_folders + attributes: + label: Allowed Folders + description: Which folders may be edited for this security task? + placeholder: | + - docs/SECURITY_MODEL.md + - .github/ + validations: + required: true + - type: textarea + id: forbidden_folders + attributes: + label: Forbidden Folders + description: Which folders or risky actions are out of scope? + placeholder: | + - production deployment config + - private keys or live credentials + - tokenomics + validations: + required: true - type: textarea id: impact attributes: @@ -37,6 +58,40 @@ body: description: What could go wrong if this is real? validations: required: true + - type: textarea + id: acceptance_criteria + attributes: + label: Acceptance Criteria + description: What must be true before this can close? + placeholder: | + - The affected trust boundary is documented. + - No live secrets are exposed. + - Mitigation or next investigation step is clear. + validations: + required: true + - type: dropdown + id: risk_level + attributes: + label: Risk Level + options: + - Low + - Medium + - High + validations: + required: true + - type: dropdown + id: recommended_agent_worktree + attributes: + label: Recommended Agent / Worktree + options: + - 'Review / maintenance - E:\FlowMemory\flowmemory-review' + - 'Protocol contracts - E:\FlowMemory\flowmemory-contracts' + - 'Services indexer/verifier - E:\FlowMemory\flowmemory-indexer' + - 'Hardware - E:\FlowMemory\flowmemory-hardware' + - 'Crypto - E:\FlowMemory\flowmemory-crypto' + - 'Chain/devnet research - E:\FlowMemory\flowmemory-chain' + validations: + required: true - type: textarea id: recommendation attributes: diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 3d0a0565..8d60ceb6 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -8,6 +8,13 @@ - TBD +## Scope + +- Allowed folders: +- Forbidden folders: +- Recommended agent/worktree: +- Risk level: Low / Medium / High + ## Tests Or Checks - [ ] I ran the relevant tests or checks. @@ -21,6 +28,9 @@ - [ ] I read `docs/CURRENT_STATE.md`. - [ ] I only edited files in my assigned scope. - [ ] I did not hardcode secrets. +- [ ] I did not add production deployment automation unless explicitly scoped. +- [ ] I did not add tokenomics or appchain/L1 implementation unless explicitly scoped. +- [ ] I did not add dynamic fees, production hook deployment, hardware manufacturing, GPU proofs, verifier economics, or full dashboard implementation unless explicitly scoped. ## Risk And Follow-Ups diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index d5f27cb1..67d1454d 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -32,6 +32,11 @@ jobs: "docs/SECURITY_MODEL.md" "docs/AGENT_ROLES.md" "docs/DECISIONS" + "contracts/FLOWPULSE_SCHEMA.md" + "contracts/FlowPulse.sol" + "contracts/RootfieldRegistry.sol" + "tests/README.md" + "tests/RootfieldRegistry.t.sol" "contracts" "services" "apps" @@ -39,6 +44,7 @@ jobs: "research" "crypto" "infra/scripts" + "infra/scripts/setup-worktrees.ps1" "inbox/claude-code" "inbox/old-prompts" "inbox/unsorted" diff --git a/AGENTS.md b/AGENTS.md index a64b52f9..246e9599 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -18,6 +18,15 @@ These instructions apply to every agent, assistant, script, and human operating - Do not build product features during bootstrap, planning, or research tasks. - When blocked, document the blocker and the smallest useful next step. +## HQ Program Management + +- Use `docs/ISSUE_BACKLOG.md` to understand issue dependencies and milestone placement. +- Use `docs/AGENT_PROMPTS.md` when launching or briefing a worktree agent. +- Use `docs/PR_PROCESS.md` for branch naming, draft PRs, merge order, dirty worktrees, and issue closing. +- Use `docs/DAILY_HQ_RUNBOOK.md` for morning review, triage, monitoring, and handoff. +- Use `infra/scripts/status-report.ps1` for read-only local worktree, PR, and issue status. +- The immediate major milestone is a runnable local V0 stack. Do not reinterpret that as approval for production deployment. + ## Engineering Rules - Do not hardcode secrets, tokens, private keys, seed phrases, RPC credentials, API keys, or webhook URLs. diff --git a/README.md b/README.md index aed1790a..30423235 100644 --- a/README.md +++ b/README.md @@ -2,12 +2,12 @@ FlowMemory is a Base-native AI memory, neural-geometry, reliability, decentralized hardware, and future appchain/L1 research project. -This repository is currently in bootstrap mode. It contains project context, collaboration rules, planning documents, GitHub templates, and placeholder directories for future implementation work. Do not treat the current repo as containing production product features yet. +This repository has completed the initial bootstrap and contracts-foundation passes. It contains project context, collaboration rules, planning documents, GitHub templates, a CI scaffold, worktree setup, placeholder work areas, and an initial FlowPulse/Rootfield contracts foundation. Do not treat the current repo as containing production product features yet. ## What FlowMemory Is Exploring -- Base and Uniswap v4 hook integrations -- FlowPulse events +- Base and future Uniswap v4 hook integrations +- FlowPulse event schema v0 and future event expansion - Rootflow and Rootfield state commitments - AI memory and neural geometry research - FlowRouter decentralized internet hardware @@ -27,6 +27,7 @@ This repository is currently in bootstrap mode. It contains project context, col - Indexers and verifiers derive `txHash` and `logIndex` after reading receipts and logs. - Heavy AI, model, memory, and artifact data stays off-chain. - On-chain state stores roots, receipts, commitments, attestations, proofs, and work state. +- `metadataURI` and `evidenceURI` values are emitted as on-chain log bytes and are not contract-enforced as short pointers. - Meshtastic and LoRa are low-bandwidth control signaling paths, not normal internet bandwidth. ## Start Here @@ -37,21 +38,65 @@ Every contributor and agent should read: 2. `docs/START_HERE.md` 3. `docs/FLOWMEMORY_HQ_CONTEXT.md` 4. `docs/CURRENT_STATE.md` +5. `docs/DAILY_HQ_RUNBOOK.md` if operating HQ or coordinating agents Then work only inside the assigned scope. +## HQ Operating System + +FlowMemory is managed as a multi-agent program. The management layer is part of the repo and should be kept current before large subsystem work begins. + +- `docs/ISSUE_BACKLOG.md`: maps issues #6-#55 into milestones, dependencies, and agent worktrees +- `docs/AGENT_PROMPTS.md`: copy-ready prompts for each worktree +- `docs/PR_PROCESS.md`: branch, draft PR, review, merge, conflict, and issue-closing rules +- `docs/DAILY_HQ_RUNBOOK.md`: morning review, triage, agent launch, PR monitoring, merge order, and handoff +- `infra/scripts/status-report.ps1`: read-only local worktree, PR, and issue status report + +Immediate major milestone: build a runnable local V0 stack. This means local contracts/tests, FlowPulse fixtures, indexer/verifier schemas, crypto vocabulary, app data model, and local smoke-test gates. It does not mean production deployment. + +## What Not To Claim + +- Do not claim FlowMemory has production contracts or deployment automation. +- Do not claim Uniswap v4 hook integration exists yet. +- Do not claim indexer, verifier, dashboard, explorer, hardware console, FlowRouter hardware, or Meshtastic integration exists yet. +- Do not claim cryptographic proof systems, tokenomics, or appchain/L1 implementation exists yet. +- Do not claim URI fields enforce off-chain storage. Current URI values are caller-supplied log data. + ## Repository Map - `apps/`: future dashboard, explorer, and hardware console applications -- `contracts/`: future on-chain protocol and hook contracts +- `contracts/`: FlowPulse schema/interface, RootfieldRegistry foundation, and future on-chain protocol and hook contracts - `crypto/`: future cryptographic receipt, proof, and attestation work - `docs/`: project context, architecture, roadmap, security model, and decisions - `hardware/`: future FlowRouter, LoRa, Meshtastic, and enclosure work -- `infra/scripts/`: future automation and repository maintenance scripts +- `infra/scripts/`: worktree setup and future automation or repository maintenance scripts - `inbox/`: staging area for imported prompts, notes, and unsorted context - `research/`: future AI memory, neural geometry, and appchain/L1 research - `services/`: future indexer, verifier, worker, and API services +## Implemented Foundation + +- Repo operating system: `AGENTS.md`, start-here docs, current state, roadmap, architecture, security model, agent roles, and decision-record home +- GitHub issue and pull request templates +- Repository hygiene CI scaffold +- Worktree setup script +- `contracts/FlowPulse.sol` +- `contracts/RootfieldRegistry.sol` +- `contracts/FLOWPULSE_SCHEMA.md` +- `tests/RootfieldRegistry.t.sol` +- Initial Foundry tests for the Rootfield registry foundation +- Documented URI/log-data limitations for the current contract skeleton + +## Still Conceptual + +- Uniswap v4 hook integration +- Indexer and verifier services +- FlowRouter hardware implementation +- Meshtastic integration +- Dashboard, explorer, and hardware console applications +- Cryptographic proof systems +- Appchain/L1 design and implementation + ## Current Status See `docs/CURRENT_STATE.md` for the latest repo state. diff --git a/docs/AGENT_PROMPTS.md b/docs/AGENT_PROMPTS.md new file mode 100644 index 00000000..1fddcf87 --- /dev/null +++ b/docs/AGENT_PROMPTS.md @@ -0,0 +1,289 @@ +# Agent Prompts + +Use these prompts when starting Codex agents in dedicated worktrees. Replace issue numbers and task text with the assigned GitHub issue. + +Every prompt begins with this common instruction: + +```text +You are a FlowMemory agent working from a dedicated Git worktree. + +Read first: +- AGENTS.md +- docs/START_HERE.md +- docs/FLOWMEMORY_HQ_CONTEXT.md +- docs/CURRENT_STATE.md +- docs/ROADMAP.md +- docs/ARCHITECTURE.md +- docs/ISSUE_BACKLOG.md + +Work only on the assigned GitHub issue. Copy the issue's objective, allowed folders, forbidden folders, acceptance criteria, risk level, and recommended worktree into your local plan before editing. + +Do not build outside scope. Do not add tokenomics, dynamic fees, production deployment, production Uniswap v4 hook deployment, production L1/appchain, hardware manufacturing, GPU proofs, verifier economics, or full dashboard implementation unless the issue explicitly allows it. + +Before finishing, run git status --short --branch and git diff --check. Run area-specific tests or checks when they exist. End with changed files, checks run, risks, assumptions, and follow-up issues. +``` + +## Contracts Agent + +Worktree: `E:\FlowMemory\flowmemory-contracts` + +Allowed by default: + +- `contracts/` +- `tests/` +- `foundry.toml` +- Contract-related decision records when the issue allows docs + +Forbidden by default: + +- `services/` +- `apps/` +- `hardware/` +- `research/` +- `crypto/` unless explicitly assigned +- Production deployment config + +Required checks: + +- `forge test` when Foundry config exists. +- `git diff --check`. + +Prompt suffix: + +```text +Assigned issue: #. +Keep this to contracts foundation hardening. Do not add deployment scripts, tokenomics, dynamic fees, production hooks, or governance mechanics unless a separate accepted issue explicitly scopes them. +``` + +## Indexer/Verifier Agent + +Worktree: `E:\FlowMemory\flowmemory-indexer` + +Allowed by default: + +- `services/indexer/` +- `services/verifier/` +- Shared docs only when the issue allows cross-links + +Forbidden by default: + +- `contracts/` +- `apps/` +- `hardware/` +- `research/` +- `crypto/` unless explicitly assigned +- Production service deployment + +Required checks: + +- Schema or fixture validation commands added by the issue. +- `git diff --check`. + +Prompt suffix: + +```text +Assigned issue: #. +Keep receipt metadata derived from receipts/logs only. Do not build live production indexing, hosted services, verifier economics, or APIs unless explicitly scoped. +``` + +## Crypto Agent + +Worktree: `E:\FlowMemory\flowmemory-crypto` + +Allowed by default: + +- `crypto/` +- Crypto-related docs or decision records when the issue allows them + +Forbidden by default: + +- `contracts/` +- `services/` +- `apps/` +- `hardware/` +- `research/` unless explicitly assigned +- Proof circuits, GPU proofs, verifier economics, production crypto infrastructure + +Required checks: + +- Test-vector validation if vectors are changed. +- `git diff --check`. + +Prompt suffix: + +```text +Assigned issue: #. +Define vocabulary, schemas, domain separation, and validation boundaries. Do not implement a proof system or verifier network unless a later accepted issue explicitly scopes it. +``` + +## Chain/Devnet Research Agent + +Worktree: `E:\FlowMemory\flowmemory-chain` + +Allowed by default: + +- `research/` +- Devnet/appchain docs when explicitly scoped +- Cross-links in `docs/ROADMAP.md` or `docs/ARCHITECTURE.md` only when needed + +Forbidden by default: + +- `contracts/` +- `services/` +- `apps/` +- `hardware/` +- Tokenomics, validators, sequencers, bridges, production deployment + +Required checks: + +- `git diff --check`. + +Prompt suffix: + +```text +Assigned issue: #. +Keep this no-value and research-only. Do not design or deploy a production chain, token, validator set, bridge, or sequencer. +``` + +## Dashboard Agent + +Worktree: `E:\FlowMemory\flowmemory-dashboard` + +Allowed by default: + +- `apps/` +- App data-model docs when scoped + +Forbidden by default: + +- `contracts/` +- `services/` +- `hardware/` +- `crypto/` +- `research/` +- Full frontend implementation, production APIs, deployment config + +Required checks: + +- `git diff --check`. + +Prompt suffix: + +```text +Assigned issue: #. +Define operator and explorer data models before UI. Do not scaffold a full dashboard or production API unless a later issue explicitly scopes that build. +``` + +## Hardware Agent + +Worktree: `E:\FlowMemory\flowmemory-hardware` + +Allowed by default: + +- `hardware/` +- Hardware-related architecture or security notes when scoped + +Forbidden by default: + +- `contracts/` +- `services/` +- `apps/` +- `crypto/` +- `research/` unless explicitly assigned +- Firmware production, final CAD, manufacturing files, production deployment + +Required checks: + +- `git diff --check`. + +Prompt suffix: + +```text +Assigned issue: #. +Treat FlowRouter as research hardware. Treat Meshtastic and LoRa as low-bandwidth control signaling only. Do not claim manufacturing readiness, broadband-over-LoRa, ISP replacement, or production field deployment. +``` + +## Research Agent + +Worktree: `E:\FlowMemory\flowmemory-research` + +Allowed by default: + +- `research/` +- Cross-link docs when scoped + +Forbidden by default: + +- `contracts/` +- `services/` +- `apps/` +- `hardware/` +- `crypto/` unless explicitly assigned +- Model training pipelines, large artifacts, production chain work + +Required checks: + +- `git diff --check`. + +Prompt suffix: + +```text +Assigned issue: #. +Separate hypotheses, experiments, accepted decisions, and open questions. Keep heavy artifacts off-chain and out of the repo. +``` + +## Review/HQ Agent + +Worktree: `E:\FlowMemory\flowmemory-review` + +Allowed by default: + +- `docs/` +- `.github/` +- `infra/scripts/` +- `README.md` +- `AGENTS.md` + +Forbidden by default: + +- Product implementation in subsystem folders +- Protocol behavior changes +- Runtime services +- Frontend implementation +- Hardware manufacturing files + +Required checks: + +- `git diff --check`. +- PowerShell parser check for changed `.ps1` files. + +Prompt suffix: + +```text +Assigned issue: #. +You are the program manager and reviewer. Keep source-of-truth docs, issue mapping, PR process, runbooks, templates, labels, milestones, and scripts aligned. Do not implement subsystem product work. +``` + +## PR Summary Format + +Use this structure in every PR: + +```md +## Summary +- TBD + +## Scope +- Issue: +- Allowed folders: +- Forbidden folders: +- Worktree: +- Risk level: + +## Checks +- [ ] git status --short --branch +- [ ] git diff --check +- [ ] Area-specific tests/checks: + +## Risks And Follow-Ups +- TBD +``` diff --git a/docs/AGENT_ROLES.md b/docs/AGENT_ROLES.md index 30549045..116cd313 100644 --- a/docs/AGENT_ROLES.md +++ b/docs/AGENT_ROLES.md @@ -2,6 +2,24 @@ Agents may be assigned one of these roles. Each role should still read `AGENTS.md`, `docs/START_HERE.md`, `docs/FLOWMEMORY_HQ_CONTEXT.md`, and `docs/CURRENT_STATE.md`. +## Shared Folder Boundary Rules + +- Work only in the folders named by the issue or assignment. +- Treat issue "Allowed folders" as the write boundary, not just a suggestion. +- Do not edit forbidden folders even for cleanup unless the issue is updated first. +- Cross-link docs instead of moving code or expanding scope. +- If a task appears to need another agent's folder, stop and create or request a follow-up issue. + +## Recommended Worktrees + +- `E:\FlowMemory\flowmemory-contracts`: protocol contracts work +- `E:\FlowMemory\flowmemory-indexer`: services, indexer, and verifier work +- `E:\FlowMemory\flowmemory-dashboard`: apps, dashboard, explorer, and console work +- `E:\FlowMemory\flowmemory-hardware`: hardware, FlowRouter, LoRa, and Meshtastic work +- `E:\FlowMemory\flowmemory-research`: AI memory, neural geometry, reliability, and appchain/L1 research +- `E:\FlowMemory\flowmemory-crypto`: receipts, attestations, roots, proofs, and commitment-format work +- `E:\FlowMemory\flowmemory-review`: review, docs maintenance, templates, and repo hygiene + ## Bootstrap Agent Scope: @@ -13,6 +31,8 @@ Scope: Do not build product features. +Default worktree: `E:\FlowMemory\flowmemory-review` + ## Protocol Contracts Agent Scope: @@ -25,6 +45,8 @@ Scope: Must document event and storage assumptions. +Default worktree: `E:\FlowMemory\flowmemory-contracts` + ## Services Agent Scope: @@ -37,6 +59,8 @@ Scope: Must derive `txHash` and `logIndex` from receipts and logs, not from hook execution assumptions. +Default worktree: `E:\FlowMemory\flowmemory-indexer` + ## Apps Agent Scope: @@ -48,6 +72,8 @@ Scope: Must distinguish observed, verified, pending, and failed states in UI. +Default worktree: `E:\FlowMemory\flowmemory-dashboard` + ## Hardware Agent Scope: @@ -60,6 +86,8 @@ Scope: Must treat radio links as low-bandwidth control signaling. +Default worktree: `E:\FlowMemory\flowmemory-hardware` + ## Research Agent Scope: @@ -72,6 +100,8 @@ Scope: Must separate hypotheses, experiments, and accepted decisions. +Default worktree: `E:\FlowMemory\flowmemory-research` + ## Crypto Agent Scope: @@ -85,6 +115,8 @@ Scope: Must document threat assumptions and verification requirements. +Default worktree: `E:\FlowMemory\flowmemory-crypto` + ## Infra Agent Scope: @@ -96,6 +128,8 @@ Scope: Must avoid leaking secrets through scripts, logs, or CI output. +Default worktree: `E:\FlowMemory\flowmemory-review` + ## Security Agent Scope: @@ -107,6 +141,8 @@ Scope: Must create actionable issues or PR comments for findings. +Default worktree: `E:\FlowMemory\flowmemory-review` + ## Handoff Format Every agent should finish with: diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 9d804787..d44007fe 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -1,88 +1,185 @@ # Architecture -## Overview +FlowMemory is a layered system for commitment-oriented AI memory, verification, local operator tooling, and bounded hardware research. Only the repository operating system and initial contracts foundation are implemented. Everything else is either specification, local fixture work, or research until explicitly merged. -FlowMemory is organized as a layered system: +## Layer Map -1. On-chain protocol layer on Base -2. Off-chain indexing and verification layer -3. AI memory and neural-geometry research layer -4. Hardware and control-signaling layer -5. Operator apps and explorer layer -6. Future appchain/L1 research layer +1. Contracts foundation +2. Integration harness and local fixtures +3. Indexer/verifier +4. Crypto schema layer +5. Dashboard and operator apps +6. Hardware and control signaling +7. Research lab +8. Devnet/appchain research +9. HQ program operating system -No layer is fully implemented yet. +## Contracts -## On-Chain Layer +Current implementation: -Expected responsibilities: +- `contracts/FlowPulse.sol` defines the FlowPulse v0 event interface and pulse type constants. +- `contracts/RootfieldRegistry.sol` registers Rootfield namespaces, accepts root commitments, and emits FlowPulse events. +- `contracts/FLOWPULSE_SCHEMA.md` documents event semantics. +- `tests/RootfieldRegistry.t.sol` provides initial Foundry tests. + +Responsibilities: - Emit FlowPulse events. -- Store intentional protocol state. -- Store roots, receipts, commitments, attestations, proofs, and work state where appropriate. -- Integrate with Base and possibly Uniswap v4 hooks. +- Store intentional compact protocol state. +- Store roots, receipts, commitments, attestations, proofs, and work state only when deliberately part of the protocol. + +Boundaries: + +- Contracts do not store heavy AI memory, model artifacts, media, or raw evidence. +- Contracts do not know final `txHash` or `logIndex`. +- `metadataURI` and `evidenceURI` are advisory log strings in the current skeleton. +- Dynamic fees, tokenomics, production deployment, and production hooks are out of scope. + +## Integration Harness And Local Fixtures + +Purpose: + +- Connect contracts, fixture logs, parser expectations, verifier report shape, and local smoke tests. +- Provide a runnable local V0 stack before live service or production deployment work. + +Expected artifacts: + +- Foundry test output. +- FlowPulse fixture logs. +- Local devnet smoke-test notes. +- Receipt fixture handoff documents. +- Deterministic parser and verifier fixture expectations. Boundaries: -- On-chain storage is expensive. -- Transaction hashes are identifiers, not arbitrary data storage. -- Uniswap v4 hooks cannot know final `txHash` or `logIndex`. -- Contracts should not pretend to know receipt metadata that only exists after execution. +- No mainnet deployment. +- No production RPC credentials. +- No hosted services. + +## Indexer And Verifier -## Indexer And Verifier Layer +Status: specification and fixture work only. -Expected responsibilities: +Responsibilities: - Read receipts and logs. -- Derive `txHash` and `logIndex`. +- Derive `txHash`, `logIndex`, block metadata, and observation identity. - Reconstruct FlowPulse streams. -- Resolve off-chain artifacts. -- Verify roots, receipts, commitments, attestations, and proofs. -- Produce deterministic verification outputs. +- Track pending, finalized, duplicate, invalid, unsupported, unresolved, and reorged states. +- Verify commitments against allowed off-chain evidence. +- Produce deterministic verification reports. + +Boundaries: + +- Indexers and verifiers derive receipt metadata after execution. +- Service runtimes, persistence, APIs, and live RPC readers should follow fixture and schema decisions. +- Verifier economics, staking, slashing, and production networks are out of scope. + +## Crypto + +Status: vocabulary and schema planning only. + +Responsibilities: + +- Define receipts, attestations, roots, commitments, proofs, report digests, and signature envelopes. +- Define domain separation, replay boundaries, canonical serialization, and test-vector expectations. +- Support verifier/report schemas without forcing a proof system. + +Boundaries: -## AI Memory Layer +- No proof circuits. +- No GPU proofs. +- No verifier economics. +- No production cryptographic infrastructure. -Expected responsibilities: +## Dashboard -- Store and process heavy memory, model, embedding, and artifact data off-chain. -- Commit to important data through roots or receipts. -- Support research into neural geometry, retrieval, continuity, compression, and reliability. +Status: data model planning only. -## Hardware Layer +Responsibilities: -Expected responsibilities: +- Define app-facing entities for operator dashboard and protocol explorer. +- Present observed, pending, finalized, verified, invalid, unresolved, unsupported, and reorged states clearly. +- Consume indexer/verifier outputs once local schemas stabilize. -- Explore FlowRouter hardware. -- Test Meshtastic and LoRa sidecar signaling. -- Prototype 3D-printed enclosures. -- Define device identity, operator controls, and field diagnostics. +Boundaries: + +- No frontend scaffolding until the data model is accepted. +- No production APIs. +- No full dashboard implementation in the foundation-hardening phase. + +## Hardware + +Status: bounded research and POC planning only. + +Responsibilities: + +- Define FlowRouter v0 research scope. +- Explore Meshtastic and LoRa control-signaling messages. +- Explore enclosure, NFC memory cartridge, FlowCore indicator, and two-node demo concepts. +- Track physical, operator, power, cooling, and radio assumptions. Boundaries: -- LoRa and Meshtastic are low-bandwidth control channels. -- Heavy data transfer must use appropriate network paths, not radio sidecar links. +- Meshtastic and LoRa are low-bandwidth control channels. +- Hardware work must not claim broadband-over-LoRa, ISP replacement, production mesh, or manufacturing readiness. +- Firmware production, final CAD, RF certification, manufacturing files, and production deployment are out of scope. + +## Research + +Status: research-only. + +Responsibilities: + +- Define AI memory artifact taxonomy. +- Separate hypotheses, experiments, accepted decisions, and committed artifacts. +- Track neural geometry, retrieval, continuity, compression, reliability, and proof-carrying receipt research. + +Boundaries: + +- Heavy memory and model artifacts stay off-chain. +- No model training pipeline is implied by architecture docs. +- Research notes do not authorize protocol implementation. + +## Devnet And Appchain Research + +Status: gated research only. + +Responsibilities: + +- Define no-value local devnet criteria. +- Define Base settlement anchor specs. +- Research bridge/security review requirements. +- Define appchain hardware-node implications. + +Boundaries: -## App Layer +- No production L1 or appchain. +- No tokenomics. +- No validator or sequencer deployment. +- No bridge deployment. -Expected responsibilities: +## HQ Program Operating System -- Dashboard for operators. -- Explorer for protocol and verification state. -- Hardware console for FlowRouter and sidecar status. +Responsibilities: -## Future Appchain/L1 Layer +- Keep `docs/CURRENT_STATE.md`, `docs/ROADMAP.md`, this architecture doc, and `docs/ISSUE_BACKLOG.md` current. +- Keep agent prompts and PR process enforceable. +- Maintain labels, milestones, review flow, and daily runbook. +- Prevent agents from overlapping folders or expanding into gated work. -Expected responsibilities: +## Data Flow -- Research whether FlowMemory needs a dedicated execution, settlement, or verification environment. -- Compare appchain/L1 options against Base-native design. -- Define criteria before implementation. +1. A local or future deployed contract action emits FlowPulse and updates compact on-chain state. +2. The local harness or chain client produces receipts and logs. +3. The indexer reads logs and receipts, then derives `txHash`, `logIndex`, block metadata, and observation identity. +4. The verifier consumes indexed observations and checks commitments against allowed off-chain evidence. +5. Crypto schemas define report digests, attestations, commitments, and domain separation. +6. Dashboard models consume observation and verification states. +7. Hardware sidecars may exchange compact control messages or receipt references, but not heavy data. +8. Research artifacts stay off-chain and become protocol-relevant only through explicit commitments or accepted decision records. -## Data Flow Sketch +## Source Of Truth Flow -1. A protocol action emits events and updates intentional on-chain state. -2. Indexers read receipts and logs after execution. -3. Indexers derive transaction and log metadata. -4. Verifiers check off-chain artifacts against commitments and roots. -5. Apps present state, proofs, and operational health. -6. Hardware sidecars exchange compact control signals where useful. +GitHub issues define planned work. Pull requests propose changes. Merged files update source truth. `docs/CURRENT_STATE.md` summarizes what is actually merged. Unmerged worktree changes are not source truth. diff --git a/docs/CURRENT_STATE.md b/docs/CURRENT_STATE.md index ec0deb6d..ae7b26b6 100644 --- a/docs/CURRENT_STATE.md +++ b/docs/CURRENT_STATE.md @@ -1,56 +1,97 @@ # Current State -Last updated: 2026-05-12 +Last updated: 2026-05-13 -## Repository State +This file is the beginner-friendly source of truth for what exists in FlowMemory right now. It should stay factual, dated, and conservative. GitHub issues, pull requests, and merged files remain the final project record. -The repository is in bootstrap mode. +## Repo Phase -Before bootstrap, the repository contained: +FlowMemory is in foundation hardening. -- `README.md` +The bootstrap repository operating system and first contracts foundation have merged. The next major target is a runnable local V0 stack that connects contract fixtures, local indexing/verifier specs or fixtures, crypto schema vocabulary, and operator-facing data models without production deployment. -This bootstrap pass adds: +## Implemented In The Merged Repo -- Agent instructions -- Project docs -- Decision record directory -- Work-area directories -- GitHub issue and pull request templates -- A conservative CI workflow for repository hygiene +Repository operating system: -## Implementation State +- `AGENTS.md` with shared agent instructions. +- `docs/START_HERE.md` with required reading order and local multi-agent worktree workflow. +- Source-of-truth docs for context, roadmap, architecture, security model, project charter, agent roles, and current state. +- `docs/DECISIONS/` for durable decision records. +- GitHub issue and pull request templates. +- Conservative repository hygiene CI. +- `infra/scripts/setup-worktrees.ps1` for local multi-agent worktrees under `E:\FlowMemory`. +- Placeholder work areas for `contracts/`, `services/`, `apps/`, `hardware/`, `research/`, `crypto/`, `infra/scripts/`, and `inbox/`. -No product implementation is present yet. +Contracts foundation: -- Contracts: not implemented -- Services: not implemented -- Apps: not implemented -- Hardware files: not implemented -- Research artifacts: not implemented -- Cryptographic proof systems: not implemented -- Infrastructure scripts: not implemented +- `contracts/FlowPulse.sol` defines the FlowPulse v0 event interface and initial pulse type constants. +- `contracts/RootfieldRegistry.sol` registers Rootfield namespaces, accepts committed roots, and emits FlowPulse events. +- `contracts/FLOWPULSE_SCHEMA.md` documents event fields, receipt boundaries, and URI/log-data limitations. +- `tests/RootfieldRegistry.t.sol` contains initial Foundry tests. +- `tests/README.md` documents the current test command. -## Active Boundaries +## Conceptual Or Not Implemented Yet -- Storage is not free. -- Transaction hashes do not store arbitrary data. -- Uniswap v4 hooks cannot know `txHash` or `logIndex`. -- Indexers and verifiers derive `txHash` and `logIndex` after reading receipts and logs. -- Heavy AI, model, memory, and artifact data stays off-chain. -- On-chain state stores roots, receipts, commitments, attestations, proofs, and work state. -- Meshtastic and LoRa are low-bandwidth control signaling paths, not normal internet bandwidth. +- Production protocol deployment. +- Production ownership, upgrade, governance, fee, token, or incentive mechanics. +- Dynamic fees or tokenomics. +- Production Uniswap v4 hook deployment. +- Indexer or verifier service runtime. +- Persistence layer, live RPC reader, production APIs, or hosted services. +- Dashboard, explorer, or hardware console implementation. +- FlowRouter hardware implementation, firmware, manufacturing, final enclosure work, or field deployment. +- Meshtastic or LoRa integration. +- Cryptographic proof systems, GPU proofs, verifier networks, or verifier economics. +- Appchain/L1 implementation, validator planning, sequencer planning, bridge deployment, or mainnet deployment. + +## Active GitHub Work Shape + +Issues #6 through #55 define the current foundation-hardening backlog. They are organized into program milestones in `docs/ISSUE_BACKLOG.md`. + +Closed issue notes: + +- #16 was closed as not planned because its scope was folded into other architecture/status issues. +- #39 was closed; future on-chain verifier adapter work should stay gated behind accepted verifier and crypto boundaries. -## Open Questions +Open PRs should be treated as review candidates only after their changed files match the issue's allowed folders and forbidden folders. -- What is the first minimal FlowPulse event schema? -- What belongs in Rootflow versus Rootfield? -- Which facts require cryptographic receipts or attestations? -- What is the smallest useful indexer/verifier loop? -- What hardware proof-of-concept should FlowRouter start with? -- What AI memory and neural-geometry research artifacts should be tracked first? -- What appchain/L1 research criteria would justify deeper investment? +## Active Local Work -## How To Update This File +Local worktrees may contain unmerged work. Unmerged files are not source of truth until reviewed and merged. -Update this file whenever the actual repo state changes in a way that affects new agents. Keep it factual and dated. +Use: + +```powershell +cd E:\FlowMemory\flowmemory-main +.\infra\scripts\status-report.ps1 +``` + +Before assigning agents, check for dirty worktrees and avoid overlapping folders. + +## Active Technical Boundaries + +- AI does not run on-chain. +- Storage is not free. +- Transaction hashes do not store arbitrary data. +- Uniswap v4 hooks cannot know `txHash` or `logIndex` during execution. +- Indexers and verifiers derive `txHash` and `logIndex` after receipts and logs exist. +- Heavy AI, model, memory, media, and artifact data stays off-chain. +- On-chain state stores only intentional roots, receipts, commitments, attestations, proofs, and work state. +- `RootfieldRegistry` is a skeleton/foundation contract, not a production protocol surface. +- `metadataURI` and `evidenceURI` are arbitrary caller-supplied strings emitted as log data. +- The current contract does not enforce URI length, content, format, resolvability, or short-pointer behavior. +- Meshtastic and LoRa are low-bandwidth control-signaling paths, not normal internet bandwidth. + +## Current Operator Priorities + +1. Keep current-state, roadmap, architecture, backlog, and review docs aligned with GitHub. +2. Finish contracts foundation hardening without production deployment or token mechanics. +3. Specify the local indexer/verifier loop before building runtime services. +4. Define crypto vocabulary before proof systems or verifier economics. +5. Define hardware and dashboard scopes before implementation. +6. Keep chain/appchain work research-only and no-value until explicit gates are passed. + +## Update Rule + +Update this file whenever merged repository state changes in a way that affects new agents. Keep it concrete, dated, and conservative. diff --git a/docs/DAILY_HQ_RUNBOOK.md b/docs/DAILY_HQ_RUNBOOK.md new file mode 100644 index 00000000..bb499d20 --- /dev/null +++ b/docs/DAILY_HQ_RUNBOOK.md @@ -0,0 +1,125 @@ +# Daily HQ Runbook + +This runbook is for the FlowMemory HQ operator. It keeps many Codex agents moving without overlapping folders or expanding into premature product work. + +## Morning Review + +Run: + +```powershell +cd E:\FlowMemory\flowmemory-main +git fetch --all --prune +.\infra\scripts\status-report.ps1 +gh pr list --repo FlowmemoryAI/FlowMemory --state open +gh issue list --repo FlowmemoryAI/FlowMemory --state open --limit 80 +``` + +Check: + +- Dirty worktrees. +- Open PRs and changed file scope. +- Blocked issues. +- Issues missing labels or milestones. +- Any PR touching forbidden folders. + +## Issue Triage + +For each issue: + +- Confirm objective is concrete. +- Confirm allowed folders and forbidden folders. +- Confirm risk level. +- Confirm recommended worktree/agent. +- Confirm dependencies in `docs/ISSUE_BACKLOG.md`. +- Add missing labels or milestones before starting work. + +Priority order: + +1. Repo OS and review process. +2. Contracts foundation hardening. +3. Indexer/verifier fixture and schema work. +4. Crypto vocabulary. +5. Dashboard data model. +6. Hardware POC specs. +7. Research gates. + +## Starting Agents + +Use one terminal per agent: + +```powershell +cd E:\FlowMemory\flowmemory-contracts +codex +``` + +Give the agent the prompt from `docs/AGENT_PROMPTS.md` plus the assigned issue number. + +Do not start two agents on the same folder family unless the changed files are clearly disjoint. + +## Monitoring PRs + +For each open PR: + +- Check issue linkage. +- Check changed files. +- Check `git diff --check` result. +- Check area-specific tests or documented absence. +- Check for scope creep. +- Check whether docs/current state need updates. + +Reject or send back any PR that adds: + +- Tokenomics. +- Dynamic fees. +- Production deployment. +- Production L1/appchain implementation. +- Production Uniswap v4 hook deployment. +- Hardware manufacturing or production field deployment. +- GPU proofs or verifier economics. +- Full dashboard implementation. + +## Merge Order + +Prefer: + +1. Repo OS, labels, milestones, PR process, runbook. +2. Current-state, roadmap, architecture, decision records. +3. Contracts test/config hardening. +4. Indexer/verifier fixture/spec changes. +5. Crypto vocabulary. +6. Dashboard data model. +7. Hardware scope docs. +8. Research docs. + +If two PRs touch the same source-of-truth doc, merge the one that updates shared process first and ask the second PR to rebase or refresh. + +## Updating Current State + +Update `docs/CURRENT_STATE.md` when a merge changes: + +- Implemented files or systems. +- Conceptual/not-implemented status. +- Active boundaries. +- Major issue or milestone organization. +- Agent workflow expectations. + +Do not update it for unmerged local work unless the note clearly says the work is not source of truth. + +## End-Of-Day Handoff + +Record: + +- Merged PRs. +- Open PRs and review status. +- Dirty worktrees. +- Blocked issues. +- Next five priorities. +- Any scope creep stopped. +- Any docs that need source-of-truth updates tomorrow. + +Suggested command: + +```powershell +cd E:\FlowMemory\flowmemory-main +.\infra\scripts\status-report.ps1 +``` diff --git a/docs/DECISIONS/README.md b/docs/DECISIONS/README.md index 02f4e54b..3972cde8 100644 --- a/docs/DECISIONS/README.md +++ b/docs/DECISIONS/README.md @@ -1,16 +1,52 @@ # Decision Records -Use this directory for durable architectural and product decisions. +Use this directory for durable FlowMemory decisions. Decision records are for architecture, protocol boundaries, security assumptions, workflow policy, and research gates that future agents must respect. ## Naming Use: -`YYYY-MM-DD-short-title.md` +```text +YYYY-MM-DD-short-title.md +``` Example: -`2026-05-12-repository-bootstrap.md` +```text +2026-05-13-flowpulse-observation-identity.md +``` + +## Status Workflow + +### Proposed + +Use `Proposed` when a decision is drafted for review but not yet accepted. + +Rules: + +- Proposed decisions may guide discussion. +- Proposed decisions must not be treated as implementation approval. +- Proposed decisions should name open questions and alternatives. + +### Accepted + +Use `Accepted` when a decision is reviewed and should guide future work. + +Rules: + +- Accepted decisions are source-of-truth constraints. +- If implementation is needed, create a separate issue. +- Accepted decisions should include consequences and follow-ups. + +### Superseded + +Use `Superseded` when a newer decision replaces the record. + +Rules: + +- Do not delete the old record. +- Add a link to the superseding decision. +- Explain what changed. ## Template @@ -31,11 +67,27 @@ What problem, constraint, or decision point led to this? What are we deciding? +## Alternatives Considered + +- Option A +- Option B + ## Consequences What becomes easier, harder, safer, or riskier? +## Scope Boundaries + +What does this decision explicitly not authorize? + ## Follow-Ups What should happen next? ``` + +## Review Checklist + +- Does the decision preserve core technical boundaries? +- Does it avoid tokenomics, production deployment, production L1/appchain, production hooks, hardware manufacturing, and full dashboard implementation unless explicitly scoped? +- Does it name implementation follow-ups as issues rather than silently authorizing work? +- Does it clarify whether the status is Proposed, Accepted, or Superseded? diff --git a/docs/FLOWMEMORY_HQ_CONTEXT.md b/docs/FLOWMEMORY_HQ_CONTEXT.md index 66f4a299..087b3b3d 100644 --- a/docs/FLOWMEMORY_HQ_CONTEXT.md +++ b/docs/FLOWMEMORY_HQ_CONTEXT.md @@ -24,12 +24,14 @@ FlowMemory is expected to explore Base-native protocol mechanics and Uniswap v4 ### FlowPulse Events -FlowPulse events are the intended event stream for protocol activity, work lifecycle, routing signals, memory updates, and reliability checkpoints. The exact event schema is not implemented yet and should be designed before contracts or indexers depend on it. +FlowPulse events are the intended event stream for protocol activity, work lifecycle, routing signals, memory updates, and reliability checkpoints. A v0 schema and Solidity interface now exist in `contracts/FLOWPULSE_SCHEMA.md` and `contracts/FlowPulse.sol`; future schema changes should be versioned and documented before contracts, indexers, or verifiers depend on them. ### Rootflow And Rootfield Rootflow and Rootfield refer to state commitment concepts for FlowMemory. They should be treated as commitment layers, not as unlimited data storage. Agents should define what is committed, what stays off-chain, and how verifiers reconstruct or challenge the claimed state. +`contracts/RootfieldRegistry.sol` is the current Rootfield foundation. It registers Rootfield namespaces, accepts committed roots, and emits FlowPulse events. It is not a production protocol deployment and does not implement hook integration, tokenomics, fees, upgrades, governance, verifier policy, or production ownership controls. + ### AI Memory And Neural Geometry The project includes research into AI memory structures, retrieval, embeddings, semantic geometry, compression, continuity, and reliability. Heavy memory and model artifacts stay off-chain. On-chain records should point to commitments, receipts, and verification state rather than raw model data. @@ -50,6 +52,7 @@ Meshtastic and LoRa are low-bandwidth control signaling paths. They are useful f - Indexers and verifiers derive `txHash` and `logIndex` after reading receipts and logs. - Heavy AI, model, memory, and artifact data stays off-chain. - On-chain state stores roots, receipts, commitments, attestations, proofs, and work state. +- `metadataURI` and `evidenceURI` values in the current RootfieldRegistry are arbitrary strings emitted as on-chain log bytes. The contract does not enforce short-pointer behavior or off-chain-storage boundaries. - Meshtastic and LoRa are low-bandwidth control signaling paths, not normal internet bandwidth. ## Intended Work Areas diff --git a/docs/ISSUE_BACKLOG.md b/docs/ISSUE_BACKLOG.md new file mode 100644 index 00000000..baa3de1c --- /dev/null +++ b/docs/ISSUE_BACKLOG.md @@ -0,0 +1,132 @@ +# Issue Backlog + +Last synced: 2026-05-13 + +This file maps existing GitHub issues #6-#55 into program milestones and agent worktrees. GitHub is still the source of truth for issue state; update this index after issue or milestone changes. + +## Milestones + +- V0 Repo OS: management layer, docs, templates, labels, scripts, review process. +- V0 Contracts Foundation: FlowPulse, RootfieldRegistry, contract test hardening, contract-boundary decisions. +- V0 Local Stack: local fixtures, indexer/verifier schemas, local devnet gates, persistence boundary, live-reader boundary. +- V0 Hardware POC: FlowRouter, Meshtastic/LoRa, enclosure, indicators, NFC cartridge, hardware demo planning. +- V0 Research Lab: AI memory, crypto vocabulary, no-value devnet/appchain research, proof-carrying receipt research. +- V0 Review/Audit: security process, static analysis, review workflow, audit-readiness gates. + +## Agent Worktrees + +- Contracts: `E:\FlowMemory\flowmemory-contracts` +- Indexer/verifier: `E:\FlowMemory\flowmemory-indexer` +- Crypto: `E:\FlowMemory\flowmemory-crypto` +- Chain/devnet research: `E:\FlowMemory\flowmemory-chain` +- Dashboard: `E:\FlowMemory\flowmemory-dashboard` +- Hardware: `E:\FlowMemory\flowmemory-hardware` +- Research: `E:\FlowMemory\flowmemory-research` +- Review/HQ: `E:\FlowMemory\flowmemory-review` + +## V0 Repo OS + +| Issue | State | Agent/worktree | Dependencies | Notes | +| --- | --- | --- | --- | --- | +| #9 `[infrastructure] Add CI validation for setup-worktrees.ps1 syntax` | Open | Review/HQ - `flowmemory-review` | None | Read-only CI validation; no worktree creation in CI. | +| #10 `[infrastructure] Align issue templates with repo labels and agent scopes` | Open | Review/HQ - `flowmemory-review` | Label audit | Keep issue fields aligned with allowed/forbidden folders. | +| #15 `[docs/architecture] Add Rootflow and Rootfield glossary and boundary notes` | Open | Review/HQ - `flowmemory-review` | #8 | Architecture vocabulary; no contract changes. | +| #16 `[docs/architecture] Map observed, committed, and verified state boundaries` | Closed | Review/HQ - `flowmemory-review` | Folded into #14/#15 | Closed as not planned; keep as historical note. | +| #48 `[infrastructure] Ignore generated Foundry artifacts` | Open | Review/HQ - `flowmemory-review` | #6 | `.gitignore` or docs hygiene only. | + +## V0 Contracts Foundation + +| Issue | State | Agent/worktree | Dependencies | Notes | +| --- | --- | --- | --- | --- | +| #6 `[contracts] Add Foundry configuration for contract test commands` | Open | Contracts - `flowmemory-contracts` | None | Enables simple local contract tests. | +| #7 `[contracts] Expand RootfieldRegistry v0 negative-path tests` | Open | Contracts - `flowmemory-contracts` | #6 | Tests existing behavior only. | +| #8 `[contracts] Define RootfieldRegistry URI boundary policy` | Open | Contracts - `flowmemory-contracts` | None | Decision before stricter URI implementation. | +| #21 `[contracts] Assess Rootfield namespace squatting policy` | Open | Contracts - `flowmemory-contracts` | #8 | Policy first; no fees or tokenomics. | +| #22 `[contracts] Define Rootfield deactivation and status lifecycle` | Open | Contracts - `flowmemory-contracts` | #8 | Status vocabulary before implementation. | +| #23 `[contracts] Define Rootfield ownership transfer and recovery policy` | Open | Contracts - `flowmemory-contracts` | #22 | Ownership policy before mutation logic. | +| #25 `[contracts] Define future Uniswap v4 hook adapter boundary` | Open | Contracts - `flowmemory-contracts` | #13 | Boundary only; no production hook. | +| #26 `[contracts] Defer CursorRegistry until indexer identity spec stabilizes` | Open | Contracts - `flowmemory-contracts` | #13, #14 | Explicit deferral; do not implement. | +| #28 `[contracts] Define future ReceiptVerifier contract boundary` | Open | Contracts + Crypto | #14, #17, #45 | Boundary only; no verifier network. | +| #29 `[contracts] Define future WorkDebtScheduler contract boundary` | Open | Contracts - `flowmemory-contracts` | #22, #52 | Boundary only; no economics. | +| #39 `[contracts/shared] Define future on-chain verifier adapter boundary` | Closed | Contracts + Crypto | Folded into #28/#40 | Closed; keep future adapter gated. | +| #52 `[contracts] Define WorkerRegistry and VerifierRegistry authorization policy` | Open | Contracts - `flowmemory-contracts` | #23, #28 | Authorization policy only. | +| #53 `[contracts] Define ArtifactRegistry canonicalization and resolver policy` | Open | Contracts + Crypto | #8, #17, #45 | Canonicalization before contract design. | + +## V0 Local Stack + +| Issue | State | Agent/worktree | Dependencies | Notes | +| --- | --- | --- | --- | --- | +| #13 `[indexer/verifier] Define canonical FlowPulse observation identity` | Open | Indexer - `flowmemory-indexer` | #8 | Defines receipt/log identity. | +| #14 `[indexer/verifier] Define verifier result status vocabulary` | Open | Indexer - `flowmemory-indexer` | #13 | Status vocabulary for reports/apps. | +| #38 `[services/verifier] Validate crypto v0 test vectors` | Open | Indexer + Crypto | #17, #40 | Validate fixtures, not production verifier network. | +| #43 `[indexer/verifier] Build minimal fixture-based FlowPulse parser` | Open | Indexer - `flowmemory-indexer` | #13, #6 | Fixture-based parser before live RPC. | +| #44 `[indexer/verifier] Define reorg-state model and fixture tests` | Open | Indexer - `flowmemory-indexer` | #13, #43 | Fixture tests before persistence. | +| #45 `[indexer/verifier] Define verifier report JSON schema` | Open | Indexer - `flowmemory-indexer` | #14, #17 | Deterministic schema. | +| #46 `[indexer/verifier] Design future live RPC indexer boundary` | Open | Indexer - `flowmemory-indexer` | #13, #44 | Boundary only before live reader. | +| #47 `[services/shared] Define crypto package integration boundary` | Open | Indexer + Crypto | #17, #45 | Package boundary, not production service. | +| #49 `[chain/devnet] Define local devnet smoke-test gate` | Open | Chain - `flowmemory-chain` | #6, #43, #51 | No mainnet; local smoke gate only. | +| #51 `[chain/devnet] Define local FlowPulse receipt fixture handoff` | Open | Chain + Indexer | #13, #43 | Fixture handoff for local stack. | +| #54 `[indexer/verifier] Add V0 persistence layer for observations and reports` | Open | Indexer - `flowmemory-indexer` | #44, #45 | After report/reorg schemas stabilize. | +| #55 `[indexer] Promote V0 local RPC reader toward live Base test indexing` | Open | Indexer - `flowmemory-indexer` | #46, #49, #54 | Later boundary; no production indexing. | + +## V0 Hardware POC + +| Issue | State | Agent/worktree | Dependencies | Notes | +| --- | --- | --- | --- | --- | +| #11 `[hardware] Define FlowRouter v0 research scope and non-goals` | Open | Hardware - `flowmemory-hardware` | None | Scope guard for all hardware work. | +| #12 `[hardware] Draft Meshtastic and LoRa control-message inventory` | Open | Hardware - `flowmemory-hardware` | #11 | Low-bandwidth control messages only. | +| #30 `[hardware] Draft FlowRouter enclosure concept v0` | Open | Hardware - `flowmemory-hardware` | #11 | Concept only; no manufacturing. | +| #31 `[hardware] Prototype NFC memory cartridge v0` | Open | Hardware - `flowmemory-hardware` | #11, #17 | Prototype planning; no production BOM. | +| #32 `[hardware] Prototype FlowCore light-pipe status indicator` | Open | Hardware - `flowmemory-hardware` | #11 | Concept/prototype only. | +| #33 `[hardware] Plan two-node FlowRouter Meshtastic demo` | Open | Hardware - `flowmemory-hardware` | #12 | Demo plan; no field deployment claim. | +| #34 `[hardware] Measure FlowRouter v0 CAD dimensions` | Open | Hardware - `flowmemory-hardware` | #30 | Measurement only; no final CAD/manufacturing. | + +## V0 Research Lab + +| Issue | State | Agent/worktree | Dependencies | Notes | +| --- | --- | --- | --- | --- | +| #17 `[crypto] Define v0 receipt, attestation, and commitment schema vocabulary` | Open | Crypto - `flowmemory-crypto` | #13, #14 helpful | Schema vocabulary only. | +| #18 `[chain/appchain research] Define future appchain or L1 go/no-go criteria` | Open | Chain - `flowmemory-chain` | None | Research gate; no chain design. | +| #35 `[chain/appchain] Define no-value appchain prototype criteria` | Open | Chain - `flowmemory-chain` | #18 | No-value prototype criteria only. | +| #36 `[chain/appchain] Define Base settlement anchor spec` | Open | Chain - `flowmemory-chain` | #35 | Research/spec; no deployment. | +| #37 `[chain/appchain] Define appchain hardware node requirements` | Open | Chain + Hardware | #35, #11 | Requirements only. | +| #40 `[crypto/verifier] Implement verifier signature envelope validation` | Open | Crypto - `flowmemory-crypto` | #17, #45 | Keep bounded; no verifier economics. | +| #41 `[chain/appchain] Research bridge and security review requirements` | Open | Chain - `flowmemory-chain` | #35, #36 | Research requirements; no bridge implementation. | +| #42 `[research/cryptography] Define zk proof-carrying receipt milestones` | Open | Research + Crypto | #17 | Milestones only; no GPU proofs. | +| #50 `[chain/appchain] Select no-value appchain prototype framework` | Open | Chain - `flowmemory-chain` | #35, #41, #49 | Framework selection only after gates. | + +## V0 Dashboard + +| Issue | State | Agent/worktree | Dependencies | Notes | +| --- | --- | --- | --- | --- | +| #19 `[dashboard/app data model] Define operator and explorer state model` | Open | Dashboard - `flowmemory-dashboard` | #14, #45 | Data model only; no UI scaffold. | + +## V0 Review/Audit + +Primary milestone: V0 Review/Audit. + +| Issue | State | Agent/worktree | Dependencies | Notes | +| --- | --- | --- | --- | --- | +| #20 `[review] Define foundation review and audit workflow` | Open | Review/HQ - `flowmemory-review` | #10 | Base review process. | +| #24 `[contracts] Add Slither and static-analysis plan for v0 contracts` | Open | Review/Audit + Contracts | #6 | Static-analysis plan. | +| #27 `[security/process] Add SECURITY.md and private reporting guidance` | Open | Review/HQ - `flowmemory-review` | #20 | Reporting process. | + +## Priority Notes + +P0 sequence: + +1. #10, #20, #9 +2. #6, #7, #8 +3. #13, #14, #17 +4. #43, #44, #45, #49, #51 + +P1 sequence: + +1. #21, #22, #23, #24 +2. #11, #12, #19 +3. #35, #36, #41 + +Blocked or gated: + +- #25, #26, #28, #29, #39, #50, #52, #53, #54, #55 require earlier specs or decisions. +- Any tokenomics, dynamic-fee, production L1, mainnet deployment, hardware manufacturing, or production hook task is out of scope until a later explicit gate. diff --git a/docs/PROJECT_CHARTER.md b/docs/PROJECT_CHARTER.md index 5ace2e66..24a243f3 100644 --- a/docs/PROJECT_CHARTER.md +++ b/docs/PROJECT_CHARTER.md @@ -6,7 +6,7 @@ FlowMemory aims to build a trustworthy memory and reliability substrate for AI a ## Near-Term Goal -The near-term goal is to create a clean multi-agent workspace where protocol, service, app, hardware, research, crypto, and security work can proceed without stepping on each other. +The near-term goal is to keep a clean multi-agent workspace where protocol, service, app, hardware, research, crypto, and security work can proceed without stepping on each other. ## Long-Term Direction @@ -21,13 +21,14 @@ FlowMemory may evolve toward a dedicated appchain or L1 if the protocol, memory, - Favor durable documentation and decision records over hidden context. - Use GitHub issues and pull requests as the operational source of truth. -## Non-Goals During Bootstrap +## Current Non-Goals Unless Explicitly Scoped - No production contracts. - No product dashboard. - No hardware firmware. - No token mechanics. - No appchain/L1 implementation. +- No production deployment automation. - No claims that data exists on-chain unless the design explicitly stores or commits it there. ## Success Criteria diff --git a/docs/PR_PROCESS.md b/docs/PR_PROCESS.md new file mode 100644 index 00000000..fded9353 --- /dev/null +++ b/docs/PR_PROCESS.md @@ -0,0 +1,121 @@ +# Pull Request Process + +FlowMemory uses small, scoped pull requests from dedicated worktrees. GitHub is the source of truth for PR state, review, and merge history. + +## Branch Naming + +Use one branch per issue: + +```text +agent/-issue--short-title +``` + +Examples: + +- `agent/contracts-issue-6-foundry-config` +- `agent/indexer-issue-43-flowpulse-parser` +- `agent/review-issue-20-foundation-review` + +Use `hq/` only for HQ operating-system work that spans docs, templates, scripts, labels, or milestones. + +## Draft PRs + +Open a draft PR as soon as a branch has a coherent direction and useful file ownership is visible. + +Draft PRs should include: + +- Linked issue number. +- Allowed folders. +- Forbidden folders. +- Worktree path. +- Current checklist state. +- Known blockers. + +## Review Requirements + +Every PR must show: + +- It is tied to one primary issue. +- Changed files stay inside allowed folders. +- Forbidden folders were not touched. +- `git diff --check` passed. +- Area-specific tests or checks were run, or the PR explains why none exist. +- The PR does not add gated work such as tokenomics, dynamic fees, production deployment, production L1/appchain, production hooks, hardware manufacturing, GPU proofs, verifier economics, or full dashboard implementation. + +## Merge Order + +Preferred order: + +1. Repo OS, templates, labels, milestones, runbooks, and review process. +2. Current-state, roadmap, architecture, and decision-record updates. +3. Contracts foundation hardening. +4. Indexer/verifier fixtures and schemas. +5. Crypto vocabulary and validation boundaries. +6. Dashboard data model. +7. Hardware POC specs. +8. Research docs. + +When two PRs touch the same file, merge the source-of-truth or reviewer PR first, then rebase or update the dependent PR. + +## Avoiding Conflicts + +- Start each agent from its assigned worktree. +- Run `git fetch --all --prune` before starting. +- Run `git status --short --branch` before editing. +- Keep issue scope to one folder family when possible. +- Use cross-links instead of moving files across agent boundaries. +- Do not edit another agent's folder unless the issue explicitly allows it. +- If a second folder becomes necessary, create or request a follow-up issue. + +## Dirty Worktrees + +Dirty worktrees are expected in multi-agent work, but they must be explicit. + +Before assigning an agent: + +```powershell +cd E:\FlowMemory\flowmemory-main +.\infra\scripts\status-report.ps1 +``` + +If a worktree is dirty: + +- Identify whether the dirty files match the assigned issue. +- Do not reuse that worktree for unrelated work. +- Commit, stash, or move the work only with explicit operator intent. +- Never discard changes made by another agent without approval. + +## Closing Issues + +Close an issue only when: + +- Acceptance criteria are met. +- The PR is merged. +- Required docs are updated. +- Tests or checks are recorded. +- Follow-up issues exist for deferred work. + +Use closing keywords only when the PR fully satisfies the issue: + +```text +Closes # +``` + +Use weaker references when partial: + +```text +Refs # +``` + +## Emergency Scope Stop + +Stop and ask for HQ review if a PR starts adding: + +- Tokenomics. +- Dynamic fees. +- Mainnet or production deployment. +- Production Uniswap v4 hook deployment. +- Production L1/appchain implementation. +- Hardware manufacturing or production field deployment. +- GPU proofs or verifier economics. +- Full dashboard implementation. diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md index 267e33a6..310f9286 100644 --- a/docs/ROADMAP.md +++ b/docs/ROADMAP.md @@ -1,55 +1,130 @@ # Roadmap -This roadmap is directional. Use issues and decision records for committed work. +This roadmap is the project-management view of FlowMemory. Use GitHub issues for execution and `docs/DECISIONS/` for durable decisions. -## Phase 0: Repository Readiness +Production L1, tokenomics, mainnet deployment, production Uniswap v4 hook deployment, hardware manufacturing, and full dashboard implementation are later gated work. They are not approved by this roadmap. -- Establish agent instructions and shared context. -- Create work-area directories. -- Add issue and pull request templates. -- Add conservative CI. -- Record architecture, security, roadmap, and current state docs. +## Immediate Major Milestone: Runnable Local V0 Stack -## Phase 1: Protocol Definitions +Goal: make a local developer able to run the smallest FlowMemory loop without production deployment. -- Define FlowPulse event vocabulary. -- Define Rootflow and Rootfield commitment semantics. -- Decide what data is on-chain, off-chain, or derived. -- Draft receipt, attestation, proof, and root formats. -- Document Uniswap v4 hook constraints and Base assumptions. +The local V0 stack means: -## Phase 2: Minimal Indexer And Verifier Loop +- Contracts compile and tests run locally. +- FlowPulse fixtures can be produced or consumed deterministically. +- Indexer/verifier specs define observation identity, reorg states, and report shape. +- Crypto vocabulary defines receipts, attestations, roots, commitments, and proof boundaries. +- Dashboard planning has a data model for observed, pending, verified, failed, unsupported, and reorged states. +- Hardware and research tracks have bounded specs but do not block local software validation. -- Read chain receipts and logs. -- Derive `txHash` and `logIndex` from observed logs. -- Reconstruct FlowPulse activity. -- Verify commitments against off-chain artifacts. -- Produce deterministic verification reports. +Non-goals: -## Phase 3: Applications +- No tokenomics. +- No dynamic fees. +- No production deployments. +- No production L1/appchain. +- No production hook deployment. +- No hardware manufacturing. +- No full dashboard app. -- Build an operator dashboard. -- Build a protocol explorer. -- Build a hardware console. -- Make verification state visible and understandable. +## Near-Term Phases -## Phase 4: Hardware Research +### Phase 0: V0 Repo OS -- Define FlowRouter hardware scope. -- Validate Meshtastic and LoRa control-signaling use cases. -- Prototype device identity and compact receipt exchange. -- Develop and test 3D-printed enclosures. +Status: active maintenance. -## Phase 5: AI Memory And Neural Geometry Research +- Keep source-of-truth docs accurate. +- Keep agent prompts, PR process, daily runbook, and issue backlog current. +- Keep issue templates and PR templates enforcing scope boundaries. +- Keep status scripts read-only and safe. +- Keep labels and milestones aligned with agent ownership. -- Define memory artifact formats and commitments. -- Explore embedding, retrieval, continuity, and reliability metrics. -- Connect research artifacts to verifiable receipts. -- Keep heavy artifacts off-chain. +### Phase 1: V0 Contracts Foundation -## Phase 6: Appchain/L1 Research +Status: active. -- Define why an appchain or L1 would be needed. -- Compare Base-native, appchain, and L1 tradeoffs. -- Model validator, data availability, verification, and hardware implications. -- Produce a go/no-go decision record before implementation. +- Add minimal Foundry config and contract test workflow. +- Harden existing RootfieldRegistry tests. +- Lock FlowPulse v0 and Rootfield URI/log-data decisions. +- Define status lifecycle, ownership/recovery, namespace policy, and static-analysis plan before implementation. +- Keep dynamic fees, tokenomics, production deployment, and production hooks out of scope. + +### Phase 2: V0 Local Stack + +Status: active as specs and local fixtures before services. + +- Specify canonical FlowPulse observation identity. +- Define verifier statuses and report JSON schema. +- Define fixture-based parser and reorg-state tests. +- Define persistence and local RPC reader boundaries only after fixture behavior stabilizes. +- Define local devnet smoke-test gates without mainnet or production deployment. + +### Phase 3: V0 Review/Audit + +Status: active. + +- Define foundation PR review rules. +- Add security reporting guidance. +- Add static-analysis planning before claiming audit readiness. +- Enforce allowed-folder and forbidden-folder boundaries. + +## Mid-Term Phases + +### Phase 4: V0 Crypto Schema Layer + +Status: planning. + +- Define receipt, attestation, commitment, root, and proof vocabulary. +- Define domain separation and replay boundaries. +- Validate test vectors through verifier specs. +- Keep proof circuits, GPU proofs, verifier economics, and production crypto infrastructure out of scope. + +### Phase 5: V0 Dashboard Data Model + +Status: planning. + +- Define app-facing entities for dashboard and explorer. +- Model observed, pending, finalized, verified, invalid, unresolved, unsupported, and reorged states. +- Keep frontend scaffolding and production APIs out of scope until the local stack stabilizes. + +### Phase 6: V0 Hardware POC + +Status: planning and bounded research. + +- Define FlowRouter v0 as research hardware. +- Document Meshtastic/LoRa control-message candidates. +- Explore enclosure concepts, NFC memory cartridge concepts, light-pipe indicators, and two-node demos as specs or prototypes only when scoped. +- Keep manufacturing, firmware production, RF certification work, and field deployment out of scope. + +## Research Phases + +### Phase 7: V0 Research Lab + +Status: research-only. + +- Define AI memory artifact taxonomy. +- Define no-value devnet/appchain research criteria. +- Compare Base settlement anchors and local devnet smoke-test requirements. +- Research bridge/security review requirements before any chain design. + +### Phase 8: Later Gated Work + +Status: blocked until explicit go/no-go decisions exist. + +- Production L1 or appchain. +- Tokenomics or value-bearing systems. +- Mainnet deployment. +- Production Uniswap v4 hook deployment. +- Verifier networks, staking, slashing, or incentives. +- Hardware manufacturing or production decentralized internet claims. + +## Merge Order Preference + +1. Repo OS and review process changes. +2. Current state, roadmap, architecture, and decision records. +3. Contracts foundation hardening. +4. Indexer/verifier fixture and schema work. +5. Crypto schema vocabulary and test-vector validation. +6. Dashboard data model. +7. Hardware POC specs. +8. Research lab documents. diff --git a/docs/START_HERE.md b/docs/START_HERE.md index d38c518e..0a42525f 100644 --- a/docs/START_HERE.md +++ b/docs/START_HERE.md @@ -16,7 +16,9 @@ This is the first document to read after `AGENTS.md`. - Check the current branch and working tree. - Read the files you plan to edit. - Identify whether the task is docs, protocol, service, app, hardware, research, crypto, infra, or security work. +- If working from an issue, copy its allowed folders, forbidden folders, acceptance criteria, risk level, and recommended worktree into your local plan before editing. - If the task touches architecture, security assumptions, public schemas, or cross-agent workflow, update docs in the same pull request. +- If local files disagree with GitHub issue or pull request state, stop and reconcile the difference before editing. ## Multi-Agent Worktree Setup @@ -91,6 +93,8 @@ codex - Check `git status --short --branch` before starting and before handing off work. - Avoid assigning two agents to edit the same files at the same time. - Use `git worktree list` from `E:\FlowMemory\flowmemory-main` to inspect all local worktrees. +- Long-running bucket agents should post or record short handoffs that name touched files, checks run, unresolved risks, and the next smallest safe task. +- Review agents should avoid product implementation and should work in docs, templates, scripts, and issue/PR hygiene unless an issue explicitly assigns a narrower technical scope. ## During Work diff --git a/infra/scripts/status-report.ps1 b/infra/scripts/status-report.ps1 new file mode 100644 index 00000000..b3ea44ea --- /dev/null +++ b/infra/scripts/status-report.ps1 @@ -0,0 +1,78 @@ +$ErrorActionPreference = "Stop" +Set-StrictMode -Version Latest + +function Write-Section { + param( + [Parameter(Mandatory = $true)] + [string] $Title + ) + + Write-Host "" + Write-Host "== $Title ==" +} + +function Get-WorktreePaths { + $lines = & git worktree list --porcelain + if ($LASTEXITCODE -ne 0) { + throw "Failed to list git worktrees." + } + + foreach ($line in $lines) { + if ($line -like "worktree *") { + $line.Substring("worktree ".Length) + } + } +} + +if (-not (Get-Command git -ErrorAction SilentlyContinue)) { + throw "git was not found on PATH." +} + +$repoRoot = (& git rev-parse --show-toplevel).Trim() +if ($LASTEXITCODE -ne 0 -or [string]::IsNullOrWhiteSpace($repoRoot)) { + throw "Run this script inside a Git repository." +} + +Set-Location -LiteralPath $repoRoot + +Write-Section "Repository" +Write-Host "Root: $repoRoot" +& git status --short --branch + +Write-Section "Worktrees" +$dirtyWorktrees = @() +foreach ($path in Get-WorktreePaths) { + Write-Host "" + Write-Host $path + $status = & git -C $path status --short --branch + $status | ForEach-Object { Write-Host " $_" } + + $dirty = $status | Where-Object { + $_ -and + ($_ -notlike "## *") + } + + if ($dirty) { + $dirtyWorktrees += $path + } +} + +Write-Section "Dirty Worktrees" +if ($dirtyWorktrees.Count -eq 0) { + Write-Host "None" +} +else { + $dirtyWorktrees | ForEach-Object { Write-Host $_ } +} + +if (Get-Command gh -ErrorAction SilentlyContinue) { + Write-Section "Open Pull Requests" + & gh pr list --repo FlowmemoryAI/FlowMemory --state open --limit 50 + + Write-Section "Open Issues" + & gh issue list --repo FlowmemoryAI/FlowMemory --state open --limit 80 +} +else { + Write-Section "GitHub" + Write-Host "gh CLI not found; skipping PR and issue summaries." +} From 9522389e54f1e739d13840b5c12e041b6da1c6b3 Mon Sep 17 00:00:00 2001 From: FlowmemoryAI <283694809+FlowmemoryAI@users.noreply.github.com> Date: Wed, 13 May 2026 09:52:06 -0500 Subject: [PATCH 2/5] Define Rootflow and Flow Memory launch core --- AGENTS.md | 3 +- README.md | 11 +- docs/AGENT_PROMPTS.md | 38 ++++++- docs/ARCHITECTURE.md | 51 +++++++--- docs/CURRENT_STATE.md | 23 ++++- docs/DAILY_HQ_RUNBOOK.md | 24 +++-- docs/DECISIONS/rootflow-v0.md | 68 +++++++++++++ docs/FLOW_MEMORY_V0.md | 184 ++++++++++++++++++++++++++++++++++ docs/ISSUE_BACKLOG.md | 16 ++- docs/ROADMAP.md | 30 +++--- docs/ROOTFLOW_V0.md | 155 ++++++++++++++++++++++++++++ docs/START_HERE.md | 5 +- docs/V0_LAUNCH_ACCEPTANCE.md | 123 +++++++++++++++++++++++ 13 files changed, 684 insertions(+), 47 deletions(-) create mode 100644 docs/DECISIONS/rootflow-v0.md create mode 100644 docs/FLOW_MEMORY_V0.md create mode 100644 docs/ROOTFLOW_V0.md create mode 100644 docs/V0_LAUNCH_ACCEPTANCE.md diff --git a/AGENTS.md b/AGENTS.md index 246e9599..c79819c2 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -8,6 +8,7 @@ These instructions apply to every agent, assistant, script, and human operating - Read `docs/START_HERE.md` before starting any task. - Read `docs/FLOWMEMORY_HQ_CONTEXT.md` before making design or implementation choices. - Read `docs/CURRENT_STATE.md` immediately before working so you understand what exists and what does not. +- Read `docs/ROOTFLOW_V0.md`, `docs/FLOW_MEMORY_V0.md`, and `docs/V0_LAUNCH_ACCEPTANCE.md` before working on launch-core Rootflow, Flow Memory, verifier, receipt, dashboard, or memory-signal tasks. - If local context conflicts with GitHub, stop and reconcile the difference before editing. ## Scope Discipline @@ -25,7 +26,7 @@ These instructions apply to every agent, assistant, script, and human operating - Use `docs/PR_PROCESS.md` for branch naming, draft PRs, merge order, dirty worktrees, and issue closing. - Use `docs/DAILY_HQ_RUNBOOK.md` for morning review, triage, monitoring, and handoff. - Use `infra/scripts/status-report.ps1` for read-only local worktree, PR, and issue status. -- The immediate major milestone is a runnable local V0 stack. Do not reinterpret that as approval for production deployment. +- The immediate major milestone is the Rootflow V0 and Flow Memory V0 launch core. Do not reinterpret that as approval for production deployment. ## Engineering Rules diff --git a/README.md b/README.md index 30423235..8a301cb4 100644 --- a/README.md +++ b/README.md @@ -38,7 +38,10 @@ Every contributor and agent should read: 2. `docs/START_HERE.md` 3. `docs/FLOWMEMORY_HQ_CONTEXT.md` 4. `docs/CURRENT_STATE.md` -5. `docs/DAILY_HQ_RUNBOOK.md` if operating HQ or coordinating agents +5. `docs/ROOTFLOW_V0.md` +6. `docs/FLOW_MEMORY_V0.md` +7. `docs/V0_LAUNCH_ACCEPTANCE.md` +8. `docs/DAILY_HQ_RUNBOOK.md` if operating HQ or coordinating agents Then work only inside the assigned scope. @@ -46,13 +49,13 @@ Then work only inside the assigned scope. FlowMemory is managed as a multi-agent program. The management layer is part of the repo and should be kept current before large subsystem work begins. -- `docs/ISSUE_BACKLOG.md`: maps issues #6-#55 into milestones, dependencies, and agent worktrees +- `docs/ISSUE_BACKLOG.md`: maps issues into milestones, dependencies, and agent worktrees - `docs/AGENT_PROMPTS.md`: copy-ready prompts for each worktree - `docs/PR_PROCESS.md`: branch, draft PR, review, merge, conflict, and issue-closing rules - `docs/DAILY_HQ_RUNBOOK.md`: morning review, triage, agent launch, PR monitoring, merge order, and handoff - `infra/scripts/status-report.ps1`: read-only local worktree, PR, and issue status report -Immediate major milestone: build a runnable local V0 stack. This means local contracts/tests, FlowPulse fixtures, indexer/verifier schemas, crypto vocabulary, app data model, and local smoke-test gates. It does not mean production deployment. +Immediate major milestone: build the Rootflow V0 and Flow Memory V0 launch core. This means local contracts/tests, FlowPulse fixtures, Rootflow transitions, Flow Memory schemas, verifier reports, crypto fixtures, dashboard-readable state, and local smoke-test gates. It does not mean production deployment. ## What Not To Claim @@ -91,6 +94,8 @@ Immediate major milestone: build a runnable local V0 stack. This means local con - Uniswap v4 hook integration - Indexer and verifier services +- Complete Rootflow runtime implementation +- Complete Flow Memory runtime implementation - FlowRouter hardware implementation - Meshtastic integration - Dashboard, explorer, and hardware console applications diff --git a/docs/AGENT_PROMPTS.md b/docs/AGENT_PROMPTS.md index 1fddcf87..c6e8c0d0 100644 --- a/docs/AGENT_PROMPTS.md +++ b/docs/AGENT_PROMPTS.md @@ -15,6 +15,9 @@ Read first: - docs/ROADMAP.md - docs/ARCHITECTURE.md - docs/ISSUE_BACKLOG.md +- docs/ROOTFLOW_V0.md +- docs/FLOW_MEMORY_V0.md +- docs/V0_LAUNCH_ACCEPTANCE.md Work only on the assigned GitHub issue. Copy the issue's objective, allowed folders, forbidden folders, acceptance criteria, risk level, and recommended worktree into your local plan before editing. @@ -23,6 +26,36 @@ Do not build outside scope. Do not add tokenomics, dynamic fees, production depl Before finishing, run git status --short --branch and git diff --check. Run area-specific tests or checks when they exist. End with changed files, checks run, risks, assumptions, and follow-up issues. ``` +## Launch-Core Rootflow And Flow Memory Add-On + +Use this add-on when the user or assigned issue mentions Rootflow V0, Flow Memory V0, launch core, memory signals, Rootfield bundles, verifier reports, or dashboard-readable state. + +```text +You are contributing to the Rootflow V0 and Flow Memory V0 launch core. + +This task is not complete just because a small PR is opened. Continue until your assigned subsystem produces concrete evidence for docs/V0_LAUNCH_ACCEPTANCE.md. + +Rootflow V0 must connect: +- Rootfield namespace +- FlowPulse pulseId +- parent pulse or parent root +- new root +- receipt id +- verifier report id +- status +- source observation + +Flow Memory V0 must expose: +- MemorySignal +- MemoryReceipt +- RootfieldBundle +- AgentMemoryView + +Use deterministic local fixtures before live production integrations. Do not claim production L1, production mainnet readiness, full trustless verification, free storage, or AI running on-chain. + +Before finishing, name exactly which launch acceptance rows your work satisfies and which rows remain incomplete. +``` + ## Contracts Agent Worktree: `E:\FlowMemory\flowmemory-contracts` @@ -53,6 +86,7 @@ Prompt suffix: ```text Assigned issue: #. Keep this to contracts foundation hardening. Do not add deployment scripts, tokenomics, dynamic fees, production hooks, or governance mechanics unless a separate accepted issue explicitly scopes them. +If this issue is part of Rootflow V0, keep contract state compact and emit enough FlowPulse/Rootfield data for indexer-derived Rootflow transitions without pretending the contract knows txHash or logIndex. ``` ## Indexer/Verifier Agent @@ -84,6 +118,7 @@ Prompt suffix: ```text Assigned issue: #. Keep receipt metadata derived from receipts/logs only. Do not build live production indexing, hosted services, verifier economics, or APIs unless explicitly scoped. +If this issue is part of Rootflow V0 or Flow Memory V0, produce or consume deterministic fixtures for MemorySignal, MemoryReceipt, RootflowTransition, verifier report, and AgentMemoryView handoff. ``` ## Crypto Agent @@ -114,6 +149,7 @@ Prompt suffix: ```text Assigned issue: #. Define vocabulary, schemas, domain separation, and validation boundaries. Do not implement a proof system or verifier network unless a later accepted issue explicitly scopes it. +If this issue is part of Rootflow V0 or Flow Memory V0, define canonical ids, hash inputs, JSON schemas, and test vectors for MemorySignal, MemoryReceipt, RootflowTransition, RootfieldBundle, and verifier reports. ``` ## Chain/Devnet Research Agent @@ -171,7 +207,7 @@ Prompt suffix: ```text Assigned issue: #. -Define operator and explorer data models before UI. Do not scaffold a full dashboard or production API unless a later issue explicitly scopes that build. +Define operator and explorer data models before UI. Fixture-backed local display paths are allowed when explicitly scoped by the Rootflow V0 or Flow Memory V0 launch goal. Do not scaffold hosted production APIs or deployment unless a later issue explicitly scopes that build. ``` ## Hardware Agent diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index d44007fe..7b2cb1ff 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -6,13 +6,14 @@ FlowMemory is a layered system for commitment-oriented AI memory, verification, 1. Contracts foundation 2. Integration harness and local fixtures -3. Indexer/verifier -4. Crypto schema layer -5. Dashboard and operator apps -6. Hardware and control signaling -7. Research lab -8. Devnet/appchain research -9. HQ program operating system +3. Rootflow and Flow Memory launch core +4. Indexer/verifier +5. Crypto schema layer +6. Dashboard and operator apps +7. Hardware and control signaling +8. Research lab +9. Devnet/appchain research +10. HQ program operating system ## Contracts @@ -57,6 +58,31 @@ Boundaries: - No production RPC credentials. - No hosted services. +## Rootflow And Flow Memory + +Status: launch-critical V0 specification, with implementation expected across contracts, crypto, indexer/verifier, and dashboard PRs. + +Primary docs: + +- `docs/ROOTFLOW_V0.md` +- `docs/FLOW_MEMORY_V0.md` +- `docs/V0_LAUNCH_ACCEPTANCE.md` +- `docs/DECISIONS/rootflow-v0.md` + +Responsibilities: + +- Define Rootflow transitions from observed FlowPulse events to committed memory roots. +- Define Flow Memory objects for AI agents and dashboards. +- Link Rootfield namespaces, root commitments, parent state, receipts, verifier reports, and statuses. +- Preserve the distinction between compact on-chain commitments and off-chain memory/artifact data. + +Boundaries: + +- Rootflow is not a production L1. +- Flow Memory is not unlimited on-chain storage. +- V0 verification is local/testnet readiness, not a full trustless verifier network. +- Dashboard-readable state may be fixture-backed until services stabilize. + ## Indexer And Verifier Status: specification and fixture work only. @@ -174,11 +200,12 @@ Responsibilities: 1. A local or future deployed contract action emits FlowPulse and updates compact on-chain state. 2. The local harness or chain client produces receipts and logs. 3. The indexer reads logs and receipts, then derives `txHash`, `logIndex`, block metadata, and observation identity. -4. The verifier consumes indexed observations and checks commitments against allowed off-chain evidence. -5. Crypto schemas define report digests, attestations, commitments, and domain separation. -6. Dashboard models consume observation and verification states. -7. Hardware sidecars may exchange compact control messages or receipt references, but not heavy data. -8. Research artifacts stay off-chain and become protocol-relevant only through explicit commitments or accepted decision records. +4. The indexer constructs MemorySignal and Rootflow transition candidates. +5. The verifier consumes indexed observations and checks commitments against allowed off-chain evidence. +6. Crypto schemas define receipt ids, report digests, attestations, commitments, transition ids, and domain separation. +7. Dashboard models consume Rootfield, Rootflow, MemorySignal, MemoryReceipt, and AgentMemoryView states. +8. Hardware sidecars may exchange compact control messages or receipt references, but not heavy data. +9. Research artifacts stay off-chain and become protocol-relevant only through explicit commitments or accepted decision records. ## Source Of Truth Flow diff --git a/docs/CURRENT_STATE.md b/docs/CURRENT_STATE.md index ae7b26b6..00c15491 100644 --- a/docs/CURRENT_STATE.md +++ b/docs/CURRENT_STATE.md @@ -10,6 +10,8 @@ FlowMemory is in foundation hardening. The bootstrap repository operating system and first contracts foundation have merged. The next major target is a runnable local V0 stack that connects contract fixtures, local indexing/verifier specs or fixtures, crypto schema vocabulary, and operator-facing data models without production deployment. +Launch-critical direction: Rootflow V0 and Flow Memory V0 are the core of the next milestone. Rootflow defines memory-state transitions. Flow Memory defines the agent-facing memory objects derived from FlowPulse observations, receipts, verifier reports, and committed roots. + ## Implemented In The Merged Repo Repository operating system: @@ -31,12 +33,23 @@ Contracts foundation: - `tests/RootfieldRegistry.t.sol` contains initial Foundry tests. - `tests/README.md` documents the current test command. +Launch-core specifications: + +- `docs/ROOTFLOW_V0.md` defines the Rootflow V0 transition model, status vocabulary, agent ownership, and launch acceptance. +- `docs/FLOW_MEMORY_V0.md` defines MemorySignal, MemoryReceipt, RootfieldBundle, AgentMemoryView, work-lane vocabulary, and dashboard display expectations. +- `docs/V0_LAUNCH_ACCEPTANCE.md` maps the Rootflow and Flow Memory objective to concrete artifacts and evidence. +- `docs/DECISIONS/rootflow-v0.md` records the V0 decision and non-goal boundaries. + ## Conceptual Or Not Implemented Yet - Production protocol deployment. - Production ownership, upgrade, governance, fee, token, or incentive mechanics. - Dynamic fees or tokenomics. - Production Uniswap v4 hook deployment. +- Complete Rootflow runtime implementation. +- Complete Flow Memory runtime implementation. +- Canonical JSON schema package for Rootflow and Flow Memory objects. +- End-to-end fixture-backed Rootflow acceptance run. - Indexer or verifier service runtime. - Persistence layer, live RPC reader, production APIs, or hosted services. - Dashboard, explorer, or hardware console implementation. @@ -85,12 +98,12 @@ Before assigning agents, check for dirty worktrees and avoid overlapping folders ## Current Operator Priorities -1. Keep current-state, roadmap, architecture, backlog, and review docs aligned with GitHub. +1. Make Rootflow V0 and Flow Memory V0 pass the launch acceptance matrix in `docs/V0_LAUNCH_ACCEPTANCE.md`. 2. Finish contracts foundation hardening without production deployment or token mechanics. -3. Specify the local indexer/verifier loop before building runtime services. -4. Define crypto vocabulary before proof systems or verifier economics. -5. Define hardware and dashboard scopes before implementation. -6. Keep chain/appchain work research-only and no-value until explicit gates are passed. +3. Build deterministic local fixtures for FlowPulse, receipts, Rootflow transitions, verifier reports, and dashboard state. +4. Define canonical crypto and JSON schema vocabulary before proof systems or verifier economics. +5. Keep dashboard work fixture-backed until indexer/verifier outputs stabilize. +6. Keep chain/appchain work no-value and local until explicit gates are passed. ## Update Rule diff --git a/docs/DAILY_HQ_RUNBOOK.md b/docs/DAILY_HQ_RUNBOOK.md index bb499d20..161f95d5 100644 --- a/docs/DAILY_HQ_RUNBOOK.md +++ b/docs/DAILY_HQ_RUNBOOK.md @@ -21,6 +21,8 @@ Check: - Blocked issues. - Issues missing labels or milestones. - Any PR touching forbidden folders. +- Rootflow and Flow Memory launch-core issues #63 through #67. +- Evidence gaps in `docs/V0_LAUNCH_ACCEPTANCE.md`. ## Issue Triage @@ -36,12 +38,13 @@ For each issue: Priority order: 1. Repo OS and review process. -2. Contracts foundation hardening. -3. Indexer/verifier fixture and schema work. -4. Crypto vocabulary. -5. Dashboard data model. -6. Hardware POC specs. -7. Research gates. +2. Rootflow and Flow Memory V0 launch-core issues #63 through #67. +3. Contracts foundation hardening. +4. Crypto vocabulary and deterministic fixtures. +5. Indexer/verifier fixture and schema work. +6. Dashboard fixture-backed display path. +7. Hardware POC specs. +8. Research gates. ## Starting Agents @@ -66,6 +69,7 @@ For each open PR: - Check area-specific tests or documented absence. - Check for scope creep. - Check whether docs/current state need updates. +- Check whether the PR satisfies named rows in `docs/V0_LAUNCH_ACCEPTANCE.md`. Reject or send back any PR that adds: @@ -83,11 +87,11 @@ Reject or send back any PR that adds: Prefer: 1. Repo OS, labels, milestones, PR process, runbook. -2. Current-state, roadmap, architecture, decision records. +2. Rootflow and Flow Memory specs, current-state, roadmap, architecture, decision records. 3. Contracts test/config hardening. -4. Indexer/verifier fixture/spec changes. -5. Crypto vocabulary. -6. Dashboard data model. +4. Crypto vocabulary and launch-core fixtures. +5. Indexer/verifier fixture/spec changes. +6. Dashboard fixture-backed display path. 7. Hardware scope docs. 8. Research docs. diff --git a/docs/DECISIONS/rootflow-v0.md b/docs/DECISIONS/rootflow-v0.md new file mode 100644 index 00000000..b82a2726 --- /dev/null +++ b/docs/DECISIONS/rootflow-v0.md @@ -0,0 +1,68 @@ +# Decision: Rootflow V0 Launch Core + +Date: 2026-05-13 + +Status: Accepted for V0 planning. + +## Context + +FlowMemory needs a launch-critical core that connects Base or local contract events to AI-readable memory without claiming that the full future L1, proof network, or hardware network is complete. + +The merged contracts foundation already includes `FlowPulse` and a baseline `RootfieldRegistry`, but Rootflow and the Flow Memory layer need a shared definition before builders can safely implement contracts, crypto fixtures, indexer/verifier logic, and dashboard views. + +## Decision + +Rootflow V0 is the cross-layer state-transition model for FlowMemory. + +Flow Memory V0 is the agent-facing memory layer built from FlowPulse observations, Rootflow transitions, receipts, verifier reports, and committed roots. + +Rootflow V0 must remain compact and receipt-oriented: + +- contracts emit FlowPulse events and store intentional compact state; +- indexers derive receipt metadata such as `txHash` and `logIndex`; +- crypto packages define canonical serialization, ids, signatures, and fixture validation; +- verifiers assign launch vocabulary statuses; +- dashboards render Rootfield, Rootflow, receipt, and memory state; +- heavy AI/model/memory/artifact data stays off-chain. + +The minimum shared status set is: + +- `observed` +- `pending` +- `verified` +- `failed` +- `reorged` +- `unsupported` + +## Consequences + +Builder agents can work in parallel without redefining the product core: + +- Contracts agent owns compact on-chain state and FlowPulse emission. +- Crypto agent owns canonical object shapes, hashes, receipts, and fixtures. +- Indexer/verifier agent owns observation identity, transition construction, reports, and status handling. +- Dashboard agent owns the operator and agent-readable display path. +- HQ/review owns docs, acceptance matrix, merge order, and claim discipline. + +The launch acceptance test is an end-to-end local V0 flow: + +1. emit or load a FlowPulse; +2. observe it with the indexer; +3. create or validate a receipt; +4. commit or update a Rootfield root; +5. produce a Rootflow transition; +6. show the resulting Flow Memory state in the dashboard. + +## Boundaries + +This decision does not approve: + +- production L1 or appchain claims; +- production mainnet deployment; +- production Uniswap v4 hook deployment; +- tokenomics; +- dynamic fees; +- full trustless verifier network claims; +- free-storage claims; +- AI-running-on-chain claims; +- hardware trustlessness claims without verifier/proof infrastructure. diff --git a/docs/FLOW_MEMORY_V0.md b/docs/FLOW_MEMORY_V0.md new file mode 100644 index 00000000..0a60fb9a --- /dev/null +++ b/docs/FLOW_MEMORY_V0.md @@ -0,0 +1,184 @@ +# Flow Memory V0 + +Status: launch-critical V0 specification. + +Flow Memory is the AI-facing memory layer built from FlowPulse observations, Rootflow transitions, receipts, verifier reports, and committed roots. + +Flow Memory V0 does not put heavy AI memory on-chain. It turns compact public signals and verifiable receipts into structured memory objects that agents and dashboards can read. + +## Purpose + +Flow Memory V0 answers: + +1. What happened? +2. Why does it matter as memory? +3. Which root or Rootfield does it affect? +4. What is the verification status? +5. How can an AI agent cite or use it without pretending raw model data lives on-chain? + +## Launch Flow + +```text +Uniswap v4 or fixture activity +-> FlowPulse +-> indexed observation +-> MemorySignal +-> MemoryReceipt +-> RootflowTransition +-> RootfieldBundle +-> AgentMemoryView +``` + +## Core Objects + +### MemorySignal + +A `MemorySignal` is the smallest agent-readable event derived from a FlowPulse observation. + +Minimum V0 fields: + +```json +{ + "schema": "flowmemory.memory_signal.v0", + "signalId": "bytes32-or-hex-string", + "pulseId": "bytes32-or-hex-string", + "rootfieldId": "bytes32-or-hex-string", + "signalType": "root_commitment|swap_activity|failure|repair|evaluation|hardware_heartbeat|unsupported", + "subject": "bytes32-or-hex-string", + "commitment": "bytes32-or-hex-string", + "source": { + "chainId": 84532, + "contractAddress": "0x...", + "blockNumber": 1, + "blockHash": "0x...", + "txHash": "0x...", + "logIndex": 0 + }, + "status": "observed|pending|verified|failed|reorged|unsupported" +} +``` + +### MemoryReceipt + +A `MemoryReceipt` links a signal to evidence, commitments, and verifier output. + +Minimum V0 fields: + +```json +{ + "schema": "flowmemory.memory_receipt.v0", + "receiptId": "bytes32-or-hex-string", + "signalId": "bytes32-or-hex-string", + "rootfieldId": "bytes32-or-hex-string", + "artifactCommitment": "bytes32-or-hex-string", + "evidenceURI": "string-or-null", + "verifierReportId": "bytes32-or-hex-string-or-null", + "status": "pending|verified|failed|reorged|unsupported" +} +``` + +### RootfieldBundle + +A `RootfieldBundle` is the current dashboard and agent-facing state for one Rootfield namespace. + +Minimum V0 fields: + +```json +{ + "schema": "flowmemory.rootfield_bundle.v0", + "rootfieldId": "bytes32-or-hex-string", + "schemaHash": "bytes32-or-hex-string", + "metadataHash": "bytes32-or-hex-string", + "latestRoot": "bytes32-or-hex-string", + "latestTransitionId": "bytes32-or-hex-string-or-null", + "pulseCount": 1, + "rootCount": 1, + "status": "active|inactive|unknown", + "updatedAt": "iso-8601" +} +``` + +### AgentMemoryView + +An `AgentMemoryView` is the safe output shape for AI agents. + +Minimum V0 fields: + +```json +{ + "schema": "flowmemory.agent_memory_view.v0", + "rootfieldId": "bytes32-or-hex-string", + "latestRoot": "bytes32-or-hex-string", + "verifiedSignals": [], + "pendingSignals": [], + "failedSignals": [], + "reorgedSignals": [], + "openQuestions": [], + "limitations": [ + "Heavy memory artifacts are off-chain.", + "V0 verification is local/testnet readiness, not a production trustless proof network." + ] +} +``` + +## Work And Reliability Vocabulary + +Flow Memory V0 reserves these work lanes for agent and dashboard vocabulary: + +- `MEMORY_REFRESH` +- `FAILURE_DISCOVERY` +- `FAILURE_REPAIR` +- `MANIFOLD_DISCOVERY` +- `STEERING_VALIDATION` +- `CHECKPOINT_STORAGE` +- `GPU_TRAINING` +- `EVAL_COUNTEREXAMPLE` + +These names do not mean the repo already implements GPU training, proof networks, or production agent automation. They are V0 vocabulary for future-compatible memory records. + +## What Agents May Say + +Allowed: + +- "This swap or fixture produced a FlowPulse." +- "The indexer observed the pulse and derived receipt metadata." +- "The verifier produced a V0 report." +- "Rootflow moved this Rootfield from one committed root to another." +- "This AgentMemoryView exposes verified and pending memory signals." + +Not allowed: + +- "AI runs on-chain." +- "All memory is stored on-chain." +- "Storage is free." +- "The hook knows txHash or logIndex during execution." +- "FlowMemory is a production L1." +- "V0 verification is fully trustless." + +## Dashboard Display Path + +The dashboard should be able to render: + +- Rootfield list. +- Rootfield detail. +- Rootflow transition timeline. +- MemorySignal feed. +- MemoryReceipt detail. +- Verifier report status. +- AgentMemoryView JSON or readable summary. + +Fixtures are acceptable for V0 launch if they are deterministic and documented. + +## Launch Acceptance + +Flow Memory V0 is launch-ready only when the local system can: + +1. Produce or load a FlowPulse fixture. +2. Derive a MemorySignal. +3. Link a MemoryReceipt. +4. Produce a verifier report. +5. Produce a Rootflow transition. +6. Update a RootfieldBundle. +7. Render an AgentMemoryView or dashboard equivalent. + +The first launch can be fixture-backed, but the boundaries must be honest and documented. diff --git a/docs/ISSUE_BACKLOG.md b/docs/ISSUE_BACKLOG.md index baa3de1c..6441ba09 100644 --- a/docs/ISSUE_BACKLOG.md +++ b/docs/ISSUE_BACKLOG.md @@ -7,6 +7,7 @@ This file maps existing GitHub issues #6-#55 into program milestones and agent w ## Milestones - V0 Repo OS: management layer, docs, templates, labels, scripts, review process. +- Rootflow and Flow Memory V0 Launch Core: cross-agent launch target for Rootfield namespaces, Rootflow transitions, Flow Memory schemas, deterministic fixtures, verifier reports, and dashboard-readable state. - V0 Contracts Foundation: FlowPulse, RootfieldRegistry, contract test hardening, contract-boundary decisions. - V0 Local Stack: local fixtures, indexer/verifier schemas, local devnet gates, persistence boundary, live-reader boundary. - V0 Hardware POC: FlowRouter, Meshtastic/LoRa, enclosure, indicators, NFC cartridge, hardware demo planning. @@ -34,6 +35,18 @@ This file maps existing GitHub issues #6-#55 into program milestones and agent w | #16 `[docs/architecture] Map observed, committed, and verified state boundaries` | Closed | Review/HQ - `flowmemory-review` | Folded into #14/#15 | Closed as not planned; keep as historical note. | | #48 `[infrastructure] Ignore generated Foundry artifacts` | Open | Review/HQ - `flowmemory-review` | #6 | `.gitignore` or docs hygiene only. | +## Rootflow And Flow Memory V0 Launch Core + +Primary milestone: make `docs/V0_LAUNCH_ACCEPTANCE.md` pass with concrete implementation evidence. + +| Issue | State | Agent/worktree | Dependencies | Notes | +| --- | --- | --- | --- | --- | +| #63 `[launch-core/contracts] Build Rootflow V0 contract support and coverage` | Open | Contracts - `flowmemory-contracts` | #6, #7, #8, #22 | Launch epic for contracts-side evidence; no production hook or deployment. | +| #64 `[launch-core/crypto] Define Rootflow and Flow Memory V0 canonical schemas and fixtures` | Open | Crypto - `flowmemory-crypto` | #17, #40, #45 helpful | Canonical ids, schemas, fixtures, and validation; no proof circuits. | +| #65 `[launch-core/indexer] Implement Rootflow V0 fixture engine and verifier reports` | Open | Indexer - `flowmemory-indexer` | #13, #14, #43, #44, #45, #64 | Must output dashboard-readable Rootflow and Flow Memory fixture state. | +| #66 `[launch-core/dashboard] Render Rootflow and Flow Memory V0 fixture state` | Open | Dashboard - `flowmemory-dashboard` | #19, #65 | Fixture-backed display path; no hosted production API. | +| #67 `[launch-core/review] Audit Rootflow and Flow Memory V0 acceptance across PRs` | Open | Review/HQ - `flowmemory-review` | #63, #64, #65, #66 | Acceptance audit and merge readiness; no subsystem implementation. | + ## V0 Contracts Foundation | Issue | State | Agent/worktree | Dependencies | Notes | @@ -118,7 +131,8 @@ P0 sequence: 1. #10, #20, #9 2. #6, #7, #8 3. #13, #14, #17 -4. #43, #44, #45, #49, #51 +4. #63, #64, #65, #66, #67 +5. #43, #44, #45, #49, #51 P1 sequence: diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md index 310f9286..bb19db5c 100644 --- a/docs/ROADMAP.md +++ b/docs/ROADMAP.md @@ -4,17 +4,19 @@ This roadmap is the project-management view of FlowMemory. Use GitHub issues for Production L1, tokenomics, mainnet deployment, production Uniswap v4 hook deployment, hardware manufacturing, and full dashboard implementation are later gated work. They are not approved by this roadmap. -## Immediate Major Milestone: Runnable Local V0 Stack +## Immediate Major Milestone: Rootflow And Flow Memory V0 Launch Core Goal: make a local developer able to run the smallest FlowMemory loop without production deployment. -The local V0 stack means: +The launch-core V0 stack means: - Contracts compile and tests run locally. - FlowPulse fixtures can be produced or consumed deterministically. +- Rootflow transitions link FlowPulse observations, parent state, receipts, verifier reports, and new roots. +- Flow Memory objects expose MemorySignal, MemoryReceipt, RootfieldBundle, and AgentMemoryView shapes. - Indexer/verifier specs define observation identity, reorg states, and report shape. - Crypto vocabulary defines receipts, attestations, roots, commitments, and proof boundaries. -- Dashboard planning has a data model for observed, pending, verified, failed, unsupported, and reorged states. +- Dashboard can consume fixture-backed observed, pending, verified, failed, unsupported, and reorged states. - Hardware and research tracks have bounded specs but do not block local software validation. Non-goals: @@ -25,7 +27,7 @@ Non-goals: - No production L1/appchain. - No production hook deployment. - No hardware manufacturing. -- No full dashboard app. +- No hosted production dashboard or production API. ## Near-Term Phases @@ -55,6 +57,8 @@ Status: active as specs and local fixtures before services. - Specify canonical FlowPulse observation identity. - Define verifier statuses and report JSON schema. +- Define Rootflow transition schema and parent/child state-linking behavior. +- Define Flow Memory schemas for MemorySignal, MemoryReceipt, RootfieldBundle, and AgentMemoryView. - Define fixture-based parser and reorg-state tests. - Define persistence and local RPC reader boundaries only after fixture behavior stabilizes. - Define local devnet smoke-test gates without mainnet or production deployment. @@ -72,20 +76,22 @@ Status: active. ### Phase 4: V0 Crypto Schema Layer -Status: planning. +Status: active as launch-core schema and fixture work. - Define receipt, attestation, commitment, root, and proof vocabulary. - Define domain separation and replay boundaries. +- Define canonical ids for MemorySignal, MemoryReceipt, RootflowTransition, RootfieldBundle, and verifier reports. - Validate test vectors through verifier specs. - Keep proof circuits, GPU proofs, verifier economics, and production crypto infrastructure out of scope. -### Phase 5: V0 Dashboard Data Model +### Phase 5: V0 Dashboard Data Model And Display Path -Status: planning. +Status: active as fixture-backed local display work. - Define app-facing entities for dashboard and explorer. - Model observed, pending, finalized, verified, invalid, unresolved, unsupported, and reorged states. -- Keep frontend scaffolding and production APIs out of scope until the local stack stabilizes. +- Render Rootfield, Rootflow transition, MemorySignal, MemoryReceipt, verifier report, and AgentMemoryView fixtures. +- Keep hosted production APIs and deployment out of scope until the local stack stabilizes. ### Phase 6: V0 Hardware POC @@ -121,10 +127,10 @@ Status: blocked until explicit go/no-go decisions exist. ## Merge Order Preference 1. Repo OS and review process changes. -2. Current state, roadmap, architecture, and decision records. +2. Rootflow and Flow Memory specs, current state, roadmap, architecture, and decision records. 3. Contracts foundation hardening. -4. Indexer/verifier fixture and schema work. -5. Crypto schema vocabulary and test-vector validation. -6. Dashboard data model. +4. Crypto schema vocabulary and test-vector validation. +5. Indexer/verifier fixture, Rootflow transition, and report schema work. +6. Dashboard data model and fixture-backed display path. 7. Hardware POC specs. 8. Research lab documents. diff --git a/docs/ROOTFLOW_V0.md b/docs/ROOTFLOW_V0.md new file mode 100644 index 00000000..19fe1d55 --- /dev/null +++ b/docs/ROOTFLOW_V0.md @@ -0,0 +1,155 @@ +# Rootflow V0 + +Status: launch-critical V0 specification. + +Rootflow is the FlowMemory state-transition layer. It explains how a FlowPulse event, receipt, verifier report, and committed root become a new memory state. + +Rootflow V0 is not a production L1, proof network, storage layer, governance system, or token system. It is the local and testnet-ready transition model that lets contracts, crypto, indexers, verifiers, and dashboard agents agree on one memory-state shape. + +## Purpose + +Rootflow answers five questions: + +1. What Rootfield namespace does this memory state belong to? +2. What pulse or previous root does this transition build on? +3. What new root or commitment is being proposed? +4. What receipt and verifier status support the transition? +5. What should a dashboard or AI agent show as the current state? + +The launch wedge is: + +```text +FlowPulse +-> indexed observation +-> receipt +-> verifier report +-> Rootflow transition +-> Rootfield bundle +-> dashboard-readable Flow Memory state +``` + +## Core Terms + +- `FlowPulse`: the compact on-chain event emitted by a contract or future hook adapter. +- `Rootfield`: a namespace for a memory-state stream. +- `RootfieldBundle`: the current committed root state for a Rootfield namespace. +- `RootflowTransition`: one proposed or accepted state transition within a Rootfield. +- `MemoryReceipt`: an off-chain or future on-chain receipt that links evidence to a signal or transition. +- `VerifierReport`: a deterministic report describing whether a receipt or transition is valid. +- `AgentMemoryView`: the agent-facing projection of verified or pending memory state. + +## Required Statuses + +Rootflow V0 uses this minimum status vocabulary: + +| Status | Meaning | +| --- | --- | +| `observed` | A FlowPulse log or fixture has been read, but it is not yet ready to commit. | +| `pending` | A transition candidate exists and is waiting for verification, confirmation, or required evidence. | +| `verified` | The transition is accepted by the V0 verifier rules. | +| `failed` | The transition was checked and rejected. | +| `reorged` | The underlying observation was removed or superseded by a chain reorg. | +| `unsupported` | The event or receipt uses a schema the V0 verifier does not support. | + +Dashboard and verifier work may expose more detailed internal states, but these statuses are the V0 cross-agent contract. + +## Rootflow Transition Shape + +Every Rootflow transition must be expressible with this canonical shape: + +```json +{ + "schema": "flowmemory.rootflow.transition.v0", + "transitionId": "bytes32-or-hex-string", + "rootfieldId": "bytes32-or-hex-string", + "pulseId": "bytes32-or-hex-string", + "parentPulseId": "bytes32-or-hex-string-or-null", + "parentRoot": "bytes32-or-hex-string-or-null", + "newRoot": "bytes32-or-hex-string", + "artifactCommitment": "bytes32-or-hex-string", + "receiptId": "bytes32-or-hex-string", + "verifierReportId": "bytes32-or-hex-string-or-null", + "status": "observed|pending|verified|failed|reorged|unsupported", + "sequence": 1, + "observedAt": "iso-8601-or-block-time", + "updatedAt": "iso-8601", + "source": { + "chainId": 84532, + "contractAddress": "0x...", + "blockNumber": 1, + "blockHash": "0x...", + "txHash": "0x...", + "logIndex": 0 + } +} +``` + +The exact JSON schema may live in the crypto or indexer package, but the fields above are the V0 minimum. + +## Invariants + +- A transition must belong to exactly one `rootfieldId`. +- A transition must link to one `pulseId`. +- A transition must identify its source observation after the indexer reads receipts and logs. +- A contract must not claim final `txHash` or `logIndex` during execution. +- Heavy memory, model, evaluation, media, and artifact data stays off-chain. +- On-chain state stores compact roots, commitments, receipts, counters, and intentional protocol state only. +- A `verified` transition must have a verifier report or accepted V0 fixture proof. +- A `reorged` transition must not remain the current verified state. + +## Agent Responsibilities + +Contracts agent: + +- Keep `RootfieldRegistry` compact. +- Emit `FlowPulse` events. +- Add lifecycle support only when the status and ownership decisions are accepted. +- Do not add production hooks, tokenomics, governance, or dynamic fees. + +Crypto agent: + +- Define canonical serialization and hash inputs for Rootflow transitions. +- Define receipt ids, verifier report ids, and domain separation. +- Produce deterministic fixtures. +- Do not build proof circuits or verifier economics for V0. + +Indexer/verifier agent: + +- Derive `txHash`, `logIndex`, block metadata, and observation identity from receipts and logs. +- Build transition candidates. +- Apply verifier statuses. +- Persist or export the Rootflow timeline for dashboard use. + +Dashboard agent: + +- Display Rootfield namespaces, Rootflow transitions, status, source observation, and receipt links. +- Treat fixtures as the first data source. +- Do not imply production proof security. + +HQ/review agent: + +- Keep this spec, current state, roadmap, decision records, and acceptance matrix aligned with GitHub. +- Review PRs against the launch acceptance gates. + +## Launch Acceptance + +Rootflow V0 is launch-ready only when a local developer can: + +1. Emit or load a FlowPulse. +2. Observe it with the indexer. +3. Create or validate a receipt. +4. Commit or update a Rootfield root. +5. Produce a Rootflow transition. +6. Show the resulting transition and status in the dashboard. + +Passing an isolated unit test or opening a small PR is not enough. + +## Explicit Non-Goals + +- No production L1 claim. +- No production mainnet readiness claim. +- No full trustless verifier network claim. +- No free-storage claim. +- No AI-runs-on-chain claim. +- No tokenomics or dynamic fee hooks. +- No hardware trustlessness claim without verifier/proof infrastructure. diff --git a/docs/START_HERE.md b/docs/START_HERE.md index 0a42525f..3ffdc781 100644 --- a/docs/START_HERE.md +++ b/docs/START_HERE.md @@ -7,8 +7,9 @@ This is the first document to read after `AGENTS.md`. 1. `AGENTS.md` 2. `docs/FLOWMEMORY_HQ_CONTEXT.md` 3. `docs/CURRENT_STATE.md` -4. The task-specific document or issue -5. Any relevant decision records in `docs/DECISIONS/` +4. `docs/ROOTFLOW_V0.md`, `docs/FLOW_MEMORY_V0.md`, and `docs/V0_LAUNCH_ACCEPTANCE.md` for launch-core work +5. The task-specific document or issue +6. Any relevant decision records in `docs/DECISIONS/` ## Before You Edit diff --git a/docs/V0_LAUNCH_ACCEPTANCE.md b/docs/V0_LAUNCH_ACCEPTANCE.md new file mode 100644 index 00000000..f0f35e03 --- /dev/null +++ b/docs/V0_LAUNCH_ACCEPTANCE.md @@ -0,0 +1,123 @@ +# V0 Launch Acceptance Matrix + +Status: active milestone checklist. + +This matrix maps the Rootflow V0 and Flow Memory V0 goal to concrete evidence. It is intentionally strict: a PR, passing test, or useful document is only evidence if it covers the requirement named here. + +## Goal + +Build Rootflow V0 and Flow Memory V0 as the launch-critical core of FlowMemory. + +The local/testnet-ready V0 system must support: + +- Rootfield namespaces. +- Root commitments. +- Parent/child memory-state transitions. +- FlowPulse linkage. +- Receipt linkage. +- Verifier statuses. +- `pending`, `verified`, `failed`, and `reorged` states. +- Deterministic fixtures. +- Dashboard-readable state. +- Flow Memory schemas. +- Local fixtures. +- Verifier reports. +- Dashboard display path. +- Source-of-truth docs. + +It must not claim production L1, production mainnet readiness, full trustless verification, free storage, or AI running on-chain. + +## Artifact Checklist + +| Requirement | Required evidence | Owner | Current state | +| --- | --- | --- | --- | +| Rootfield namespaces | Contract or fixture registers `rootfieldId`; docs explain namespace policy. | Contracts | Baseline exists in `RootfieldRegistry`; policy still needs hardening. | +| Root commitments | Contract or fixture commits a nonzero root and emits/records the update. | Contracts | Baseline exists in `submitRoot`; tests need launch-grade coverage. | +| Parent/child transitions | `RootflowTransition` includes parent pulse/root and new root. | Indexer + Crypto + Contracts | Specified in `docs/ROOTFLOW_V0.md`; implementation still required. | +| FlowPulse linkage | Transition and memory signal reference `pulseId`. | Indexer + Dashboard | Specified; parser and display path still required. | +| Receipt linkage | `MemoryReceipt` links signal, artifact commitment, evidence URI, and verifier report. | Crypto + Indexer | Specified in `docs/FLOW_MEMORY_V0.md`; implementation still required. | +| Verifier statuses | Cross-agent status vocabulary exists and verifier reports use it. | Indexer + Crypto | Specified; schema/tests still required. | +| Pending state | Fixture/report can show pending transition. | Indexer + Dashboard | Required, not complete. | +| Verified state | Fixture/report can show verified transition. | Indexer + Crypto + Dashboard | Required, not complete. | +| Failed state | Fixture/report can show rejected transition. | Indexer + Dashboard | Required, not complete. | +| Reorged state | Fixture/report can show removed/superseded observation. | Indexer | Required, not complete. | +| Deterministic fixtures | Fixtures run without private RPC keys or secrets. | Indexer + Crypto + Chain | Required, not complete. | +| Dashboard-readable state | JSON/API/fixture shape feeds dashboard views. | Dashboard + Indexer | Required, not complete. | +| Flow Memory schemas | `MemorySignal`, `MemoryReceipt`, `RootfieldBundle`, and `AgentMemoryView` schemas exist. | Crypto + Indexer + Dashboard | Specified; canonical schemas still required. | +| Verifier reports | JSON schema and sample reports exist. | Indexer + Crypto | Required, not complete. | +| Dashboard display path | Dashboard renders Rootfield, transition, signal, receipt, and status data. | Dashboard | Required, not complete. | +| Source-of-truth docs | Current state, roadmap, decision record, and specs are updated. | HQ/Review | This PR adds the launch-core docs. | + +## End-To-End Acceptance Test + +A developer must be able to run a local V0 flow: + +1. Emit or load a FlowPulse. +2. Observe it with the indexer. +3. Create or validate a receipt. +4. Commit or update a Rootfield root. +5. Produce a Rootflow transition. +6. Show the resulting Flow Memory state in the dashboard. + +The final acceptance evidence should include: + +- exact commands run; +- fixture paths; +- output paths; +- screenshots or dashboard verification notes when UI exists; +- test results; +- PR links for each subsystem. + +## Required Agent Handoffs + +Contracts to indexer: + +- FlowPulse event ABI. +- RootfieldRegistry ABI. +- local deployment or fixture event output. +- contract tests showing root registration and root commitment. + +Crypto to indexer: + +- canonical hash inputs. +- receipt id generation. +- verifier report id generation. +- signature envelope or fixture validation rules. + +Indexer to dashboard: + +- observation fixture. +- verifier report fixture. +- Rootflow timeline fixture. +- AgentMemoryView fixture or endpoint. + +HQ/review to all agents: + +- merge order. +- non-goals. +- PR review checklist. +- current-state updates. + +## Merge Readiness + +The milestone is not ready to call complete until all of these are true: + +- Contracts tests pass. +- Crypto fixture validation passes. +- Indexer fixture parser/verifier checks pass. +- Dashboard can render fixture-backed Rootflow/Flow Memory state. +- Docs name what is implemented and what remains conceptual. +- Review agent confirms no PR claims production L1, mainnet readiness, full trustless verification, free storage, or AI running on-chain. + +## Non-Goal Guardrails + +Do not use this milestone to add: + +- tokenomics; +- dynamic fee hooks; +- production deployment config; +- production L1 or appchain claims; +- production Uniswap v4 hook deployment; +- GPU proof systems; +- verifier economics; +- hardware manufacturing claims. From e59232f4b381df78afa49cb623e70c00aafa87f0 Mon Sep 17 00:00:00 2001 From: FlowmemoryAI <283694809+FlowmemoryAI@users.noreply.github.com> Date: Wed, 13 May 2026 09:56:03 -0500 Subject: [PATCH 3/5] Add Rootflow launch acceptance audit --- docs/CURRENT_STATE.md | 2 + docs/DAILY_HQ_RUNBOOK.md | 1 + docs/ISSUE_BACKLOG.md | 2 +- ...OOTFLOW_FLOW_MEMORY_V0_ACCEPTANCE_AUDIT.md | 166 ++++++++++++++++++ 4 files changed, 170 insertions(+), 1 deletion(-) create mode 100644 docs/reviews/ROOTFLOW_FLOW_MEMORY_V0_ACCEPTANCE_AUDIT.md diff --git a/docs/CURRENT_STATE.md b/docs/CURRENT_STATE.md index 00c15491..a87360f7 100644 --- a/docs/CURRENT_STATE.md +++ b/docs/CURRENT_STATE.md @@ -39,6 +39,7 @@ Launch-core specifications: - `docs/FLOW_MEMORY_V0.md` defines MemorySignal, MemoryReceipt, RootfieldBundle, AgentMemoryView, work-lane vocabulary, and dashboard display expectations. - `docs/V0_LAUNCH_ACCEPTANCE.md` maps the Rootflow and Flow Memory objective to concrete artifacts and evidence. - `docs/DECISIONS/rootflow-v0.md` records the V0 decision and non-goal boundaries. +- `docs/reviews/ROOTFLOW_FLOW_MEMORY_V0_ACCEPTANCE_AUDIT.md` tracks evidence and missing work for the active launch-core goal. ## Conceptual Or Not Implemented Yet @@ -50,6 +51,7 @@ Launch-core specifications: - Complete Flow Memory runtime implementation. - Canonical JSON schema package for Rootflow and Flow Memory objects. - End-to-end fixture-backed Rootflow acceptance run. +- Completed launch-core acceptance audit. - Indexer or verifier service runtime. - Persistence layer, live RPC reader, production APIs, or hosted services. - Dashboard, explorer, or hardware console implementation. diff --git a/docs/DAILY_HQ_RUNBOOK.md b/docs/DAILY_HQ_RUNBOOK.md index 161f95d5..0619f2ce 100644 --- a/docs/DAILY_HQ_RUNBOOK.md +++ b/docs/DAILY_HQ_RUNBOOK.md @@ -23,6 +23,7 @@ Check: - Any PR touching forbidden folders. - Rootflow and Flow Memory launch-core issues #63 through #67. - Evidence gaps in `docs/V0_LAUNCH_ACCEPTANCE.md`. +- Current audit notes in `docs/reviews/ROOTFLOW_FLOW_MEMORY_V0_ACCEPTANCE_AUDIT.md`. ## Issue Triage diff --git a/docs/ISSUE_BACKLOG.md b/docs/ISSUE_BACKLOG.md index 6441ba09..825da356 100644 --- a/docs/ISSUE_BACKLOG.md +++ b/docs/ISSUE_BACKLOG.md @@ -45,7 +45,7 @@ Primary milestone: make `docs/V0_LAUNCH_ACCEPTANCE.md` pass with concrete implem | #64 `[launch-core/crypto] Define Rootflow and Flow Memory V0 canonical schemas and fixtures` | Open | Crypto - `flowmemory-crypto` | #17, #40, #45 helpful | Canonical ids, schemas, fixtures, and validation; no proof circuits. | | #65 `[launch-core/indexer] Implement Rootflow V0 fixture engine and verifier reports` | Open | Indexer - `flowmemory-indexer` | #13, #14, #43, #44, #45, #64 | Must output dashboard-readable Rootflow and Flow Memory fixture state. | | #66 `[launch-core/dashboard] Render Rootflow and Flow Memory V0 fixture state` | Open | Dashboard - `flowmemory-dashboard` | #19, #65 | Fixture-backed display path; no hosted production API. | -| #67 `[launch-core/review] Audit Rootflow and Flow Memory V0 acceptance across PRs` | Open | Review/HQ - `flowmemory-review` | #63, #64, #65, #66 | Acceptance audit and merge readiness; no subsystem implementation. | +| #67 `[launch-core/review] Audit Rootflow and Flow Memory V0 acceptance across PRs` | Open | Review/HQ - `flowmemory-review` | #63, #64, #65, #66 | Acceptance audit and merge readiness in `docs/reviews/ROOTFLOW_FLOW_MEMORY_V0_ACCEPTANCE_AUDIT.md`; no subsystem implementation. | ## V0 Contracts Foundation diff --git a/docs/reviews/ROOTFLOW_FLOW_MEMORY_V0_ACCEPTANCE_AUDIT.md b/docs/reviews/ROOTFLOW_FLOW_MEMORY_V0_ACCEPTANCE_AUDIT.md new file mode 100644 index 00000000..390db585 --- /dev/null +++ b/docs/reviews/ROOTFLOW_FLOW_MEMORY_V0_ACCEPTANCE_AUDIT.md @@ -0,0 +1,166 @@ +# Rootflow And Flow Memory V0 Acceptance Audit + +Date: 2026-05-13 + +Status: active audit, not complete. + +This audit tracks the active goal: build Rootflow V0 and Flow Memory V0 as the launch-critical core of FlowMemory. + +Do not use this file as proof that the milestone is complete. Use it to decide what evidence is still missing. + +## Objective Restated As Deliverables + +Rootflow V0 and Flow Memory V0 are complete only when the repo has concrete, reviewed evidence for all of these deliverables: + +1. Rootfield namespaces. +2. Root commitments. +3. Parent/child memory-state transitions. +4. FlowPulse linkage. +5. Receipt linkage. +6. Verifier statuses. +7. Pending, verified, failed, reorged, and unsupported states. +8. Deterministic fixtures. +9. Dashboard-readable state. +10. Flow Memory schemas. +11. Local fixtures. +12. Verifier reports. +13. Dashboard display path. +14. Source-of-truth docs. +15. No production L1, production mainnet readiness, full trustless verification, free storage, or AI-runs-on-chain claims. + +The end-to-end acceptance gate is: + +1. Emit or load a FlowPulse. +2. Observe it with the indexer. +3. Create or validate a receipt. +4. Commit or update a Rootfield root. +5. Produce a Rootflow transition. +6. Show the resulting Flow Memory state in the dashboard. + +## Evidence Sources Checked + +Local checkout: + +- Branch: `hq/program-manager-os`. +- Commit: `9522389 Define Rootflow and Flow Memory launch core`. +- `git diff --check`: clean except Windows line-ending warnings. +- Non-ASCII scan over `README.md`, `AGENTS.md`, and `docs/`: clean. + +Open PRs: + +- #57 `[codex] Build contracts v0 foundation` +- #59 `[codex] build FlowMemory HQ program manager OS` +- #60 `[codex] Build FlowMemory crypto v0 foundation` +- #61 `[codex] Build indexer verifier v0 fixture package` +- #62 `Build FlowMemory Dashboard V0` + +Launch-core issues: + +- #63 `[launch-core/contracts] Build Rootflow V0 contract support and coverage` +- #64 `[launch-core/crypto] Define Rootflow and Flow Memory V0 canonical schemas and fixtures` +- #65 `[launch-core/indexer] Implement Rootflow V0 fixture engine and verifier reports` +- #66 `[launch-core/dashboard] Render Rootflow and Flow Memory V0 fixture state` +- #67 `[launch-core/review] Audit Rootflow and Flow Memory V0 acceptance across PRs` + +GitHub checks observed: + +- PRs #57, #60, #61, and #62 currently show `Repository hygiene` passing. +- This is not enough to prove launch acceptance. Area-specific tests and fixture commands still need explicit evidence. + +## Prompt-To-Artifact Checklist + +| Requirement | Expected artifacts | Evidence found | Status | +| --- | --- | --- | --- | +| Rootfield namespaces | Contract registration, tests, namespace policy docs | Merged `RootfieldRegistry` baseline exists. PR #57 changes `RootfieldRegistry`, interfaces, and tests. | Partial, needs PR #57 review and contract test evidence. | +| Root commitments | Contract root submission, tests, fixture output | Merged `submitRoot` baseline exists. PR #57 expands tests and root commitment behavior. | Partial, needs PR #57 review and `forge test` evidence. | +| Parent/child transitions | `RootflowTransition` schema plus parent pulse/root linkage | `docs/ROOTFLOW_V0.md` specifies shape. PR #57 includes `parentPulseId`; PR #61 includes observed `parentPulseId`. | Partial, needs actual RootflowTransition artifact and fixture output. | +| FlowPulse linkage | Transition and signal reference `pulseId` | Merged `FlowPulse` exists. PR #61 fixtures include `pulseId`. | Partial, needs MemorySignal/RootflowTransition output. | +| Receipt linkage | `MemoryReceipt`, receipt id, evidence URI, report id | `docs/FLOW_MEMORY_V0.md` specifies shape. PR #60 and #61 include receipt/report files. | Partial, needs canonical `MemoryReceipt` fixture and validation command. | +| Verifier statuses | Shared status vocabulary in docs and reports | `docs/ROOTFLOW_V0.md` requires observed/pending/verified/failed/reorged/unsupported. PR #61 appears to use `valid`, `invalid`, `unresolved`, `unsupported`, `reorged` internally with mapping notes. | Needs reconciliation before acceptance. | +| Pending state | Fixture/report/dashboard state | PR #61 and #62 include pending states. | Partial, needs command output and dashboard evidence. | +| Verified state | Fixture/report/dashboard state | PR #60 has `verified` naming; PR #61 uses `valid`; PR #62 has `verified`. | Needs vocabulary adapter or standardization. | +| Failed state | Fixture/report/dashboard state | Spec requires `failed`; PR #61 uses `invalid`; dashboard also includes `invalid`. | Needs vocabulary adapter or standardization. | +| Reorged state | Fixture/report/dashboard state | PR #61 and #62 include `reorged`. | Partial, needs test evidence. | +| Unsupported state | Fixture/report/dashboard state | PR #61 and #62 include `unsupported`. | Partial, needs test evidence. | +| Deterministic fixtures | Stable JSON fixtures and commands | PR #60, #61, and #62 add fixtures. | Partial, commands not yet audited. | +| Dashboard-readable state | JSON/API shape for dashboard | PR #62 adds `apps/dashboard/public/data/flowmemory-dashboard-v0.json` and `fixtures/dashboard/flowmemory-dashboard-v0.json`. | Partial, needs local dashboard run/check. | +| Flow Memory schemas | MemorySignal, MemoryReceipt, RootfieldBundle, AgentMemoryView schemas | `docs/FLOW_MEMORY_V0.md` specifies minimum shapes. PR #60/#61/#62 need explicit canonical schemas checked. | Incomplete until schema artifacts are confirmed. | +| Local fixtures | Local fixture files across contracts/crypto/indexer/dashboard | PR #60, #61, #62 include fixtures. | Partial, needs end-to-end fixture path. | +| Verifier reports | Report schema, sample reports, validation | PR #61 includes `verification-report.schema.json` and `reports.json`. | Partial, needs validation command output. | +| Dashboard display path | Local app renders Rootflow/Flow Memory state | PR #62 adds a dashboard app and views. | Partial, needs run/test/screenshot evidence. | +| Source-of-truth docs | Current state, roadmap, decision, acceptance docs | PR #59 commit `9522389` adds launch-core docs and issue mapping. | Ready for review, not merged yet. | +| Safe claims | No prohibited production claims | Specs explicitly forbid prohibited claims. | Must be checked across PR text and docs before merge. | + +## Current Gaps + +Critical gaps: + +- No single end-to-end command has been verified that runs FlowPulse fixture -> indexer observation -> receipt/report -> Rootflow transition -> dashboard state. +- `RootflowTransition` is specified but not yet confirmed as a concrete output artifact in the subsystem PRs. +- `MemorySignal`, `MemoryReceipt`, `RootfieldBundle`, and `AgentMemoryView` are specified but not yet confirmed as canonical JSON schemas plus validated fixtures. +- Status vocabulary is split: launch docs require `verified` and `failed`, while PR #61 appears to use `valid` and `invalid` internally. Either standardize the external V0 vocabulary or document an adapter mapping. +- GitHub checks currently show repository hygiene only. They do not prove contract tests, crypto vector validation, indexer/verifier tests, or dashboard tests. +- The launch-core source-of-truth docs are in PR #59 and are not merged yet. + +Non-critical gaps: + +- PR #58 local devnet work has not yet been tied into the Rootflow/Flow Memory acceptance path. +- Hardware work is not blocking launch-core acceptance unless it is used as fixture data. + +## Required Verification Commands + +Contracts PR #57 should provide output for: + +```powershell +cd E:\FlowMemory\flowmemory-contracts +forge test +git diff --check +``` + +Crypto PR #60 should provide output for the package's declared validation command, likely: + +```powershell +cd E:\FlowMemory\flowmemory-crypto +npm test +git diff --check +``` + +Indexer/verifier PR #61 should provide output for: + +```powershell +cd E:\FlowMemory\flowmemory-indexer +npm test +git diff --check +``` + +Dashboard PR #62 should provide output for: + +```powershell +cd E:\FlowMemory\flowmemory-dashboard +npm test +npm run build +git diff --check +``` + +If any command differs from the package scripts, the PR summary must name the actual command. + +## Merge Readiness Recommendation + +Current recommendation: not ready to call the active goal complete. + +Suggested merge order: + +1. PR #59, after review, so the launch-core docs and issue map become source of truth. +2. PR #60, if canonical schemas and fixtures are validated. +3. PR #57, if contract tests pass and contract changes stay inside V0 boundaries. +4. PR #61, after status vocabulary is reconciled and verifier/report fixtures validate. +5. PR #62, after dashboard fixtures align with the indexer/verifier output shape. +6. Issue #67 audit update after each merge. + +## Follow-Up Actions + +- Ask PR #61 to either expose `verified`/`failed` externally or document the exact external adapter from `valid`/`invalid`. +- Ask PR #60 to explicitly name canonical schemas for MemorySignal, MemoryReceipt, RootflowTransition, RootfieldBundle, and AgentMemoryView. +- Ask PR #62 to show which views render each acceptance object. +- Ask PR #57 to identify exactly which contract tests prove Rootfield namespaces, root commitments, parent linkage, and FlowPulse linkage. +- Keep this audit open until every row in `docs/V0_LAUNCH_ACCEPTANCE.md` has concrete evidence. From 3a3eb27d8c89db06f56f7467920f6e38e9a1ba52 Mon Sep 17 00:00:00 2001 From: FlowmemoryAI <283694809+FlowmemoryAI@users.noreply.github.com> Date: Wed, 13 May 2026 09:57:53 -0500 Subject: [PATCH 4/5] Add launch-core agent goals --- README.md | 1 + docs/CURRENT_STATE.md | 1 + docs/DAILY_HQ_RUNBOOK.md | 2 + docs/LAUNCH_CORE_AGENT_GOALS.md | 238 ++++++++++++++++++++++++++++++++ 4 files changed, 242 insertions(+) create mode 100644 docs/LAUNCH_CORE_AGENT_GOALS.md diff --git a/README.md b/README.md index 8a301cb4..dadde25c 100644 --- a/README.md +++ b/README.md @@ -51,6 +51,7 @@ FlowMemory is managed as a multi-agent program. The management layer is part of - `docs/ISSUE_BACKLOG.md`: maps issues into milestones, dependencies, and agent worktrees - `docs/AGENT_PROMPTS.md`: copy-ready prompts for each worktree +- `docs/LAUNCH_CORE_AGENT_GOALS.md`: copy-ready Rootflow V0 and Flow Memory V0 launch-core goals - `docs/PR_PROCESS.md`: branch, draft PR, review, merge, conflict, and issue-closing rules - `docs/DAILY_HQ_RUNBOOK.md`: morning review, triage, agent launch, PR monitoring, merge order, and handoff - `infra/scripts/status-report.ps1`: read-only local worktree, PR, and issue status report diff --git a/docs/CURRENT_STATE.md b/docs/CURRENT_STATE.md index a87360f7..a47cf0ae 100644 --- a/docs/CURRENT_STATE.md +++ b/docs/CURRENT_STATE.md @@ -40,6 +40,7 @@ Launch-core specifications: - `docs/V0_LAUNCH_ACCEPTANCE.md` maps the Rootflow and Flow Memory objective to concrete artifacts and evidence. - `docs/DECISIONS/rootflow-v0.md` records the V0 decision and non-goal boundaries. - `docs/reviews/ROOTFLOW_FLOW_MEMORY_V0_ACCEPTANCE_AUDIT.md` tracks evidence and missing work for the active launch-core goal. +- `docs/LAUNCH_CORE_AGENT_GOALS.md` provides copy-ready goals for the contracts, crypto, indexer/verifier, dashboard, and review worktrees. ## Conceptual Or Not Implemented Yet diff --git a/docs/DAILY_HQ_RUNBOOK.md b/docs/DAILY_HQ_RUNBOOK.md index 0619f2ce..08fae803 100644 --- a/docs/DAILY_HQ_RUNBOOK.md +++ b/docs/DAILY_HQ_RUNBOOK.md @@ -58,6 +58,8 @@ codex Give the agent the prompt from `docs/AGENT_PROMPTS.md` plus the assigned issue number. +For Rootflow V0 and Flow Memory V0 launch-core work, use `docs/LAUNCH_CORE_AGENT_GOALS.md`. + Do not start two agents on the same folder family unless the changed files are clearly disjoint. ## Monitoring PRs diff --git a/docs/LAUNCH_CORE_AGENT_GOALS.md b/docs/LAUNCH_CORE_AGENT_GOALS.md new file mode 100644 index 00000000..dc7788ac --- /dev/null +++ b/docs/LAUNCH_CORE_AGENT_GOALS.md @@ -0,0 +1,238 @@ +# Launch-Core Agent Goals + +Status: copy-ready coordination prompts for Rootflow V0 and Flow Memory V0. + +Use these prompts for the active launch-core workstreams. They are intentionally larger than a small issue prompt. Each agent must keep working until it produces concrete evidence for `docs/V0_LAUNCH_ACCEPTANCE.md`. + +Before starting any builder, read: + +- `AGENTS.md` +- `docs/START_HERE.md` +- `docs/CURRENT_STATE.md` +- `docs/ROOTFLOW_V0.md` +- `docs/FLOW_MEMORY_V0.md` +- `docs/V0_LAUNCH_ACCEPTANCE.md` +- `docs/reviews/ROOTFLOW_FLOW_MEMORY_V0_ACCEPTANCE_AUDIT.md` + +## Shared Goal Prefix + +```text +/goal You are contributing to the Rootflow V0 and Flow Memory V0 launch core. + +This is not complete when a small PR is opened. Continue until your assigned subsystem produces concrete evidence for docs/V0_LAUNCH_ACCEPTANCE.md and resolves the relevant gaps in docs/reviews/ROOTFLOW_FLOW_MEMORY_V0_ACCEPTANCE_AUDIT.md. + +GitHub is the source of truth. Read the repo docs first. Work only in your assigned worktree and assigned folders. Add commits to the existing PR branch when one exists. + +Do not claim production L1, production mainnet readiness, full trustless verification, free storage, or AI running on-chain. + +Before finishing, provide: +- files changed; +- exact commands run; +- exact acceptance rows satisfied; +- acceptance rows still incomplete; +- risks and follow-up issues. +``` + +## Contracts Agent + +Worktree: + +```powershell +cd E:\FlowMemory\flowmemory-contracts +gh pr checkout 57 +``` + +Assigned issue: #63. + +Prompt: + +```text +Use the shared launch-core goal prefix. + +Build the contracts-side Rootflow V0 support and coverage. + +Primary scope: +- contracts/ +- tests/ +- foundry.toml +- contract decision records only when needed + +Required outcomes: +- Rootfield namespaces are hardened and tested. +- Root commitments are hardened and tested. +- Parent pulse/root linkage needed by Rootflow V0 is emitted or preserved. +- FlowPulse linkage is explicit and test-covered. +- Contract state stays compact. +- Contracts do not pretend to know txHash or logIndex. +- No production hook deployment, tokenomics, dynamic fees, governance, or production deployment config. + +Required evidence: +- forge test output. +- git diff --check output. +- PR summary mapping work to docs/V0_LAUNCH_ACCEPTANCE.md rows. +``` + +## Crypto Agent + +Worktree: + +```powershell +cd E:\FlowMemory\flowmemory-crypto +``` + +Assigned issue: #64. + +Prompt: + +```text +Use the shared launch-core goal prefix. + +Build the canonical crypto/schema/fixture layer for Rootflow V0 and Flow Memory V0. + +Primary scope: +- crypto/ +- packages/crypto/ if present +- fixtures/crypto/ if present or created +- crypto-related docs and decisions + +Required outcomes: +- Canonical ids, serialization, hash inputs, and JSON schemas for: + - MemorySignal + - MemoryReceipt + - RootflowTransition + - RootfieldBundle + - AgentMemoryView + - verifier report +- Deterministic fixture vectors. +- Positive and negative validation cases. +- Clear boundary between V0 local/testnet readiness and future proof-carrying receipts. + +Required evidence: +- package validation/test command output. +- fixture paths. +- schema paths. +- PR summary mapping work to docs/V0_LAUNCH_ACCEPTANCE.md rows. +``` + +## Indexer/Verifier Agent + +Worktree: + +```powershell +cd E:\FlowMemory\flowmemory-indexer +gh pr checkout 61 +``` + +Assigned issue: #65. + +Prompt: + +```text +Use the shared launch-core goal prefix. + +Build the Rootflow V0 fixture engine and verifier report pipeline. + +Primary scope: +- services/indexer/ +- services/verifier/ +- services/shared/ +- fixtures/ +- indexer/verifier docs + +Required outcomes: +- Parse FlowPulse fixtures. +- Derive observation identity from receipt/log data. +- Produce MemorySignal fixtures. +- Link MemoryReceipt fixtures. +- Produce RootflowTransition fixtures. +- Produce verifier reports. +- Export dashboard-readable RootfieldBundle and AgentMemoryView state. +- Support observed, pending, verified, failed, reorged, and unsupported external states. +- If internal statuses use valid/invalid, document and implement the adapter to external verified/failed naming. + +Required evidence: +- npm test or equivalent output. +- fixture generation command output. +- output fixture paths. +- PR summary mapping work to docs/V0_LAUNCH_ACCEPTANCE.md rows. +``` + +## Dashboard Agent + +Worktree: + +```powershell +cd E:\FlowMemory\flowmemory-dashboard +gh pr checkout 62 +``` + +Assigned issue: #66. + +Prompt: + +```text +Use the shared launch-core goal prefix. + +Build the fixture-backed dashboard display path for Rootflow V0 and Flow Memory V0. + +Primary scope: +- apps/dashboard/ +- dashboard docs +- dashboard fixture adapters + +Required outcomes: +- Render Rootfield namespaces. +- Render Rootflow transition timeline. +- Render MemorySignal feed. +- Render MemoryReceipt detail. +- Render verifier report status. +- Render AgentMemoryView or equivalent agent-readable state. +- Support observed, pending, verified, failed, reorged, unsupported, unresolved, and invalid where adapters require them. +- Use deterministic fixtures first. +- No hosted production API or production deployment config. + +Required evidence: +- npm test output. +- npm run build output. +- local preview or screenshot evidence when possible. +- PR summary mapping views to docs/V0_LAUNCH_ACCEPTANCE.md rows. +``` + +## Review Agent + +Worktree: + +```powershell +cd E:\FlowMemory\flowmemory-review +``` + +Assigned issue: #67. + +Prompt: + +```text +Use the shared launch-core goal prefix. + +Audit Rootflow V0 and Flow Memory V0 acceptance across PRs. + +Primary scope: +- docs/ +- .github/ +- infra/scripts/ +- review notes + +Required outcomes: +- Update docs/reviews/ROOTFLOW_FLOW_MEMORY_V0_ACCEPTANCE_AUDIT.md after each launch-core PR changes. +- Map every acceptance row to concrete files, commands, tests, fixtures, or dashboard evidence. +- Identify missing evidence. +- Identify unsafe claims. +- Identify cross-PR conflicts. +- Recommend merge order. +- Do not implement subsystem product work. + +Required evidence: +- updated review matrix. +- merge readiness status. +- named blockers. +- comments on PRs when acceptance evidence is missing. +``` From a0e788114e8ef2a529e296a5d3b530306870b328 Mon Sep 17 00:00:00 2001 From: FlowmemoryAI <283694809+FlowmemoryAI@users.noreply.github.com> Date: Wed, 13 May 2026 11:17:27 -0500 Subject: [PATCH 5/5] Document open PR merge readiness --- README.md | 1 + docs/CURRENT_STATE.md | 3 + docs/reviews/OPEN_PR_MERGE_READINESS.md | 81 +++++++++++++++++++ ...OOTFLOW_FLOW_MEMORY_V0_ACCEPTANCE_AUDIT.md | 20 ++++- 4 files changed, 102 insertions(+), 3 deletions(-) create mode 100644 docs/reviews/OPEN_PR_MERGE_READINESS.md diff --git a/README.md b/README.md index dadde25c..d034871d 100644 --- a/README.md +++ b/README.md @@ -52,6 +52,7 @@ FlowMemory is managed as a multi-agent program. The management layer is part of - `docs/ISSUE_BACKLOG.md`: maps issues into milestones, dependencies, and agent worktrees - `docs/AGENT_PROMPTS.md`: copy-ready prompts for each worktree - `docs/LAUNCH_CORE_AGENT_GOALS.md`: copy-ready Rootflow V0 and Flow Memory V0 launch-core goals +- `docs/reviews/OPEN_PR_MERGE_READINESS.md`: open PR merge order, local test evidence, and remaining build gaps - `docs/PR_PROCESS.md`: branch, draft PR, review, merge, conflict, and issue-closing rules - `docs/DAILY_HQ_RUNBOOK.md`: morning review, triage, agent launch, PR monitoring, merge order, and handoff - `infra/scripts/status-report.ps1`: read-only local worktree, PR, and issue status report diff --git a/docs/CURRENT_STATE.md b/docs/CURRENT_STATE.md index a47cf0ae..a82d6e18 100644 --- a/docs/CURRENT_STATE.md +++ b/docs/CURRENT_STATE.md @@ -40,6 +40,7 @@ Launch-core specifications: - `docs/V0_LAUNCH_ACCEPTANCE.md` maps the Rootflow and Flow Memory objective to concrete artifacts and evidence. - `docs/DECISIONS/rootflow-v0.md` records the V0 decision and non-goal boundaries. - `docs/reviews/ROOTFLOW_FLOW_MEMORY_V0_ACCEPTANCE_AUDIT.md` tracks evidence and missing work for the active launch-core goal. +- `docs/reviews/OPEN_PR_MERGE_READINESS.md` summarizes open PR test evidence, merge order, and remaining build gaps. - `docs/LAUNCH_CORE_AGENT_GOALS.md` provides copy-ready goals for the contracts, crypto, indexer/verifier, dashboard, and review worktrees. ## Conceptual Or Not Implemented Yet @@ -53,6 +54,8 @@ Launch-core specifications: - Canonical JSON schema package for Rootflow and Flow Memory objects. - End-to-end fixture-backed Rootflow acceptance run. - Completed launch-core acceptance audit. +- Area-specific CI jobs for contracts, crypto, services, dashboard, devnet, and hardware checks. +- Single generated end-to-end Rootflow/Flow Memory acceptance command. - Indexer or verifier service runtime. - Persistence layer, live RPC reader, production APIs, or hosted services. - Dashboard, explorer, or hardware console implementation. diff --git a/docs/reviews/OPEN_PR_MERGE_READINESS.md b/docs/reviews/OPEN_PR_MERGE_READINESS.md new file mode 100644 index 00000000..c121df4e --- /dev/null +++ b/docs/reviews/OPEN_PR_MERGE_READINESS.md @@ -0,0 +1,81 @@ +# Open PR Merge Readiness + +Date: 2026-05-13 + +Status: active review summary. + +This file summarizes the open PRs that contain most of the currently built FlowMemory work. It distinguishes what is already merged, what is built in PR branches, and what still needs to be built after merge. + +## Already Merged Into Main + +| PR | Status | What it contains | +| --- | --- | --- | +| #1 bootstrap repository scaffolding | Merged | Repo structure, initial docs, workflow scaffolding. | +| #2 contracts foundation | Merged | Initial `FlowPulse`, `RootfieldRegistry`, and Foundry test foundation. | + +## Open PRs Reviewed + +| PR | Area | Local checks verified | Merge readiness | +| --- | --- | --- | --- | +| #59 HQ program manager OS | Docs/HQ | `git diff --check`; non-ASCII scan; GitHub issue/PR verification | Merge first. Establishes Rootflow/Flow Memory source-of-truth docs, audit, goals, backlog, and runbook. | +| #57 contracts V0 foundation | Contracts | `forge test` -> 33 passing; `git diff --check origin/main...HEAD` | Ready after #59 if no conflicts. Provides registries, Rootfield lifecycle, hook boundary, receipts/reports/work skeletons, and tests. | +| #60 crypto V0 foundation | Crypto | `npm test` -> 13 passing; `npm run validate:vectors` -> 21 vectors; Python vector recompute passed; diff check passed | Ready after #59 if docs do not conflict. Provides canonical crypto helpers, ids, receipts, report digests, fixtures, attestations, and docs. | +| #61 indexer/verifier fixture package | Services | `npm test` -> 24 passing; `npm run e2e` -> 7 observations and 7 reports; diff check passed after cleanup commit `125f84f` | Ready after #59/#60, with one integration note: external status mapping must remain explicit. | +| #62 dashboard V0 | Dashboard | `npm test` -> 4 passing; `npm run build` passed; diff check passed after cleanup commit `4577968` | Ready after #61 if fixture shape remains compatible. | +| #58 local devnet prototype | Chain/devnet | `cargo test --manifest-path crates\flowmemory-devnet\Cargo.toml` -> 7 passing; diff check passed | Ready after source docs, but not required for first Rootflow/Flow Memory launch core. | +| #56 FlowRouter hardware POC | Hardware | simulator fixture validation passed; diff check passed | Ready as bounded hardware POC. Not blocking Rootflow/Flow Memory core. | + +## Recommended Merge Order + +1. #59 HQ program manager OS. +2. #60 crypto V0 foundation. +3. #57 contracts V0 foundation. +4. #61 indexer/verifier fixture package. +5. #62 dashboard V0. +6. #58 local devnet prototype. +7. #56 FlowRouter hardware POC. + +Reasoning: + +- #59 should merge first because it updates source-of-truth docs, launch-core goals, and review audit. +- #60 should merge before #61 because indexer/verifier depends on crypto schema and fixture boundaries. +- #57 can merge before or after #60, but it should land before services are treated as contract-adjacent truth. +- #61 should merge before #62 because dashboard should follow service fixture shapes. +- #58 and #56 are useful but not blockers for Rootflow/Flow Memory launch core. + +## What Still Needs To Be Built + +Launch-core missing work: + +- A single end-to-end command that runs FlowPulse fixture -> indexer observation -> receipt/report -> Rootflow transition -> dashboard state. +- Concrete `RootflowTransition` output artifacts, not only docs and implicit parent-pulse links. +- Canonical Flow Memory JSON schemas for: + - `MemorySignal` + - `MemoryReceipt` + - `RootfieldBundle` + - `AgentMemoryView` +- A generated dashboard fixture that is produced from indexer/verifier output rather than hand-maintained dashboard fixture data. +- CI jobs that run area-specific checks: + - `forge test` + - crypto `npm test` and vector validation + - services `npm test` and `npm run e2e` + - dashboard `npm test` and `npm run build` + - devnet `cargo test` + - hardware simulator validation +- A clear external status adapter between verifier `valid`/`invalid` and Flow Memory/dashboard `verified`/`failed` or a decision to standardize the names. +- Updated `docs/CURRENT_STATE.md` after each PR merge. + +Not launch blockers: + +- Production L1. +- Tokenomics. +- Production Uniswap v4 hook deployment. +- Full trustless verifier network. +- Hardware manufacturing. +- Production decentralized internet claims. + +## Current Bottom Line + +Most of the V0 foundation exists in GitHub PR branches. It is not all merged into `main` yet. + +The project is ready for a careful merge sequence, followed by one integration pass that creates the end-to-end Rootflow/Flow Memory acceptance command and generated dashboard fixture. diff --git a/docs/reviews/ROOTFLOW_FLOW_MEMORY_V0_ACCEPTANCE_AUDIT.md b/docs/reviews/ROOTFLOW_FLOW_MEMORY_V0_ACCEPTANCE_AUDIT.md index 390db585..c709bf22 100644 --- a/docs/reviews/ROOTFLOW_FLOW_MEMORY_V0_ACCEPTANCE_AUDIT.md +++ b/docs/reviews/ROOTFLOW_FLOW_MEMORY_V0_ACCEPTANCE_AUDIT.md @@ -67,6 +67,20 @@ GitHub checks observed: - PRs #57, #60, #61, and #62 currently show `Repository hygiene` passing. - This is not enough to prove launch acceptance. Area-specific tests and fixture commands still need explicit evidence. +## Area-Specific Checks Verified Locally + +These checks were run from the matching PR worktrees on 2026-05-13. + +| PR | Worktree | Commands verified | Result | +| --- | --- | --- | --- | +| #57 contracts | `E:\FlowMemory\flowmemory-contracts` | `forge test`; `git diff --check origin/main...HEAD` | 33 Foundry tests passed; diff check passed. | +| #58 chain/devnet | `E:\FlowMemory\flowmemory-chain` | `cargo test --manifest-path crates\flowmemory-devnet\Cargo.toml`; `git diff --check origin/main...HEAD` | 7 Rust tests passed; diff check passed. | +| #56 hardware | `E:\FlowMemory\flowmemory-hardware` | `python hardware\simulator\flowrouter_sim.py --validate-file hardware\fixtures\flowrouter_sample_seed42.json`; `git diff --check origin/main...HEAD` | Fixture validation passed; diff check passed. | +| #60 crypto | `E:\FlowMemory\flowmemory-crypto\crypto` | `npm ci`; `npm test`; `npm run validate:vectors`; `python validate_test_vectors.py`; `git diff --check origin/main...HEAD` | 13 package tests passed; 21 vectors validated; Python FlowPulse vector recompute passed; diff check passed. | +| #61 indexer/verifier | `E:\FlowMemory\flowmemory-indexer` | `npm ci`; `npm test`; `npm run e2e`; `git diff --check origin/main...HEAD` | 24 package tests passed; e2e produced 7 observations and 7 verifier reports; diff check passed after cleanup commit `125f84f`. | +| #62 dashboard | `E:\FlowMemory\flowmemory-dashboard\apps\dashboard` | `npm ci`; `npm test`; `npm run build`; `git diff --check origin/main...HEAD` | 4 dashboard tests passed; production build passed; diff check passed after cleanup commit `4577968`. | +| #59 HQ | `E:\FlowMemory\flowmemory-main` | `git diff --check`; non-ASCII scan; GitHub issue/PR verification | Passed; docs and issue control plane pushed. | + ## Prompt-To-Artifact Checklist | Requirement | Expected artifacts | Evidence found | Status | @@ -98,8 +112,8 @@ Critical gaps: - No single end-to-end command has been verified that runs FlowPulse fixture -> indexer observation -> receipt/report -> Rootflow transition -> dashboard state. - `RootflowTransition` is specified but not yet confirmed as a concrete output artifact in the subsystem PRs. - `MemorySignal`, `MemoryReceipt`, `RootfieldBundle`, and `AgentMemoryView` are specified but not yet confirmed as canonical JSON schemas plus validated fixtures. -- Status vocabulary is split: launch docs require `verified` and `failed`, while PR #61 appears to use `valid` and `invalid` internally. Either standardize the external V0 vocabulary or document an adapter mapping. -- GitHub checks currently show repository hygiene only. They do not prove contract tests, crypto vector validation, indexer/verifier tests, or dashboard tests. +- Status vocabulary is split: launch docs and crypto use `verified` and `failed`, while PR #61 verifier reports use `valid` and `invalid` internally. PR #61 includes mapping notes in `services/verifier/VERIFIER_STATUS_VOCABULARY.md`, but the end-to-end dashboard adapter still needs to be treated as an explicit integration boundary. +- GitHub checks currently show repository hygiene only. Local area-specific checks now exist in this audit, but CI does not yet enforce them. - The launch-core source-of-truth docs are in PR #59 and are not merged yet. Non-critical gaps: @@ -146,7 +160,7 @@ If any command differs from the package scripts, the PR summary must name the ac ## Merge Readiness Recommendation -Current recommendation: not ready to call the active goal complete. +Current recommendation: not ready to call the active goal complete, but the open PRs are now locally test-verified enough to begin merge sequencing. Suggested merge order: