Governed Legacy Documentation Transfer to Docusaurus

1. Purpose

This page is the canonical working procedure for transferring legacy ZAYAZ documentation into Docusaurus.

It is intentionally written as a handover reference for future ChatGPT / ZAYAZ Architect sessions as well as for human contributors. When a conversation reaches its context limit, a new session should be able to read this page, inspect the current repository state, receive the relevant legacy source chapter, and continue the migration without rediscovering the process or silently reverting to obsolete architectural assumptions.

The goal is not to copy the old manual into MDX. The goal is to convert legacy material into current, governed, implementation-ready ZAYAZ specifications while preserving useful historical knowledge and rejecting obsolete architecture.

The expected result is documentation that can safely act as canonical input to:

Docusaurus;
ZARA and semantic search;
Hecate Need Creator;
Jira implementation orchestration;
OMR and architectural lineage;
MICE / engine registries;
SSSR and signal governance;
schema and constitutional validation;
code review and implementation review;
evidence, trust, replay and audit systems.

2. Constitutional authority and source precedence

Migration is governed by the current CONSTITUTION_MANIFEST.yaml. Do not use one unconditional source order for every kind of conflict.

Before modifying canonical documentation, load the constitutional context required by the manifest, including the platform, ontology and documentation constitutions. Higher constitutional authority constrains lower authority, and conflicts must be escalated rather than silently resolved.

2.1. Cross-cutting invariants

For identity, ontology, governance, graph semantics, constitutional metadata and other cross-cutting invariants, use the manifest's constitutional precedence:

ZAYAZ Constitution
Applicable domain constitution, including the Ontology or Documentation Constitution where relevant
Approved constitutional ADR
Canonical Docusaurus specification
Supporting GitHub documentation and machine-readable sources
Legacy manual
Historical draft

2.2. Detailed component behavior

For detailed behavior of a specific architectural object, use the manifest's detailed-component profile:

Canonical Docusaurus specification
Applicable domain constitution
Approved architectural ADR
Supporting GitHub documentation and machine-readable sources
Legacy manual
Historical draft

A canonical Docusaurus specification therefore defines detailed runtime behavior, but it may not weaken or silently contradict a higher constitutional invariant.

The legacy PDF is an input source, not an authority over current architecture. A migration must never overwrite a newer governed concept merely because the legacy manual uses an older model.

If sources conflict:

determine whether the conflict concerns a cross-cutting invariant or detailed component behavior;
apply the corresponding manifest precedence profile;
preserve still-valid intent and source detail;
do not silently preserve an obsolete interface, boundary, identifier or data contract;
stop and report a genuine unresolved constitutional conflict rather than choosing a convenient interpretation;
use a governed TODO only for unresolved implementation or migration debt that does not itself require a constitutional decision.

3. Mandatory first step for a new AI session

Before drafting or rewriting a migrated page, the assistant must inspect the current repository state. Do not rely only on remembered conventions from a previous chat.

At minimum, inspect the files relevant to the document class being migrated.

3.1. General constitutional and documentation references

Purpose	Canonical repository reference
Constitution loading order and authority model	`content/architecture/constitutions/CONSTITUTION_MANIFEST.yaml`
Platform constitution	`content/architecture/constitutions/ZAYAZ_CONSTITUTION.mdx`
Ontology taxonomy and relationships	`content/architecture/constitutions/ONTOLOGY_CONSTITUTION.mdx`
Documentation constitution	`content/architecture/constitutions/DOCUMENTATION_CONSTITUTION.mdx`
Constitutional documentation lint configuration	`config/docs-lint.yaml`
Constitutional Metadata Standard	`content/standards/cms/cms.mdx`
Documentation guidance	`content/system-info/documentation-guidelines.mdx`
Official Module Registry	`config/system/omr.modules.json`
Registered document identities / graph targets	`config/system/acronyms.json`
Controlled architectural tags	`config/system/tags.json`
Package scripts / current validation commands	`package.json`

The current constitutional lint requires, at minimum, the base Constitutional Header fields declared in config/docs-lint.yaml. At the time of this version these include id, title, version, and status, but the configuration file is authoritative and must be re-read when work resumes.

Relationship fields such as related, depends_on, interfaces_with and governed_by must use registered canonical IDs when the governing schema/consumer expects document identities. Do not substitute Docusaurus route strings for registered graph identities.

