Phenomenological Workspace monorepo

This repository contains the full phase-by-phase implementation of the conversation operating system.

🟧 🟫 🟧 🟫 🟧

Workspace Map 🟧🟫

• crates/phenom-core: phenomenological system semantics, learning, empirical and alignment layers
• crates/phenom-storage: 5-tier storage and lifecycle movement
• crates/phenom-log: append-only event sourcing with branching/merge semantics
• crates/phenom-snapshot: .phen snapshot format and compatibility
• crates/phenom-graph: graph structure, traversal, references, viewport operations
• crates/phenom-compression: compression and expand-on-demand behavior
• crates/phenom-render: viewport-capped WGPU renderer with pre-tokenized text blocks and glyph-run submission
• crates/phenom-noumenon: NOUMENON hyperfield DB layer returning RenderSlice bundles for viewport queries
• crates/phenom-ui: workspace model, command routing, desktop contract surfaces
• crates/phenom-crdt: deterministic CRDT sync model
• crates/phenom-net: rendezvous, convergence, and coherence networking
• crates/phenom-ingest: corpus ingestion pipeline for batch text processing
• apps/workspace-desktop: desktop host application

phenom-ui Internal Layout 🟧

Navigation note: the Phase 57 phenom-ui decomposition happened within the same crate to avoid crate churn.

• crates/phenom-ui/src/workspace_model.rs: workspace/model construction and stateful runtime helpers
• crates/phenom-ui/src/command_router.rs: command parsing and routing helpers
• crates/phenom-ui/src/desktop_bridge.rs: typed desktop/Qt bridge contracts and JSON bridge entrypoints
• crates/phenom-ui/src/runtime_status.rs: stable UI/runtime snapshot and status types
• crates/phenom-ui/src/task_runtime.rs: ingestion/model-lifecycle/task-adjacent runtime helper types

Contributor Expectations 🟧

• Determinism first: new runtime behavior must stay replayable and bounded in the default headless path.
• Reason codes required: policy decisions, degraded modes, and benchmark/report states need stable machine-readable reason codes plus readable detail.
• Observability is part of the feature: new runtime surfaces must expose health, diagnostics, audit, or trust-report visibility instead of hiding state in logs or implicit branches.
• Policies must stay auditable: new commands and command kinds need explicit runtime-policy mappings so --policy-audit-json does not regress into fallback-only coverage.

Quick Start 🟧

# build + run desktop shell
cargo run -p workspace-desktop -- ./phenom-data

# run with Ollama backend
cargo run -p workspace-desktop -- --model ollama:llama3.2 ./phenom-data

Desktop Baseline 🟧

• Plain chat is the guaranteed baseline: the center pane stays on the normal chat list until the runtime reports chat_viewport_readiness.selected_mode = advanced_texture.
• Advanced viewport is readiness-gated: the texture/WGPU path only activates when the desktop state explicitly reports ready = true; renderer/backend requests alone are not treated as proof.
• Composer contract: Enter sends, Shift+Enter inserts a newline, and whitespace-only prompts are ignored.
• Status chips meanings: Runtime shows attached vs fallback simulation, Asset shows whether a model artifact/spec is unconfigured, upgrading, or artifact-ready, Chat shows whether a backend is active/ready/pending/fallback, Renderer shows the active backend, and Viewport shows whether the app is on plain chat or advanced texture.
• Model truth model: configured or upgraded is not the same as live inference. Chat only uses a backend once model_runtime_status.active_for_chat = true; otherwise fallback remains active with an explicit reason code/detail.
• Local GGUF attach: use Browse GGUF in the Models panel for local .gguf files, or type ollama:<model> for remote activation. Missing local GGUF paths now fail fast with model_invalid_path instead of silently attaching a stub backend.
• Assistant provenance: assistant turns now carry structured backend provenance in the desktop inspector and in --qt-command-json output, so you can verify whether a response came from fallback simulation or an active backend.
• Safe startup fallback: the standalone QML launcher now auto-enables fallback simulation when no Rust bridge is attached, so the app degrades into an explicit offline/plain-chat baseline instead of a blank center pane.

# inspect desktop state headlessly
cargo run -p workspace-desktop -- --qt-state-json

# inspect model activation/readiness headlessly
cargo run -p workspace-desktop -- --model-health-json

# prove prompt submission through the desktop command path
cargo run -p workspace-desktop -- --qt-command-json '{"kind":"process_prompt","prompt":"hello from the desktop baseline"}'

# prove the desktop headless path with an explicit model runtime
cargo run -p workspace-desktop -- --model stub-model --qt-command-json '{"kind":"process_prompt","prompt":"headless model routing check"}'

NOUMENON Desktop Loop 🟧

# run desktop with NOUMENON segmented persistence
cargo run -p workspace-desktop -- ./phenom-data

# corpus + query loop in the app:
# 1) use "Import..." to ingest a folder of .md/.txt files
# 2) use "Query..." + Enter to run retrieval
# 3) use Prev/Next paging and the NOUMENON status panel for counts/mode

# NOUMENON data location (default segmented mode)
./phenom-data/noumenon-db

