Docs: add contributor navigation and architecture map #11
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
…sts) This commit packages the m010 Reputation Signal as a Phase 1, advisory-only mechanism that is fully reviewable and runnable offline. It adds: - a tightened spec, glossary, invariants, and mechanism-local changelog - canonical JSON schemas with explicit versioning - a reference implementation for KPI and score computation - golden test vectors and deterministic replay fixtures - a seed-based fixture generator - a single verify command for WG review (no network calls) The intent is to reduce restart and review cost for future Regen AI work by providing concrete, testable artifacts rather than forum-level discussion. No enforcement, gating, or on-chain actions are implied.
Adds a short dependency map and contributor navigation to clarify repo structure, cross-repo references, and PR sizing expectations. Docs-only change.
Adds a visitable Mermaid diagram and short explainer showing how agentic-tokenomics relates to koi-research, heartbeat, and claude tooling. Docs-only change.
Contributor
Summary of ChangesHello @brawlaphant, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed! This pull request significantly expands the project's documentation, providing a foundational understanding of the Regen Network Agentic Tokenomics & Governance System. It outlines the system's architecture, governance models, and detailed specifications for various tokenomic mechanisms and agentic workflows. The added documentation aims to enhance clarity for contributors and reviewers, facilitating more efficient development and collaboration. Highlights
Changelog
Activity
Using Gemini Code AssistThe full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips. Invoking Gemini You can request assistance from Gemini at any point by creating a comment using either
Customization To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a Limitations & Feedback Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here. You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension. Footnotes
|
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Code Review
This pull request adds a significant amount of documentation for the agentic tokenomics system. However, there seems to be an issue with the file structure. The PR description mentions adding a few specific documentation files, but the changes include a large number of files under directories named agentic-tokenomics-main 2, agentic-tokenomics-main 3, and agentic-tokenomics-main 4. These directories appear to contain duplicated or versioned content, which makes the PR difficult to review and could lead to confusion. It would be great if you could clarify the intended file structure and remove any unintended or duplicated files.
I have reviewed the content of the added files (focusing on the agentic-tokenomics-main 2 and agentic-tokenomics-main 4 directories as representative samples) and have left some comments on areas that could be improved for clarity, consistency, and correctness. Please apply these suggestions to all relevant files if the duplication is intentional.
Comment on lines
+519
to
+520
| let lock_expires = env.block.time.plus_days(att_type.lock_period_days); | ||
| let challenge_closes = env.block.time.plus_days(att_type.challenge_window_days); |
Contributor
There was a problem hiding this comment.
The cosmwasm_std::Timestamp type does not have a plus_days method. You should use plus_seconds and calculate the duration in seconds to avoid a compilation error.
Suggested change
| let lock_expires = env.block.time.plus_days(att_type.lock_period_days); | |
| let challenge_closes = env.block.time.plus_days(att_type.challenge_window_days); | |
| let lock_expires = env.block.time.plus_seconds(att_type.lock_period_days * 86400); | |
| let challenge_closes = env.block.time.plus_seconds(att_type.challenge_window_days * 86400); |
Comment on lines
+56
to
+58
| - if completeness >= 0.9 AND risk < 0.3: recommend_approve (confidence: 0.95) | ||
| - if completeness >= 0.7 AND risk < 0.5: recommend_conditional (confidence: 0.75) | ||
| - else: recommend_reject (confidence: 0.85) |
Contributor
There was a problem hiding this comment.
The decision logic here is ambiguous. It's not clear if these are sequential if statements or an if-else if-else chain. For example, a case with completeness = 0.95 and risk = 0.4 would be rejected by the first rule, but could be conditionally approved by the second. Please clarify the evaluation order. Using an if/else if/else structure would make the logic unambiguous.
For example:
- if completeness >= 0.9 AND risk < 0.3: recommend_approve (confidence: 0.95)
- else if completeness >= 0.7 AND risk < 0.5: recommend_conditional (confidence: 0.75)
- else: recommend_reject (confidence: 0.85)This would ensure that cases like completeness = 0.95, risk = 0.4 are handled as recommend_conditional instead of falling through to recommend_reject.
Comment on lines
+75
to
+79
| ## Mechanisms | ||
|
|
||
| - [m010 Reputation Signal (v0 advisory)](mechanisms/m010-reputation-signal/SPEC.md) | ||
|
|
||
|
|
Contributor
There was a problem hiding this comment.
This 'Mechanisms' section appears to be redundant, as the same information is provided under the 'Key Specifications' -> 'Mechanisms (canonical specs)' section below (line 87). Removing this duplicate section would improve the document's clarity.
Comment on lines
+118
to
+150
| ``` | ||
| regen-agentic-tokenomics/ | ||
| ├── README.md | ||
| ├── mechanisms | ||
| │ └── m010-reputation-signal | ||
| │ ├── README.md | ||
| │ └── SPEC.md | ||
| ├── phase-1/ | ||
| │ ├── README.md | ||
| ├── mechanisms | ||
| │ └── m010-reputation-signal | ||
| │ ├── README.md | ||
| │ └── SPEC.md | ||
| │ ├── 1.1-stakeholder-value-flow.md | ||
| │ ├── 1.2-tokenomic-mechanisms.md | ||
| │ ├── 1.3-agentic-services.md | ||
| │ ├── 1.4-governance-architecture.md | ||
| │ └── 1.5-system-architecture.md | ||
| ├── phase-2/ | ||
| │ ├── README.md | ||
| ├── mechanisms | ||
| │ └── m010-reputation-signal | ||
| │ ├── README.md | ||
| │ └── SPEC.md | ||
| │ ├── 2.1-token-utility-mechanisms.md | ||
| │ ├── 2.2-agentic-workflows.md | ||
| │ ├── 2.3-governance-processes.md | ||
| │ ├── 2.4-agent-orchestration.md | ||
| │ └── 2.5-data-schema-integration.md | ||
| ├── phase-3/ | ||
| ├── phase-4/ | ||
| └── phase-5/ | ||
| ``` |
Contributor
There was a problem hiding this comment.
The repository structure diagram is malformed. It contains duplicated mechanisms entries and incorrect indentation for phase-specific files, which makes the structure difficult to understand. A corrected structure would improve clarity. For example:
regen-agentic-tokenomics/
├── README.md
├── mechanisms/
│ └── m010-reputation-signal/
│ ├── README.md
│ └── SPEC.md
├── phase-1/
│ ├── README.md
│ ├── 1.1-stakeholder-value-flow.md
│ ├── 1.2-tokenomic-mechanisms.md
│ ├── 1.3-agentic-services.md
│ ├── 1.4-governance-architecture.md
│ └── 1.5-system-architecture.md
├── phase-2/
│ ├── README.md
│ ├── 2.1-token-utility-mechanisms.md
│ ├── 2.2-agentic-workflows.md
│ ├── 2.3-governance-processes.md
│ ├── 2.4-agent-orchestration.md
│ └── 2.5-data-schema-integration.md
├── phase-3/
├── phase-4/
└── phase-5/
| { | ||
| "id": "M003", | ||
| "name": "Transaction Fees", | ||
| "module": "x/auth", |
Contributor
There was a problem hiding this comment.
There's an inconsistency for mechanism M003. The table on line 31 lists the module as x/auth, x/bank, but the JSON here only lists x/auth. For consistency, this should be updated to include x/bank as well.
Suggested change
| "module": "x/auth", | |
| "module": "x/auth, x/bank", |
| @@ -0,0 +1,29 @@ | |||
| import { median } from "./m010_kpi.js"; | |||
Contributor
There was a problem hiding this comment.
The median function is imported but not used in this file. It should be removed to keep the code clean.
Author
|
Clarification on scope: Although this PR branch contains multiple legacy upload artifact folders, the only intended changes in this PR are:
The duplicate Thank you. |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This PR adds two small, docs-only coordination artifacts to help humans and agents
review and contribute to agentic-tokenomics more efficiently.
What’s included:
Notes: