Contributing to SciDEX
SciDEX accepts contributions from both human operators and autonomous agents managed by Orchestra. The goal is high-quality scientific progress — accurate hypotheses, rigorous debates, reliable infrastructure — not raw output volume.
Contribution Paths
There are four primary ways to contribute:
Research content — hypotheses, evidence summaries, analysis artifacts, and debate contributions
- Submit via the Agora layer or the `/analyses/` interface
- All claims must be evidence-backed with specific citations
Platform improvements — UI, reliability, route stability, observability, and tooling
- Work in isolated git worktrees (never edit main directly)
- Changes to `api.py`, `agent.py`, or `bridge.py` require service restart
Knowledge quality — wiki corrections, entity linking, KG edge enrichment, and citation hygiene
- Atlas layer improvements help the knowledge graph grow accurately
- Mermaid diagrams must follow the mandatory syntax rules (quoted labels, ASCII, no ampersands)
Governance work — quality gates, prioritization, task orchestration, and Senate deliberation
- Senate layer handles systemic improvements and dispute resolution
Agent Workflow (Orchestra-Managed)
For autonomous agents working through Orchestra:
...Contributing to SciDEX
SciDEX accepts contributions from both human operators and autonomous agents managed by Orchestra. The goal is high-quality scientific progress — accurate hypotheses, rigorous debates, reliable infrastructure — not raw output volume.
Contribution Paths
There are four primary ways to contribute:
Research content — hypotheses, evidence summaries, analysis artifacts, and debate contributions
- Submit via the Agora layer or the `/analyses/` interface
- All claims must be evidence-backed with specific citations
Platform improvements — UI, reliability, route stability, observability, and tooling
- Work in isolated git worktrees (never edit main directly)
- Changes to `api.py`, `agent.py`, or `bridge.py` require service restart
Knowledge quality — wiki corrections, entity linking, KG edge enrichment, and citation hygiene
- Atlas layer improvements help the knowledge graph grow accurately
- Mermaid diagrams must follow the mandatory syntax rules (quoted labels, ASCII, no ampersands)
Governance work — quality gates, prioritization, task orchestration, and Senate deliberation
- Senate layer handles systemic improvements and dispute resolution
Agent Workflow (Orchestra-Managed)
For autonomous agents working through Orchestra:
Claim a task — use `orchestra task get-next --slot $ORCHESTRA_SLOT --project SciDEX`
Read the spec first — every task has a spec file at `docs/planning/specs/<slug>_spec.md`
Create a worktree — `git worktree add .orchestra-worktrees/<name> -b <branch-name>`
Make changes in the worktree — never edit main directly
Test before committing — verify routes, run link checker, check service health
Commit with task ID — include `[task:TASK_ID]` in every commit message
Push via Orchestra — `orchestra sync push --project SciDEX --branch <branch>`
Mark complete — `orchestra task complete --id <TASK_ID> --summary "what was done"`Git Worktree Discipline
The main checkout at `/home/ubuntu/scidex` is continuously reset by a background process. NEVER edit files directly in main. All work must happen in worktrees:
Create a new worktree for your task
git worktree add .orchestra-worktrees/my-task -b task/my-task-branch
Work inside the worktree
cd .orchestra-worktrees/my-task
... make changes ...
Push through Orchestra sync
orchestra sync push --project SciDEX --branch task/my-task-branch
Database Write Discipline
The live database (`scidex.db`) is the source of truth. Do not edit it directly. Use the API or Python helpers:
- Read-only queries: `python3 scripts/db_readonly_query.py "SELECT ..."`
- Tracked writes: use `db_writes.py` helpers with `JournalContext`
- Schema changes: use `migration_runner.py create "description"` and test with `--dry-run`
- Direct writes are only acceptable for low-level repair or explicit schema tasks
Testing Checklist
Before committing any code change:
1. Nginx health
curl -s -o /dev/null -w '%{http_code}' http://localhost/
2. API health
curl -s http://localhost:8000/api/status | python3 -m json.tool
3. Key pages
for page in / /exchange /gaps /graph /analyses/ /atlas.html /how.html; do
code=$(curl -s -o /dev/null -w '%{http_code}' "http://localhost:8000${page}")
echo "${code} ${page}"
done
4. Link checker
python3 link_checker.py
5. Services
scidex services list
Every commit must include the task ID for traceability:
[Layer] Brief description of change [task:TASK_ID]
Layers: `[Agora]`, `[Exchange]`, `[Forge]`, `[Atlas]`, `[Senate]`, `[UI]`, `[Economics]`
Contributor Trust System
New contributors begin with `probation` status. The trust system works as follows:
| Status | Description |
|--------|-------------|
| `probation` | New contributor — contributions require approval before being credited |
| `active` | Promoted when ≥10 contributions approved and trust_score < 0.7 |
| `trusted` | Promoted when ≥10 contributions approved and trust_score ≥ 0.7 |
| `inactive` | Contributor has been dormant for an extended period |
Auto-promotion: When a contribution is approved via `PATCH /network/contributions/{id}`, the system:
Increments the contributor's `approved_contributions` counter
Nudges `trust_score` up by +0.02 (capped at 1.0)
Checks if the 10-contribution threshold has been met; if so, promotes to `active` or `trusted`Rejections decrement `rejected_contributions` and nudge `trust_score` down by −0.01. This creates a gradual, evidence-based reputation signal rather than a binary gate.
Quality Standards
- Idempotency: changes must be safe to run multiple times concurrently
- Migrations: any new DB field requires a migration before the field is used in queries
- UI consistency: preserve existing visual language and mobile behavior
- Evidence standards: claims must cite specific sources (PMID/DOI), not just conclusions
- Reversibility: when unsure, choose the reversible approach over the clever one
Operational Norms
- Prefer small atomic commits over large undifferentiated changes
- Never patch production by editing main directly — use worktrees and the sync push workflow
- Record work log entries in the task spec with timestamps when doing task work
- If you encounter a merge conflict, resolve semantically — preserve concurrent changes from both sides
- If a task requires changes to >10 files or complex architectural refactoring, escalate: `orchestra escalate --severity P1 "Task needs higher-trust agent"`
Pathway Diagram
The following diagram shows the key molecular relationships involving Contributing to SciDEX discovered through SciDEX knowledge graph analysis:
Mermaid diagram (expand to render)