# benchmark report (NOUMENON vs baseline vector retrieval)
cargo run -p phenom-noumenon --example bench_report

# optional external judge hook (reads JSON from stdin, prints noumenon|baseline|tie)
NOUMENON_BENCH_JUDGE_CMD="./scripts/judge.sh" \
  cargo run -p phenom-noumenon --features bench_judge --example bench_report

Benchmark outputs: target/noumenon-bench/bench_report.json and target/noumenon-bench/bench_report.md Runtime benchmark governance: cargo run -p workspace-desktop -- --benchmark-report-json ./phenom-data emits a versioned JSON report over NOUMENON query latency, context assembly latency, scheduler queue construction, task run-loop step overhead, and event-log write overhead, compared against docs/benchmarks/platform_runtime_baseline.json.

Golden Path (CLI) 🟧

# workflow 1: conversation loop (headless, no Qt runtime required)
cargo run -p workspace-desktop -- --demo --cmd "/stats" ./phenom-data-demo
cargo run -p workspace-desktop -- --demo --cmd "hello" ./phenom-data-demo

# workflow 2: ingestion loop
printf "phase55 demo corpus\nRootStream::AttractorInvariantSnapshot\n" > /tmp/phase55-demo.txt
cargo run -p workspace-desktop -- --demo --cmd "/ingest /tmp/phase55-demo.txt phase55:demo" ./phenom-data-demo
cargo run -p workspace-desktop -- --demo --cmd "/stats" ./phenom-data-demo

# workflow 3: automation/status loop
cargo run -p workspace-desktop -- --demo --status-json ./phenom-data-demo
cargo run -p workspace-desktop -- --cmd-json '{"kind":"snapshot_state"}'
cargo run -p workspace-desktop -- --bridge-cmd-json '{"protocol_version":1,"request_id":"demo","command":{"kind":"snapshot_state"}}'

# command script mode (blank lines + # comments ignored)
cargo run -p workspace-desktop -- --demo --cmd-file ./scripts/commands.txt ./phenom-data-demo

# full reproducible 3-loop demo runner
scripts/golden_path_demo.sh

Golden path integration tests: cargo test -p workspace-desktop --test phase55_golden_path_cli

Phase 55 progress notes: docs/program/PHASE55-GOLDEN-PATH-OPERATOR-TOOL.md Status contract note: --status-json now reports module gating through a single canonical diagnosis path in phenom-ui. Demo mode note: --demo now applies safe defaults (detaches model backend, disables phase36 panel routing, and clamps viewport budget). Phase 55 status: Complete.

Phase 56 Progress Notes 🟧

• 2026-03-06 56.1.1 Added the stable Task JSON contract in apps/workspace-desktop/src/tasks.rs with deterministic serialization coverage.
• 2026-03-06 56.1.2 Added the disk-backed TaskStore with deterministic workspace_data/tasks/t-XXXX.json persistence and monotonic local task IDs.
• 2026-03-06 56.1.3 Extended the headless Phase 55 CLI with /task create, /task list, /task show, /task complete, and optional /task fail.
• 2026-03-06 56.2.1 Added a public Noumenon memory-event helper and replay API on the existing segmented log path for task/tool/artifact lifecycle notes.
• 2026-03-06 56.2.2 Hooked task create/complete/fail lifecycle changes into Noumenon memory while keeping task JSON as the canonical persisted state.
• 2026-03-06 56.3.1 Added the stable versioned AgentEvent JSON contract for append-only task execution logs.
• 2026-03-06 56.3.2 Added append-only JSONL persistence for per-task execution logs at workspace_data/tasks/<task_id>.events.jsonl.
• 2026-03-06 56.3.3 Wrapped the headless command entrypoints so command execution now emits persistent task_state_changed, tool_call, tool_result, error, and artifact events.
• 2026-03-06 56.3.4 Mirrored every appended AgentEvent into Noumenon as a compact memory summary while keeping the full structured payload only in JSONL.
• 2026-03-06 56.4.1 Added --run-loop for headless execution of pending persistent tasks.
• 2026-03-06 56.4.2 Stored task commands initially executed automatically in deterministic task-id order when dependencies were complete; that Phase 56 baseline was later superseded by the Phase 57 scheduler.
• 2026-03-06 56.4.3 Added /task replay <task_id> to print the stored JSONL audit trail headlessly.
• 2026-03-06 56.5.1 Added the workspace artifacts/ directory contract for persistent task outputs.
• 2026-03-06 56.5.2 Artifact references from tracked task execution now emit both JSONL artifact_written events and compact Noumenon artifact_generated summaries.
• 2026-03-06 56.6 Added integration coverage for task lifecycle persistence, restart persistence, automation loop execution, and Noumenon memory smoke validation.
• 2026-03-06 56.7 Added README task-system usage sections and docs/TASK_SYSTEM.md.

Phase 57 Progress Notes 🟧

