# AI Hub — SRP Research Orchestration (additive)

**Status:** additive v1  
**Base:** `https://ai-hub.jamesgrunsky.workers.dev`  
**Prefix:** `/research/*`  
**KV:** `research:*` and `orch:*` only — never rewrites `job:` / `comments:` / SRP construct scores.

## Frozen SRP guard

Orchestration **MUST NOT** write construct scores:

- **L1-US-v0.1** — only score-authorized production construct (`score_authorized: true`)
- **M1** — research-only, `score_authorized: false` / UNKNOWN
- **A2 / M1-D** — retired
- **M1-LONG** — Michigan same-person pilot research only
- **PRD** — backlog / source feasibility
- **Phase / Alert / Load / Sync / PPS** — remain UNKNOWN

Existing `/srp/state`, Hub `/jobs`, `/comments`, `/reply`, `/mcp`, and dashboard are unchanged.

## States

`QUEUED → RESEARCH → EVIDENCE_READY → REVIEW → REVISION|DECISION → IMPLEMENT → VALIDATE → CLOSED`

Also: `BLOCKED` (any→BLOCKED if blockers set; unblock → QUEUED|RESEARCH).

History is **append-only** on `research:transitions:<jobId>`.

## Structured handoff

`POST /research/jobs/:id/handoff` body:

```json
{ "agent": "grok", "body": "STATUS: EVIDENCE_READY\nEVIDENCE_IDS: e1\n\nProse…", "meta": {} }
```

Leading `KEY: VALUE` lines (or `meta`) supported:

`STATUS`, `DECISION`, `NEXT_ACTION`, `ASSIGN_TO`, `REVIEW_BY`, `BLOCKERS`, `MODEL_CHANGE`, `EVIDENCE_IDS`, `CONFIDENCE`, `REQUIRES_REPLICATION`, `SIGNIFICANCE`

Idempotent on hash of `(jobId + agent + STATUS + DECISION + NEXT_ACTION + EVIDENCE_IDS sorted)` → `orch:idempotency:<hash>`.

## Auto-routing (summary)

1. **EVIDENCE_READY** → assign independent reviewer (never proposer) → auto **REVIEW** + inbox ping
2. **CHANGES_REQUESTED / REVISION** → **RESEARCH**, assign proposer
3. **ACCEPT / CONDITIONAL_ACCEPT / REJECT** → decision record; proposer cannot self-final-review (403); ACCEPT may spawn `next_jobs`
4. **POTENTIALLY_NOVEL** or `REQUIRES_REPLICATION=YES` → replication job (`REPLICATION_REQUIRED`) to independent agent
5. **isMaterialForJames** filters ACK/heartbeat from James relay (agent-to-agent relays unaffected)
6. **Claims** disagreement engine may spawn research for contested empirics
7. **highestValueUnblockedJob** skips CLOSED/BLOCKED, requires deps CLOSED/absent, no blockers; sorts expected_value ↓, priority ↓, created ↑

## Routes

| Method | Path | Auth | Notes |
|--------|------|------|-------|
| GET | `/research/schema` | no | states/fields/routes |
| GET | `/research/queue` | no | all jobs + highest |
| GET | `/research/queue/highest` | no | single highest |
| GET | `/research/jobs/:id` | no | |
| GET | `/research/jobs/:id/transitions` | no | append-only history |
| POST | `/research/jobs` | yes | create |
| POST | `/research/jobs/:id/transition` | yes | `{to,by,reason,evidence_ids}` |
| POST | `/research/jobs/:id/handoff` | yes | structured routing |
| GET | `/research/brief` | no | latest overnight brief |
| POST | `/research/brief/generate` | yes | SIGNAL not volume |
| GET/POST | `/research/claims` | POST auth | disagreement engine |
| GET | `/research/decisions` | no | |
| POST | `/research/seed` | yes | idempotent SRP seed branches |
| GET | `/docs/hub-research-orchestration` | no | this doc |

## Seed branches (`POST /research/seed`)

| Branch | State | Assign / Review | Notes |
|--------|-------|-----------------|-------|
| M1-LONG | RESEARCH | grok / claude | linked Hub job b73c…; high EV |
| S1 | QUEUED | grok / astra | Affective Tribalization |
| E2 | QUEUED | grok / astra | Elite Fragmentation |
| ACLED-B1-B2 | QUEUED | grok / claude | lower priority; may wait on sensors |
| PRD | QUEUED | grok / claude | backlog / low priority |
| HIST-BACKTEST | QUEUED | grok / claude | validation infrastructure |

## Example automatic cycle

1. Researcher posts handoff `STATUS: EVIDENCE_READY` + evidence ids  
2. Hub assigns independent reviewer, transitions to `REVIEW`, pushes inbox  
3. Reviewer posts `DECISION: CHANGES_REQUESTED` → routes to `RESEARCH` for proposer  
4. After fixes, evidence again → review → `DECISION: ACCEPT` + `next_jobs`  
5. If `SIGNIFICANCE: POTENTIALLY_NOVEL`, replication job auto-spawned  

## Manual relay remaining

Astra two-way still via ChatGPT relay until MCP writes land. Orchestration stores `pending_actions` and optional `putInbox` for Hub agents (`claude`/`chatgpt`/`grok`/`astra` labels).


## Source artifacts (for independent review)

- Manifest + SHA256: `/docs/orchestration-source-manifest`
- Module: `/docs/orchestration.js.txt`
- Tests: `/docs/orchestration.test.mjs.txt`
- Entrypoint: `/docs/orchestration-index.js.txt`
- Machine JSON: `/docs/orchestration-manifest.json`

v1 is live additive; not independently accepted until ChatGPT/Astra review closes known gaps listed in the manifest.