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

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, this optional field appears as an input port populated by user adapters such as 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, 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.

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 §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.

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 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:

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:

# 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:

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: Contains the full stage-by-stage matrix, flow diagrams, and gate definitions governing passport flow
• 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: Lint script ensuring the repro_lock field is present or explicitly null before Stage 4.5 completion
• scripts/adapters/folder_scan.py: Example adapter that populates literature_corpus[] before the pipeline executes
• 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: Specifies how audit_artifact[] entries are injected after downstream-agent deliverables
• 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
• Only the academic-pipeline orchestrator can modify integrity fields; 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 and the Iron Rules in 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}