• 2026-03-06 Step 0 added the Phase 57 roadmap to microtasks.md and opened docs/program/PHASE57-DECISION-RUNTIME-POLICY-GOVERNED-SCHEDULER-STRUCTURAL-HARDENING.md for incremental implementation notes.
• 2026-03-06 57.1.1 Added deterministic task classification and reason reporting in apps/workspace-desktop/src/tasks.rs, and /task list now shows whether each task is runnable, dependency-blocked, policy-blocked, complete, failed, or invalid.
• 2026-03-06 57.1.2 Added backwards-compatible task priority metadata plus an inspectable deterministic scoring model so runnable tasks can be ordered by explicit priority, age, dependency readiness, retry penalty, status, and pinned urgency.
• 2026-03-06 57.1.3 Added explicit scheduler queue/select APIs and switched --run-loop to consume scheduler decisions with scores, classifications, reasons, and dependency summaries instead of doing a naive first-pending scan.
• 2026-03-06 57.2.1 Added a stable policy model in apps/workspace-desktop/src/policy.rs covering command categories, normalized command prefixes, JSON command kinds, execution surfaces, and deterministic allow/deny style decisions with explicit reasons.
• 2026-03-06 57.2.2 Added default policy sets for interactive CLI, headless CLI, command files, automation-loop execution, and Qt JSON surfaces, then enforced them in workspace-desktop so blocked commands now fail with explicit policy reasons.
• 2026-03-06 57.2.3 Added /policy explain '<command>' plus automation-policy diagnostics in /task list and /task show, so command allowance/denial is inspectable without trial execution.
• 2026-03-06 57.3.1 Added a Noumenon task-context helper that composes bounded task queries from task metadata, recent activity, and replayed memory summaries, then reuses the existing context compiler to return stable slice bundles for planning.
• 2026-03-06 57.3.2 Added stable tasks/<task_id>.plan.json planning artifacts that capture the chosen context query, context summaries and slice ids, chosen command, scheduler reason, policy result, and execution intent before task execution.
• 2026-03-06 57.3.3 Upgraded the run-loop planner to make explicit deterministic execute, defer, and fail decisions from dependency readiness, policy severity, and bounded Noumenon context availability, while keeping deferred tasks replayable and pending.
• 2026-03-06 57.4.1 Reworked --run-loop to rebuild queue analysis with automation-loop policy blocks on every pass, then select, plan, and execute or defer tasks through the deterministic scheduler/planner path rather than a naive pending-task scan.
• 2026-03-06 57.4.2 Added bounded headless loop controls: --max-steps, --max-failures, and --run-task, keeping the existing --run-loop surface backwards compatible while making automation safer to constrain.
• 2026-03-06 57.4.3 Added /task queue so operators can inspect the actual scheduler order, scores, dependency summaries, and policy-block reasons without running the loop.
• 2026-03-06 57.5.1 Extended the task event stream with explicit scheduler_decision, planner_decision, policy_decision, and task_deferred events so JSONL replay shows the runtime’s decision path instead of collapsing it into generic tool-result entries.
• 2026-03-06 57.5.2 Mirrored compact decision summaries into Noumenon using the existing event-memory bridge, keeping full structured detail in JSONL/plan artifacts while making blocked/deferred/executed reasoning queryable through memory.
• 2026-03-06 57.6.1 Added headless scheduler determinism integration coverage in apps/workspace-desktop/tests/phase57_decision_runtime.rs, proving stable queue ordering and explicit dependency-blocked reasons from persisted task JSON plus /task queue.
• 2026-03-06 57.6.2 Added policy enforcement integration coverage for /policy explain, automation-loop denial, and safe allowed commands, and tightened --run-task so targeted runs terminate deterministically after one evaluated task.
• 2026-03-06 57.6.3 Added a planning-trace smoke test that seeds Noumenon memory, runs the headless loop, verifies tasks/<task_id>.plan.json, and asserts replayable scheduler/policy/planner decision events.
• 2026-03-06 57.6.4 Added /eval runtime, a stable JSON evaluation report for queue order, blocked reasons, completed tasks, failures, and deferred work, and kept it side-effect free by skipping implicit command-task creation for inspection commands.
• 2026-03-06 57.7.1 Started the internal phenom-ui split by introducing dedicated workspace_model, runtime_status, task_runtime, command_router, and desktop_bridge modules, then moved the shared UI/runtime status types and WorkspaceModel shell out of lib.rs.
• 2026-03-06 57.7.2 Moved UiCommand and the parser helpers into crates/phenom-ui/src/command_router.rs, leaving lib.rs as a thinner facade that re-exports the stable command surface instead of owning the parser implementation inline.
• 2026-03-06 57.7.3 Moved the runtime-status structs, ingestion/model-lifecycle helper types, and WorkspaceModel construction/state helpers into runtime_status.rs, task_runtime.rs, and workspace_model.rs, shrinking crates/phenom-ui/src/lib.rs to a smaller orchestration facade while preserving the public API through re-exports.
• 2026-03-06 57.7.4 Moved the bridge result/texture contracts, command-kind labeling helper, and JSON bridge entrypoint into crates/phenom-ui/src/desktop_bridge.rs, and relaxed the generic typed-bridge policy fallback so the local bridge runtime stays usable while noumenon_import_folder still requires confirmation.
• 2026-03-06 57.8.1 Audited the phase-coded phenom-core modules and documented the domain mappings phase36 -> augmentation_runtime, phase37 -> diagnostic_runtime, phase38 -> field_dynamics, and phase39 -> agency_runtime before applying compatibility-preserving renames.
• 2026-03-06 57.8.2 Renamed the canonical phenom-core module files to augmentation_runtime, diagnostic_runtime, field_dynamics, and agency_runtime, kept phase36 through phase39 as compatibility wrappers, and verified the rename with cargo test -q -p phenom-core.
• 2026-03-06 57.8.3 Updated the phenom-core crate docs and Phase 57 notes to describe these runtime families by domain name, keeping phase36 through phase39 only as compatibility/history language instead of conceptual runtime vocabulary.
• 2026-03-06 57.9.1 Added docs/GLOSSARY.md, a contributor-oriented map of the major crates and metaphor-heavy runtime families with plain-language roles and primary responsibilities.
• 2026-03-06 57.10.1 Added a gated live-backend integration test at crates/phenom-core/tests/phase57_live_backend_ollama.rs that opts into a real Ollama path only when PHENOM_TEST_OLLAMA=1 is set, while keeping default test runs deterministic.
• 2026-03-06 57.10.2 Added docs/LIVE_BACKEND_TESTS.md and linked it from the main docs surface so contributors can intentionally opt into the Ollama-backed smoke lane without confusing it with the default deterministic test path.
• 2026-03-06 57.11.1 Audited the most obviously stub-like surfaces and documented the low-risk list: phenom-snapshot is a three-line re-export shell around format.rs, while phenom-core::phase36 through phase39 are now explicit compatibility wrappers pointing at the new domain modules.
• 2026-03-06 57.11.2 Clarified crates/phenom-snapshot by adding crate-level docs plus a local README that state it is an intentionally narrow snapshot-format seam whose real implementation lives in src/format.rs.
• 2026-03-06 57.12.1 Expanded the README with decision-runtime operator sections covering scheduler-driven headless execution, policy inspection, queue inspection, replayable planning traces, the contributor glossary, and the gated live-backend lane.
• 2026-03-06 57.12.2 Added docs/DECISION_RUNTIME.md, the stable contract note for scheduler analysis, priority scoring, policy outcomes, Noumenon task-context selection, planning traces, decision events, and runtime evaluation.
• 2026-03-06 Final verification aligned crates/phenom-ui/tests/phase34_live_bridge_runtime.rs with the documented max viewport radius of 32 so the full workspace test pass reflects the current UI contract instead of a stale Phase 34 assumption.
• 2026-03-06 57.13.1 Finalized the root roadmap metadata by adding Phase 57 to the Phase Index, marking Phase 57 complete in microtasks.md, and opening Subphase 57.13 for the final consistency pass.
• 2026-03-06 57.13.2 Audited the Phase 57 CLI docs against apps/workspace-desktop/src/main.rs, then corrected the task-system/runtime examples so the documented /task, /policy explain, --cmd-file, --cmd-json, --bridge-cmd-json, --status-json, and bounded --run-loop surfaces match the real handlers.
• 2026-03-06 57.13.3 Tightened docs/DECISION_RUNTIME.md to match the real scheduler/planner code paths, including the queue classification order, runnable selection rule, and the exact compact Noumenon memory-summary categories mirrored from task lifecycle and decision events.
• 2026-03-06 57.13.4 Expanded docs/GLOSSARY.md so each major crate entry now includes a related conceptual paper/family column alongside the plain-language role and main responsibility, covering the full Phase 57 contributor-facing crate map.
• 2026-03-06 57.13.5 Clarified the live-backend lane in the README with the required env vars and the stub-first default, keeping docs/LIVE_BACKEND_TESTS.md as the detailed reference for the gated Ollama smoke path.
• 2026-03-06 57.13.6 Updated docs/TASK_SYSTEM.md so it now documents the Phase 57 decision-event kinds, /task queue replay/inspection surfaces, and the difference between canonical per-task JSONL history and compact Noumenon semantic memory summaries.
• 2026-03-06 57.13.7 Added a contributor-facing phenom-ui internal layout note to the README and glossary, making the new workspace_model.rs, command_router.rs, desktop_bridge.rs, runtime_status.rs, and task_runtime.rs seams easy to navigate while stating clearly that the split stayed within the same crate.
• 2026-03-06 57.13.8 Ran the final Phase 57 consistency sweep, clarifying the remaining historical Phase 56 task-order note as superseded by the scheduler, tightening wording across the current docs, and stabilizing the PHENOM_LLM_DEBUG env-var test harness so cargo test -q remains reliable.
• 2026-03-06 57.14.1 Added deterministic planning-quality tiers (minimal, contextual, evidence_checked) so the run-loop can choose bounded Noumenon context budgets without leaving the inspectable Phase 57 planning-trace path.
• 2026-03-06 57.14.2 Added bounded task-memory context selection on top of the existing Noumenon memory log, so similar prior task failures/completions can influence planner decisions and appear in replayable planning reasons.
• 2026-03-06 57.14.3 Added normalized decision reason codes across scheduler, planner, policy, queue, and planning-trace surfaces so repeated runs can be compared mechanically without losing readable operator-facing explanations.
• 2026-03-06 57.14.4 Added conflict-aware defer heuristics so contextual and evidence-checked plans now wait instead of acting when bounded memory/evidence is sparse, contradictory, or too weak.
• 2026-03-06 57.14.5 Added deterministic headless capability scenarios covering safe completion, dependency deferral, policy blocking, and memory-informed retry behavior, all through the existing run-loop and planning-trace path.
• 2026-03-06 57.14.6 Added replayable deferred_by_budget handling so --max-steps and --max-failures exits leave explicit task_deferred records for runnable work skipped by the run budget.
• 2026-03-06 57.14.7 Extended /task show into a single JSON inspection envelope that includes the current scheduler snapshot, automation-policy decision, latest planning trace, and latest deferred reason alongside the persisted task fields.
• 2026-03-06 57.14.8 Upgraded /eval runtime to evaluation_version: 2, adding side-effect-free capability-quality aggregates for planning tiers, planner reasons, execution intent, and deferred-reason totals.
• 2026-03-07 57.16.1 Added explicit typed runtime contracts in apps/workspace-desktop/src/runtime_contracts.rs; /health and --health-check now emit RuntimeHealthReport version 2 with typed readiness, degraded reasons, policy-enforcement status, migration compatibility, and benchmark metadata instead of loose status strings.
• 2026-03-07 57.16.2 Added deterministic degraded-mode behavior: NOUMENON now falls back to explicit in-memory mode when segmented startup fails, corrupt task event logs are isolated instead of aborting replay/context gathering, and failed snapshot exports now return artifact_write_failed after cleaning up partial output.
• 2026-03-07 57.16.3 Added executable runtime invariants: task-state transitions are now validated before persistence, AgentEvent logs reject invalid versions or missing contract fields, planning traces validate required fields on write/load, and the run-loop refuses to execute work if a denied policy decision somehow reaches an execute intent.
• 2026-03-07 57.16.4 Added --diagnostics-export <path>, which writes a stable versioned diagnostic bundle containing runtime health/readiness, recent tasks and AgentEvent tail, policy configuration summary, migration compatibility, benchmark metadata, and runtime version identifiers.
• 2026-03-07 57.16.5 Added --benchmark-report-json, a stable benchmark-governance report that compares five headless runtime measurements against the committed docs/benchmarks/platform_runtime_baseline.json snapshot and flags missing baselines or regressions with typed statuses and reason codes.
• 2026-03-07 57.16.6 Added resilience scenario coverage for corrupt event-log isolation, migration incompatibility, denied run-loop actions, degraded NOUMENON fallback, and requested live-backend failures; the health surface now reports live_backend_unavailable explicitly when a requested backend cannot be opened.
• 2026-03-07 57.16.7 Added --policy-audit-json, which emits a stable governance report over known command mappings, per-surface rule counts, allow/deny/confirmation totals, exercised commands, default-deny surfaces, and any unmapped command paths.
• 2026-03-07 57.16.8 Added --trust-report-json, a stable service-quality report that rolls up runtime health/readiness, policy enforcement, migration compatibility, governed benchmark status, recent failures/deferred work, warning reason codes, test-coverage indicators, and live-backend availability into one headless JSON review surface.
• 2026-03-07 57.16.9 Added contributor guardrails to the repo docs and rustdoc surface: the new runtime-contract and migration APIs now carry explicit module/docs comments, and the README now states that deterministic behavior, stable reason codes, observability surfaces, and auditable policy mappings are mandatory for new runtime work.
• 2026-03-07 57.17.1 Audited the desktop chat path and documented the current failure mode truthfully: the composer only sends via the button, the center pane defaults into a texture-first viewport path while chatViewportWgpuEnabled starts true, and the bridge/runtime/model fallback state is present in the Qt JSON state but not surfaced strongly enough in the main chat UI.
• 2026-03-07 57.17.2 Recovered the guaranteed desktop baseline by making the plain chat list the default center-pane path until a real Rust wgpu runtime has actually produced a texture payload; cold boot and non-ready renderer states now show the existing chat transcript instead of a blank advanced viewport placeholder.
• 2026-03-07 57.17.3 Added a typed chat_viewport_readiness contract to the desktop Qt state surface so both the Rust workspace model and the QML fallback bridge report explicit texture support, selected viewport mode, readiness, and degraded reasons instead of relying on scattered renderer strings.
• 2026-03-07 57.17.4 Restored basic chat ergonomics in the desktop composer: Enter now submits through the existing guarded prompt path, Shift+Enter inserts a newline, and whitespace-only prompts still do not send.
• 2026-03-07 57.17.5 Added a visible desktop chat-status row and banner so operators can immediately see whether the UI is attached to the real runtime or fallback simulation, whether a model backend is attached or offline, which renderer/backend is active, which viewport mode is selected, and why the chat surface may be degraded.
• 2026-03-07 57.17.6 Added a startup self-check for the Qt desktop path so the pure-QML launcher automatically enables safe fallback simulation when no Rust runtime bridge is attached, and unsupported advanced viewport/model startup assumptions now degrade visibly to the plain-chat offline baseline instead of leaving the center pane blank.
• 2026-03-07 57.17.7 Replaced the old placeholder startup transcript with a deterministic desktop welcome that keeps the chat workspace visibly non-empty and updates the first system line to describe the real startup mode, whether that is runtime-attached, offline, fallback-simulated, or advanced-viewport-ready.
• 2026-03-07 57.17.8 Added repeatable headless desktop verification coverage around the existing --qt-state-json and --qt-command-json surfaces, proving prompt submission, viewport fallback selection, and runtime/model/renderer state exposure without launching the GUI manually.
• 2026-03-07 57.17.9 Added a focused desktop regression suite that protects the recovered baseline: composer Enter wiring, cold-boot plain-chat fallback, truthful viewport readiness reporting, prompt submission through the Qt command path, and startup fallback/bootstrap contracts in Main.qml and Bridge.js.
• 2026-03-07 57.17.10 Completed the desktop docs/UX consistency sweep: the README, Decision Runtime note, Phase 57 program doc, and desktop workflow guide now all describe the same startup rule set, status meanings, readiness-gated viewport behavior, and headless verification commands.
• 2026-03-07 57.18.1 Audited the current desktop model lifecycle and chat execution path before changing behavior: attach state currently means Workspace.mind exists, upgrade history is real but separate from runtime activation, chat dispatch only branches on mind.is_some(), inference fallback can happen inside process_prompt_with_mind(...), and the desktop UI still conflates configured/attached models with genuinely active chat backends.
• 2026-03-07 57.18.2 Added a typed ModelRuntimeStatus contract in phenom-core and surfaced it through the Rust desktop Qt state, so the workspace now exports explicit configured, artifact_available, activation_pending, active_for_chat, and fallback_active lifecycle information instead of making downstream code infer readiness from model_attached and model_healthy.
• 2026-03-07 57.18.3 Split desktop model visibility into two truths: model asset state and chat backend state. The chat header now shows separate Asset and Chat chips, the model manager panel exposes artifact_available, ready_for_inference, active_for_chat, fallback_active, and configured source/path independently, and fallback QML mode now publishes the same typed model_runtime_status contract instead of collapsing back to optimistic attachment booleans.
• 2026-03-07 57.18.4 Added an explicit activation handoff: attach/load now runs a bounded readiness probe before a backend is marked active_for_chat, local/Ollama failures degrade to typed failed + fallback_active state with explicit reason codes, stub backends are rejected as live chat backends, and the Qt/CLI attach messages now report activation success or failure instead of treating load alone as proof.
• 2026-03-07 57.18.6 Added structured assistant-response provenance: runtime-produced chat turns now carry versioned assistant_provenance plus prompt/assistant node ids through phenom-core, the Qt command JSON surface, and the desktop transcript inspector, and assistant-node provenance now survives snapshot export/import instead of disappearing into freeform fallback text.
• 2026-03-07 57.18.7 Added --model-health-json and the versioned ModelHealthReport, giving operators a stable headless report for configured source/spec, artifact presence, tokenizer/inference readiness, active_for_chat, fallback state, and the exact reason chat is still not using a real backend when activation has not succeeded.
• 2026-03-07 57.18.8 Tightened model attach/upgrade messaging so desktop and CLI surfaces now say model asset configured, model artifact prepared and upgrade recorded, activation succeeded, activation failed, or backend detached after upgrade explicitly, and they always state when fallback simulation remains active instead of implying that download/attach alone made inference live.
• 2026-03-07 57.18.9 Added a .gguf file picker to the desktop model panel and explicit local-path validation for attach, so missing local GGUF files now fail fast with model_invalid_path instead of silently degrading into a stub backend.
• 2026-03-07 57.18.10 Added dedicated headless model-reality verification and fixed the Qt headless --model gap, so --qt-state-json, --qt-command-json, --qt-bridge-state-json, and --qt-bridge-command-json can now exercise a configured model path directly and the regression suite proves fallback routing, explicit stub/non-active reporting, invalid-path errors, and live-vs-fallback provenance switching.
• 2026-03-07 57.18.11 Completed the final model-reality consistency sweep: the README, Decision Runtime note, Phase 57 record, and desktop workflow guide now all describe the same Asset vs Chat status model, active_for_chat activation contract, provenance surface, Browse GGUF expectations, --model-health-json report, and Qt headless --model verification path.

