# DEVON - MASTER ARCHITECTURE INDEX

<!-- CHECKPOINT_2026_04_03_SEMANTIC_RUNTIME_UI -->

## Checkpoint 2026-04-03 — Semantic Runtime Reading Canon

### Validated closure
- `build_runtime_contracts.py` already emits canonical runtime contracts with explicit semantics.
- `collect_runtime.py` was refactored so `runtime_status.json` now preserves semantic fields from the registry snapshot into final published runtime rows.
- The Devon collector now emits semantically typed rows including:
  - `row_kind`
  - `semantic_scope`
  - `counts_toward_completion`
  - `display_in_cards`
  - `display_in_donuts`
  - `ui_group`
  - `source_contract`
  - `status_resolution`
  - `rollup_source`
- `stage_rollup` is now a sovereign runtime row type and its `progress_pct` is the canonical source for stage completion in the UI.
- `project_progress.json` remains the sovereign source for global project completion.
- `export_panel_runtime.sh` was validated as the Devon → Waresite publication bridge for:
  - `runtime_snapshot.json`
  - `runtime_status.json`
  - `host_runtime.json`
  - `docker_runtime.json`
  - `project_progress.json`

### Mandatory semantic runtime rule
Any runtime row that feeds UI completion or operational grouping must be published by Devon with explicit semantic boundaries. Minimum required fields:
- `deployment_stage`
- `subcategory`
- `row_kind`
- `semantic_scope`
- `counts_toward_completion`
- `display_in_cards`
- `display_in_donuts`
- `ui_group`
- `source_contract`

### Mandatory UI reading rule
- Waresite UI must read completion only from declared semantics emitted by Devon.
- Global project completion must read from `project_progress.json`.
- Stage completion must read from `stage_rollup.progress_pct`.
- Subcategory cards must not render percentage donuts when `completionRows == 0`.
- If a runtime row is visible but not eligible for completion, the UI must render `MISSING / not eligible`, never `0%`.
- No semantic mixing between rollup rows and item rows in the same completion calculation.

### Canonical closure reached on 2026-04-03
The semantic runtime bottleneck is considered closed under the following validated path:
1. Devon server changes observable state
2. `collect_runtime.py` regenerates sovereign runtime artifacts
3. `export_panel_runtime.sh` synchronizes runtime artifacts to Waresite
4. Operator Panel reads published semantics without manual donut patching for new server-side evidence

### Operational implication
- The UI is now render-only relative to runtime semantics.
- Newly installed or configured Devon components must appear through collector + export, not through Waresite-side workaround patches.
- Future work returns to Devon server configuration and host/runtime expansion.

<!-- /CHECKPOINT_2026_04_03_SEMANTIC_RUNTIME_UI -->


### Material Devon runtime-contract artifacts now validated
The following files already exist materially on the Devon server and must be treated as the current runtime-contract artifacts in force:

- Canonical expected-runtime manifest: `/opt/devon/canon/runtime_expected_manifest.json`
- Canonical probe registry: `/opt/devon/canon/runtime_probe_registry.json`
- Contract builder/compiler: `/opt/devon/bin/build_runtime_contracts.py`

These artifacts are the current material base for runtime expectation + probe execution mapping.
They already exist and therefore must be referenced explicitly in continuity and master before any attempt to invent parallel contract files.

version: v3.0
status: ACTIVE
mode: CANONICAL_ROOT
role: supreme_reference

## 1. SYSTEM IDENTITY
Devon is a first-party cognitive development control plane.

It is designed to:
- architect
- validate
- generate
- canonize
- execute
- benchmark
- observe
- promote

All operations follow:
- sandbox-first execution
- evidence-based validation
- PASS / FAIL / MISSING rules


## 1.1 OPERATIONAL CONTEXT RULE

All Devon operations MUST start with canonical context reconstruction.

Mandatory command:
`/home/yeff/public_html/devon/context_dump.sh`

Rules:
- no analysis without dump
- no patch without dump
- no context = MISSING
- ChatGPT memory is NOT a valid source of truth
- only server evidence defines system state

This rule is non-optional and applies to all execution flows.


## 2. GLOBAL STATUS MODEL
PASS = observable evidence exists and validation passes
FAIL = observable evidence exists and validation fails
MISSING = no observable evidence
PLANNED = formally defined but not yet materially present

No inference allowed.

## 3. SUPREME REFERENCE LAW
If a file is not registered in this master index, it does not exist for Devon canonical governance.

This file is the highest human-readable reference for:
- canonical file existence
- file role
- phase ownership
- authority ownership
- precedence and conflict resolution
- structured canon registration

## 4. CANONICAL ROOT

Devon canonical structure is composed of two distinct but complementary roots:

### 4.1 DATA ROOT (UI / Runtime / Contracts)
`/home/yeff/public_html/devon/panel/data/`

Purpose:
- UI data source
- runtime artifacts
- contracts and schemas
- documentation hub bridge

### 4.2 GOVERNANCE ROOT (Operational Canon)
`/home/yeff/public_html/devon/canon/`

Purpose:
- operational rules
- decision registry
- execution flow
- project scope and boundaries
- continuity and next actions

Rule:
- panel/data = system state
- canon = system governance

Both roots are mandatory and must remain strictly separated.

## 5. DOCUMENTATION MODEL
Devon canonical documentation is composed of:
- authority documents
- satellite documents
- structured canonical JSON artifacts
- runtime/support JSON artifacts
- panel/documentation bridge artifacts

Rule:
one concept = one primary authority

A concept may be referenced by multiple files, but only one file may define its sovereign canonical meaning.

## 6. DOCUMENT PRECEDENCE RULE
If two files mention the same concept, precedence is:

1. this master index decides registration and ownership
2. the designated authority file defines the sovereign meaning
3. structured canonical JSON defines machine-readable enforcement
4. satellite files may contextualize but may not redefine
5. runtime/support files may operationalize but may not redefine canon

## 7. CANONICAL ORGANIZATION MODEL

This master index is organized by two mandatory axes:

