===== CANON =====

----- 03_RULES_OF_OPERATION.md -----
# RULES OF OPERATION

## PRINCÍPIO CENTRAL
O sistema NÃO depende de memória do ChatGPT.
Toda execução deve ser baseada em evidência real do servidor.

---

## REGRA 1 — EVIDÊNCIA OBRIGATÓRIA
Todo novo chat deve iniciar com reconstrução de contexto via dump canônico.

Comando obrigatório:
/home/yeff/public_html/devon/context_dump.sh

Sem dump inicial = MISSING.

---

## REGRA 2 — FLUXO FIXO
1. Evidência
2. Análise
3. Patch

Proibido misturar etapas.

---

## REGRA 3 — SOURCE OF TRUTH
A fonte de verdade é distribuída em duas raízes obrigatórias:

- /home/yeff/public_html/devon/panel/data
- /home/yeff/public_html/devon/canon

Regra:
- panel/data = estado do sistema
- canon = governança do sistema

---

## REGRA 4 — PROIBIÇÕES
- confiar em memória do ChatGPT
- analisar sem dump
- criar patch sem dump
- inventar caminhos
- alterar fora do escopo

---

## REGRA 5 — PATCH
- sempre backup
- sempre REPLACE no ponto canônico
- APPEND só com autorização explícita

---

## REGRA 6 — STATUS
PASS / FAIL / MISSING

---

## REGRA 7 — CONTEXTO
Contexto é reconstruído via dump canônico.
Somente evidência do servidor define o estado do sistema.

---

## REGRA 8 — OBRIGATORIEDADE
Esta regra é não opcional e se aplica a todos os fluxos de execução.

----- 06_DECISIONS.md -----
# DECISIONS

## D-001
Decisão: usar diretório /canon
Motivo: separar runtime de governança
Impacto: organização estrutural
Reversível: não

## D-002
Decisão: evidence-first obrigatório
Motivo: eliminar erro de contexto
Impacto: consistência operacional
Reversível: não

## D-003
Decisão: context_dump.sh obrigatório no início de todo novo chat
Motivo: reconstruir contexto canônico a partir de evidência real do servidor
Impacto: elimina dependência de memória do ChatGPT e reduz drift operacional
Reversível: não

## D-004
Decisão: manter separação formal entre panel/data e canon
Motivo: distinguir estado do sistema de governança do sistema
Impacto: arquitetura canônica com raízes complementares e sem mistura de responsabilidades
Reversível: não

----- 07_SCOPE.md -----
# SCOPE

## IN
- governança operacional
- canon do projeto
- regras e fluxo

## OUT
- runtime
- UI data
- logs

----- 08_NEXT_ACTION.md -----
# NEXT ACTION

## Objetivo
Operar todo novo chat do projeto com reconstrução obrigatória de contexto via dump canônico.

## Próximo passo
Antes de qualquer análise ou patch em novo chat, executar:
/home/yeff/public_html/devon/context_dump.sh

## Critério de pronto
- dump executado no início do chat
- contexto colado no chat
- análise feita somente após evidência
- patch gerado somente após análise

===== CORE ARCHITECTURE =====
# 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


===== CONTINUITY =====
# DEVON CONTINUITY

<!-- CHECKPOINT_2026_04_09_CANON_CLEANUP_MONITORING -->

## Checkpoint 2026-04-09 — Canon Cleanup + Monitoring Layer

### O que foi feito
- Limpeza completa de arquivos órfãos no Waresite /panel/data
- Limpeza de baks no Devon /opt/devon/bin e /opt/devon/canon
- runtime_row_semantics_canonical.json criado no disco e registrado no master
- monitoring_canonical.json criado — define CPU, memory, disk, network, containers, nginx, security
- sse_bridge_canonical.json criado — transport SSE PLANNED, push_snapshot ainda ACTIVE
- master_architecture_index.md atualizado: seção 8.7, Phase 10, 11.2, 11.3
- hub_index.json atualizado: 10 phases, 12 categories, monitoring_observability adicionado
- project_progress_canonical.json e project_progress_model.json registrados em overview_scope
- runtime_row_semantics_canonical registrado em observability_audit
- Export script Devon corrigido para sincronizar canon completo (panel_export/current)
- DH funcionando e refletindo tudo corretamente