Persistent Tasks 🟧

# create a persistent task
cargo run -p workspace-desktop -- --cmd "/task create 'summarize ingestion'" ./phenom-data

# create an automatable task with a stored command
cargo run -p workspace-desktop -- --cmd "/task create 'summarize ingestion' '/stats'" ./phenom-data

# inspect persisted tasks
cargo run -p workspace-desktop -- --cmd "/task list" ./phenom-data
cargo run -p workspace-desktop -- --cmd "/task show t-0001" ./phenom-data

# update task state explicitly
cargo run -p workspace-desktop -- --cmd "/task complete t-0001" ./phenom-data
cargo run -p workspace-desktop -- --cmd "/task fail t-0001 'missing source corpus'" ./phenom-data

Task files: ./phenom-data/tasks/t-XXXX.json Task inspection: /task show now returns enriched JSON that includes the persisted task record plus the current scheduler snapshot, automation-policy decision, latest planning trace, and latest deferred-reason summary.

Automation Loop 🟧

# process pending tasks headlessly until no runnable tasks remain
cargo run -p workspace-desktop -- --run-loop ./phenom-data

# constrain the loop deterministically
cargo run -p workspace-desktop -- --run-loop --max-steps 10 --max-failures 1 ./phenom-data

Execution policy: the scheduler selects the highest-priority runnable task with satisfied dependencies; blocked tasks stay pending with explicit dependency or policy reasons.

