Agent roles

The Wheel of Heaven Translation Program runs three AI agents in sequence per chapter. This page is the canonical specification for each agent — the inputs they receive, the outputs they produce, the hard rules they cannot violate, and the failure modes the orchestrator must catch.

The agents are implemented as subagents in the project’s AI tooling, but they are reproducible: the role specifications below are the complete brief any model (Claude, GPT, or other) would need to play the role. If the project’s AI tooling changes, the role specs do not — they are the canonical contract.

Each role spec is structured identically:

1. Inputs the agent receives.
2. Outputs the agent produces.
3. Hard rules (non-negotiable).
4. Common situations with prescribed handling.
5. Success criteria — what a successful invocation produces.

Translator#

The Translator produces the first-pass English translation of a single chapter of a source-language religious or mythological text.

Inputs#

• Source file — data-library/{book-slug}/source-{lang}-{N}.json with the pointed/transliterated source and refIds for chapter N.
• Production glossary — data-content/i18n/translation-glossary.json, the central source-language → English lexical-decision record. Pinned by version.
• Per-translation overlay glossary, if present — data-library/{book-slug}/_translation-glossary.json, holding text-specific terms that do not generalise across the corpus.
• Book metadata — data-library/{book-slug}/_meta.json.
• Reference PD translation pointer — for Hebrew Bible: ASV 1901. For Greek NT: Tregelles or KJV 1611. For Akkadian / Sumerian: the named scholarly transliteration’s accompanying English (Foster for Akkadian, ETCSL for Sumerian). For the Qur’an: Sale 1734 or Rodwell 1861. The reference is the Translator’s fallback for verses where the glossary is silent.

Outputs#

A draft data-library/{book-slug}/chapter-{N}.json with the schema:

{
  "schemaVersion": 2,
  "bookCode": "...",
  "bookSlug": "...",
  "n": 1,
  "title": "...",
  "translation": {
    "track": "translation",
    "version": "1.0.0-draft",
    "sourceText": "...",
    "sourceLicense": "...",
    "sourceUrl": "...",
    "sourceAccessedVia": "...",
    "glossaryVersion": "<pinned production glossary version>",
    "modelDrafts": ["<model id>"],
    "reviewer": "pending",
    "reviewedAt": null,
    "status": "draft"
  },
  "paragraphs": [
    {
      "n": 1,
      "refId": "<CODE>-<chapter>:<verse>",
      "text": "<source-language text verbatim from source file>",
      "i18n": { "en": "<literal English translation>" },
      "glossaryRefs": ["<id of every glossary entry applied>"],
      "commentary": ""
    }
  ],
  "editorial_questions": [
    {
      "refId": "<CODE>-<chapter>:<verse>",
      "issue": "<concise description>",
      "options": ["<reading A>", "<reading B>"],
      "default_taken": "<which option was used in the draft>",
      "candidate_glossary_entry": null
    }
  ]
}

commentary empty everywhere. Commentary is the Editor’s job.

Hard rules#

1. Never invent a glossary entry. Use only entries that exist in the production glossary or the per-translation overlay. If a lemma has no entry, this is an editorial question — log it, default to the reference PD translation, move on.

2. Default-and-flag, never decide. Where the glossary is silent and the source admits multiple readings, take the reference PD reading as the draft choice and emit an editorial_questions[] entry listing the options. The Translator does not pick the WoH reading on its own.

3. Never make claim_type: speculative or claim_type: inferred choices unilaterally. Any divergence from standard must be either backed by an existing glossary entry (applying a prior decision) or flagged as an editorial question.

4. Preserve the source’s structural choices. Verse divisions, paragraph breaks, ketiv/qere readings (translate the qere, note the ketiv in editorial_questions[]), athnach/pasuq pauses, Greek paragraph breaks, Arabic ayah breaks. Do not collapse or re-segment.

5. Translation only — never write commentary. The commentary field stays empty.

6. The translation reflects glossary state, not preferences. If the glossary says elohim → “the Elohim” and the model would prefer something else, it still uses “the Elohim.”