1. canonical layer
2. installation / configuration order

Rule:
- layer defines cognitive and operational classification
- phase origin preserves real installation and configuration sequence
- no layer may break deployment order
- no categorization may override operational dependency

System flow:
Strategy → Architecture → Delivery → Runtime → Trust → Memory

Cross-layer mandatory controls:
- release artifact hygiene must be defined before unrestricted promotion
- distribution and packaging observability must exist before runtime evidence is treated as operationally complete
- environment-specific exposure policy must exist before memory-bearing runtime is treated as trusted

## 8. LAYERED CANONICAL INDEX

### 8.1 STRATEGY LAYER
Purpose:
defines what is being built, why it exists, under which scope, rules and environment constraints.

Installation/configuration order:
this layer comes first.

Phase origin:
- Phase 01 - Overview & Scope

Authority and registered files:

#### 8.1.1 System Root and Registration
Authority:
- master_architecture_index.md

#### 8.1.2 Project Scope
Authority:
- project_scope_canonical.json

Supporting context:
- devon_panel_chat_checkpoint.md

#### 8.1.3 Deployment Order
Authority:
- deployment_order_canonical.json

#### 8.1.4 Sandbox Environment
Authority:
- sandbox_environment_canonical.json

#### 8.1.5 Server Registry
Authority:
- server_registry_canonical.json

---

### 8.2 ARCHITECTURE LAYER
Purpose:
defines the software structure, domains, contracts, state legitimacy, naming, governance and system topology.

Installation/configuration order:
this layer is defined after strategy and before execution.

Phase origin:
- Phase 02 - Architecture & Engineering Canon
- Phase 03 - Cognitive Flow Canon

Authority and registered files:

#### 8.2.1 Cognitive Architecture
Authority:
- cas.md

Satellite references allowed in:
- cfc.md
- ris.md
- ccc.md

#### 8.2.2 Governance Model
Authority:
- cgs.md

#### 8.2.3 Artifact Canon and Structure
Authority:
- acs.md

#### 8.2.4 Contracts and Schemas
Authority:
- css.md

Structured support:
- card_contract_minimums.json
- panel_data_contract.json
- panel_component_contract.json
- panel_sync_contract.json

#### 8.2.5 Naming
Authority:
- ncs.md

#### 8.2.6 State Legitimacy and Transitions
Authority:
- sts.md

Satellite references allowed in:
- cfc.md
- ofc.md

#### 8.2.7 Deployment Structure
Authority:
- cdms.md

#### 8.2.8 Deterministic Orchestration and Cognitive Flow
Authority:
- cfc.md

Satellite references allowed in:
- cas.md
- ris.md
- ofc.md
- lpc.md

#### 8.2.9 Role Interaction Context
Authority:
- ris.md

Rule:
RIS is contextual and may not redefine sovereign authority.

#### 8.2.10 Operational Flow Mapping
Authority:
- ofms.md

Rule:
OFMS is contextual and may not redefine canonical flow.

#### 8.2.11 Panel Canonical Tree
Authority:
- panel_canonical_tree.json

#### 8.2.12 Panel Navigation
Authority:
- panel_navigation_spec.json

#### 8.2.13 Panel UI Blueprint
Authority:
- panel_ui_blueprint.json

#### 8.2.14 Canonical Matrix
Authority:
- canonical_matrix_v1.json

---

### 8.3 DELIVERY LAYER
Purpose:
defines build progression, release logic, operational flows, canonization and project execution mapping.

Installation/configuration order:
this layer starts after architecture is materially defined.

Phase origin:
- Phase 09 - Operational Flows Canon
- build/release references from Phase 02

Authority and registered files:

#### 8.3.1 Build, Release and Promotion
Authority:
- brps.md

#### 8.3.2 Release Artifact Hygiene and Supply-Chain Evidence
Authority:
- brps.md

Structured enforcement:
- delivery_security_canonical.json
- subcategory_pipelines.json

Canonical scope:
- sourcemap blocking in production artifacts
- debug artifact exclusion from production delivery
- packaging audit before promotion
- SBOM generation and traceability for releaseable artifacts

Rule:
delivery promotion is not canonically safe if release artifacts expose debug-sensitive material or lack auditable packaging evidence.

#### 8.3.3 Operational Flows Canon
Authority:
- ofc.md

#### 8.3.4 Subcategory Pipelines
Authority:
- subcategory_pipelines.json

#### 8.3.5 Panel Content Index
Authority:
- panel_content_index.json

#### 8.3.6 Panel Manifest
Authority:
- panel_manifest.json

---

### 8.4 RUNTIME LAYER
Purpose:
defines live system state, runtime bridge, containers, observability and operational support artifacts.

Installation/configuration order:
this layer becomes valid only after delivery/configuration begins materializing runtime.

Phase origin:
- Phase 04 - Containerization Canon
- Phase 05 - Latency & Performance Canon
- Phase 06 - Noise Reduction Canon
- Phase 07 - Observability & Audit Canon

Authority and registered files:

#### 8.4.1 Container Topology and Isolation
Authority:
- cdms.md

Rule:
cdms.md is the sovereign authority for Phase 04 containerization, deployment topology and isolation boundaries.
ccc.md remains a Phase 03 contextual component reference and may not redefine containerization authority.

#### 8.4.2 Latency and Performance
Authority:
- lpc.md

#### 8.4.3 Noise Reduction
Authority:
- nrc.md

#### 8.4.4 Observability and Audit
Authority:
- oac.md

#### 8.4.5 Distribution and Packaging Observability
Authority:
- oac.md

Support artifacts:
- panel_runtime_bridge.json
- runtime_status.json
- host_runtime.json
- docker_runtime.json

Canonical scope:
- distribution failure visibility
- packaging anomaly visibility
- promotion-to-runtime traceability
- runtime-visible evidence of what artifact was actually delivered

Rule:
runtime observability is incomplete if Devon can observe execution failure but cannot expose distribution or packaging failure.

