Migration and Lifecycle Conventions

Package provenance — this chapter ships with the Ontology & Structure Engine. Provenance tag: source-ontology-project. When loaded into a new world, grep the tag to find the engine's templates and instructions.

The other chapters say how to build content on this engine. This one says how to change the system itself: migrate a world onto the engine, retire types cleanly, keep the knowledge index honest, and run bulk multi-file work without corrupting shared documents. These rules are the post-mortem of a large production conversion — a ~1,350-file cyberpunk world rebuilt onto this engine, where every rule below was learned from a failure that cost a round trip, a corrupted document, or a re-do.

Era and truth discipline

Migrations copy claims, and copies drift. Every claim you write carries era and canonLevel; legacy-era content is never quoted as fact. An overturned claim is marked retconned with a note of its replacement — never deleted. A converted world is a record of belief over time, not a snapshot.

Package provenance

Every file this engine creates, or reworks from a base world, carries the provenance tag source-ontology-project. The tag is the engine's footprint: it lets a later session differentiate engine-owned content from the base system's native files, count what has been rebuilt, and verify a merge. It is a query surface, not a trigger — merging runs on demand, never automatically (see Ingesting External Content).

Slug verification

Slugs are derived from file names, and there is no canonical reference list to check them against. Before writing any reference, list the target folder and confirm the slug:

• An explicit designator keeps its dash: the file "Militech M-10AF Lexington" slugifies to militech-m-10af-lexington, not militech-m10af-lexington.
• After a migration, every slug lookup must resolve to exactly one file. If it does not, you have a retire-then-relocate violation.

Retire-then-relocate

The standard retirement step is: rename the type → move its files to an archive tree → migrate. Retiring a type but leaving its files in live folders is the root cause of ambiguous slug lookups: the slug resolver matches by slug, and two files with the same display name in the same folder produce the same slug.

• After a type is retired, move its files to /Legacy/<domain>/ (preserving nesting underneath), or delete them only with explicit user approval.
• The archive tree keeps the content retrievable; live folders hold only canonical files.

No-draft-refs rule

A reference field whose target domain is empty saves as an unresolved draft — graceful, and invisible. Never create one:

• Either point the field at a real, populated type, or drop it.
• Record known-empty domains in the Knowledge-Index type lifecycle registry so the next session knows without probing.
• Run a reference-integrity check at the end of every phase.

Single-writer documents

The knowledge index and the handbook chapter lists are shared documents with no merge protection. Parallel edits to them can report success and silently not stick ("No changes detected"). Rule: one edit pass per phase, applied sequentially, never in parallel.

Subagent contract

Handbook chapters, /project.json, the knowledge index, and file-type configs are main-agent commits. Subagents research and return full drafts; the main agent applies them. Publishing this contract where agents read it (bulk-work playbooks, this chapter) is what prevents a round trip of eight workers discovering the rule by failing.

Type lifecycle registry

The Knowledge-Index carries a registry of every type: slug, display name, status (canonical / retired / demo), extension, and whether the slug still carries a migration artifact (-1). Consult it before targeting a type. A retired slug is never referenced. Demo-ness is expressed at the file level (the example tag).

Knowledge-Index self-verification

The index is the retrieval map. It stays verifiable in one pass:

• Exact file names per folder.
• Counts that reconcile with ls.
• The type-lifecycle registry.
• Lean: map + counts + names, not prose.

Out of scope — file, don't hack

These need platform engineering, not content workarounds: native type lifecycle, concurrency-safe shared documents, a published subagent capability contract, archived/live slug resolution, auto-generated ontology maps, migration wizards, and enum-extension UX. If the platform cannot do it, record the need and work around it only as far as the conventions above allow.

Verification

A migration replay passes when: no slug lookup is ambiguous; the registry audit greps clean of retired slugs and reconciles with ls; the reference-integrity check is clean at phase end; the tag plan that the merge intends is stamped (logs must show the provenance tag count and the raw lookups); and handbook and index edits produce no concurrency errors.