Tags are controlled vocabulary. Resolve new values through config/system/tags.json; do not invent convenient tags in frontmatter.

3.2. MICE-specific references

For Micro-Engine work, inspect at least:

Purpose	Canonical repository reference
MICE overview and architecture	`content/computation-hub-calcs/micro-engines/micro-engines.mdx`
Current Micro-Engine reference structure	`content/computation-hub-calcs/micro-engines/reference-template.mdx`
Generated / governed engine-profile examples	`code/engine-profiles/`
MICE registry generator	`scripts/generate-mice-registry.mjs`
Micro-engine registry generation / import	`scripts/generate_micro_engine_registry_json.mjs`, `scripts/import_micro_engine_registry.mjs`
Canonical ID architecture / MEID context	`content/key-zayaz-features/zar-artifact-framework/canonical-id-arch.mdx`

Do not copy an old MICE frontmatter example merely because it appears in a legacy chapter. Compare it with the current MICE reference page, the Ontology Constitution and the current validation/generator logic first.

3.3. Hecate references

Before declaring a migrated specification implementation-ready, inspect:

Purpose	Canonical repository reference
Hecate Need Creator specification	`content/architecture/hecate-need-creator.mdx`
Need creation handler / PR behavior	`scripts/hecate/create-need-handler.ts`
Hecate audit scripts and commands	`scripts/hecate/`, `package.json`
Operational Jira Needs view	`content/system/needs.mdx`

Jira is the implementation orchestration plane. It does not become the architectural source of truth. The canonical specification remains in Docusaurus, constrained by applicable constitutional authority.

3.4. Snippet and associated-file references

Before embedding or linking code, inspect:

Purpose	Canonical repository reference
Snippet renderer	`docusaurus/src/components/Snippet.jsx`
Snippet manifest generator	`code/tools/generate-snippet-manifest.mjs`
Snippet preflight validation	`scripts/preflight-snippets.cjs`
Associated-file conventions	`code/README-Code.md`
Associated files root	`code/associated-files/`

4. ZAYAZ ontology rule during migration

The migration must preserve the architectural taxonomy defined by ONTOLOGY_CONSTITUTION.mdx. Do not collapse engines, services, registries or workflows into the Component type merely because they are implementation units.

4.1. Canonical architectural types

Module — the highest functional domain. A module organizes related constitutional capabilities and does not execute logic.
Component — a constitutional building block belonging to exactly one module. A component provides a capability and may expose services, APIs, workflows, engines or registries.
Engine — performs deterministic or governed execution: it consumes inputs, executes logic and produces governed outputs.
Service — exposes capabilities to other components and orchestrates without redefining constitutional behavior.
Registry — manages constitutional identities and does not execute business logic.
Workflow — coordinates execution across multiple components while individual components retain responsibility.
Artifact — an immutable constitutional output with identity, lineage, provenance, replay characteristics and governance.

Other governed architectural types may exist in applicable constitutions or canonical specifications. Use the exact registered/constitutional type rather than forcing an object into one of the types above.

The canonical containment spine defined by the Ontology Constitution is:

Module
   │
contains
   ▼
Component
   │
contains / exposes as constitutionally defined
   ▼
Engine / Service / Registry / Workflow
   │
produces
   ▼
Artifact

The Constitution explicitly defines Module → Component → Engine → Artifact as the core relationship and separately defines services, registries and workflows. A migration must preserve those distinctions in prose, frontmatter, registries and graph lineage.

4.2. Migration classification procedure

For every migrated architectural object:

Identify its Module from the current Official Module Registry.
Identify the owning Component when the object is an Engine, Service, Registry or Workflow.
Classify the object by its actual constitutional type.
Preserve parent/containment and supported graph relationships without inventing undocumented relationship types.
Preserve stable object identity separately from documentation identity and route identity.
If the current canonical sources do not establish the owning component or type, stop and flag the classification for architectural review rather than guessing.

Pergamum Pulse and other graph/lineage consumers should preserve the available lineage at each governed level—for example Module → Component → Engine—rather than flattening all executable or supporting objects into a single component bucket.

4.3. MICE / Micro-Engine classification

A Micro-Engine is an Engine under the Ontology Constitution, not automatically a Component. Its MICE/MEID identity identifies the engine; its owning Component and Module must be resolved from current canonical architecture and registries.

For a MICE migration:

