# Devon Execution & Monitoring Panel Contract

## Status

Status: CANONICAL_DRAFT  
Scope: Execution & Monitoring Panel  
Source layer: Documentation Hub JSON mirror  
Runtime authority: canon, FSM, runtime artifacts and material evidence  
LLM authority: none  

## Purpose

This contract defines the transition from the completed Documentation Hub to the future Devon Execution & Monitoring Panel.

The Documentation Hub is now the architectural-operational model. The JSON mirror under `/home/yeff/public_html/devon/docs/json` is the machine-readable projection of that model. The Execution & Monitoring Panel must consume those contracts without inventing state, progress, evidence, readiness or authority.

The panel is not a documentation renderer. The panel is the operational interface that will expose, validate, block, route and monitor the execution architecture derived from the Documentation Hub, canon and runtime evidence.

## Validated DH Baseline

The current validated baseline is:

- DH renderer: `/home/yeff/public_html/devon/docs/index.php`
- DH JSON mirror root: `/home/yeff/public_html/devon/docs/json`
- DH JSON index: `/home/yeff/public_html/devon/docs/json/_hub_json_index.json`
- validated docs: 152
- total JSON files: 153
- missing phase docs: 0
- invalid JSON files: 0
- missing directory: absent
- generated phases: phase-01 through phase-14
- exported backup: `devon_dh_index_json_backup_20260531_011019.tar.gz`
- exported checksum: `devon_dh_index_json_backup_20260531_011019.sha256`

The DH baseline must not be regenerated, rewritten or structurally changed during the first panel contract implementation.

## Source of Truth Hierarchy

The panel must respect the following hierarchy:

1. Material runtime evidence from the server.
2. Canon files under `/home/yeff/public_html/devon/canon`.
3. DH JSON mirror under `/home/yeff/public_html/devon/docs/json`.
4. DH renderer under `/home/yeff/public_html/devon/docs/index.php`.
5. Validated backups and audit checkpoints.
6. Operator input.
7. LLM interpretation.

The LLM never outranks material evidence, canon, DH JSON or runtime artifacts.

## Non-Negotiable Rules

The panel must not calculate fake progress.

The panel must not infer PASS, FAIL or MISSING from visible labels, UI position, hardcoded percentages or category names.

The panel must not treat a rendered card as evidence of runtime readiness.

The panel must not convert missing runtime data into PASS.

The panel must not promote a phase, category, bucket, technology, runtime service or execution gate without material evidence.

The panel must not mutate the DH while implementing panel behavior.

The panel must not create a second truth layer inside the UI.

The panel must not decide. The panel displays, requests, routes and records. FSM and canon decide.

## Required Inputs

The first implementation layer of the panel must read:

- `/home/yeff/public_html/devon/docs/json/_hub_json_index.json`
- `/home/yeff/public_html/devon/docs/json/phase-*/*.json`
- `/home/yeff/public_html/devon/canon`
- `/home/yeff/public_html/devon/panel/data`
- future runtime artifacts generated by the Devon runtime layer

Known runtime and panel data candidates include:

- `/home/yeff/public_html/devon/panel/data/runtime_status.json`
- `/home/yeff/public_html/devon/panel/data/project_progress.json`
- `/home/yeff/public_html/devon/panel/data/runtime_snapshot.json`
- `/home/yeff/public_html/devon/panel/data/canonical_matrix_v1.json`
- `/home/yeff/public_html/devon/panel/data/subcategory_pipelines.json`

Any missing file must be treated as MISSING, not silently replaced by inferred UI state.

## Panel MVP Contract

The first panel MVP must provide:

1. Phase navigation from DH JSON index.
2. Category registry from DH JSON files.
3. Bucket visibility per category.
4. Technology requirements visibility when present.
5. PASS, FAIL and MISSING display only from accepted sources.
6. Missing evidence display.
7. Runtime artifact presence display.
8. Canon reference display.
9. Blocking matrix placeholder fed by canon or runtime, not UI inference.
10. Execution readiness placeholder.
11. Audit checkpoint visibility.
12. No production action.
13. No shell execution.
14. No deploy action.
15. No approval mutation.
16. No automatic promotion.

The MVP is a read and validation surface before it becomes an execution surface.

## Layer Separation

The panel must be built in layers.

### Layer 1: Contract Reader

Reads DH JSON, validates structure, lists phases, categories, buckets and technology requirements.

### Layer 2: Canon Binder

Connects category and phase contracts to canon files and expected runtime artifacts.

### Layer 3: Runtime Binder

Reads material runtime outputs and exposes PASS, FAIL and MISSING without local guessing.

### Layer 4: Evidence Viewer

Shows which file, command output, JSON, backup, log or runtime artifact supports each status.

### Layer 5: Blocking Matrix

Shows what is blocked and why, based on canon, FSM rule output or runtime evidence.