#### 8.4.6 Panel Runtime Bridge
Authority:
- panel_runtime_bridge.json

#### 8.4.7 Runtime Status and Host/Docker Runtime Records
Registered support artifacts:
- runtime_status.json
- host_runtime.json
- docker_runtime.json

Rule:
These are runtime/support records and do not override canonical authority.

---

### 8.5 TRUST LAYER
Purpose:
defines security governance, approval control, protection boundaries and enforcement priority.

Installation/configuration order:
trust rules govern all layers, but are materially formalized before unrestricted runtime operation.

Phase origin:
- Phase 08 - Security Canon

Authority and registered files:

#### 8.5.1 Security Governance
Authority:
- sec.md

Structured implementation authorities:
- host_security_canonical.json
- app_security_canonical.json
- module_security_canonical.json
- runtime_security_canonical.json
- delivery_security_canonical.json
- approval_canonization_policy.json
- memory_isolation_canonical.json
- security_monitoring_canonical.json

Canonical scope:
- policy for memory exposure by environment
- policy for data exposure by environment
- separation between operator-facing, runtime-facing and debug-facing visibility
- prohibition of unrestricted cross-environment exposure
- protection against runtime-sensitive artifact exposure outside declared trust boundaries

Rule:
no environment may expose memory, payload, secrets, debug output or runtime-sensitive artifacts outside its declared boundary.

---

### 8.6 MEMORY LAYER
Purpose:
defines historical cognition, memory boundaries, learning governance, planning and knowledge continuity.

Installation/configuration order:
memory becomes operational after trust boundaries and architecture rules are defined.

Phase origin:
- Phase 08 - Security Canon (trust-bound activation point)
- post-core canonical expansion registered in this master index

Rule:
memory-layer authorities become canonically activatable only after trust boundaries are defined.
Operationally, their trust-bound phase origin is Phase 08.

Authority and registered files:

#### 8.6.1 Memory Architecture
Authority:
- memory_canonical_architecture.json

#### 8.6.2 Memory Isolation and Partitioning
Authority:
- memory_isolation_canonical.json

Narrative governance:
- sec.md

Flow enforcement reference:
- cfc.md

#### 8.6.3 Memory Lifecycle and Consolidation
Authority:
- memory_lifecycle_canonical.json

#### 8.6.4 Learning Governance
Authority:
- learning_governance_canonical.json

#### 8.6.5 Planning and Reasoning
Authority:
- planning_reasoning_canonical.json

#### 8.6.6 Tool Execution and Permission Model
Authority:
- tool_execution_canonical.json

#### 8.6.7 Knowledge Ingestion and Indexing
Authority:
- knowledge_ingestion_canonical.json

---

### 8.7 MONITORING LAYER
Purpose:
defines real-time operational monitoring of the Devon host, containers and services.
Monitoring is a first-class operational layer and feeds the Operator Panel monitoring section.

Installation/configuration order:
this layer becomes active after core_runtime is operational.
It must be installed before SSE bridge is activated.

Phase origin:
- Phase 10 - Monitoring & Real-time Observability

Authority and registered files:

#### 8.7.1 Monitoring Authority
Authority:
- monitoring_canonical.json

Canonical scope:
- CPU, memory, disk, network and uptime monitoring
- Docker container health per container with CPU, memory and restart count
- Nginx, UFW, Fail2ban service status
- Process count and file descriptor monitoring
- Latency monitoring for API and network paths
- Alert thresholds per metric
- Refresh intervals per target

Rule:
Devon has no GPU. CPU is the primary compute resource.
CPU monitoring is mandatory and must be continuous.

#### 8.7.2 SSE Bridge
Authority:
- sse_bridge_canonical.json

Canonical scope:
- Defines the SSE permanent channel that replaces export_panel_runtime.sh
- Devon emits SSE events on /monitoring/stream
- Waresite Operator Panel consumes via EventSource
- Fallback to 5-second polling if SSE disconnects
- Migration gate: SSE only replaces push_snapshot after monitoring is fully operational


## 9. PHASE REGISTRY
This registry is preserved as the operational installation and configuration sequence reference.

### Phase 01 - Overview & Scope
Authority set:
- master_architecture_index.md
- project_scope_canonical.json

Supporting context:
- devon_panel_chat_checkpoint.md

### Phase 02 - Architecture & Engineering Canon
Authority files:
- cas.md
- cgs.md
- acs.md
- css.md
- ncs.md
- sts.md
- brps.md
- cdms.md

Satellite files:
- ris.md
- ofms.md

#### Phase 02 Process-Spec

Purpose:
canonize the architecture and engineering foundation that governs structure, contracts, naming, state legitimacy, deployment structure and contextual boundaries.

Mandatory implementation items:

##### P02-01 Cognitive Architecture Spec
- authority_owner: cas.md
- canonical_role: sovereign architecture definition
- why_this_item_exists: define the cognitive architecture baseline before downstream orchestration, runtime and monitoring exist
- required_before:
  - cfc.md
  - ofms.md
  - operator/runtime implementation
- hard_dependencies:
  - master_architecture_index.md
  - project_scope_canonical.json
- install_steps:
  1. register cas.md in the canonical root
  2. bind the file to Phase 02 and architecture layer
  3. expose the file to the Documentation Hub
- config_steps:
  1. define architecture scope
  2. define core domains and structural boundaries
  3. define sovereignty versus allowed satellite references
- validation_gates:
  - file exists in /panel/data
  - file is registered in the master
  - category binding is correct
  - DH loads the file without error
- observable_evidence:
  - /panel/data/cas.md exists
  - DH renders CAS under Architecture & Engineering Canon
- failure_modes:
  - missing file
  - wrong phase binding
  - satellite redefining sovereign meaning
- done_when:
  - CAS is registered, readable, categorized and treated as sovereign authority
- feeds_operational_ui:
  - category cards
  - evidence drawer
  - dependency drawer
  - phase registry view

##### P02-02 Governance Model
- authority_owner: cgs.md
- canonical_role: governance authority
- why_this_item_exists: define governance rules for architecture, engineering and canonical control
- required_before:
  - structured contracts
  - runtime enforcement
