# How the Material Passport Flows Through ARS Pipeline Stages: A Complete Technical Guide

> Learn how the Material Passport flows through ARS pipeline stages. Discover its full journey and integrity checks in this complete technical guide. Understand its role from creation to verification.

- Repository: [Edward Cheng-I Wu/academic-research-skills](https://github.com/Imbad0202/academic-research-skills)
- Tags: how-to-guide
- Published: 2026-05-13

---

**The Material Passport is an append-only ledger (Schema 9) that travels with every artifact through nine phases of the Academic Research Skills pipeline, passing through mandatory machine-verified integrity gates at stages 2.5 and 4.5 that transition the `verification_status` from UNVERIFIED to VERIFIED.**

The Material Passport serves as the central provenance system in the **Imbad0202/academic-research-skills** repository, governing how research artifacts maintain integrity and auditability from initial conception through final publication. Understanding how the Material Passport flows through ARS pipeline stages is essential for implementing reproducible research workflows that comply with the system's strict Iron Rules for data integrity.

## The Nine-Phase Journey of the Material Passport

### Stage 1: Research (deep-research)

The passport is **created** when the first raw outputs are produced, including the RQ brief, methodology blueprint, and bibliography. Required fields such as **`origin_skill`**, **`origin_mode`**, **`origin_date`**, **`verification_status`**, and **`version_label`** are initialized.

- **`verification_status`** is set to **UNVERIFIED**
- **`content_hash`** is calculated for the RQ brief using SHA-256

### Stage 2: Write (academic-paper)

The passport is **carried forward** and enriched with the paper outline, draft text, and optionally a **`literature_corpus[]`** if the user supplied one via an adapter. According to [`shared/handoff_schemas.md`](https://github.com/Imbad0202/academic-research-skills/blob/main/shared/handoff_schemas.md), this optional field appears as an input port populated by user adapters such as [`scripts/adapters/folder_scan.py`](https://github.com/Imbad0202/academic-research-skills/blob/main/scripts/adapters/folder_scan.py).

### Stage 2.5: Integrity Gate (academic-pipeline)

A **machine-verified integrity gate** runs a 7-mode AI-failure checklist. If the check passes:

- **`verification_status`** updates to **VERIFIED**
- **`integrity_pass_date`** records the timestamp
- **`compliance_history[]`** may receive an entry (Schema 12)

This gate cannot be skipped; the user must acknowledge the integrity report before advancing.

### Stage 3: Review (academic-paper-reviewer)

The passport continues unchanged as the full-review package generates. Reviewers' Sprint Contracts (Schema 13) attach externally, not inside the passport. No new fields are added, but the **`verification_status`** remains **VERIFIED**.

### Stage 3 to 4: Revision Coaching

The passport is **read-only** during the Socratic revision dialogue. No mutation occurs during this transition phase.

### Stage 4: Revise (academic-paper)

The draft undergoes revision and the passport receives updates:

- **`version_label`** bumps (e.g., from `paper_draft_v1` to `paper_draft_v2`)
- New **`content_hash`** computes for the revised manuscript

If the revision introduces new claims, the system flags the passport for re-checking at Stage 4.5.

### Stage 4.5: Final Integrity (academic-pipeline)

A **second integrity gate** runs deeper re-verification with 100% claim sampling:

- **`verification_status`** stays **VERIFIED**
- **`integrity_pass_date`** refreshes with the new timestamp
- **`repro_lock`** block (Schema 12) must be present or explicitly set to `null`

This mandatory gate is enforced by [`scripts/check_repro_lock.py`](https://github.com/Imbad0202/academic-research-skills/blob/main/scripts/check_repro_lock.py), which ensures the reproducibility lockfile exists before the pipeline advances.

### Stage 5: Finalize (academic-paper)

The final manuscript renders with the last **`version_label`** (e.g., `final`). The passport achieves **finalized** status and accepts no further mutations.

### Stage 6: Process Summary (academic-pipeline)

The passport is included in the **Process Summary** record alongside the **Collaboration Depth** chapter. All historic fields—including **`audit_artifact[]`**, **`reset_boundary[]`**, and previous integrity timestamps—are retained for downstream auditability as specified in [`docs/design/2026-04-30-ars-v3.6.7-step-6-orchestrator-hooks-spec.md`](https://github.com/Imbad0202/academic-research-skills/blob/main/docs/design/2026-04-30-ars-v3.6.7-step-6-orchestrator-hooks-spec.md).

## Core Mechanics and Data Integrity Guarantees

### Append-Only Ledger Architecture

Every stage **appends** new fields to the passport; existing entries are never overwritten. This guarantees an immutable audit trail from Stage 1 through Stage 6, satisfying the reproducibility requirements outlined in [`docs/ARCHITECTURE.md`](https://github.com/Imbad0202/academic-research-skills/blob/main/docs/ARCHITECTURE.md) §7.

### Mandatory Integrity Gates

Stages 2.5 and 4.5 enforce **`verification_status: VERIFIED`** before the pipeline may advance. The orchestrator (`academic-pipeline`) is the only component authorized to add integrity-related fields; downstream agents are prohibited from altering the passport directly. This restriction is enforced by lint scripts such as [`scripts/check_corpus_consumer_protocol.py`](https://github.com/Imbad0202/academic-research-skills/blob/main/scripts/check_corpus_consumer_protocol.py).

### Optional Schema Extensions

The passport supports several optional fields added at specific versions:

- **`literature_corpus[]`**: Populated by user adapters before Stage 2 (see [`academic-pipeline/references/literature_corpus_consumers.md`](https://github.com/Imbad0202/academic-research-skills/blob/main/academic-pipeline/references/literature_corpus_consumers.md) for the four Iron Rules governing consumption)
- **`audit_artifact[]`**: Ledger of cross-model audit runs for downstream agents (added in v3.6.7)
- **`repro_lock`**: Reproducibility lockfile requirement (v3.3.5+)
- **`reset_boundary[]`**: Cross-session resume ledger (opt-in via `ARS_PASSPORT_RESET=1`)

## Working with the Material Passport: Code Examples

### Creating a Minimal Passport

The following Python function initializes a passport at Stage 1, computing the required SHA-256 hash for the content blob:

```python
import yaml, hashlib, datetime

def make_passport(origin_skill, origin_mode, content):
    # Compute a SHA‑256 hash of the content blob

    content_hash = hashlib.sha256(content.encode()).hexdigest()
    passport = {
        "origin_skill": origin_skill,
        "origin_mode": origin_mode,
        "origin_date": datetime.datetime.utcnow().isoformat() + "Z",
        "verification_status": "UNVERIFIED",
        "version_label": "v1.0",
        "content_hash": content_hash,
    }
    with open("passport.yaml", "w") as f:
        yaml.safe_dump(passport, f)
    print("Material Passport written to passport.yaml")

# Example: create a passport for the RESEARCH stage

make_passport("deep-research", "full", "RQ brief and methodology")

```

### Updating at Integrity Gates

After Stage 2.5 verification succeeds, update the passport using this shell snippet:

```bash

# After Stage 2.5 integrity verification succeeds:

python -c '
import yaml, datetime, hashlib, sys
with open("passport.yaml") as f:
    p = yaml.safe_load(f)
p["verification_status"] = "VERIFIED"
p["integrity_pass_date"] = datetime.datetime.utcnow().isoformat() + "Z"

# Re‑hash the updated content (e.g., the outline stored separately)

with open("outline.md") as f:
    p["content_hash"] = hashlib.sha256(f.read().encode()).hexdigest()
with open("passport.yaml", "w") as f:
    yaml.safe_dump(p, f)
print("Passport updated with integrity info")
'

```

### Consuming Literature Corpus Entries

Downstream agents read the optional `literature_corpus[]` following the CSL-JSON schema:

```python
import yaml, json

with open("passport.yaml") as f:
    passport = yaml.safe_load(f)

for entry in passport.get("literature_corpus", []):
    # Each entry follows the CSL‑JSON schema

    print(json.dumps(entry, indent=2))

```

## Key Source Files for Implementation

- **[`docs/ARCHITECTURE.md`](https://github.com/Imbad0202/academic-research-skills/blob/main/docs/ARCHITECTURE.md)**: Contains the full stage-by-stage matrix, flow diagrams, and gate definitions governing passport flow
- **[`shared/handoff_schemas.md`](https://github.com/Imbad0202/academic-research-skills/blob/main/shared/handoff_schemas.md)**: Formal definition of Schema 9 (Material Passport) and optional extensions including `compliance_history[]` and `repro_lock`
- **[`scripts/check_repro_lock.py`](https://github.com/Imbad0202/academic-research-skills/blob/main/scripts/check_repro_lock.py)**: Lint script ensuring the `repro_lock` field is present or explicitly `null` before Stage 4.5 completion
- **[`scripts/adapters/folder_scan.py`](https://github.com/Imbad0202/academic-research-skills/blob/main/scripts/adapters/folder_scan.py)**: Example adapter that populates `literature_corpus[]` before the pipeline executes
- **[`academic-pipeline/references/literature_corpus_consumers.md`](https://github.com/Imbad0202/academic-research-skills/blob/main/academic-pipeline/references/literature_corpus_consumers.md)**: Documents the four Iron Rules for consumer-side protocol compliance
- **[`docs/design/2026-04-30-ars-v3.6.7-step-6-orchestrator-hooks-spec.md`](https://github.com/Imbad0202/academic-research-skills/blob/main/docs/design/2026-04-30-ars-v3.6.7-step-6-orchestrator-hooks-spec.md)**: Specifies how `audit_artifact[]` entries are injected after downstream-agent deliverables
- **[`scripts/check_corpus_consumer_protocol.py`](https://github.com/Imbad0202/academic-research-skills/blob/main/scripts/check_corpus_consumer_protocol.py)**: Enforces Iron Rules and prevents unauthorized passport mutations by downstream agents

## Summary

- The **Material Passport** is Schema 9 in the ARS pipeline, functioning as an append-only ledger that tracks every artifact from Stage 1 (Research) through Stage 6 (Process Summary)
- **Mandatory integrity gates** at Stages 2.5 and 4.5 enforce `verification_status: VERIFIED` and refresh `integrity_pass_date` using 7-mode and 100% claim sampling checks respectively
- The **`repro_lock`** block must be present (or explicitly `null`) by Stage 4.5, enforced by [`scripts/check_repro_lock.py`](https://github.com/Imbad0202/academic-research-skills/blob/main/scripts/check_repro_lock.py)
- Only the `academic-pipeline` orchestrator can modify integrity fields; [`scripts/check_corpus_consumer_protocol.py`](https://github.com/Imbad0202/academic-research-skills/blob/main/scripts/check_corpus_consumer_protocol.py) prevents unauthorized mutations by downstream agents
- Optional fields like `literature_corpus[]`, `audit_artifact[]`, and `reset_boundary[]` extend the passport for specific workflow requirements while maintaining backward compatibility

## Frequently Asked Questions

### What happens if the integrity gate at Stage 2.5 fails?

The pipeline **cannot advance** to Stage 3. The `verification_status` remains **UNVERIFIED**, and the user must acknowledge the integrity report and resolve the 7-mode AI-failure checklist items before the system allows progression to the Review stage.

### Can downstream agents modify the Material Passport directly?

No. According to [`scripts/check_corpus_consumer_protocol.py`](https://github.com/Imbad0202/academic-research-skills/blob/main/scripts/check_corpus_consumer_protocol.py) and the Iron Rules in [`academic-pipeline/references/literature_corpus_consumers.md`](https://github.com/Imbad0202/academic-research-skills/blob/main/academic-pipeline/references/literature_corpus_consumers.md), downstream agents are **read-only** consumers. Only the `academic-pipeline` orchestrator can append integrity-related fields such as `verification_status` and `integrity_pass_date`.

### When is the `repro_lock` field required in the passport?

The **`repro_lock`** block becomes mandatory at **Stage 4.5** (Final Integrity). It must be present in the passport or explicitly set to `null` before the second integrity gate completes. The validator [`scripts/check_repro_lock.py`](https://github.com/Imbad0202/academic-research-skills/blob/main/scripts/check_repro_lock.py) enforces this requirement to ensure reproducibility compliance in versions 3.3.5 and later.

### How does the Material Passport handle cross-session resumption?

When the environment variable `ARS_PASSPORT_RESET=1` is set, the passport maintains a **`reset_boundary[]`** ledger that enables cross-session resume capabilities. This optional extension tracks reset boundaries without overwriting existing audit history, allowing researchers to pause and resume long-running academic workflows while preserving the append-only guarantee.