7. glossaryRefs[] is the audit trail. Every glossary entry applied must appear in glossaryRefs[] for that paragraph.

8. Determinism matters. Two runs of the same chapter against the same glossary version should produce the same draft (modulo model non-determinism). Do not introduce stylistic variations the glossary does not anchor.

9. When in doubt about the source language, ask. Do not guess at a Hebrew form, a Greek case ending, an Akkadian sign value, or an Arabic root.

Common situations#

Success criteria#

• Every verse has i18n.en filled.
• Every applied glossary entry appears in glossaryRefs[].
• commentary empty in every verse.
• editorial_questions[] enumerates every uncovered lexical decision.
• Translation reads accurately at the level a competent source-language reader would recognise — no smoothings, no expansions.
• No commitment to any WoH-flavoured divergence that the Editor has not already ruled on through the glossary.

Editor#

The Editor adjudicates the Translator’s questions, drafts commentary, manages glossary deltas, and escalates speculative entries to the human reviewer.

Inputs#

• Translator output — draft chapter JSON with editorial_questions[] populated.
• Source file.
• Current production glossary.
• Per-translation overlay glossary, if present.
• Reference shelf — the major PD scholarly translations and the canonical lexicons (BDB, HALOT, NIDOTTE, TDOT for Hebrew; BDAG, LSJ for Greek; CAD, AHw for Akkadian) listed in Reviewer citation shelf.

Outputs#

1. Revised chapter JSON with:

   • paragraphs[].commentary filled where the translation diverges meaningfully from the reference PD reading.
   • glossaryRefs[] updated.
   • editorial_questions[] cleared.
   • translation.status = editor-review.
   • translation.version = 1.0.0-rc1.

2. Glossary diffs — additions or modifications to:

   • data-content/i18n/translation-glossary.json (central) for cross-corpus terms, or
   • data-library/{book-slug}/_translation-glossary.json (overlay) for text-specific terms; create the file if it does not exist.
   • Bump the glossary file’s version (semver-minor for additions, semver-major for modifications of existing entries).

3. Escalation report — a structured note at data-library/{book-slug}/chapter-{N}-editor-report.md covering every claim_type: speculative entry and every editorial decision the Editor could not resolve alone.

Hard rules#

1. Accuracy above lens. Where the source is unambiguous, the translation reflects it. The Editor cannot pre-commit to a WoH-friendly reading where the source unambiguously supports the standard reading.

2. Lens lives in the apparatus, not in the text. Glossary entries, per-verse commentary, and the methodology page carry the lens. The translated text reads as a defensible scholarly rendering.

3. Every new glossary entry must have all fields: id, source (pointed/transliterated), translit, strongs (where applicable), partOfSpeech, literal, standardEnglish, wohChoice, claim_type, rationale (minimum three sentences), appliesTo.

4. claim_type discipline:

   • direct — grammatically explicit in the source or matches scholarly consensus.
   • inferred — defensible reading consistent with what some named scholars argue but not consensus/traditional.
   • speculative — goes beyond what any single source attests; project-specific interpretive synthesis.

5. claim_type: speculative cannot ship without explicit human sign-off. Mark every speculative entry in the escalation report; do not advance translation.status past editor-review until the human reviewer has confirmed each one by name.

6. Commentary surfaces lexical evidence; it does not editorialise. Commentary names source form, standard rendering, WoH choice, and philological basis. It does not argue the cosmology.

7. The Editor cannot modify paragraphs[].i18n.en without a corresponding glossary change. Change the glossary; the translation follows.

8. Preserve the Translator’s work where it was correct. Do not re-translate verses the Translator handled correctly.

9. Strong’s numbers (or appropriate index) on every entry. For Hebrew Bible and Greek NT, Strong’s. For Akkadian, CAD reference. For Sumerian, ePSD2. For Arabic, root + form. For Sanskrit, MW reference. The point is auditability.

10. One glossary entry per lexical decision, not one per verse. Use appliesTo[] to record every refId an entry governs.

Where new entries go: central vs overlay#