- hard_dependencies:
  - cas.md
  - master_architecture_index.md
- install_steps:
  1. register cgs.md in canonical root
  2. bind the file to Phase 02 and architecture layer
  3. expose governance authority in DH
- config_steps:
  1. define governance scope
  2. define rule ownership
  3. define what satellites may not override
- validation_gates:
  - file exists
  - file is registered
  - file is mapped to Phase 02
- observable_evidence:
  - /panel/data/cgs.md exists
  - DH relation map shows governance role
- failure_modes:
  - governance file missing
  - duplicated authority
  - governance scope undefined
- done_when:
  - governance authority is materialized and bound to Phase 02
- feeds_operational_ui:
  - contract drawer
  - dependency drawer
  - evidence drawer

##### P02-03 Artifact Canon and Structure
- authority_owner: acs.md
- canonical_role: artifact structure authority
- why_this_item_exists: define how canonical artifacts are shaped, separated and registered
- required_before:
  - structured json artifacts
  - DH/UI artifact mapping
- hard_dependencies:
  - cgs.md
  - master_architecture_index.md
- install_steps:
  1. register acs.md
  2. bind artifact structure to architecture layer
- config_steps:
  1. define artifact classes
  2. define authority versus satellite separation
  3. define structural expectations
- validation_gates:
  - file exists
  - file is registered
  - structure rules are referenced by dependent artifacts
- observable_evidence:
  - /panel/data/acs.md exists
  - dependent docs and jsons remain structurally coherent
- failure_modes:
  - structure undefined
  - mixed authority boundaries
  - artifact overlap
- done_when:
  - artifact structure is explicit and enforceable
- feeds_operational_ui:
  - artifact view
  - contract view
  - validation timeline

##### P02-04 Contracts and Schemas
- authority_owner: css.md
- canonical_role: contracts and schemas authority
- why_this_item_exists: define machine-readable interfaces and operational schema boundaries
- required_before:
  - panel_data_contract.json
  - panel_component_contract.json
  - panel_sync_contract.json
  - card_contract_minimums.json
- hard_dependencies:
  - acs.md
  - cgs.md
- install_steps:
  1. register css.md
  2. register contract json artifacts
  3. bind them to Phase 02
- config_steps:
  1. define required fields
  2. define join rules
  3. define status/data resolution rules
- validation_gates:
  - all declared contract artifacts exist
  - each contract artifact loads correctly
  - no fake status derivation rule is preserved
- observable_evidence:
  - css.md exists
  - contract json files exist and load
  - DH exposes them under the correct category
- failure_modes:
  - missing contract artifact
  - incomplete schema
  - conflicting field authority
- done_when:
  - contract layer is materialized and readable end to end
- feeds_operational_ui:
  - contract drawer
  - card shell rendering
  - evidence rules
  - status resolution

##### P02-05 Naming and State Legitimacy
- authority_owner:
  - ncs.md
  - sts.md
- canonical_role: naming authority plus state legitimacy authority
- why_this_item_exists: prevent naming drift and invalid state transitions during implementation
- required_before:
  - runtime status handling
  - operator counters
  - dependency logic
- hard_dependencies:
  - css.md
  - cgs.md
- install_steps:
  1. register ncs.md and sts.md
  2. bind both to Phase 02
- config_steps:
  1. define naming patterns
  2. define legal states
  3. define forbidden transitions
- validation_gates:
  - both files exist
  - naming is referenced consistently
  - state legitimacy is not contradicted downstream
- observable_evidence:
  - /panel/data/ncs.md exists
  - /panel/data/sts.md exists
- failure_modes:
  - naming drift
  - invalid state labels
  - impossible transitions in runtime/UI
- done_when:
  - naming and state legitimacy are explicit and reusable
- feeds_operational_ui:
  - status badges
  - state rendering
  - evidence/status reconciliation

##### P02-06 Deployment Structure and Contextual Boundaries
- authority_owner:
  - cdms.md
  - ris.md
  - ofms.md
  - brps.md
- canonical_role: deployment structure plus contextual boundary support
- why_this_item_exists: bind architecture to deployment structure, delivery promotion and role/context references without allowing contextual files to redefine sovereign canon
- required_before:
  - delivery layer
  - runtime materialization
- hard_dependencies:
  - cas.md
  - cgs.md
  - acs.md
  - css.md
- install_steps:
  1. register cdms.md, ris.md, ofms.md and brps.md
  2. bind all files to Phase 02
  3. expose dependencies in DH
- config_steps:
  1. define deployment model
  2. define contextual interaction boundaries
  3. define operational flow mapping references
  4. define build/release/promotion references
- validation_gates:
  - all support files exist
  - no contextual file overrides sovereign authority
  - dependencies are declared
- observable_evidence:
  - files exist in /panel/data
  - DH relation map shows their role and dependencies
- failure_modes:
  - contextual override
  - undeclared dependency
  - deployment structure ambiguity
- done_when:
  - deployment structure and contextual support are explicitly registered and bounded
- feeds_operational_ui:
  - dependency drawer
  - timeline drawer
  - promotion/timeline views

##### Phase 02 Category Completion
- not_done_when:
  - any authority file is missing
  - any required contract artifact is missing
  - phase binding is absent
  - sovereign versus satellite separation is ambiguous
  - DH cannot load the registered source
- canonization_gate:
  - Phase 02 is canonized only when all Phase 02 implementation items satisfy done_when and expose observable evidence
- promotion_gate:
  - downstream runtime, trust and memory layers may not be treated as canonically safe until Phase 02 is materially valid

### Phase 03 - Cognitive Flow Canon
Authority file:
- cfc.md

#### Phase 03 Process-Spec

Purpose:
canonize deterministic orchestration, cognitive flow routing, execution sequence, context handling and operational flow references before runtime implementation is treated as valid.

Mandatory implementation items:

##### P03-01 Deterministic Orchestration and Cognitive Flow
- authority_owner: cfc.md
- canonical_role: sovereign cognitive flow authority
- why_this_item_exists: define how interpretation, orchestration and deterministic execution are sequenced without allowing probabilistic components to control the system
- required_before:
  - runtime layer materialization
  - observability logic
  - tool execution and planning integration
- hard_dependencies:
  - cas.md
  - cgs.md
  - sts.md
  - master_architecture_index.md
- install_steps:
  1. register cfc.md in the canonical root
  2. bind the file to Phase 03 and architecture layer
  3. expose the file in the Documentation Hub under Cognitive Flow Canon
- config_steps:
  1. define orchestration stages
  2. define deterministic control boundaries
  3. define allowed interaction with interpretation layers
  4. define downstream runtime implications
- validation_gates:
  - file exists in /panel/data
  - file is registered in the master
  - file is mapped to Phase 03
  - DH loads the file without error
- observable_evidence:
  - /panel/data/cfc.md exists
  - DH renders CFC under Cognitive Flow Canon
- failure_modes:
  - missing file
  - orchestration undefined
  - probabilistic layer overriding deterministic flow
- done_when:
  - CFC is registered, readable and treated as sovereign authority for cognitive flow
- feeds_operational_ui:
  - category cards
  - contract drawer
  - dependency drawer
  - phase registry view

##### P03-02 Cognitive Component Context
- authority_owner: ccc.md
- canonical_role: contextual component reference
- why_this_item_exists: describe cognitive components and contextual relationships used by the flow authority without redefining sovereign flow
- required_before:
  - downstream runtime mapping
  - operator flow visualization
- hard_dependencies:
  - cfc.md
  - cas.md
- install_steps:
  1. register ccc.md
  2. bind the file to Phase 03
  3. expose the file in DH as contextual support
- config_steps:
  1. define component roles
  2. define contextual relationship boundaries
  3. preserve sovereign authority ownership in cfc.md
- validation_gates:
  - file exists
  - file is registered
  - file is presented as contextual, not sovereign
- observable_evidence:
  - /panel/data/ccc.md exists
  - DH relation map shows contextual role
- failure_modes:
  - contextual file missing
  - contextual file redefining sovereign flow
  - component role ambiguity
- done_when:
  - contextual component reference is registered and bounded by CFC sovereignty
- feeds_operational_ui:
  - relation map
  - dependency drawer
  - artifact view

##### P03-03 Latency and Performance Context
- authority_owner: lpc.md
- canonical_role: latency/performance contextual reference
- why_this_item_exists: define performance-sensitive flow expectations that must be respected before runtime optimization phases are implemented
- required_before:
  - latency monitoring
  - noise reduction
  - runtime optimization cards
- hard_dependencies:
  - cfc.md
  - cas.md
  - cdms.md
- install_steps:
  1. register lpc.md
  2. bind the file to Phase 03
  3. expose latency/performance context in DH
- config_steps:
  1. define latency-sensitive path segments
  2. define expected performance boundaries
  3. define what later runtime phases must preserve
- validation_gates:
  - file exists
  - file is registered
  - DH loads the file correctly
- observable_evidence:
  - /panel/data/lpc.md exists
  - DH shows latency/performance context under Phase 03
- failure_modes:
  - performance context absent
  - runtime optimization later contradicting flow expectations
  - latency path ambiguity
- done_when:
  - latency/performance context is explicitly registered and traceable to Phase 03
- feeds_operational_ui:
  - dependency drawer
  - timeline drawer
  - performance-related views downstream

##### P03-04 Noise and Runtime Context References
- authority_owner:
  - nrc.md
  - oac.md
- canonical_role: contextual runtime/noise references
- why_this_item_exists: preserve upstream cognitive flow constraints when runtime noise and observability concerns are later materialized
- required_before:
  - Phase 06 - Noise Reduction Canon
  - Phase 07 - Observability & Audit Canon
- hard_dependencies:
  - cfc.md
  - lpc.md
  - ofms.md
- install_steps:
  1. register nrc.md and oac.md
  2. bind both files to Phase 03 as contextual references
  3. expose dependencies in DH
- config_steps:
  1. define noise-sensitive execution boundaries
  2. define observability-sensitive checkpoints
  3. preserve contextual status only
- validation_gates:
  - both files exist
  - both files are registered
  - neither file overrides sovereign authority
- observable_evidence:
  - /panel/data/nrc.md exists
  - /panel/data/oac.md exists
  - DH shows both as contextual references
- failure_modes:
  - missing runtime-context files
  - contextual override
  - observability path undefined
- done_when:
  - runtime/noise context references are registered and bounded
- feeds_operational_ui:
  - dependency drawer
  - timeline drawer
  - observability-related downstream views

##### Phase 03 Category Completion
- not_done_when:
  - cfc.md is missing
  - contextual support files are missing where declared
  - sovereign versus contextual separation is ambiguous
  - DH cannot load the registered source
  - deterministic flow boundaries remain undefined
- canonization_gate:
  - Phase 03 is canonized only when sovereign flow authority and all declared contextual references satisfy done_when and expose observable evidence
- promotion_gate:
  - downstream containerization, runtime optimization, observability and tool execution monitoring may not be treated as canonically safe until Phase 03 is materially valid

### Phase 04 - Containerization Canon
Authority file:
- cdms.md

#### Phase 04 Process-Spec

Purpose:
canonize containerization, service isolation, networking, persistent state mounting and deployment topology so runtime execution starts from an explicit and monitorable infrastructure baseline.

Mandatory implementation items:

##### P04-01 Container Topology Definition
- authority_owner: cdms.md
- canonical_role: deployment structure authority for container topology
- why_this_item_exists: define which services must exist, how they are isolated and how they compose the canonical runtime baseline
- required_before:
  - docker compose materialization
  - runtime status collection
  - observability wiring
- hard_dependencies:
  - cas.md
  - cgs.md
  - acs.md
  - cfc.md
  - server_registry_canonical.json