Replay / Audit Trail 🟧

# print the stored event history for one task
cargo run -p workspace-desktop -- --cmd "/task replay t-0001" ./phenom-data

Event logs: ./phenom-data/tasks/t-0001.events.jsonl

Task Memory Integration 🟧

Noumenon memory summaries: task lifecycle, tool-call/result, artifact, and error summaries are mirrored into the existing segmented NOUMENON log while task JSON and JSONL remain the canonical detailed state. Task-system reference: docs/TASK_SYSTEM.md

Decision Runtime 🟧

# run the dependency-aware scheduler with bounded automation
cargo run -p workspace-desktop -- --run-loop --max-steps 10 ./phenom-data

Runtime behavior: the headless loop now analyzes dependency state, applies runtime policy, gathers bounded Noumenon context, writes a stable planning trace, and then deterministically executes, defers, or fails work with replayable reasons. Planning tiers: the planning trace now records whether the runtime used minimal, contextual, or evidence_checked context gathering for a task. Memory-conditioned execution: the planner can now surface similar prior task failures/completions from Noumenon memory before choosing whether to execute or defer. Conflict-aware caution: contextual/evidence-checked runs now defer with explicit reason codes when the bounded evidence is sparse or contradictory. Budget-aware replay: if --max-steps or --max-failures cuts a run short, remaining runnable tasks now receive replayable task_deferred entries with reason code deferred_by_budget. Runtime invariants: task-state transitions, AgentEvent versions/required fields, planning-trace required fields, and policy-decision reasoning are now validated at persistence/execution boundaries so denied actions and malformed runtime records fail explicitly instead of silently mutating state.