do not assume the documentation folder determines the owning Component;
do not assume every Micro-Engine is directly owned by the Computation Hub module without an intervening Component;
use omr_module_ids only for valid module identity from OMR;
preserve MEID / MICE engine identity separately;
preserve the owning Component relationship when current canonical sources establish it;
never create a new module or component merely to satisfy validation.

Example module metadata, when the current OMR and owning architecture establish Computation Hub as the module:

omr_module_ids:
  - computation-hub

That field establishes module lineage only. It does not by itself establish the Component or Engine identity.

5. Migration unit: one golden specimen first, then small coherent batches

When beginning a new documentation family, migrate one representative document first and make it the golden specimen.

For MICE, the recommended sequence is:

Select one representative Micro-Engine chapter from the legacy manual.
Produce a fully governed current MDX specification with explicit Module → Component → Engine lineage where established.
Add / link associated implementation artifacts.
Pass Hecate-readiness review.
Pass schema, constitutional, registry, snippet and build validation.
Pass human / AI code and architecture review.
Merge it.
Use the successful page as a structural pattern for the next batch without copying identifiers or relationships blindly.

After the golden specimen is established, migrate approximately 3–6 related Micro-Engines per PR.

Avoid a single long-lived branch containing 20–30 engines. Large branches become stale against main, make review difficult, and allow one broken engine to block many valid migrations.

Recommended branch pattern:

docs/mice-carbon-engines
docs/mice-energy-engines
docs/mice-batch-01
docs/mice-batch-02

6. Per-document migration workflow

Phase A — Receive and understand the legacy source

The input will often be one PDF chapter describing a Micro-Engine or another ZAYAZ architectural object.

The assistant should:

extract the architectural intent;
identify what appears historical or obsolete;
compare the chapter with current Docusaurus concepts, constitutions, registries, schemas and adjacent objects;
distinguish facts actually supported by the legacy source from current architecture supported by the repository;
preserve useful algorithmic, mathematical, data-model and governance detail;
never invent missing canonical identifiers, ownership, tables, signals, evidence paths or policies.

The resulting MDX should be a current specification, not a transcription.

Phase B — Reconcile with current architecture

First establish the object's constitutional type and lineage. For an Engine this means, where known:

Module → Component → Engine

Then review the proposed object against, where applicable:

module boundary and OMR identity;
owning component boundary;
Engine / Service / Registry / Workflow classification;
current MICE categories and MEID conventions for Micro-Engines;
input/output contracts;
current tables and foreign-key relationships;
CMID / metric identities;
SSSR signal registry and signal lineage;
policies and governance;
evidence and provenance;
TrustGate and replay requirements;
ZAR artifact interactions;
dependencies and interfaces;
APIs and callable interfaces;
security and data classification;
deterministic vs probabilistic behavior;
confidence / uncertainty treatment;
lifecycle and versioning.

If the old manual proposes architecture that no longer fits, update the description to the current model and record unresolved gaps explicitly. Do not promote a legacy label into a constitutional Component, Module or relationship without current authority.

Phase C — Build the Constitutional Header / frontmatter

Do not use a stale copied frontmatter block as the authority.

Start from the current document-family reference template and validate against current constitutional, registry and generator expectations.

At minimum verify:

canonical document id;
semantic_id where required / established;
clear title and description;
canonical slug;
correct source_file;
correct hub;
resolvable omr_module_ids for module lineage;
document version;
document status;
owner / audience / security metadata as required by current conventions;
correct classification / ontology metadata for the architectural object;
registered IDs in relationship fields rather than route strings where required;
controlled tags resolved through config/system/tags.json;
MICE / MEID metadata when the object is a Micro-Engine;
Jira linkage only where a valid governed linkage exists;
graph metadata when used by the surrounding document family.

Important distinctions:

document identity is not architectural object identity;
module identity is not component identity;
component identity is not engine identity;
document lifecycle and architectural-object lifecycle are separate concepts;
a nested object status must not be assumed to satisfy a top-level constitutional document status field.

Phase D — Structure the implementation specification

A MICE specification should be detailed enough that Hecate Need Creator can derive implementation work without guessing architecture.

Where applicable, explicitly specify:

Purpose and bounded responsibility
Constitutional type: Engine
Module → Component → Engine lineage
Canonical document identity and MEID / engine identity
Inputs
Outputs
Input validation
Core algorithm / equations / decision logic
Units and dimensional rules
Data quality expectations
Canonical data sources
Tables / persistence dependencies
Foreign keys and relationships
CMIDs / metrics affected
Signals consumed
Signals emitted
SSSR relationships
Policies and governance constraints
Evidence / provenance requirements
TrustGate implications
Failure and exception behavior
Confidence / uncertainty behavior
Determinism and replay requirements
API / runtime interface where applicable
Security and classification requirements
Observability / logging requirements
Associated implementation artifacts
Test expectations
Acceptance criteria
Known limitations
Open governed TODOs

Not every engine requires every subsection. Omit irrelevant sections rather than filling them with invented boilerplate.

7. Hecate-readiness rule

The final review question for every migrated implementation specification is:

Could Hecate Need Creator create a bounded, testable implementation Need from this page without inventing architecture?

A document is not fully Hecate-ready if a developer would still have to guess any critical item such as:

the constitutional type;
the Module → Component → Engine ownership chain;
the intended input contract;
the expected output contract;
the canonical table or signal;
the acceptance condition;
the evidence requirement;
the policy constraint;
the error behavior.

If the documentation is structurally valid but implementation intent is still insufficient, use the additional governed marker:

This means:

The page may be architecturally valid, but an implementation contract or acceptance criterion still requires clarification before Hecate should create an implementation Need from that section.

Do not use HECATE TODOs as a substitute for writing clear acceptance criteria when the information is already available.

8. Governed TODO markers

TODO markers are first-class migration debt markers. They are used when a required relationship or contract cannot yet be resolved without guessing.

To avoid this reference page itself being detected as containing live TODO debt, the examples below are HTML-escaped. In a migrated MDX page, use the normal HTML-comment form.

Marker to use in migrated page	Meaning
`<!-- ZAYAZ-TODO: STRUCTURE -->`	Structural / architectural review still required
`<!-- ZAYAZ-TODO: ADD-CMID -->`	Metric identity is not yet canonical
`<!-- ZAYAZ-TODO: ADD-FK -->`	Foreign key / table relation is missing or unresolved
`<!-- ZAYAZ-TODO: LINK-SSSR -->`	SSSR / signal-registry linkage is missing
`<!-- ZAYAZ-TODO: DATA-SOURCE -->`	Authoritative underlying data source is not identified
`<!-- ZAYAZ-TODO: EVIDENCE -->`	Evidence / audit lineage is incomplete
`<!-- ZAYAZ-TODO: POLICY -->`	Governed policy relationship is unresolved
`<!-- ZAYAZ-TODO: HECATE -->`	Hecate implementation contract / acceptance detail is incomplete

Add a concise explanation after the tag when useful. Example, written here in escaped form:

&lt;!-- ZAYAZ-TODO: ADD-FK | Confirm dim_countries.iso_cc_id -> fact_emissions.country_id --&gt;

Rules for TODOs

Never guess a CMID merely to remove ADD-CMID.
Never invent a foreign key merely to remove ADD-FK.
Never assign an arbitrary SSSR signal merely to remove LINK-SSSR.
Never write “source: internal database” if the authoritative data source is unknown.
Never invent evidence requirements merely to make a document look complete.
Never create a policy relationship without a real governed policy.
Never use a TODO to bypass an unresolved constitutional conflict.
Never treat a TODO as acceptable permanent architecture; it is explicit debt that must remain discoverable.

To find live TODO debt from the repository root:

grep -R "<!-- ZAYAZ-TODO:" content/

9. Code and associated-file policy

Large or implementation-significant code blocks should not be maintained as duplicate canonical copies inside narrative MDX when they belong as governed implementation artifacts.

For each MDX document, use the corresponding associated-files path where appropriate.

Canonical path mapping:

content/computation-hub-calcs/micro-engines/example-engine.mdx
↓
code/associated-files/computation-hub-calcs/micro-engines/example-engine/

Store appropriate artifacts there, for example:

TypeScript / JavaScript;
Python;
SQL / DDL;
JSON / JSON Schema;
YAML rulesets;
test fixtures;
API payload examples;
deterministic reference vectors;
pseudocode only when it is deliberately a governed artifact rather than executable code.

Then render the canonical artifact through the repository Snippet mechanism rather than copying it into the MDX.