- install_steps:
  1. register container topology authority under Phase 04
  2. bind topology definition to architecture and runtime preparation
  3. expose the file in the Documentation Hub
- config_steps:
  1. define required services
  2. define service roles
  3. define isolation boundaries
  4. define which services are mandatory versus contextual
- validation_gates:
  - topology authority exists
  - topology is registered in master
  - topology is mapped to Phase 04
  - DH loads the source without error
- observable_evidence:
  - deployment structure file exists in /panel/data
  - DH renders containerization references under Phase 04
- failure_modes:
  - topology undefined
  - missing service role definition
  - isolation boundary ambiguity
- done_when:
  - container topology is explicit, registered and readable as canonical authority
- feeds_operational_ui:
  - category cards
  - dependency drawer
  - contract drawer
  - phase registry view

##### P04-02 Service Networking and Reverse Proxy Boundaries
- authority_owner: cdms.md
- canonical_role: network and routing boundary authority
- why_this_item_exists: define service communication paths, ingress/egress rules and reverse proxy expectations before runtime traffic exists
- required_before:
  - exposed endpoints
  - runtime bridge
  - host/docker telemetry
- hard_dependencies:
  - P04-01 Container Topology Definition
  - server_registry_canonical.json
  - sandbox_environment_canonical.json
- install_steps:
  1. bind network/routing expectations to Phase 04
  2. register reverse proxy and networking references
  3. expose them in DH
- config_steps:
  1. define internal networks
  2. define ingress path
  3. define reverse proxy scope
  4. define allowed service-to-service communication
- validation_gates:
  - network scope is documented
  - reverse proxy boundary is documented
  - service communication path is explicit
- observable_evidence:
  - deployment/network references exist in canonical docs
  - DH shows network-related dependencies under Phase 04
- failure_modes:
  - routing ambiguity
  - unbounded service communication
  - reverse proxy undefined
- done_when:
  - networking and routing boundaries are explicit and traceable
- feeds_operational_ui:
  - dependency drawer
  - evidence drawer
  - server scope drawer

##### P04-03 Volumes, Persistent State and Artifact Storage
- authority_owner:
  - cdms.md
  - acs.md
- canonical_role: state persistence and artifact storage authority
- why_this_item_exists: define what must persist across runs and where structured state, cache, vectors and artifacts are allowed to live
- required_before:
  - runtime snapshots
  - memory lifecycle downstream
  - artifact generation and storage
- hard_dependencies:
  - Artifact Canon and Structure
  - server_registry_canonical.json
  - sandbox_environment_canonical.json
- install_steps:
  1. register persistent-state expectations in Phase 04
  2. bind volumes and storage classes to deployment structure
  3. expose storage/state references in DH
- config_steps:
  1. define structured state locations
  2. define cache locations
  3. define vector/state locations
  4. define artifact storage locations
- validation_gates:
  - persistence rules are documented
  - storage classes are separated
  - storage paths remain consistent with canon
- observable_evidence:
  - Phase 04 docs reference storage/state classes
  - DH relation map shows storage/state relevance
- failure_modes:
  - state mixed without boundary
  - artifact storage undefined
  - persistence scope ambiguous
- done_when:
  - persistent state and artifact storage rules are explicit and enforceable
- feeds_operational_ui:
  - artifact view
  - evidence drawer
  - dependency drawer
  - memory/server scope downstream

##### P04-04 Runtime Bootstrap Readiness
- authority_owner:
  - panel_runtime_bridge.json
  - host_runtime.json
  - docker_runtime.json
  - runtime_status.json
- canonical_role: observable runtime bootstrap readiness reference
- why_this_item_exists: connect containerization canon to observable runtime evidence without allowing runtime artifacts to redefine sovereign canon
- required_before:
  - runtime layer monitoring
  - Operator Panel telemetry
  - host/docker/pipeline runtime views
- hard_dependencies:
  - P04-01 Container Topology Definition
  - panel_data_contract.json
  - panel_sync_contract.json
  - panel_runtime_bridge.json
- install_steps:
  1. register runtime bridge/support artifacts in the master
  2. bind them to Phase 04/Runtime preparation
  3. expose them in DH as observable support, not sovereign canon
- config_steps:
  1. define bridge relationship between canon and runtime snapshots
  2. define expected runtime entities
  3. define monitoring source paths
- validation_gates:
  - runtime bridge artifact exists
  - support runtime json artifacts exist
  - panel can read them as support evidence
  - no runtime artifact overrides sovereign canon
- observable_evidence:
  - /panel/data/panel_runtime_bridge.json exists
  - /panel/data/host_runtime.json exists
  - /panel/data/docker_runtime.json exists
  - /panel/data/runtime_status.json exists
- failure_modes:
  - missing runtime bridge
  - runtime support file missing
  - support artifact treated as sovereign canon
- done_when:
  - runtime bootstrap evidence is wired and clearly bounded as support state
- feeds_operational_ui:
  - host runtime view
  - docker runtime view
  - pipeline runtime view
  - evidence drawer
  - timeline drawer

##### Phase 04 Category Completion
- not_done_when:
  - topology authority is missing
  - network/routing boundaries are undefined
  - persistence/state rules are undefined
  - runtime bridge/support artifacts are missing where declared
  - runtime support is being used to redefine canon
- canonization_gate:
  - Phase 04 is canonized only when topology, networking, persistence and runtime-bootstrap references satisfy done_when and expose observable evidence
- promotion_gate:
  - latency, noise reduction, observability and security monitoring may not be treated as canonically reliable until Phase 04 is materially valid

### Phase 05 - Latency & Performance Canon
Authority file:
- lpc.md

### Phase 06 - Noise Reduction Canon
Authority file:
- nrc.md

### Phase 07 - Observability & Audit Canon
Authority file:
- oac.md

### Phase 08 - Security Canon
Authority file:
- sec.md

Structured implementation canon:
- host_security_canonical.json
- app_security_canonical.json
- module_security_canonical.json
- runtime_security_canonical.json
- delivery_security_canonical.json
- approval_canonization_policy.json
- memory_isolation_canonical.json
- security_monitoring_canonical.json