Diagnostics Export 🟧

# export a headless operator bundle for debugging
cargo run -p workspace-desktop -- --diagnostics-export ./phenom-data/reports/diagnostics.json ./phenom-data

Bundle contract: the export writes DiagnosticBundle version 1, including the current RuntimeHealthReport, top-level readiness, recent persisted task summaries, a recent AgentEvent tail, policy configuration summary, migration compatibility, benchmark metadata, and stable runtime version identifiers. Degraded export behavior: if the app cannot initialize fully, the export still emits a bounded degraded bundle so operators can inspect startup failures without attaching Qt or reproducing the issue interactively.

Recovery Scenarios 🟧

Corrupt task event logs: /task replay now isolates valid lines, emits task_event_log_corrupt, and /health marks the task-store component degraded instead of aborting the whole runtime. Migration mismatch: /health now reports incompatible storage versions as readiness: not_ready with migration_incompatible. Denied automation work: a policy-denied targeted run-loop task now fails explicitly without preventing later runnable tasks from completing. Requested live backend failures: if a requested model/backend cannot be opened, the snapshot component now uses live_backend_unavailable instead of a generic snapshot error.

Policy Audit 🟧

# export the full policy governance audit
cargo run -p workspace-desktop -- --policy-audit-json ./phenom-data

