How We Build This

Universal Manifest is built with an intentionally rigorous development methodology. This page explains the three systems that govern how work is planned, executed, and verified — so that contributors understand how to participate and evaluators can assess the project’s maturity claims.

Journey-driven proof model

The project does not consider “docs exist” as proof that something works.

Every major capability is anchored to a user journey — a concrete, end-to-end scenario that demonstrates a real use of the standard. Journeys are not acceptance tests in the traditional sense; they are the project’s “show it works” layer.

What a journey is

Each journey defines:

A human-readable scenario (for example: “Parse a manifest and safely ignore unknown fields”).
Explicit pass criteria that can be verified by running code.
A mapping to an executable test in the proof suite.

The journey list (J01—J11)

The project currently tracks eleven canonical journeys:

ID	Journey	What it proves
J01	Parse and ignore unknown fields	Forward compatibility works
J02	TTL and freshness	Expiration enforcement works
J03	Signature verification (v0.2)	Cryptographic integrity works
J04	UMID resolution	Resolver lookup works end-to-end
J05	Edge-to-display smoke	Reference implementation flow works
J06	Public profile projection	Social profile shard consumption works
J07	RP1 spatial fabric projection	Spatial anchoring shard consumption works
J08	Smart glasses consent enforcement	Consent model enforcement works
J09	Metaverse cross-world projection	Cross-world identity portability works
J10	Multi-provider personhood	Multiple proof-of-personhood providers coexist
J11	OMATrust attestation interoperability	Trust attestation interoperability works

Running the proof suite

Journeys are executable. Run them with:

cd packages/universal-manifest && npm run journeys

The runner produces a JSON report under docs/journeys/_artifacts/ with explicit pass/fail rows for every journey ID.

Why this matters

Journey-driven proof prevents “done by documentation.” A maturity claim is only as strong as the journey evidence that backs it. If a journey fails, the capability it represents is not proven — regardless of how thorough the documentation is.

Done-done framework

Universal Manifest uses a formal, gate-based definition of “done done” that goes beyond “implemented” or “tested locally.”

A release is only done when all required acceptance gates pass with auditable evidence.

Maturity targets

The project tracks three levels of maturity:

Target	Name	Meaning
A	Early-adopter ready	Stable enough for controlled adoption. Non-final areas are documented. Conformance baseline exists.
B	Production-candidate	Strong interoperability evidence. Hardened conformance suite. Reliable governance.
C	World-ready	Broad independent implementation success. Hardened security. Sustainable governance. Low ambiguity.

“World-ready” is Maturity C. It requires at least three independent organizations implementing the spec successfully, with at least two outside the originating ecosystem.

Acceptance gates (G1—G7)

Seven gates must pass for a done-done claim:

Gate	Name	What it checks
G1	Contract completeness	Required fields, semantics, versioning, and extension rules are explicit.
G2	Conformance testability	Valid and invalid fixtures exist. A reproducible harness passes and fails as expected.
G3	Integrity and trust profile	Signature behavior, canonicalization, and verification failure handling are explicit.
G4	Interoperability proof	At least one end-to-end integration path demonstrates real consumption.
G5	Publishing and discoverability	Stable URLs, release process, and newcomer-friendly navigation exist.
G6	Governance and change control	Decisions are logged, breaking changes are classified, and deprecation policy exists.
G7	Operational realism	Local-first assumptions, TTL/cache behavior, and anti-overbuild boundaries are addressed.

For the current early-adopter target (Maturity A), gates G1, G2, G4, G5, G6, and G7 are required. G3 may be staged, but its scope and limitations must be explicitly documented.

Evidence requirements

Every gate claim must map to reproducible, path-addressable, date-stamped evidence that can be reviewed by someone not involved in the implementation. “We tested it” without artifacts is not sufficient.

The project provides a template for evidence packs: docs/DONE-DONE-EVIDENCE-PACK-TEMPLATE.md.

Work order system

All non-trivial work is tracked through work orders (WOs). A work order is a scoped, self-contained unit of work with explicit objectives, acceptance criteria, and validation commands.

Anatomy of a work order

Each work order includes:

Status — NOT_STARTED, IN_PROGRESS, COMPLETED, or BLOCKED.
Priority — P0 (critical) through P3 (nice-to-have).
Objective — What the work achieves.
Scope — What files are created, modified, or removed.
Acceptance criteria — Checkable conditions that define completion.
Validation commands — Reproducible commands that verify the work.
Dependencies — Other work orders that must complete first.

Why work orders matter

Work orders prevent scope creep, make progress auditable, and ensure that every piece of work has clear completion criteria before it starts. They also make it possible for multiple contributors (human or AI) to work in parallel without stepping on each other.

Work orders are stored in docs/workorders/ and indexed for discoverability.

How the pieces fit together

The three systems reinforce each other:

Journeys define what “working” means in concrete, executable terms.
Done-done gates define what “ready for release” means with auditable evidence.
Work orders define what “scoped work” means with clear acceptance criteria.

A typical flow: a work order is created to implement a capability. The work order references the journey that will prove the capability works. When the work is done, the journey passes, and the gate evidence is updated. The done-done claim is only made when all required gates have passing evidence.

How to contribute

Contributions to Universal Manifest follow the work-order-driven workflow:

Read the Contributing Guide for the standard fork-and-PR process.
Check existing work orders in docs/workorders/ to see if the work is already scoped.

Run tests before submitting:

# Validate the spec package
cd packages/universal-manifest && npm test

# Run journey tests
cd packages/universal-manifest && npm run journeys

# Build the site
cd site && npm run build:clean

Follow existing patterns in the codebase. Specification changes require discussion via a GitHub issue before a PR.

The project welcomes contributions of all kinds: spec improvements, fixture additions, integration guidance, documentation, and tooling. The work order system and done-done framework are there to help you succeed, not to create bureaucracy — they ensure that your contribution has clear scope, clear criteria, and clear evidence of completion.

Done-Done — The full done-done definition with gate details.
Decisions — Major project decisions with rationale.
Journeys — The executable proof suite.
Critical Path — The phased execution plan from v0.1 to world-ready.