Skip to content

0011. Manifest-based consumption contract for course content

Status

Accepted (backfilled 2026-07-31; canonical in aptitude-course CONSUMPTION.md, its issue #22, and adepthood epic #388).

Context

The Adepthood app consumes the APTITUDE curriculum from the aptitude-course repo, but that repo is also a working authoring space — Google-Docs exports, backups, prompts, and per-stage TOCs churn freely. The app integrating against raw paths would turn every content reorganization into an app breakage.

Decision

Define a strict published surface: the app vendors a pinned commit (the SHA in the app's CONTENT_VERSION) and within it may rely on exactly three things — manifest.json (generated by scripts/build_manifest.py, validated against schema/manifest.schema.json, carrying a semver schema_version), the Markdown bodies the manifest references, and the assets those bodies reference. Everything else is internal and may change without notice. Reads go through the manifest (never globbing markdown/**), and identity is the manifest id/slug, not the path.

Consequences

  • Content authors refactor freely behind the manifest; the app is structurally unable to depend on internals (if it reads an uncontracted file, that is an app bug by definition).
  • Versioning is explicit: schema evolution rides schema_version (1.1.0 added stage_intros[]), and content updates are deliberate pin bumps rather than silent drift.
  • Drip-feed pacing is data, not app logic — each chapter's release_day drives the 36-week schedule.
  • The pattern generalizes: the docs-sync watermark file and the graph release manifests in this ecosystem follow the same "machine-readable contract, everything else internal" instinct.