A live Snippet element is only valid when its associated file exists and resolves through the current manifest/preflight logic. In documentation that merely explains Snippet syntax, do not place a fake <Snippet ... /> element inside a fenced example because the current preflight scanner may still interpret it as a live reference. Prefer a non-element textual representation or an example backed by a real associated file.

Before PR merge, run / require snippet validation using the current repository scripts. At the time of this version the package includes:

npm run preflight-snippets
npm run snippets:gen

Do not hard-code /workspaces/zayaz-docs paths into canonical generated artifacts or portable scripts unless a specific development-container contract explicitly requires it.

10. Grounding pass after each small batch

After approximately 3–6 related pages, stop migrating new content and perform a grounding pass.

For each page, verify:

constitutional type;
module lineage;
owning component identity where applicable;
engine/service/registry/workflow identity where applicable;
MEID / MICE metadata for Micro-Engines;
CMIDs;
table references;
foreign keys;
data-source authority;
SSSR links;
emitted and consumed signals;
policies;
evidence requirements;
trust / replay implications;
registered relationship IDs;
controlled tags;
associated files;
cross-document links;
open TODO markers.

This prevents the migration from becoming a prose dump that must be re-read months later to reconstruct the intended graph relationships.

11. Git branch and PR workflow

Do not routinely write migration content directly to main.

11.1. Start from current main

git switch main
git pull origin main

11.2. Create a logical working branch

git switch -c docs/mice-carbon-engines

The branch name can be chosen by the contributor, but use descriptive and consistent names. Good patterns include:

docs/mice-carbon-engines
docs/mice-energy-engines
docs/mice-batch-01
fix/mice-registry-lineage

11.3. Commit the coherent change

git add content/computation-hub-calcs/micro-engines
git add code/associated-files/computation-hub-calcs/micro-engines
git commit -m "docs(mice): migrate carbon micro-engine specifications"

11.4. Push the branch

git push -u origin docs/mice-carbon-engines

The first push creates the corresponding branch on GitHub; the branch does not have to be created manually in the GitHub UI first.

11.5. Open a PR to `main`

The PR is the governed quality boundary.

Expected flow:

Legacy source
    ↓
Constitutional loading + architecture reconciliation
    ↓
Canonical MDX + associated artifacts
    ↓
Working branch
    ↓
Pull Request
    ↓
Schema / constitutional / registry / build / snippet validation
    ↓
Greptile / Codex / human review where configured
    ↓
All required checks green
    ↓
Merge to main
    ↓
Docusaurus becomes canonical for detailed behavior

After a batch is merged, create the next branch from the newly updated main rather than continuing indefinitely on an old migration branch.

12. PR validation expectations

The exact GitHub required checks are controlled by current workflows and repository rulesets and may change. A future session must inspect the current .github/workflows/, repository rulesets and package.json rather than assuming this list is exhaustive.

For MICE migration, expect validation of at least the following classes:

Documentation / constitutional integrity

constitutional header requirements;
MDX syntax;
frontmatter correctness;
canonical IDs;
slugs and source paths;
required status/version metadata;
documentation hygiene;
constitutional precedence and conflict handling.

Ontology / registry integrity

valid OMR module IDs;
correct Module → Component → Engine lineage;
correct distinction between Component, Engine, Service, Registry and Workflow;
MICE / MEID registry compatibility;
registered acronym/document relationship references;
controlled tags;
graph and relationship integrity.

Code / snippet integrity

associated files exist where referenced;
Snippet references resolve;
illustrative syntax does not accidentally become a live preflight reference;
generated snippet manifest remains coherent;
code examples are reviewed as code, not merely as prose.

Architecture and implementation readiness

inputs/outputs are bounded;
algorithms are sufficiently specified;
no unsupported legacy interfaces are carried forward;
no guessed module/component/engine ownership, CMIDs, signals, policies or evidence paths;
Hecate can create implementation work without architectural invention.

Build / generated-artifact integrity

Docusaurus builds;
generated artifacts are not stale;
generators should preferably detect drift and update through bot branch / PR flows rather than race to push directly to main.

13. Recommended local preflight before pushing

Use the repository's current scripts rather than an obsolete copied command list. At the time of this version, useful checks include:

npm run preflight-snippets
npm run docs:extract-modules
npm run hecate:audit:local
npm run gen:mice-registry
npm run generate:micro-engine-registry
npm run generate-graph
npm run build