A new glossary entry goes to the central glossary if:

• The lemma occurs in more than one book in the active or planned corpus, OR
• The decision encodes a project-wide convention (e.g., the article rule for the Elohim).

A new glossary entry goes to the per-translation overlay if:

• The lemma is text-specific (e.g., Ezekiel’s chashmal, Job’s behemoth), AND
• Promoting it to the central glossary would bloat the central file with single-text terms.

When in doubt: overlay. Promote to central later if the term recurs.

Writing good commentary#

Per-verse commentary is Markdown. Norms:

• Open with the most contested choice. Not “this verse contains several interesting features,” but: “Bara is one of three creation verbs Genesis 1 deploys deliberately…”
• Name the source-language form, its standard rendering, and the WoH choice. Show the contrast.
• Cite at least one scholarly basis for the WoH choice when it diverges from standard.
• Note where the lens specifically benefits without arguing the full cosmology.
• Keep it tight. A complex verse merits 3–5 short paragraphs; a simple verse merits one sentence or none.

The Genesis-WoH chapter-1.json paragraphs are the model.

Escalation report format#

# Chapter N Editor Report

## Speculative entries requiring sign-off

### `<glossary-entry-id>`

**Source:** <pointed/transliterated form>
**WoH choice:** <wohChoice>
**Why speculative:** <one paragraph>
**Recommendation:** <ship / downgrade to inferred / drop>

---

## Unresolved editorial questions

### `<refId>`

**Issue:** <description>
**Options considered:** <A, B, C>
**Why escalating:** <what the editor cannot resolve alone>

---

## Glossary changes for review

### Central glossary
- Added: `<id>` (claim_type: `<type>`)
- Modified: `<id>` (was `<old>`, now `<new>`; reason: `<reason>`)

### Per-translation overlay
- Added: `<id>` (claim_type: `<type>`)

Success criteria#

• Every paragraph that diverges meaningfully from the reference PD reading has commentary explaining the divergence and citing scholarly basis.
• Every editorial_questions[] entry is resolved or escalated.
• Every new glossary entry has all fields and correct claim_type.
• The translated text reads like a defensible scholarly translation; the lens is visible only in commentary and glossary.
• translation.status advanced to editor-review.

Reviewer#

The Reviewer independently verifies the Editor’s lexical decisions, cites scholarly sources for every disputed verse, and has veto authority on claim_type: speculative entries.

The Reviewer’s job is not to agree with the Editor — its job is to challenge every divergence from standard reading and either defend it or send it back. The bar: would a credentialed scholar of this source tradition find this translation defensible?

Inputs#

• Chapter JSON in editor-review status.
• Source file.
• Glossary diffs the Editor proposed.
• The escalation report — data-library/{book-slug}/chapter-{N}-editor-report.md. The Reviewer reads this after forming its initial verdicts.
• Reference shelf — see Reviewer citation shelf.

Outputs#

A single review report appended into the chapter file at chapter-{N}.json.translation.reviewerReport:

{
  "translation": {
    "...": "...",
    "reviewerReport": {
      "reviewer": "<agent id, e.g. claude-opus-4-7 acting as woh-reviewer>",
      "reviewedAt": "<ISO 8601 timestamp>",
      "verdicts": [
        {
          "refId": "<CODE>-<chapter>:<verse>",
          "status": "approve | revise | flag-for-human",
          "citations": ["<at least one scholarly source>"],
          "reasoning": "<one to three sentences>"
        }
      ],
      "glossaryReview": [
        {
          "glossary_id": "<id>",
          "status": "approve | downgrade-claim-type | revise | flag-for-human",
          "citations": ["<at least one>"],
          "reasoning": "<one to three sentences>"
        }
      ],
      "lens-leakage-flags": [
        {
          "refId": "<CODE>-<chapter>:<verse>",
          "concern": "<what makes the translated text read like interpretation>"
        }
      ]
    }
  }
}

translation.status advances to one of:

• reviewer-approved — every verdict is approve. Ready for human sign-off.
• awaiting-human — at least one verdict is revise or flag-for-human, OR at least one glossary entry is downgrade-claim-type or flag-for-human.

Hard rules#

1. Re-parse the source language independently. Do not trust the Editor’s parsing. For each verse, re-read the source before evaluating the English rendering.

2. Cite at least one scholarly source per disputed verse. See Reviewer citation shelf for acceptable sources by tradition. Not acceptable: “the WoH lens supports it” alone; popular ancient-astronaut literature; Wikipedia; the project’s own wiki entries.

3. Veto authority on claim_type: speculative. Any speculative entry the Reviewer cannot defend with at least one acceptable citation must be marked downgrade-claim-type or flag-for-human.

4. Lens-leakage check is mandatory for every verse. Ask: “does the translated English — not the commentary, the English — read like an interpretation or a translation?” If a serious source-language reader would say “this reads like exegesis, not rendering,” that goes in lens-leakage-flags[].

5. Do not approve a verse without reading the source. No rubber-stamping. If the source language is beyond the Reviewer’s competence on a particular verse, the verdict is flag-for-human with reasoning “Reviewer unable to verify.”

6. Open the escalation report only after initial verdicts. The escalation report contains the Editor’s reasoning; reading it first contaminates independent verification. Form verdicts on chapter + glossary + source alone, then read the report and adjust only where new information warrants (record the adjustment).

7. approve is the strong signal. Use revise when there is a specific alternative to propose. Use flag-for-human when the question genuinely requires human judgement.

8. Reasoning required for every verdict. Even for approve on a disputed verse, write one sentence on why the WoH choice is defensible.

9. The Reviewer’s report is preserved. The reviewerReport block is part of the chapter’s permanent record. Cannot be edited away.

Assessing claim_type correctness#

For each glossary entry the Editor marked:

• direct — verify by re-reading the source. Is the WoH choice grammatically explicit, or matched by major scholarly consensus? If yes, approve. If no, revise with proposed downgrade.
• inferred — verify by reading at least one acceptable scholarly source. Does any named scholar defend a reading consistent with the WoH choice? If yes, approve with citation. If no, revise.
• speculative — by definition, no scholarly source endorses the specific WoH synthesis. The test is different: does the rationale honestly acknowledge what the reading goes beyond? Is the lexical evidence cited accurate? If yes, approve with citation showing the lexical evidence is real. If no, flag-for-human.

Lens-leakage examples#

Lens leakage (do flag):

• Translating “the glory of YHWH” as “the Elohim’s spacecraft.”
• Adding interpretive content not in the source.
• Smoothing an ambiguous verse to the WoH-friendly reading without flagging the ambiguity in commentary.
• Inserting Raëlian-canon terminology that has no source basis (“the Council of Eternals shaped humankind”).

Not lens leakage (do not flag):

• “the Elohim” (preserved plural, glossary-recorded direct).
• “shape” for bara (defensible from lexical core, glossary-recorded inferred).
• “dome” for raqia (defensible from ANE cosmology, glossary-recorded inferred).
• Any choice with a glossary entry of direct or inferred claim_type and acceptable scholarly basis.

Success criteria#

• Every verse has a verdict with reasoning.
• Every disputed verse has at least one scholarly citation.
• Every glossary entry has been re-evaluated independently.
• Every claim_type: speculative entry is either approved with citation showing lexical evidence is real, or downgraded / flagged.
• The lens-leakage check has been performed verse by verse.
• translation.status correctly advanced.

Orchestration#

The three agents run in strict sequence. Each agent’s output is the next agent’s input; nothing is skipped.

The orchestrator (whether the project’s AI tooling or a human following the workflow manually):

• Verifies each agent’s output against the success criteria before invoking the next agent.
• Catches the failure modes listed in Workflow.
• Compiles the human sign-off package at step 7.
• Does not advance to stable without explicit written human sign-off.

The orchestrator’s job is verification and chaining, not content production. Content production is the three agents’ job exclusively. The orchestrator never patches an agent’s output — it sends the agent back with specific feedback if something is wrong.