Trust-bound memory expansion attached to Phase 08:
- memory_canonical_architecture.json
- memory_lifecycle_canonical.json
- learning_governance_canonical.json
- planning_reasoning_canonical.json
- tool_execution_canonical.json
- knowledge_ingestion_canonical.json

### Phase 09 - Operational Flows Canon
Authority file:
- ofc.md

### Phase 10 - Monitoring & Real-time Observability
Authority files:
- monitoring_canonical.json
- sse_bridge_canonical.json

Installation order: 85-86
Depends on: core_runtime (order 70), observability_audit_base (order 80)

Purpose:
real-time host, container and service monitoring with SSE transport to the Operator Panel.
This phase must be complete before SSE bridge replaces the push_snapshot model.


## 10. CROSS-DOCUMENT RULES

1. A file not registered here does not exist canonically.
2. A satellite file may reference a concept, but may not redefine it.
3. A phase authority file may define a concept only if ownership is assigned here.
4. If a concept needs both narrative governance and structured enforcement:
   - narrative governance belongs to the authority document
   - machine-readable enforcement belongs to the structured canonical JSON
5. If state and flow conflict:
   - STS wins on state legitimacy
6. If security conflicts with flow, latency or convenience:
   - SEC wins
7. If naming conflicts with content:
   - NCS wins on naming
8. If latency conflicts with optional processing:
   - LPC wins on latency budget
9. If memory access scope is ambiguous:
   - deny by default
10. If retrieval scope exceeds memory boundary:
   - memory isolation canon wins
11. Memory lifecycle must respect memory isolation and security boundaries.
12. Learning cannot bypass validation layer.
13. Planning cannot override deterministic control.
14. Tool execution must respect security and scope boundaries.
15. Knowledge ingestion must be versioned and auditable.
16. Runtime/support JSON artifacts may report state, but may not redefine canon.
17. Panel artifacts may represent canon, but may not create sovereign canon by themselves.

## 11. COMPLETE CANONICAL FILE REGISTRY

### 11.1 Authority and Satellite Markdown Files
- acs.md
- brps.md
- cas.md
- ccc.md
- cdms.md
- cfc.md
- cgs.md
- css.md
- devon_panel_chat_checkpoint.md
- lpc.md
- master_architecture_index.md
- ncs.md
- nrc.md
- oac.md
- ofc.md
- ofms.md
- ris.md
- sec.md
- sts.md

### 11.2 Structured Canonical JSON Files
- app_security_canonical.json
- approval_canonization_policy.json
- canonical_matrix_v1.json
- card_contract_minimums.json
- delivery_security_canonical.json
- deployment_order_canonical.json
- host_security_canonical.json
- knowledge_ingestion_canonical.json
- learning_governance_canonical.json
- memory_canonical_architecture.json
- memory_isolation_canonical.json
- memory_lifecycle_canonical.json
- module_security_canonical.json
- panel_canonical_tree.json
- panel_component_contract.json
- panel_content_index.json
- panel_data_contract.json
- panel_manifest.json
- panel_navigation_spec.json
- panel_runtime_bridge.json
- panel_sync_contract.json
- panel_ui_blueprint.json
- planning_reasoning_canonical.json
- project_scope_canonical.json
- runtime_row_semantics_canonical.json
- runtime_security_canonical.json
- sandbox_environment_canonical.json
- security_monitoring_canonical.json
- server_registry_canonical.json
- subcategory_pipelines.json
- tool_execution_canonical.json
- project_progress_canonical.json
- project_progress_model.json
- runtime_row_semantics_canonical.json
### 11.3 Runtime and Support JSON Files
- docker_runtime.json
- host_runtime.json
- monitoring_runtime.json
- project_progress.json
- runtime_snapshot.json
- runtime_status.json

## 12. CANONICAL DEPENDENCY MATRIX

This section defines explicit dependencies between canonical domains.
No domain operates in isolation.

### 12.1 Memory Domain
- memory_lifecycle_canonical.json depends on:
  - memory_canonical_architecture.json
  - memory_isolation_canonical.json
  - learning_governance_canonical.json

### 12.2 Learning Domain
- learning_governance_canonical.json depends on:
  - validation layer (implicit)
  - memory_lifecycle_canonical.json
  - security_monitoring_canonical.json

### 12.3 Planning / Reasoning Domain
- planning_reasoning_canonical.json depends on:
  - deterministic control layer
  - tool_execution_canonical.json
  - project_scope_canonical.json

### 12.4 Tool Execution Domain
- tool_execution_canonical.json depends on:
  - runtime_security_canonical.json
  - module_security_canonical.json
  - project_scope_canonical.json

### 12.5 Knowledge Ingestion Domain
- knowledge_ingestion_canonical.json depends on:
  - memory_canonical_architecture.json
  - memory_lifecycle_canonical.json
  - canonical_matrix_v1.json

## 13. CANONICAL PROCESS SPEC MODEL

This section defines the mandatory process model that every canonical category, section, card and implementation item must follow.

Purpose:
turn canonical documentation into an executable process reference for the Documentation Hub, Operator Panel and future real-time build monitoring.

Rule:
a category is not sufficiently documented if it only declares files, layers, phase origin or dependencies.
A category becomes operationally valid only when its process is explicitly documented step by step.

### 13.0 Canonical execution hierarchy

The canonical execution hierarchy for Devon documentation, Documentation Hub and Operator Panel is:

1. Phase
2. Category
3. Process bucket
4. Item

Definitions:

#### Phase
A Phase is the macro execution stage shown in left navigation.
It preserves installation/configuration order and canonical progression.
Examples:
- Overview & Scope
- Architecture & Engineering Canon
- Cognitive Flow Canon
- Containerization Canon

#### Category
A Category is a sovereign or supporting document group inside a selected Phase.
Examples inside a phase:
- Master Architecture Index
- Panel Manifest
- Project Scope Canonical
- Contracts and Schemas
- Governance Model