### Próximo passo
- Refatorar Operator Panel (UI) — novo chat
- Após UI: implementar SSE bridge Devon → Waresite
- Após SSE: remover export_panel_runtime.sh

<!-- /CHECKPOINT_2026_04_09_CANON_CLEANUP_MONITORING -->


<!-- CHECKPOINT_2026_04_03_SEMANTIC_RUNTIME_UI -->

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

### Real state validated
- Devon is already emitting real runtime for host, docker, pipeline and project progress.
- Waresite is already consuming published runtime rows from Devon.
- The UI numbers are not being filled manually.
- The current problem is semantic, not cosmetic and not “manual digit editing”.

### Structural diagnosis
- The Operator Panel is still grouping runtime rows with insufficient semantic separation.
- Some visual groups are mixing rollup rows, matrix-derived rows and item-level runtime rows.
- This makes some donuts mathematically calculated but semantically invalid.
- The correct correction is not another ad hoc UI patch.
- The correct correction is explicit semantic typing in the runtime publication contract.

### Sovereign rule now in force
- Devon must publish runtime truth with explicit row semantics.
- Waresite UI must only consume published runtime truth and declared row meaning.
- Canon stays canonical.
- Runtime stays operational.
- UI stays render-only.
- No manual UI recognition workflow is allowed as normal operating mode.
- No ambiguous row grouping is allowed for completion semantics.

### Mandatory next correction
- Canonize the runtime row semantics model.
- Keep the probe-registry model as mandatory architecture.
- Bind every emitted row to an explicit `row_kind` and `semantic_scope`.
- Refactor `collect_runtime.py` and export artifacts to publish semantically typed rows.
- Keep `Canon -> DH -> UI` intact, but eliminate semantic ambiguity in runtime consumption.

<!-- /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 are the current runtime-contract base in force:

- `/opt/devon/canon/runtime_expected_manifest.json`
- `/opt/devon/canon/runtime_probe_registry.json`
- `/opt/devon/bin/build_runtime_contracts.py`

Operational reading:
- `runtime_expected_manifest.json` is the expected-runtime manifest.
- `runtime_probe_registry.json` is the probe registry.
- `build_runtime_contracts.py` is the builder/compiler that generates these contracts.

Rule now fixed:
- Do not invent a parallel canonical file when the contract base already exists materially in Devon.
- Any semantic/runtime correction must start from these files first.

## 1. MEMORY

### 1.1 Project Identity
- Devon is the cognitive development control plane of the YEFF architecture.
- Waresite server hosts the canonical documentation, Documentation Hub, and Operational UI.
- Devon server is the origin of real runtime, host, container, and execution data.
- The Operational UI does not define truth. It validates and exposes canonical truth.

### 1.2 Canonical References
- Canonical root: `/home/yeff/public_html/devon/panel/data/master_architecture_index.md`
- Canonical child-files: markdown and JSON artifacts referenced by the canonical root
- Canonical contracts: JSON/YAML files consumed by the Documentation Hub and Operational UI
- Canonical continuity file: `/home/yeff/public_html/devon/panel/data/devon_continuity.md`

### 1.3 Fixed Rules
- Evidence first, patch after.
- No guessing.
- No fake status or fake progress.
- Allowed status model is evidence-based and boolean.
- If something does not exist observably, the only allowed status is `MISSING`.
- Operational UI validates canonical contracts. It does not invent architecture.
- Waresite hosts canonical documentation and UI.
- Devon hosts real runtime and operational execution.
- Any new operational discovery must follow canonical expansion order.
- Canonical expansion order is mandatory: `Canon -> DH -> UI`.

### 1.4 Canonized Decisions
- The project truth is defined by canonical documentation, not by chat memory.
- `master_architecture_index.md` remains the canonical root.
- `devon_continuity.md` is the canonical continuity layer between chats.
- The continuity model is divided into two macrosections: `MEMORY` and `TODO`.
- The Operational UI is the operational validation layer, not the source of truth.
- Any new item discovered during server installation/configuration must be canonized before entering DH or UI.

