===== 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 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. ### 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 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-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. ### 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`