Rule:
a category is not the phase itself.
A phase contains categories.

#### Process bucket
A Process bucket is the ordered operational subdivision inside a category.
Mandatory canonical buckets are:

1. prerequisites
2. installation
3. configuration
4. validation
5. observable_evidence
6. failure_modes_recovery
7. completion_promotion

Rule:
process buckets must appear in execution order.
The Documentation Hub and Operator Panel may summarize them visually, but may not change their order.

#### Item
An Item is the smallest executable process unit inside a process bucket.
An item must describe:
- what must be done
- in which order
- what input is required
- what output is expected
- how to validate it
- what evidence proves it
- what failure can occur
- what recovery action is allowed

Example hierarchy:
Phase:
- Overview & Scope

Category:
- Project Scope Canonical

Process buckets:
- prerequisites
- installation
- configuration
- validation
- observable_evidence
- failure_modes_recovery
- completion_promotion

Items:
- register file
- bind file to phase
- expose file in DH
- validate source load
- confirm category ownership

Canonical rule:
left navigation = phase registry.
center workflow = categories inside the selected phase.
category body = ordered process buckets.
bucket body = executable items.

### 13.1 Mandatory process-spec fields

Every canonical implementation item must define, at minimum:

1. identity
- canonical_layer
- phase_origin
- category_id
- section_id
- card_id
- item_id
- authority_owner

2. process purpose
- objective
- canonical_role
- why_this_item_exists

3. prerequisites
- required_before
- blockers
- hard_dependencies
- allowed_preconditions

4. installation process
- install_steps
- installation_order
- installation_commands_or_actions
- expected_install_result

5. configuration process
- config_steps
- configuration_inputs
- configuration_outputs
- expected_configuration_result

6. validation process
- validation_gates
- checks
- pass_criteria
- fail_criteria
- missing_criteria

7. evidence model
- observable_evidence
- evidence_source
- evidence_path_or_endpoint
- evidence_frequency
- last_validation_pointer

8. failure model
- failure_modes
- probable_root_causes
- recovery_actions
- rollback_or_safe_state

9. completion model
- done_when
- not_done_when
- promotion_gate
- canonization_gate

10. operational monitoring contract
- feeds_operational_ui
- runtime_monitoring_hooks
- timeline_events
- status_counter_impact
- dependency_impact

### 13.2 Canonical process rules

1. No implementation item may be treated as complete without explicit done_when criteria.
2. No step may be considered valid without observable evidence.
3. Installation and configuration must remain separated when they are materially different actions.
4. Validation must be explicit and may not be inferred from file existence alone unless the item contract says so.
5. Runtime monitoring may report process state, but may not redefine the canonical process contract.
6. The Documentation Hub may summarize the process, but the master index remains the supreme authority.
7. The Operator Panel may visualize process execution, but may not invent missing steps.
8. If a process field is absent, its status is MISSING.
9. If an item cannot expose evidence, it cannot produce PASS.
10. If a category has files but no process spec, the category is documentation-incomplete.

### 13.3 Required DH and UI alignment

Audit split rule:

Documentation Hub responsibilities:
- canonical/document audit
- coverage against this master index
- authority ownership visibility
- phase binding visibility
- layer binding visibility
- depends_on / used_by visibility
- sovereign versus satellite separation visibility
- documentation completion gap visibility
- PASS / FAIL / MISSING only for documentary and canonical evidence

Operator Panel responsibilities:
- operational/runtime audit
- real implementation state
- real server/runtime evidence
- health, containers and process telemetry
- pipeline execution evidence
- sync/export/runtime bridge evidence
- PASS / FAIL / MISSING only for materially observable execution evidence

Boundary rule:
- Documentation Hub may summarize canonical structure, but may not claim runtime implementation as complete unless runtime evidence is exposed through the operational side.
- Operator Panel may summarize runtime state, but may not redefine canonical ownership, precedence, phase order or documentary authority.
- A runtime-relevant concept is only fully auditable when its canonical definition exists in the master/documentation side and its material evidence exists in the operational side.

The Documentation Hub must eventually expose, per category:

- required_before
- install_steps
- config_steps
- validation_gates
- observable_evidence
- failure_modes
- done_when
- feeds_operational_ui

The Operator Panel must eventually consume the same process model for:

- monitoring sequence
- timeline events
- evidence drawers
- contract drawers
- dependency drawers
- status counters
- real-time runtime tracking

### 13.4 Process-spec priority

If there is conflict between:
- file listing and process contract
- visual convenience and validation rule
- runtime report and canonical process definition

then the canonical process definition wins.

## 14. CANONICAL INTEGRITY RULES

1. No canonical file can operate without declared dependencies.
2. Cross-domain interaction must follow declared dependency paths.
3. Violations = FAIL (even if implementation exists).
4. Missing dependency = MISSING (system incomplete).
5. Circular dependencies are forbidden unless explicitly declared.

## 15. FAILURE MODES

The system must explicitly recognize invalid states:

- orphan canonical file → FAIL
- dependency missing → MISSING
- dependency violated → FAIL
- execution bypassing canonical rule → FAIL
- undocumented canonical file → FAIL

## 16. ARCHITECTURAL COMPLETENESS CRITERIA

The system is considered COMPLETE only if:

- all canonical files are referenced in this document
- all dependencies are declared
- all rules are enforceable
- all domains are isolated and governed
- validation layer is respected globally

## 17. COMPLETENESS RULE
A Documentation Hub update is complete only if:
- the canonical/document audit scope is materially reflected in the Hub
- the Hub makes clear what belongs to documentary authority versus operational/runtime verification
- no Documentation Hub element implies that runtime implementation is complete without operational evidence
- the file exists materially in `/panel/data`
- the file is registered in this master index
- the file has a defined role
- the file does not violate precedence rules

## 18. MASTER RULE FOR FUTURE EXPANSION
No new file may be introduced into the canonical root without:
- unique responsibility
- explicit registration in this master index
- non-overlap with existing authority
- observable justification