Audit contents: the report enumerates known UI commands and bridge JSON kinds against the live runtime policy tables, showing per-surface rule counts, allow/deny/confirmation totals, explicit mappings, commands exercised by repo scenarios, default-deny surfaces, and any unmapped command paths.

Trust Report 🟧

# emit one headless service-quality review document
cargo run -p workspace-desktop -- --trust-report-json ./phenom-data

Trust surface: the report aggregates the typed runtime health/readiness contract, policy-enforcement status, migration compatibility, governed benchmark status, recent failures/deferred work, warning reason codes, resilience/property/invariant coverage hints, and live-backend lane availability into one stable JSON document. Operational use: this is the quickest single headless report for “is the platform trustworthy right now?” because it reuses the same typed contracts and reason codes as the lower-level health, audit, migration, and benchmark surfaces.

Policy-Governed Execution 🟧

# inspect why a command is allowed or blocked
cargo run -p workspace-desktop -- --cmd "/policy explain '/export ./file.phen'" ./phenom-data

Policy model: runtime commands are classified into explicit allow, deny, require-confirmation, demo-only, and disabled outcomes with reason strings that also appear in task diagnostics and decision events. Other headless surfaces: --cmd-file, --cmd-json, --bridge-cmd-json, and --status-json remain supported and use the same policy evaluation path. Reason taxonomy: queue entries, policy explanations, planning traces, and decision events now also include stable machine-readable codes such as executable, dependency_unresolved, and policy_denied.

