UCCA Engine — Memory Index¶

Original authoritative map of governing documents, contracts, and decision artifacts from the engine repo. Superseded by the two-site documentation structure (docs.ucca.online + knowledge.ucca.online).

USE RULE¶

Before working on any area of the system, scan the relevant section here and open the linked documents first.

Last updated: 2026-01-05

Documentation Topology (AUTHORITATIVE)¶

The documentation set is intentionally structured into the following top-level domains. All documents referenced below are expected to live under one of these directories.

docs/
├── 00_READ_FIRST__MEMORY_INDEX.md   ← this file (authoritative map)
├── architecture/                   ← system structure, content flow, data shape
├── constitution/                   ← governance, invariants, non-technical authority
├── contracts/                      ← binding contracts (run bundle, generator, content)
├── education/                      ← education model, levels, sequencing
├── engine/                         ← ENGINE DOCTRINE (constitutional, immutable)
├── generator/                      ← generator contracts, prompt rules, quality specs
├── handovers/                      ← thread transitions and resumption briefs
├── in_camera/                      ← design exploration (non-binding, contextual)
├── meta/                           ← human / AI collaboration context (non-operational)
└── operations/                     ← how the system is run day-to-day

Directory Intent Rules (NON-NEGOTIABLE)¶

Directory	Intent
`engine/`	Constitutional engine doctrine. Immutable. Highest authority. Overrides all architecture, contracts, workflows, and implementations.
`constitution/`	Organisational governance and legal/strategic constitution. Does not override engine doctrine.
`contracts/`	Binding rules. If violated, the system is wrong.
`operations/`	How to run, validate, debug, recover, and operate the system today. Includes authoritative upstream data source definitions and reconciliation notes.
`architecture/`	Structural explanations (how pieces fit together), not rules.
`generator/`	Generator behavior, contracts, and content-quality enforcement.
`education/`	Learning model, levels, sequencing, and pedagogical intent.
`handovers/`	Thread continuity. Always consult before resuming work.
`in_camera/`	High-signal thinking notes. Useful context, never authoritative.
`meta/`	Descriptive, human-read context explaining how the system and collaboration patterns emerged. Never authoritative. Never operational.

Rule

If you create a new document and cannot clearly justify which directory it belongs in, stop and decide before writing it.

Constitutional Engine Documents (AUTHORITATIVE — READ FIRST)¶

The following documents define the immutable principles of the UCCA Engine. These documents are normative, not descriptive. They take precedence over all architecture, contracts, workflows, generators, and code.

docs/engine/ENGINE_DOCTRINE.md — Defines what the engine is and what must never change.
docs/engine/ENGINE_NON_GOALS.md — Defines what the engine will never attempt to do.
docs/engine/ENGINE_RATIONALE.md — Historical and philosophical context only. Non-authoritative. Does not override doctrine.

If you have not read these documents, do not modify the engine.

1. Golden Path and Operating Procedures¶

docs/operations/01_GOLDEN_PATH.md — Canonical workflow
docs/operations/PIPELINE_WORKFLOW.md — Pipeline behavior, run/export conventions, flags
docs/operations/02_CODE_ORIENTATION.md — Where things live in the codebase
docs/operations/SYSTEM_STATE.md — What is assumed to be true about the system right now
docs/operations/ARTIFACT_POLICY.md — What belongs in runs, what gets committed, what must not drift
docs/operations/REMOTE_PREVIEW.md — Remote preview workflow and expectations
docs/operations/PROJECT_RECOVERY.md — Primary continuity and takeover guide
docs/operations/BOOTSTRAP.md — Clean machine setup checklist
docs/operations/TGA_DATA_SOURCES.md — Authoritative upstream sources and scope
docs/operations/tga_sync_reconciliation_v0.md — Reconciliation notes for TGA exports

2. Run Bundles and Contracts¶

docs/contracts/RUN_BUNDLE_CONTRACT_v1.md — Baseline / historical reference
docs/contracts/RUN_BUNDLE_CONTRACT_V2__FREEZE.md — Current authoritative run bundle contract
docs/contracts/RUN_RESOLUTION_v1.md — Authoritative, deterministic run type resolution contract
docs/contracts/RUN_RESOLUTION_v1_APPENDIX.md — Clarification appendix
docs/contracts/RUN_RESOLUTION_v0.md — Historical reference only (superseded)

3. Generator Contract and Content Quality¶

docs/generator/GENERATOR_CONTRACT_v0.md — Design-only contract governing truthful generation
docs/contracts/course_content_contract.md — Course-level content expectations

4. Architecture and Content Flow¶

docs/architecture/content_flow.md
docs/architecture/AU_Reversibility_Guardrails.md

5. Education Model¶

docs/education/00_EDUCATION_MODEL__working.md

6. In-Camera Design Notes¶

docs/in_camera/run_bundle_v2_overview.md
docs/in_camera/run_bundle_v2_batch_wrapper.md
docs/in_camera/run_bundle_v2_batch_units_design.md
docs/in_camera/preview_golden_path.md
docs/in_camera/preview_human_reading_contract.md
docs/in_camera/generator_contract_v0.md
docs/in_camera/FUTURE_ARCHITECTURE_NOTES.md
docs/in_camera/content_quality_cq01_orientation_100_level.md

7. Meta / Human-AI Collaboration¶

docs/meta/AI_COLLABORATION_MODEL.md
docs/meta/THREAD_STATE_TRANSITION_PROTOCOL.md

8. Handovers¶

docs/handovers/00_READ_FIRST__thread_transition_*.md — Authoritative transition briefs
docs/handovers/01_REFERENCE__thread_snapshot_*.md — Supporting technical snapshots

9. Organisational Constitution¶

docs/constitution/UCCA_Constitution_v0.13.docx

Quick "What Do I Open?" Cheat Sheet¶

Task	Document
Engine invariants	`docs/engine/ENGINE_DOCTRINE.md`
Running pipeline / validating	`docs/operations/01_GOLDEN_PATH.md`
Run bundle rules	`docs/contracts/RUN_BUNDLE_CONTRACT_V2__FREEZE.md`
Run resolution semantics	`docs/contracts/RUN_RESOLUTION_v1.md`
Upstream data sources / sync scope	`docs/operations/TGA_DATA_SOURCES.md`
Generator behavior	`docs/generator/GENERATOR_CONTRACT_v0.md`
Resume work	Latest `docs/handovers/00_READ_FIRST__thread_transition_*.md`

End of 00_READ_FIRST__MEMORY_INDEX.md

Version History¶

Version	Date	Change	Author
1.0	2026-03-11	Archived from engine/ucca-engine/docs/00_READ_FIRST__MEMORY_INDEX.md	Claude Code