Some commands generate files. Review the resulting diff before committing it; do not blindly commit generated changes that are unrelated to the migration.

npm run build already composes several validation and generation steps. The exact package scripts are authoritative.

14. Migration quality rules

14.1. Precision before completeness

It is better to have an explicit TODO than a fabricated relationship, except where the uncertainty is a constitutional conflict—in that case stop and escalate.

14.2. Do not preserve legacy terminology when the canonical ontology changed

Keep useful historical terminology as an alias or explanatory note only when it helps readers and does not create a second architecture.

14.3. Preserve architectural type distinctions

Do not use Component as a generic synonym for Engine, Service, Registry, Workflow or other architectural objects. Determine and record the exact constitutional type and its ownership/containment lineage.

14.4. Do not confuse identity domains

A page id, a Module ID, a Component ID, an Engine/MEID, a CMID, a signal ID, a table ID and a Jira issue are different identity domains unless a governed contract explicitly maps them.

14.5. Do not infer module or component status from folder names

OMR determines valid Module identity. Component ownership and lower-level object classification must come from current canonical architecture/registries, not directory placement.

14.6. Keep lineage explicit

For a Micro-Engine, preserve Module → Component → Engine lineage when established. The MICE folder and MEID identify documentation/runtime concerns but do not replace the constitutional ownership chain.

14.7. Treat data relationships as architecture

Tables, FKs, source authority, evidence, signals and CMIDs are not cosmetic documentation links. They define machine-consumable semantics and must be reviewed accordingly.

14.8. Use registered graph identities and controlled vocabulary

Resolve relationship targets through the current identity registry and tags through the controlled tag registry. Do not introduce route strings or ad hoc vocabulary into machine-consumed frontmatter when registered IDs are required.

14.9. Separate current fact from planned capability

A legacy document may describe an intended future capability as if implemented. The migrated page must distinguish:

implemented / active;
specified;
planned;
experimental;
deprecated;
unresolved.

Use the current governed lifecycle vocabulary rather than inventing new statuses.

15. AI handover checklist for a future chat

When a new chat continues migration work, the user can point the assistant to this page and provide the next legacy source chapter.

The assistant should then follow this sequence:

Read this page.
Inspect the latest main branch.
Load CONSTITUTION_MANIFEST.yaml and the constitutions required for the change.
Read the current MICE reference page/template if migrating a Micro-Engine.
Read config/docs-lint.yaml, CMS, current schema and registry contracts.
Read config/system/acronyms.json, config/system/tags.json and OMR for controlled identities/vocabulary.
Read Hecate Need Creator requirements.
Inspect adjacent current Docusaurus pages for terminology and architecture.
Read the legacy PDF chapter as source material.
Identify conflicts between legacy and current architecture and classify them by the manifest precedence profile.
Determine the exact architectural type and ownership lineage; for a Micro-Engine, resolve Module → Component → Engine where current sources support it.
Draft a current implementation-grade MDX specification.
Preserve valid source detail; clearly distinguish unsupported or unresolved detail.
Apply TODO markers instead of guessing, except for constitutional conflicts which must be escalated.
Create / identify associated implementation files and valid Snippet references.
Verify OMR module identity, owning component and lower-level object identity separately.
Verify registered relationship IDs and controlled tags.
Verify Hecate readiness and acceptance criteria.
Run or reason against current validation gates.
Add the work to the current migration branch / PR, not directly to main, unless an explicit exception is approved.
Review CI and PR comments and fix the canonical source, not merely the symptom.
Merge only when required validation is green and blocking review findings are resolved.

Required mindset for the assistant

The assistant is not a transcription service. It acts as an architecture reviewer and migration engineer.

For every migrated architectural object, ask:

What is its exact constitutional type?
What Module owns the capability?
If this is an Engine, Service, Registry or Workflow, what Component owns/exposes it?
Is this still true?
Is this still the correct architecture?
Is this identifier canonical and in the correct identity domain?
Does this relationship use a registered ID?
Is this tag controlled vocabulary?
Does this table actually exist?
Does this FK actually exist?
Does this CMID actually exist?
Does this signal actually exist?
Is this policy actually governed?
Is the data source authoritative?
Is the evidence path sufficient for audit?
Could Hecate implement this without guessing?
Would the implementation be replayable and testable?

If any answer is uncertain, investigate the current repository or mark the gap explicitly. Do not fabricate architectural certainty.