Queue Inspection 🟧

# inspect the deterministic queue before running it
cargo run -p workspace-desktop -- --cmd "/task queue" ./phenom-data

Queue output: runnable tasks are shown in scheduler order with scores, dependency summaries, and blocked reasons for policy-blocked or dependency-blocked work. Runtime evaluation: /eval runtime now emits evaluation_version: 2 with queue state plus capability-quality counters for planning tiers, planner reasons, execution intent, and replayable deferred reasons.

Runtime Health Contract 🟧

# interactive health report
cargo run -p workspace-desktop -- --cmd "/health" ./phenom-data

# headless health report
cargo run -p workspace-desktop -- --health-check ./phenom-data

Typed contract: the health surface now emits RuntimeHealthReport version 2 with explicit status, readiness, and degraded_reasons instead of inferring readiness from free-form strings. Operational detail: each report includes typed component health for storage, NOUMENON, task-store, and snapshot generation, plus a PolicyEnforcementReport, a MigrationCompatibilityReport, and baseline BenchmarkMetadata. Degraded behavior: if segmented NOUMENON storage cannot initialize, the runtime now falls back to in-memory retrieval with an explicit noumenon_unavailable degraded reason instead of aborting startup.

Replayable Planning Traces 🟧

# inspect the stored event history for one task
cargo run -p workspace-desktop -- --cmd "/task replay t-0001" ./phenom-data

Planning artifacts: each evaluated task also writes ./phenom-data/tasks/<task_id>.plan.json, which captures scheduler reason, selected context, policy result, and execution intent before command execution. Corruption isolation: if one task’s JSONL event log contains corrupt lines, /task replay now emits a degraded notice and replays the valid events it can recover instead of failing the entire replay path.

Glossary 🟧

Contributor map: docs/GLOSSARY.md explains the major crates and metaphor-heavy runtime families in plain language so new contributors can navigate the repo without reverse-engineering names from papers and phase plans.

Live Backend Test Lane 🟧

# intentionally opt into the non-deterministic Ollama-backed smoke lane
PHENOM_TEST_OLLAMA=1 cargo test -q -p phenom-core --test phase57_live_backend_ollama -- --nocapture

Required opt-in: set PHENOM_TEST_OLLAMA=1. Optional overrides: PHENOM_TEST_OLLAMA_MODEL and PHENOM_OLLAMA_BASE_URL. Coverage: the gated test ingests a short source, verifies an attached Ollama backend, runs one direct inference, and then runs a normal workspace process() round-trip. Default CI behavior: the deterministic stub-first test lane remains the default when PHENOM_TEST_OLLAMA is not set. Live-lane reference: docs/LIVE_BACKEND_TESTS.md

Ubuntu / Debian Build 🟫

# system dependencies
sudo apt-get update
sudo apt-get install -y build-essential git pkg-config \
  fontconfig libfontconfig1-dev curl

# rust toolchain
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env
rustup default stable
rustup component add rustfmt clippy

# clone repository
git clone https://github.com/infinityabundance/phenom.git
cd phenom

# build + test
cargo build --workspace
cargo test --workspace --locked

# run app shell
cargo run -p workspace-desktop -- ./phenom-data

CachyOS / ArchLinux Build 🟧

Primary target platform: KDE Plasma on CachyOS/ArchLinux.

# system dependencies
sudo pacman -Syu --needed base-devel git rustup

# optional desktop/qml runtime tools (recommended on primary platform)
sudo pacman -S --needed qt6-base qt6-declarative qt6-tools

# rust toolchain
rustup default stable
rustup component add rustfmt clippy

# build + test
cargo build --workspace
cargo test --workspace --locked

# run app shell
cargo run -p workspace-desktop -- ./phenom-data

CachyOS / ArchLinux Run 🟫

# verify desktop session hints (primary target: KDE Plasma)
echo "$XDG_CURRENT_DESKTOP"
echo "$XDG_SESSION_TYPE"

# run on KDE Plasma Wayland
QT_QPA_PLATFORM=wayland cargo run -p workspace-desktop -- ./phenom-data

# run on KDE Plasma X11
QT_QPA_PLATFORM=xcb cargo run -p workspace-desktop -- ./phenom-data

Validation and Release 🟫

# full integration gate (phase0..phase32)
scripts/phase32_gate.sh

# phase31 desktop bootstrap checks
scripts/phase31_5_desktop_qml_bootstrap.sh

# phase32 chat-first desktop ui checks
scripts/phase32_ui_chat_graph.sh

# release package archive
scripts/package_release.sh

🟫 🟧 🟫 🟧 🟫

Documentation 🟧

• Build plan (active): docs/plan/BUILD_PLAN.md
• Microtasks (active): docs/plan/BUILD_PLAN_MICROTASKS.md
• Contributor glossary: docs/GLOSSARY.md
• Decision runtime contract: docs/DECISION_RUNTIME.md
• Live backend test lane: docs/LIVE_BACKEND_TESTS.md
• NOUMENON DB contract: crates/phenom-noumenon/README.md
• Historical plan archive: docs/plan/archive/
• Program phases: docs/program/