### Layer 6: Execution Gateway

Only after prior layers exist, the panel may request actions through controlled tools. The UI never executes directly.

### Layer 7: Monitoring Surface

Adds live service, job, queue, backup, heartbeat, incident and failover visibility.

## Status Semantics

Allowed status values are:

- PASS
- FAIL
- MISSING

PASS means the required evidence exists, is readable, is structurally valid and satisfies the contract.

FAIL means the required evidence exists but violates the contract.

MISSING means required evidence does not exist, cannot be read, cannot be resolved or has not been implemented.

Unknown must not be converted to PASS.

Pending must not be converted to PASS.

Planned must not be converted to PASS.

Rendered must not be converted to PASS.

## Progress Semantics

Progress must not be hand-coded.

Progress must not be calculated by card count alone.

Progress must not be calculated by number of rendered items alone.

Progress must come from the canonical runtime model once that model exists.

Until the canonical runtime model exists, panel progress must be MISSING.

## Technology Requirements Semantics

The field `technology_requirements` is the machine-readable technology contract for each category.

The panel may display technology requirements immediately.

The panel may validate technology requirements only when each item provides:

- technology
- required_for
- required_by_phase
- required_by_category
- required_by_buckets
- expected_version
- validation_command
- evidence_path
- status_source
- blocking_if_missing
- failure_impact

Technology mentioned only in prose must not be treated as a validated requirement.

Technology without material evidence must be MISSING.

Technology present but invalid must be FAIL.

Technology required and missing must block completion when `blocking_if_missing=true`.

## Evidence Semantics

Every displayed operational status must point to evidence.

Accepted evidence types include:

- current server file
- JSON contract
- canon file
- runtime artifact
- command output
- validation result
- backup file
- checksum
- log
- audit checkpoint
- restore test evidence
- FSM decision output
- approval record

Chat memory is not evidence.

Visible UI state is not evidence.

A category appearing in the menu is not evidence of completion.

## Execution Semantics

The first panel version must not execute server actions.

Execution requires a later contract with:

- Tool Registry
- FSM decision output
- risk classification
- approval requirement
- backup requirement
- rollback requirement
- timeout
- audit trail
- validation plan
- post-action evidence

No button in the UI may bypass those contracts.

## Monitoring Semantics

Monitoring must come from runtime artifacts and live service evidence.

The panel may expose:

- host status
- container status
- runtime status
- job status
- queue status
- backup status
- heartbeat status
- incident status
- failover status
- mirror status
- resource pressure
- validation status

If a runtime artifact does not exist, the corresponding section is MISSING.

## First Implementation Boundary

Allowed in the first implementation:

- read DH JSON index
- read category JSONs
- list phases
- list categories
- list buckets
- list technology requirements
- list missing runtime bindings
- display MISSING where runtime is absent
- create panel contract readers
- create validation reports

Blocked in the first implementation:

- editing DH
- regenerating DH JSON
- changing canonical DH text
- calculating project completion
- calculating fake phase progress
- executing shell commands from UI
- deploying
- restarting services
- modifying production
- mutating runtime truth
- inventing fallback status
- creating parallel truth files

## Failure Conditions

The panel contract fails if:

- UI calculates truth locally.
- UI promotes MISSING to PASS.
- UI hides absent evidence.
- UI treats DH text as runtime proof.
- UI treats JSON existence as operational completion.
- UI mutates DH during panel work.
- UI bypasses canon.
- UI bypasses FSM.
- UI accepts category names as ids.
- UI uses visible labels instead of technical ids.
- UI creates progress without canonical runtime source.
- UI executes actions without Tool Registry and FSM gate.

## Completion Criteria for Panel Contract MVP

The MVP contract is complete when:

- the panel reads `_hub_json_index.json`;
- all 152 docs are visible or countable from the JSON mirror;
- phases 01 through 14 are resolved from JSON;
- no missing phase directory exists;
- category JSON parsing returns zero invalid files;
- the panel distinguishes DH contract status from runtime status;
- runtime status remains MISSING where runtime evidence is absent;
- technology requirements are displayed but not falsely validated;
- no DH file is changed;
- no JSON file is regenerated;
- no production action exists;
- no execution action exists;
- all outputs are auditable.

## Next Required Evidence Before Any Panel Patch

Before changing panel files, collect evidence for:

- `/home/yeff/public_html/devon/panel`
- `/home/yeff/public_html/devon/panel/index.html`
- `/home/yeff/public_html/devon/panel/assets/js`
- `/home/yeff/public_html/devon/panel/assets/css`
- `/home/yeff/public_html/devon/panel/data`
- `/home/yeff/public_html/devon/docs/json/_hub_json_index.json`
- `/home/yeff/public_html/devon/canon`

No panel patch is allowed before this evidence exists.