### 1.5 Completed Milestones
- Documentation Hub baseline is already established.
- Operational UI baseline has been finalized as current operational reference.
- The continuity strategy between chats has been defined.
- Canonical expansion flow has been defined.
- Waresite has been defined as the canonical documentation host.
- Devon has been defined as the real runtime source.

### 1.6 Stable Context
- There are two distinct servers in this architecture:
  - Waresite: canonical documentation, DH, Operational UI
  - Devon: runtime origin, host state, containers, execution
- Server work must converge to canon already defined in Waresite.
- Canon must always lead implementation.

## 2. TODO

### 2.1 Current Focus
- Replace ambiguous UI/runtime reading with a sovereign Devon-side semantic publication model.
- Canonize the runtime probe-registry pattern as mandatory architecture.
- Canonize the runtime row semantics contract as mandatory architecture.
- Prepare the collector refactor from hardcoded runtime logic to registry-driven, semantically typed publication.
- Preserve existing `/opt/devon` runtime, export and bridge assets during the redesign.

### 2.2 Open Operational Fronts
- Define the canonical runtime probe registry artifact and its schema.
- Define the canonical runtime row semantics artifact and its schema.
- Bind every observable stage/subcategory/item to a deterministic probe rule.
- Bind every emitted runtime row to explicit semantic type and counting boundary.
- Refactor `collect_runtime.py` to execute the registry instead of per-case hardcoded logic.
- Stop any workflow where Waresite UI must be patched just to recognize an already-installed Devon component.
- Stop any workflow where Waresite UI must guess row meaning from loose grouping.
- Keep sync/export bridge stable while the collector model is upgraded.

### 2.3 Active Blockers
- Runtime publication is still partially hardcoded in `collect_runtime.py`.
- UI/runtime alignment still depends on case-specific downstream adjustments.
- There is no sovereign registry-driven runtime publication contract yet.
- There is no sovereign runtime row semantics contract yet.
- Current runtime granularity is incomplete for several stage/subcategory views.
- Current row grouping still allows semantic mixing between rollup rows and item rows.
- This creates operational drag and wastes time/energy during Devon server setup.

### 2.4 Next Operational Step
- The next technical deliverable is not another UI patch.
- The next technical deliverable is to evolve the existing Devon contract base, not invent a parallel contract base.
- Start from `/opt/devon/canon/runtime_expected_manifest.json`.
- Start from `/opt/devon/canon/runtime_probe_registry.json`.
- Start from `/opt/devon/bin/build_runtime_contracts.py`.
- The next chat must start from the runtime publication architecture problem, not from another installation micro-fix.
- Waresite UI must remain consumer-only while Devon becomes the complete runtime publisher.
- UI completion semantics must only be computed from semantically typed rows emitted by Devon.

### 2.5 Deferred Items
- Any DH/UI reflection not yet required for immediate continuity use.
- Any runtime/service component not yet evidenced on the Devon server.
- Any UI expansion for components that are not yet canonized.

### 2.6 Devon Host Real Status
#### 2.6.1 Observed Host Baseline
- Hostname observed: `Devon` / `vmi2858754`
- OS observed: Ubuntu 22.04.5 LTS
- Kernel observed: Linux 5.15.0-170-generic
- Architecture observed: x86-64
- CPU observed: 6 vCPU
- Memory observed: 11 GiB RAM
- Disk observed: 100 GB total with approximately 94 GB available
- Current exposed listening service observed: SSH on port 22 only

#### 2.6.2 Observed Security/Network Status
- Firewall status observed: `active`
- UFW policy observed: `deny (incoming), allow (outgoing), disabled (routed)`
- Allowed inbound rule observed: `22/tcp`
- iptables default policy observed: `INPUT DROP`, `FORWARD DROP`, `OUTPUT ACCEPT`
- Reverse proxy observed: `MISSING`
- TLS baseline observed: `MISSING`

#### 2.6.3 Observed Tooling Status
- Python3: `PRESENT`
- Git: `PRESENT`
- Curl: `PRESENT`
- Docker: `MISSING`
- Docker Compose: `MISSING` by consequence of Docker absence
- Nginx: `MISSING`

#### 2.6.4 Observed Devon Paths and Assets
- `/opt/devon`: `PRESENT`
