From d132351efd4151aa37f94b4020eaa543178390b2 Mon Sep 17 00:00:00 2001 From: "J. Kirby Ross" Date: Sat, 25 Oct 2025 08:42:56 -0700 Subject: [PATCH 1/3] docs: retire Neo4j journaling workflow --- AGENTS.md | 48 ++++---------------------- CONTRIBUTING.md | 9 +++-- docs/codex-implementation-checklist.md | 2 +- docs/execution-plan.md | 14 ++++---- docs/phase1-plan.md | 2 +- docs/rmg-demo-roadmap.md | 2 +- scripts/scaffold-community.sh | 6 ++-- 7 files changed, 24 insertions(+), 59 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 6b38354..55c1391 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -4,48 +4,15 @@ Welcome to the **Echo** project. This file captures expectations for any LLM age ## Core Principles - **Honor the Vision**: Echo is a deterministic, multiverse-aware ECS. Consult `docs/architecture-outline.md` before touching runtime code. -- **Document Ruthlessly**: Every meaningful design choice should land in `docs/` (specs, diagrams, memorials) or a Neo4j journal entry tagged `Echo`. +- **Document Ruthlessly**: Every meaningful design choice should land in `docs/` (specs, diagrams, memorials) or other durable repo artifacts (e.g. `docs/decision-log.md`). - **Docstrings Aren't Optional**: Public APIs across crates (`rmg-core`, `rmg-ffi`, `rmg-wasm`, etc.) must carry rustdoc comments that explain intent, invariants, and usage. Treat missing docs as a failing test. - **Determinism First**: Avoid introducing sources of nondeterminism without a mitigation plan. - **Temporal Mindset**: Think in timelines—branching, merging, entropy budgets. Feature work should map to Chronos/Kairos/Aion axes where appropriate. -## Shared Memory (Neo4j) -We use the agent-collab Neo4j instance as a temporal journal. - -Scripts live in `/scripts/neo4j-msg.js`. - -### Setup -```bash -# Register yourself once. Choose a display name that identifies the agent. -node path/to/agent-collab/scripts/neo4j-msg.js agent-init "Echo Codex" -``` - -### Writing a Journal Entry -```bash -node path/to/agent-collab/scripts/neo4j-msg.js msg-send \ - --from "Echo Codex" \ - --to "Echo Archive" \ - --text "[Echo] short summary of what you changed or decided." \ - --thread "echo-devlog" \ - --topic "Echo" \ - --project "Echo Engine" \ - --kind note -``` - -Guidelines: -- Prefix the message with `[Echo]` so the tag survives future searches. -- Summarise intent, work done, and next steps for future agents. -- Use the thread `echo-devlog` unless a more specific thread already exists. -- **Cadence:** Log when you start work (intent), when you hit a major milestone or decision, when you reference external sources (paths, specs), and when you finish a session (outcome + next steps). Treat Neo4j as the authoritative timeline. - -### Reading Past Entries -```bash -node path/to/agent-collab/scripts/neo4j-msg.js messages \ - --thread "echo-devlog" \ - --limit 20 -``` - -Use `messages-search --text "Echo"` for ad-hoc queries. +## Timeline Logging +- Start each session by updating *Today’s Intent* in `docs/execution-plan.md`. +- Capture milestones, blockers, and decisions directly in this repo (e.g. `docs/decision-log.md`, relevant specs, or PR descriptions). +- When wrapping up, record outcomes and next steps in the Decision Log and ensure any impacted docs stay in sync. ## Repository Layout - `packages/echo-core`: Runtime core (ECS, scheduler, Codex’s Baby, timelines). @@ -56,7 +23,6 @@ Use `messages-search --text "Echo"` for ad-hoc queries. ## Working Agreement - Keep `main` pristine. Feature work belongs on branches named `echo/` or `timeline/`. - Tests and benchmarks are mandatory for runtime changes once the harness exists. -- Update the Neo4j log before you down tools, even if the work is incomplete. - Respect determinism: preferably no random seeds without going through the Echo PRNG. - Run `cargo clippy --all-targets -- -D missing_docs` and `cargo test` before every PR; CI will expect a zero-warning, fully documented surface. @@ -68,7 +34,7 @@ Use `messages-search --text "Echo"` for ad-hoc queries. In short: no one cares about a tidy commit graph, but everyone cares if you rewrite commits on origin. ## Contact Threads -- Neo4j Thread `echo-devlog`: Daily journal, decisions, blockers. -- Neo4j Thread `echo-spec`: High-level architectural proposals. +- Docs `decision-log.md`: Chronological design decisions. +- Docs `execution-plan.md`: Working map of tasks, intent, and progress. Safe travels in the multiverse. Logged timelines are happy timelines. 🌀 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index bc93c9e..7af4caa 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -21,12 +21,12 @@ Echo is a deterministic, renderer-agnostic engine. We prioritize: ## Getting Started 1. Clone the repo and run `cargo check` to ensure the Rust workspace builds. 2. Read `docs/architecture-outline.md` and `docs/execution-plan.md`. -3. Register yourself in Neo4j via `AGENTS.md` instructions and note your display handle. +3. Review `AGENTS.md` for collaboration norms before touching runtime code. ## Branching & Workflow - Keep `main` pristine. Create feature branches like `echo/` or `timeline/`. - Before starting work, ensure `git status` is clean. If not, resolve or coordinate with the human operator. -- Log intent in Neo4j (`[Echo]` tag) at the start of each session. +- Before each session, update the “Today’s Intent” section in `docs/execution-plan.md` so future collaborators can follow the timeline. ## Testing Expectations - Write tests before or alongside code changes. @@ -36,7 +36,7 @@ Echo is a deterministic, renderer-agnostic engine. We prioritize: ## Documentation & Telemetry - Update relevant docs in `docs/` whenever behavior or architecture changes. - Record major decisions or deviations in the execution plan or decision log tables. -- Use Neo4j to leave breadcrumbs for future Codex agents. +- Capture breadcrumbs for future Codex agents in `docs/decision-log.md` or related specs. ## Submitting Changes 1. Run `cargo fmt`, `cargo clippy`, and `cargo test`. @@ -54,8 +54,7 @@ Echo is a deterministic, renderer-agnostic engine. We prioritize: - Avoid non-deterministic APIs (no wall-clock, no uncontrolled randomness). Use Echo’s deterministic services. ## Communication -- Major updates logged in Neo4j threads (`echo-devlog`, `echo-spec`). -- Use GitHub discussions or issues for larger design proposals. +- Major updates should land in `docs/execution-plan.md` and `docs/decision-log.md`; rely on GitHub discussions or issues for longer-form proposals. - Respect the temporal theme—leave the codebase cleaner for the next timeline traveler. Thanks for helping forge Echo’s spine. 🌀 diff --git a/docs/codex-implementation-checklist.md b/docs/codex-implementation-checklist.md index 5640e12..abb304b 100644 --- a/docs/codex-implementation-checklist.md +++ b/docs/codex-implementation-checklist.md @@ -57,5 +57,5 @@ A step-by-step guide for turning the event bus spec into working code. ## 10. Follow-up - [ ] Add inspector panel to display metrics. -- [ ] Extend Neo4j devlog to capture major bus events (optional). +- [ ] Extend `docs/decision-log.md` with a bus-event template (optional). - [ ] Profile throughput with scheduler benchmarks. diff --git a/docs/execution-plan.md b/docs/execution-plan.md index a5f7555..f070691 100644 --- a/docs/execution-plan.md +++ b/docs/execution-plan.md @@ -6,14 +6,14 @@ This is Codex’s working map for building Echo. Update it relentlessly—each s ## Operating Rhythm - **Before Starting** - 1. Ensure `git status` is clean. If not, document in Neo4j and wait for human guidance. - 2. Read the latest entries tagged `[Echo]` in Neo4j (`scripts/neo4j-msg.js messages --thread "echo-devlog"`). + 1. Ensure `git status` is clean. If not, capture the state in `docs/decision-log.md` and wait for human guidance. + 2. Skim the latest updates in this document and `docs/decision-log.md` to synchronize with the active timeline. 3. Update the *Today’s Intent* section below. - **During Work** - - Log major decisions, blockers, or epiphanies via Neo4j (`msg-send` with `[Echo]` prefix). + - Log major decisions, blockers, or epiphanies in the Decision Log section below (and mirror details in `docs/decision-log.md` when appropriate). - Keep this document current: mark completed tasks, add new sub-items, refine specs. - **After Work** - 1. Summarize outcomes, next steps, and open questions in Neo4j. + 1. Summarize outcomes, next steps, and open questions in the Decision Log section or `docs/decision-log.md`. 2. Update the “Next Up” queue. 3. Push branches / PRs or leave explicit instructions for future Codex. @@ -77,7 +77,7 @@ This is Codex’s working map for building Echo. Update it relentlessly—each s ### Tooling & Docs - [ ] Build `docs/data-structures.md` with Mermaid diagrams (storage, branch tree with roaring bitmaps). - [ ] Extend `docs/diagrams.md` with scheduler flow & command queue animations. -- [ ] Prepare Neo4j query cheatsheet for faster journaling. +- [ ] Document lightweight journaling workflow in `docs/decision-log.md` (templates, cadence). - [ ] Design test fixture layout (`test/fixtures/…`) with sample component schemas. - [ ] Document roaring bitmap integration and merge strategies. - [ ] Update future inspector roadmap with conflict heatmaps and causality lens. @@ -93,7 +93,7 @@ This is Codex’s working map for building Echo. Update it relentlessly—each s | 2025-10-25 | Language direction pivot: Echo core to Rust | TypeScript validated specs; long-term determinism enforced via Rust + C ABI + Lua scripting | Update Phase 1 backlog: scaffold Rust workspace, port ECS/diff engine, FFI bindings | | 2025-10-26 | Adopt RMG + Confluence as core architecture | RMG v2 (typed DPOi engine) + Confluence replication baseline | Scaffold rmg-core/ffi/wasm/cli crates; implement rewrite executor spike; integrate Rust CI; migrate TS prototype to `/reference` | -(Keep this table updated; link to Neo4j message IDs when useful.) +(Keep this table updated; include file references or commit hashes when useful.) --- @@ -109,7 +109,7 @@ Populate with concrete tasks in priority order. When you start one, move it to --- ## Notes to Future Codex -- Use `Neo4j thread: echo-devlog` for daily runtime updates. +- Update this document (and `docs/decision-log.md`) for daily runtime updates. - Record test coverage gaps as they appear; they inform future backlog items. - Ensure roaring bitmap and hashing dependencies are deterministic across environments. - Inspector pins must be recorded to keep GC deterministic. diff --git a/docs/phase1-plan.md b/docs/phase1-plan.md index 06d7af9..9887cee 100644 --- a/docs/phase1-plan.md +++ b/docs/phase1-plan.md @@ -109,6 +109,6 @@ Optimization roadmap once baseline is working: ## Documentation Checklist - Update `docs/rmg-runtime-architecture.md` as rules/loop evolve. - Append decision log entries per phase. -- Record demo outcomes in Neo4j (`echo-devlog`). +- Record demo outcomes in `docs/decision-log.md` (tag entries with the relevant demo). Phase 1 completes when Demo 6 (Live Coding) runs atop the Rust RMG runtime with inspector tooling in place. diff --git a/docs/rmg-demo-roadmap.md b/docs/rmg-demo-roadmap.md index 0c57a94..07103e3 100644 --- a/docs/rmg-demo-roadmap.md +++ b/docs/rmg-demo-roadmap.md @@ -72,7 +72,7 @@ This document captures the interactive demos and performance milestones we want | 1F | Demo dashboards | Inspector frame overlays, JSON ingestion | -**Prerequisites:** BLAKE3 hashing utilities, deterministic PRNG module, snapshot serialiser, inspector graph viewer, Neo4j logging for demo outcomes, CI runners with wasm/criterion toolchains. +**Prerequisites:** BLAKE3 hashing utilities, deterministic PRNG module, snapshot serialiser, inspector graph viewer, documentation workflow for logging demo outcomes, CI runners with wasm/criterion toolchains. **Timeline:** diff --git a/scripts/scaffold-community.sh b/scripts/scaffold-community.sh index 7d9ba8d..7fad2fb 100755 --- a/scripts/scaffold-community.sh +++ b/scripts/scaffold-community.sh @@ -29,9 +29,9 @@ PACKAGE_MANAGER=$(gum input --prompt "Package manager command" --value "$DEFAULT ARCHITECTURE_DOC=$(gum input --prompt "Architecture doc path" --value "$DEFAULT_ARCH_DOC") EXECUTION_PLAN_DOC=$(gum input --prompt "Execution plan doc" --value "$DEFAULT_EXEC_PLAN") AGENT_GUIDE=$(gum input --prompt "Agent onboarding doc" --value "$DEFAULT_AGENT_GUIDE") -PROJECT_TAG=$(gum input --prompt "Project tag for Neo4j logs" --value "$DEFAULT_TAG") -DEVLOG_THREAD=$(gum input --prompt "Devlog thread name" --value "$DEFAULT_DEVLOG") -SPEC_THREAD=$(gum input --prompt "Spec thread name" --value "$DEFAULT_SPEC_THREAD") +PROJECT_TAG=$(gum input --prompt "Project tag for timeline notes" --value "$DEFAULT_TAG") +DEVLOG_THREAD=$(gum input --prompt "Devlog document or label" --value "$DEFAULT_DEVLOG") +SPEC_THREAD=$(gum input --prompt "Spec document or label" --value "$DEFAULT_SPEC_THREAD") YEAR=$(gum input --prompt "Copyright year" --value "$DEFAULT_YEAR") COPYRIGHT_HOLDER=$(gum input --prompt "Copyright holder" --value "$DEFAULT_COPYRIGHT") LEGACY_DIR=$(gum input --prompt "Legacy directory reference" --value "$DEFAULT_LEGACY_DIR") From 96eacaf85c7010b58479734d1daf2e74e4e88e34 Mon Sep 17 00:00:00 2001 From: "J. Kirby Ross" Date: Sat, 25 Oct 2025 17:36:34 -0700 Subject: [PATCH 2/3] docs: clarify decision logging workflow --- docs/decision-log.md | 2 ++ docs/execution-plan.md | 6 +++--- docs/phase1-plan.md | 2 +- docs/rmg-demo-roadmap.md | 2 +- 4 files changed, 7 insertions(+), 5 deletions(-) diff --git a/docs/decision-log.md b/docs/decision-log.md index f852bd2..8b93c4d 100644 --- a/docs/decision-log.md +++ b/docs/decision-log.md @@ -1,5 +1,7 @@ # Decision Log +*Demo outcomes should prefix the Decision column with `Demo — …` to keep entries searchable.* + | Date | Context | Decision | Rationale | Consequence | | ---- | ------- | -------- | --------- | ----------- | | 2025-10-23 | Repo reset | Adopt pnpm + TS skeleton | Monorepo scaffolding for Echo | Phase 0 tasks established | diff --git a/docs/execution-plan.md b/docs/execution-plan.md index f070691..e53ee7d 100644 --- a/docs/execution-plan.md +++ b/docs/execution-plan.md @@ -10,10 +10,10 @@ This is Codex’s working map for building Echo. Update it relentlessly—each s 2. Skim the latest updates in this document and `docs/decision-log.md` to synchronize with the active timeline. 3. Update the *Today’s Intent* section below. - **During Work** - - Log major decisions, blockers, or epiphanies in the Decision Log section below (and mirror details in `docs/decision-log.md` when appropriate). + - Record major decisions, blockers, or epiphanies in `docs/decision-log.md` (canonical log) and copy a concise summary into the Decision Log table below for quick reference. - Keep this document current: mark completed tasks, add new sub-items, refine specs. - **After Work** - 1. Summarize outcomes, next steps, and open questions in the Decision Log section or `docs/decision-log.md`. + 1. Summarize outcomes, next steps, and open questions in the Decision Log section below and ensure the full entry is captured in `docs/decision-log.md`. 2. Update the “Next Up” queue. 3. Push branches / PRs or leave explicit instructions for future Codex. @@ -77,7 +77,7 @@ This is Codex’s working map for building Echo. Update it relentlessly—each s ### Tooling & Docs - [ ] Build `docs/data-structures.md` with Mermaid diagrams (storage, branch tree with roaring bitmaps). - [ ] Extend `docs/diagrams.md` with scheduler flow & command queue animations. -- [ ] Document lightweight journaling workflow in `docs/decision-log.md` (templates, cadence). +- [ ] Document lightweight journaling workflow in `docs/decision-log.md` (include entry template + daily/weekly cadence guidance; owner: Documentation squad before Phase 1 kickoff). - [ ] Design test fixture layout (`test/fixtures/…`) with sample component schemas. - [ ] Document roaring bitmap integration and merge strategies. - [ ] Update future inspector roadmap with conflict heatmaps and causality lens. diff --git a/docs/phase1-plan.md b/docs/phase1-plan.md index 9887cee..cdc6423 100644 --- a/docs/phase1-plan.md +++ b/docs/phase1-plan.md @@ -109,6 +109,6 @@ Optimization roadmap once baseline is working: ## Documentation Checklist - Update `docs/rmg-runtime-architecture.md` as rules/loop evolve. - Append decision log entries per phase. -- Record demo outcomes in `docs/decision-log.md` (tag entries with the relevant demo). +- Record demo outcomes in `docs/decision-log.md`, prefixing the Decision column with `Demo —` (e.g., `Demo 2 — Timeline hash verified`). Phase 1 completes when Demo 6 (Live Coding) runs atop the Rust RMG runtime with inspector tooling in place. diff --git a/docs/rmg-demo-roadmap.md b/docs/rmg-demo-roadmap.md index 07103e3..d9211b7 100644 --- a/docs/rmg-demo-roadmap.md +++ b/docs/rmg-demo-roadmap.md @@ -72,7 +72,7 @@ This document captures the interactive demos and performance milestones we want | 1F | Demo dashboards | Inspector frame overlays, JSON ingestion | -**Prerequisites:** BLAKE3 hashing utilities, deterministic PRNG module, snapshot serialiser, inspector graph viewer, documentation workflow for logging demo outcomes, CI runners with wasm/criterion toolchains. +**Prerequisites:** BLAKE3 hashing utilities, deterministic PRNG module, snapshot serialiser, inspector graph viewer, documentation workflow (`docs/decision-log.md`) for logging demo outcomes, CI runners with wasm/criterion toolchains. **Timeline:** From c618f1f6b991ca7340f777b4d883c39960487b35 Mon Sep 17 00:00:00 2001 From: "J. Kirby Ross" Date: Sat, 25 Oct 2025 17:36:52 -0700 Subject: [PATCH 3/3] ci: enforce exec-plan and decision-log updates --- .github/workflows/ci.yml | 36 ++++++++++++++++++++++++++++++++++++ 1 file changed, 36 insertions(+) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 219a31d..88d7fb6 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -24,6 +24,8 @@ jobs: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 + with: + submodules: false - uses: dtolnay/rust-toolchain@stable - name: cargo clippy run: cargo clippy --all-targets -- -D warnings -D missing_docs @@ -33,6 +35,40 @@ jobs: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 + with: + submodules: false - uses: dtolnay/rust-toolchain@stable - name: cargo test run: cargo test + + docs: + name: Docs Guard + runs-on: ubuntu-latest + if: github.event_name == 'pull_request' + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 0 + - name: Ensure execution plan and decision log were updated + run: | + set -euo pipefail + base_ref="${{ github.event.pull_request.base.ref }}" + git fetch origin "$base_ref" --depth=1 + changed=$(git diff --name-only "origin/${base_ref}"..."${{ github.sha }}") + if [ -z "$changed" ]; then + exit 0 + fi + non_doc=$(echo "$changed" | grep -vE '(^docs/)|(\.md$)' || true) + if [ -z "$non_doc" ]; then + exit 0 + fi + echo "Non-doc files changed:" + echo "$non_doc" + echo "$changed" | grep -Fx 'docs/execution-plan.md' >/dev/null || { + echo 'docs/execution-plan.md must be updated when non-doc files change.'; + exit 1; + } + echo "$changed" | grep -Fx 'docs/decision-log.md' >/dev/null || { + echo 'docs/decision-log.md must be updated when non-doc files change.'; + exit 1; + }