IDKMesh

I don't know. You don't know. Together, the mesh can discover, build, verify, and learn.

IDKMesh is an open-source research and engineering project exploring how humans, AI agents, software tools, and heterogeneous compute can coordinate on uncertain goals and turn proposals into verified useful work.

The project is intentionally ambitious, but the repository is not claiming a finished planetary-scale system. Today it is a GitHub-native research laboratory with an executable coordination/evidence foundation and a reference-product target: the Git-native Verified Swarm Runner.

A concrete question this repository can already answer: how many independent votes is your review panel actually worth? Often far fewer than the number of reviewers on it. In E017 a 25-verifier panel — every verifier a program, every error an observed missed defect — measured an effective size of 1.00 of 25: under majority vote the panel was worth no more than a single member, while the widely used N/(1+(N-1)rho) correction predicted 1.66. idkmesh gate-audit runs that measurement on verdicts you have already collected, and reports the seeded known-bad candidates your panel let through.

Try the contract demo

With Git and Python 3.11 or 3.13, use a virtual environment. Linux/macOS example:

git clone https://github.com/MSKazemi/idkmesh && cd idkmesh
python -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements-phase0.txt
python scripts/demo.py

For Windows, use the environment instructions in CONTRIBUTING.md. No model account or API key is needed. Installation time depends on your environment.

The demo validates committed synthetic fixtures with the real validators and schemas in schemas/ and inputs in examples/. It performs three positive checks and four deliberate rejection checks:

Invalid fixture	Why it is rejected
A task with no security contract	a dispatchable contract must declare its security bounds
A worker result that accepts itself	worker completion is not acceptance
A verifier using the worker's identity	the worker cannot satisfy the independent-verifier contract itself
A verification with mismatched provenance	evidence must bind to the supplied artifacts

No live worker or external verifier is executed. A fixture passing validation is not proof of real-world independence, correct work, or approval to merge. Unexpected process or programming errors fail the demo instead of counting as successful rejection evidence.

Questions and "why is it done this way" belong in Discussions; the issue tracker is for defects and bounded pieces of work. For one concrete task or shared technical responsibility, see the contributor invitation.

The central question

Can a large open community of humans and AI agents discover goals, decompose work, execute bounded tasks, verify results independently, and maintain complex systems better than isolated developers or agents can?

IDKMesh treats that as an empirical question. More agents, more activity, more commits, or more votes are not automatically better.

Current status

Executable research foundation; reference runner still incomplete.

What is already present on main:

• versioned WorkUnit contracts, with work-unit-v0.2.schema.json as the current semantic task contract;
• ResultManifest, EvaluatorPlan, and VerificationResult contracts that separate worker claims, verifier evidence, and integration authority;
• cross-object provenance and integrity validation;
• a five-arm WorkUnit decomposition benchmark contract and strict synthetic-vs-observed evidence boundary;
• protocol-neutral worker-adapter code plus A2A/MCP bindings and SDK/conformance helpers under interop/;
• simulation and experiment code under sim/ and experiments/;
• zero-project-spend compute admission and routing experiments;
• IDKGraph repository modeling, observability, link-integrity, and warning/review machinery;
• GitHub-native ACE community-growth experiments and repository-evolution control tooling;
• a first installable product surface: pip install . provides the idkmesh CLI, whose gate-audit command packages the measured verifier-panel results (E015/E016/E017) as a review-gate diagnostic;
• protected main with the stable PR gate required on Python 3.11 and 3.13.

What is not yet a finished capability:

• there is no claim that IDKMesh can safely coordinate thousands or millions of real machines;
• the reference Verified Swarm Runner is not yet a polished install-and-run product with multiple production worker adapters;
• canonical real-node integration remains subject to its independent-review/evidence gates rather than being inferred from historical prototypes;
• A2A/MCP support is an interoperability layer, not a claim that every external agent framework is production-integrated;
• autonomous repository/community actuation remains policy- and authority-gated;
• benchmark infrastructure is not scientific proof until controlled observed runs exist.

This distinction is important: implemented infrastructure is evidence of capability to run experiments, not evidence that the research hypotheses are true.

Try it in five minutes: audit a review gate

The first installable tool cut from this research is idkmesh gate-audit. It measures what a panel of reviewers/verifiers is actually worth: effective independent votes (not nominal head-count), error-correlation structure, and the breach rate of seeded known-bad probe candidates.

git clone https://github.com/MSKazemi/idkmesh
cd idkmesh
pip install .
idkmesh gate-audit examples/gate-audit/panel-votes.example.json --pretty

