The eight-pass pipeline, in detail.

/ 01Architecture

Review is a sequential pipeline of eight passes orchestrated by the analysis engine (port 8765). A document enters as canonical text; it leaves as a structured AnalysisResult carrying issues, dimension scores, a composite compliance score, and the artefacts each pass produced along the way.

The pipeline is deterministic on its inputs: the same text + same tier + same jurisdiction yields the same output, bit-for-bit. Determinism is what makes glass-box explanations defensible — every finding can be replayed.

Request shape

class AnalyseRequest:
    text: str             # Document text (min 10 chars)
    tier: str             # "A" structural · "B" + legal · "C" all
    enable_legal: bool
    enable_academic: bool
    enable_corporate: bool
    style_guide: str      # chicago | oxford | nyt | bluebook | legal | academic | corporate
    citation_style: str   # apa (default) | chicago | oxford | nyt | bluebook | legal
    jurisdiction: str     # eng | de | fr | us_ny | au | sg ... (127 options)
    sectors: list[str]   # Optional sector filter

Tier gating

/ 02The eight passes

The order is fixed. Each pass receives the document, the running issue list, and any artefacts produced by earlier passes (token graph from Structural; the term-glossary from Consistency; the obligation table from Semantic).

/ 03Pass 1 · Structural

The pre-flight check. Structural runs the document through spaCy (per detected language), produces tokens, sentences, paragraphs, POS tags, and a dependency graph. Every later pass operates on these artefacts; if Structural cannot produce them, the pipeline aborts with a hard error.

What it produces

• Token graph — sentence and clause segmentation, dependency edges
• Tense classification — present · past · future · perfect · conditional
• Voice detection — active · passive · middle, with passive-voice percentage
• Branching complexity — per-clause score over dependency depth
• Readability — Flesch-Kincaid grade and word/sentence/paragraph/clause counts

What it flags

Grammar issues, sentences over ~45 words, paragraph integrity, formatting consistency, readability scored below grade 9 / above grade 18, branching complexity above silo threshold.

/ 04Style

Style runs the configured guide (Chicago, Oxford, NYT, Bluebook, Legal, Academic, Corporate, or a YAML house-rules file) against the document. The check is precise and fast — 5 seconds is generous; most documents complete in well under 1.

What it checks

• Citation format vs. the selected citation_style
• Numbering convention — alphabetic, numeric, or roman; mixed-scheme violations
• Capitalisation against the guide
• Term consistency — same concept, same word, across the document
• House rules from a project-supplied YAML (see Authoring a legal-pack rule for syntax — the rule schema is shared)

/ 05Pass 3 · Consistency

Consistency catches the things even careful authors miss: a defined term used before its definition, a tense shift between recitals and operative clauses, a cross-reference to a clause that no longer exists after revision.

Sub-detectors

• intra_contradiction — same document, contradictory statements
• tense_shift — drift between past and present in connected clauses
• definition_coherence — circular, conflicting, or orphan definitions
• crossref_integrity — every "Section 4.2" actually resolves; 11 instrument detectors
• defined_term — declared but unused, used but undeclared, used out of scope

/ 06Legal pack

The legal pack is the heaviest pass and the heart of Redline's value: 847+ rules across 127 jurisdictions, evaluated against the document with the configured jurisdiction and sector filter applied.

Rule files, by jurisdiction

Each jurisdiction directory (e.g. eng/, de/, us_ny/) contains numbered rule files. A representative slice from eng/:

eng/
  01_boilerplate.json       Template-text detection
  02_cra.json               Consumer Rights Act
  03_employment.json        Employment law
  04_data_protection.json   GDPR / DPA 2018
  05_ucta_liability.json    Unfair Contract Terms Act
  06_fsma.json              Financial Services & Markets Act
  07_obligations.json       Deontic logic (shall/must/may)
  08_companies_act.json     Corporate governance
  09_drafting_quality.json  Style & clarity
  10_ip_insurance.json      IP indemnification
  …

Sample finding

{
  "id": "iss_8f3a1c",
  "pass": "legal",
  "rule": "eng.05_ucta_liability.cap_below_threshold",
  "severity": "major",
  "confidence": 0.91,
  "jurisdiction": "eng",
  "span": { "start": 14823, "end": 14961, "clause": "11.3" },
  "summary": "Liability cap may be unenforceable under UCTA s.3",
  "explanation": "The cap is set at 50% of fees paid in the 12 months...",
  "suggestion": "Raise the cap to at least 100% of fees, or include the carve-outs..."
}

The legal-pack rule authoring guide covers the schema, pattern grammar, suppression, and CI validation in depth.

/ 07Pass 2 · Semantic

The expensive pass — 30 seconds because semantic analysis is where the LLM-shaped work happens: lemmatisation across paraphrase, deontic logic over modal verbs, Hohfeldian rights analysis (right · duty · privilege · no-right · power · liability · immunity · disability), and discourse-relation extraction.

Deontic taxonomy

The output of Semantic feeds the Ledger obligation extractor — see the Ledger extraction model for what happens next.

/ 08Pass 4 · Synthesis

The closer. Synthesis takes the union of issues from every preceding pass, clusters them, scores them across the four dimensions, and produces the executive summary that the PDF report leads with.

The compliance score

0–100 composite across four sub-scores:

• Structure · clause organisation, numbering, cross-references
• Style · writing quality, readability, consistency
• Legal · jurisdiction compliance, statutory alignment
• Tone · formality, precision, deontic clarity

Letter grade

A ≥ 80 · B ≥ 60 · C ≥ 40 · D ≥ 20 · F < 20. Status colour: green ≥ 80 · amber ≥ 50 · red below.

/ 09When a pass times out

Time budgets are real, not aspirational. If a pass exceeds its budget the engine cancels the in-flight work, records a pass_timeout event on the result, and continues to the next pass with whatever the timed-out pass produced so far. The result is marked partial: true and the affected dimension is annotated.

/ 10Output shape

The pipeline returns a single AnalysisResult object that every export format (DOCX tracked, branded PDF, .fieldbook, CSV/JSON) is derived from. The shape, abbreviated:

interface AnalysisResult {
  id: string;
  document_hash: string;
  tier: "A" | "B" | "C";
  jurisdiction: string;
  score: { composite: number; structure: number; style: number; legal: number; tone: number };
  grade: "A" | "B" | "C" | "D" | "F";
  issues: Issue[];
  passes: { [name: string]: PassReport };
  partial: boolean;
  timed_out_passes: string[];
  summary: string;
  artefacts: Artefact[];   // obligation table, term glossary, clause hierarchy
}

See Export formats & their guarantees for what each derived artefact preserves.