16. MICE migration completion checklist

Before considering one migrated Micro-Engine complete:

Canonical documentation

Current MDX exists in the correct Docusaurus location.
Constitutional Header passes current requirements.
Source precedence was applied according to CONSTITUTION_MANIFEST.yaml.
id, slug and source path are correct.
OMR Module ID resolves.
Relationship fields use registered IDs where required.
Tags use controlled values.

Ontology and identity

The object is classified as an Engine, not generically as a Component.
Owning Module is established.
Owning Component is established, or the unresolved ownership is explicitly escalated rather than guessed.
Module → Component → Engine lineage is preserved where established.
MEID / MICE identity is correct.
Documentation ID, Module ID, Component ID and Engine/MEID are not conflated.

Architecture

Inputs and outputs are explicit.
Algorithm / logic is sufficiently specified.
Units and validation rules are explicit.
Tables and FKs are confirmed or marked TODO.
CMIDs are confirmed or marked TODO.
Signals are confirmed or marked TODO.
Policies are confirmed or marked TODO.
Evidence / provenance requirements are confirmed or marked TODO.
Trust / replay implications are reviewed.

Implementation readiness

Associated files are present where appropriate.
Live Snippet references resolve through current preflight logic.
Tests / acceptance criteria are explicit.
Hecate can derive a bounded implementation Need.
No unresolved critical architecture is hidden in prose.

Validation

Current local preflight commands pass where available.
PR validation is green.
Generated artifacts are reviewed for unintended drift.
Codex / Greptile / human review comments are resolved as applicable.

17. Definition of success

The migration is successful when the legacy manual is no longer required to understand or implement the migrated capability.

The Docusaurus specification, together with governed associated artifacts, should contain enough current information that:

a developer can implement it;
Hecate can create bounded work from it;
ZARA can retrieve and reason over it;
OMR and architectural registries can place it correctly;
Pergamum Pulse can preserve Module, Component and lower-level object lineage without flattening the ontology;
SSSR can understand its signal relationships;
TrustGate / replay systems can reason about assurance implications;
reviewers can trace unresolved debt through explicit markers;
future AI sessions can continue the work without depending on hidden chat history.

That is the standard for moving ZAYAZ documentation from a historical manual into a living constitutional architecture.

GitHub Repo Request for Change (RFC)

1. Purpose​

2. Constitutional authority and source precedence​

2.1. Cross-cutting invariants​

2.2. Detailed component behavior​

3. Mandatory first step for a new AI session​

3.1. General constitutional and documentation references​

3.2. MICE-specific references​

3.3. Hecate references​

3.4. Snippet and associated-file references​

4. ZAYAZ ontology rule during migration​

4.1. Canonical architectural types​

4.2. Migration classification procedure​

4.3. MICE / Micro-Engine classification​

5. Migration unit: one golden specimen first, then small coherent batches​

6. Per-document migration workflow​

Phase A — Receive and understand the legacy source​

Phase B — Reconcile with current architecture​

Phase C — Build the Constitutional Header / frontmatter​

Phase D — Structure the implementation specification​

7. Hecate-readiness rule​

8. Governed TODO markers​

Rules for TODOs​

9. Code and associated-file policy​

10. Grounding pass after each small batch​

11. Git branch and PR workflow​

11.1. Start from current main​

11.2. Create a logical working branch​

11.3. Commit the coherent change​

11.4. Push the branch​

11.5. Open a PR to main​

12. PR validation expectations​

Documentation / constitutional integrity​

Ontology / registry integrity​

Code / snippet integrity​

Architecture and implementation readiness​

Build / generated-artifact integrity​

13. Recommended local preflight before pushing​

14. Migration quality rules​

14.1. Precision before completeness​

14.2. Do not preserve legacy terminology when the canonical ontology changed​

14.3. Preserve architectural type distinctions​

14.4. Do not confuse identity domains​

14.5. Do not infer module or component status from folder names​

14.6. Keep lineage explicit​

14.7. Treat data relationships as architecture​

14.8. Use registered graph identities and controlled vocabulary​

14.9. Separate current fact from planned capability​

15. AI handover checklist for a future chat​

Required mindset for the assistant​

16. MICE migration completion checklist​

Canonical documentation​

Ontology and identity​

Architecture​

Implementation readiness​

Validation​

17. Definition of success​