The bundled example reports that a five-verifier panel is worth about 1.69 effective independent votes, and that the popular N/(1+(N-1)ρ) heuristic overstates it — the phenomenon measured on a real 25-verifier panel in E017 and falsified as a sizing rule in E015. The contract is specified in docs/specifications/GATE_AUDIT_V0_1.md. The audit is diagnostic only: it consumes verdicts you collected and grants no acceptance or merge authority. In CI, the same audit runs as a GitHub Action:

- uses: MSKazemi/idkmesh/actions/gate-audit@main
  with:
    votes-file: path/to/panel-votes.json

Start here

You do not need to understand the entire repository before contributing.

1. Read this README.
2. Read CONTRIBUTING.md.
3. Choose a contribution path in COMMUNITY.md.
4. Browse the live good first issue and help wanted views.
5. Before starting, check assignees, recent comments, and linked pull requests, then state the bounded change you intend to make.

Two live examples at the time of this audit:

• #167 — independently review IDKGraph orphan cohort 1, a bounded newcomer-friendly evidence/review task;
• #151 — independently audit the mathematical evolution control plane, a higher-skill security/control-systems review task.

The ACE Bootstrap Cohort Observatory is the live evidence source for the original growth-seed cohort. It intentionally distinguishes activity from verified external participation.

If something is confusing, stale, contradictory, or difficult to discover, reporting or fixing that is useful project work.

IDKMesh in 60 seconds

• IDK means I Don't Know: uncertainty, disagreement, assumptions, and competing hypotheses are first-class states.
• Mesh means a network of people, agents, tools, evidence, tasks, and compute rather than one monolithic agent.
• Workers should receive bounded Work Units, not unlimited project authority.
• Worker completion is not acceptance; verifier recommendation is not merge authority.
• Verification, provenance, reproducibility, and security must scale with generation volume.
• Diversity matters only when it adds sufficiently independent useful evidence.
• Git/GitHub are the current collaboration and canonical-history substrate.
• A2A and MCP are integration surfaces; IDKMesh should not invent commodity transport protocols unnecessarily.
• The public repository is also project memory: durable decisions, findings, evidence, and important collaboration history should remain inspectable.

The reference product

The first reference application is a Git-native Verified Swarm Runner.

The target lifecycle is:

bounded repository task
        |
        v
   WorkUnit v0.2
        |
        v
 replaceable worker adapters
        |
        v
 candidate artifacts + ResultManifest
        |
        v
 verifier-owned EvaluatorPlan
        |
        v
 independent VerificationResult
        |
        v
 non-selecting evidence/reporting
        |
        v
 explicit human/governance integration decision

The key authority rule is:

worker success != acceptance
verification recommendation != merge authority
CI success != independent human review

The current codebase already implements substantial pieces of this trust path, but the end-to-end newcomer product is still being converged and experimentally validated. See EVOLUTION.md, ROADMAP.md, and the open project issues for the live gates.

Run the repository checks

For the repository's Python research/control code:

python -m pip install --disable-pip-version-check pytest
python -m pip install --disable-pip-version-check -r requirements-phase0.txt
PYTHONPATH=. python -m pytest -q

Validate the core Phase 0 contracts directly with:

python experiments/harness.py validate

Pull requests to protected main run the stable PR gate on Python 3.11 and 3.13 plus deterministic Markdown-link integrity. Individual subsystems also have narrower workflows.

Core architecture

IDKMesh is best understood as one layered system:

human constitution / governance
           |
           v
 goals + questions + evidence
           |
           v
       Work Units
           |
           v
 capability/resource matching
           |
           v
 isolated humans / agents / tools / compute
           |
           v
 candidate artifacts + provenance
           |
           v
 independent verification / criticism
           |
           v
 explicit integration decision
           |
           v
 canonical state + outcome evidence
           |
           +------> next goals / policy learning

The canonical lifecycle vocabulary—event, action, candidate, iteration, generation, learning, and improvement—is defined in ITERATION_MODEL.md.

For implementation-level boundaries, see ARCHITECTURE.md and the curated docs/architecture/ index.

What IDKMesh builds vs reuses

IDKMesh should spend its complexity budget on the parts that express its research thesis:

• goals, uncertainty, and evidence;
• bounded Work Units and authority;
• decomposition and dependency structure;
• capability/resource matching;
• independent verification and evidence aggregation;
• provenance and reproducibility;
• experiment/benchmark machinery;
• community and governance feedback loops;
• measured self-improvement under external authority constraints.

Commodity infrastructure should normally be integrated rather than reinvented. Current examples include Git/GitHub, OCI-style isolation patterns, A2A, MCP, and established provenance/supply-chain approaches.

Research discipline

The repository distinguishes at least four states:

1. implemented mechanism — code/schema/workflow exists;
2. synthetic validation — deterministic fixtures/simulations test mechanics;
3. observed evidence — controlled runs measured real behavior;
4. accepted conclusion — evidence is strong enough for the scoped decision.

Do not collapse these states. A simulator can validate an algorithm's implementation without proving that the algorithm improves real collaboration.

One flagship research family compares, under matched budgets:

one strong worker
vs one small worker
vs replicated workers
vs heterogeneous workers
vs specialized roles
vs task/evidence DAG teams

Important outcomes include correctness, hidden-test success, regressions, error correlation, reviewer time, compute/resource use, latency, integration conflict, provenance quality, and verified useful work per unit of scarce attention/cost.

See RESEARCH_QUESTIONS.md, docs/research/, and experiments/.

Project principles

Community first. Contributor experience, review capacity, and leadership scalability are engineering constraints.

Proposal is not proof. Human or AI confidence does not replace evidence.

Popularity is not correctness. Votes, stars, reputation, or correlated model agreement cannot override failed checks.

More agents are not automatically better. Diversity, independence, decomposition quality, and verification capacity matter more than raw count.

Uncertainty is data. Competing goals and unresolved hypotheses should remain explicit when evidence is insufficient.

Generation must not outrun verification. Output volume is harmful if the project cannot review, reproduce, and maintain it.

Integrate before reinventing. Reuse open standards for commodity capabilities and keep IDKMesh-specific semantics at the coordination/evidence layer.

Scale must be earned. Simulated or small-scale results must not be advertised as Internet-scale guarantees.

Cryptographic provenance comes before blockchain. Add heavier trust infrastructure only when a demonstrated threat model requires it.

Canonical authority remains external to generators and verifiers. Protected integration is a separate decision boundary.

Repository guide

New contributor

• CONTRIBUTING.md — contribution workflow and checks.
• COMMUNITY.md — participation paths and contributor ladder.
• SUPPORT.md — how to ask for help.
• CODE_OF_CONDUCT.md — community expectations.
• SECURITY.md — vulnerability reporting.

Understand the system

• docs/WHAT_IS_IDKMESH.md — framework, research, community, reference application, and self-hosting layers.
• ITERATION_MODEL.md — canonical evolution vocabulary and authority flow.
• ARCHITECTURE.md — current architecture map.
• EVOLUTION.md — strategy, implemented foundation, and next gates.
• ROADMAP.md — evidence-gated progression from the current state.
• docs/README.md — curated documentation navigation.

Contracts and interoperability

• schemas/README.md — current machine-readable contracts and versioning rules.
• docs/specifications/ — protocol/specification index.
• interop/ — protocol-neutral adapter boundary, A2A/MCP mappings, identity binding, and conformance helpers.
• IDKIPS.md — major improvement-proposal process.

Research and evidence

• docs/research/ — research programs and evidence.
• sim/ — deterministic simulations/analysis code.
• experiments/ — experiment definitions, harnesses, and results tooling.
• docs/audits/ — bounded audits and repository-health evidence.
• docs/findings/ — research and engineering findings.

Community, governance, and project memory

• GOVERNANCE.md and CONSTITUTION.md — authority and protected principles.
• COMMUNITY_GROWTH_ENGINE.md — ACE community-growth experiment and safeguards.
• PROJECT_RULES.md — repository-wide operating rules.
• docs/conversations/ — append-only structured collaboration history.

Public project record

The repository is the durable project record. Important conclusions from project work should be promoted into current architecture, specifications, decisions, findings, research evidence, governance, or implementation—not left only in chats or buried in historical notes.

Historical records remain valuable, but they should not silently override current canonical documents. See PROJECT_RULES.md and docs/README.md for the documentation hierarchy.

License

Apache License 2.0. See LICENSE.

Invitation

IDKMesh starts from a simple admission: we do not yet know the best way to coordinate intelligence at this scale.

If you can improve a question, falsify an assumption, reproduce an experiment, write a test, find a security problem, make a contract clearer, reduce reviewer burden, improve onboarding, or build one verified component, you can contribute.

From uncertainty to collective intelligence—through evidence.