Qubit Jarvis Enterprise Documentation

Generated from repo docs

[Qubit Jarvis Documentation](#qubit-jarvis-documentation) - docs/README.md
[API](#api) - docs/architecture/api.md
[Conversation Architecture](#conversation-architecture) - docs/architecture/conversations.md
[Infrastructure](#infrastructure) - docs/architecture/infrastructure.md
[Architecture Overview](#architecture-overview) - docs/architecture/overview.md
[Redis Schema](#redis-schema) - docs/architecture/redis-schema.md
[AI App Factory](#ai-app-factory) - docs/business/ai-app-factory.md
[CRM Pipeline](#crm-pipeline) - docs/business/crm-pipeline.md
[Proposal Engine](#proposal-engine) - docs/business/proposal-engine.md
[Revenue Engine](#revenue-engine) - docs/business/revenue-engine.md
[Codex Execution](#codex-execution) - docs/builder/codex-execution.md
[Builder Projects](#builder-projects) - docs/builder/projects.md
[Builder Specifications](#builder-specifications) - docs/builder/specifications.md
[Builder Tasks](#builder-tasks) - docs/builder/tasks.md
[PnL Engine](#pnl-engine) - docs/crypto/pnl-engine.md
[Portfolio Engine](#portfolio-engine) - docs/crypto/portfolio-engine.md
[Valuation V2](#valuation-v2) - docs/crypto/valuation-v2.md
[Deployment Log](#deployment-log) - docs/operations/deployment-log.md
[Incident Log](#incident-log) - docs/operations/incident-log.md
[Runbook](#runbook) - docs/operations/runbook.md
[Current Roadmap](#current-roadmap) - docs/roadmap/current-roadmap.md
[Self-Improving Jarvis](#self-improving-jarvis) - docs/roadmap/self-improving-jarvis.md
[Benchmarks](#benchmarks) - benchmarks/README.md
[QCOS Benchmarks](#qcos-benchmarks) - benchmarks/qcos/README.md
[Attention Benchmarks](#attention-benchmarks) - benchmarks/qcos/attention_benchmarks.md
[Cognitive Economy](#cognitive-economy) - benchmarks/qcos/cognitive_economy.md
[Kernel Alpha Metrics](#kernel-alpha-metrics) - benchmarks/qcos/kernel_alpha_metrics.md
[Development OS Changelog](#development-os-changelog) - development/CHANGELOG.md
[Codex Instructions](#codex-instructions) - development/CODEX.md
[Contributing](#contributing) - development/CONTRIBUTING.md
[Development Decisions](#development-decisions) - development/DECISIONS.md
[Epic 000 - Development OS](#epic-000-development-os) - development/EPICS/epic-000-development-os.md
[Epic 001 - QCOS Kernel](#epic-001-qcos-kernel) - development/EPICS/epic-001-qcos-kernel.md
[Epic 002 - Cognitive Cells](#epic-002-cognitive-cells) - development/EPICS/epic-002-cognitive-cells.md
[Epic 003 - Platform Engineering](#epic-003-platform-engineering) - development/EPICS/epic-003-platform-engineering.md
[Epic 004 - Research and Knowledge](#epic-004-research-and-knowledge) - development/EPICS/epic-004-research-and-knowledge.md
[Epics](#epics) - development/EPICS.md
[Alpha 0.1 - Identity](#alpha-01-identity) - development/MILESTONES/alpha-0.1-identity.md
[Alpha 0.2 - Goals](#alpha-02-goals) - development/MILESTONES/alpha-0.2-goals.md
[Alpha 0.3 - Observation](#alpha-03-observation) - development/MILESTONES/alpha-0.3-observation.md
[Alpha 0.4 - Attention](#alpha-04-attention) - development/MILESTONES/alpha-0.4-attention.md
[Alpha 0.5 - Memory](#alpha-05-memory) - development/MILESTONES/alpha-0.5-memory.md
[Kernel Roadmap](#kernel-roadmap) - development/MILESTONES/roadmap.md
[Milestones](#milestones) - development/MILESTONES.md
[Benchmark Prompt Template](#benchmark-prompt-template) - development/PROMPT_LIBRARY/benchmark.md
[Bugfix Prompt Template](#bugfix-prompt-template) - development/PROMPT_LIBRARY/bugfix.md
[Documentation Prompt Template](#documentation-prompt-template) - development/PROMPT_LIBRARY/documentation.md
[Feature Prompt Template](#feature-prompt-template) - development/PROMPT_LIBRARY/feature.md
[Kernel Primitive Prompt Template](#kernel-primitive-prompt-template) - development/PROMPT_LIBRARY/kernel.md
[Refactor Prompt Template](#refactor-prompt-template) - development/PROMPT_LIBRARY/refactor.md
[Release Prompt Template](#release-prompt-template) - development/PROMPT_LIBRARY/release.md
[QCOS Development Operating System](#qcos-development-operating-system) - development/README.md
[Release Process](#release-process) - development/RELEASE_PROCESS.md
[QCOS Core Repository Extraction Plan](#qcos-core-repository-extraction-plan) - development/REPO_SPLIT_PLAN.md
[Reviews](#reviews) - development/REVIEWS/README.md
[Review Checklist](#review-checklist) - development/REVIEW_CHECKLIST.md
[API Standards](#api-standards) - development/STANDARDS/api.md
[Documentation Standards](#documentation-standards) - development/STANDARDS/documentation.md
[Naming Standards](#naming-standards) - development/STANDARDS/naming.md
[Redis Standards](#redis-standards) - development/STANDARDS/redis.md
[Security Standards](#security-standards) - development/STANDARDS/security.md
[Testing Standards](#testing-standards) - development/STANDARDS/testing.md
[Tasks](#tasks) - development/TASKS/README.md
[Task Template](#task-template) - development/TASK_TEMPLATE.md
[Development Workflow](#development-workflow) - development/WORKFLOW.md
[QCOS Kernel Version](#qcos-kernel-version) - qcos/KERNEL_VERSION.md
[Qubit Cognitive Operating System](#qubit-cognitive-operating-system) - qcos/README.md
[QCOS Kernel](#qcos-kernel) - qcos/kernel/README.md
[QCOS Cognitive Scheduler](#qcos-cognitive-scheduler) - qcos/kernel/attention/README.md
[QCOS Goal Engine](#qcos-goal-engine) - qcos/kernel/goals/README.md
[QCOS Identity](#qcos-identity) - qcos/kernel/identity/README.md
[QCOS Memory Engine](#qcos-memory-engine) - qcos/kernel/memory/README.md
[QCOS Observation Engine](#qcos-observation-engine) - qcos/kernel/observation/README.md
[QCOS Plugins](#qcos-plugins) - qcos/plugins/README.md
[Design Decisions](#design-decisions) - qkb/0001_design_decisions.md
[Engineering Principles](#engineering-principles) - qkb/0002_engineering_principles.md
[Architectural Tradeoffs](#architectural-tradeoffs) - qkb/0003_architectural_tradeoffs.md
[Failed Experiments](#failed-experiments) - qkb/0004_failed_experiments.md
[Patterns](#patterns) - qkb/0005_patterns.md
[Lessons Learned](#lessons-learned) - qkb/0006_lessons_learned.md
[Glossary](#glossary) - qkb/0007_glossary.md
[Kernel Release Notes](#kernel-release-notes) - qkb/0008_kernel_release_notes.md
[QCOS Knowledge Base](#qcos-knowledge-base) - qkb/README.md
[QCOS RFCs](#qcos-rfcs) - rfcs/README.md
[RFC-0001: QCOS Constitution](#rfc-0001-qcos-constitution) - rfcs/RFC-0001-qcos-constitution.md
[RFC-0002: Kernel Primitives](#rfc-0002-kernel-primitives) - rfcs/RFC-0002-kernel-primitives.md
[RFC-0003: Observation Immutability](#rfc-0003-observation-immutability) - rfcs/RFC-0003-observation-immutability.md
[RFC-0004: Design Review Process](#rfc-0004-design-review-process) - rfcs/RFC-0004-design-review-process.md
[RFC-0005: Attention Engine](#rfc-0005-attention-engine) - rfcs/RFC-0005-attention-engine.md
[RFC-0006: Memory Architecture](#rfc-0006-memory-architecture) - rfcs/RFC-0006-memory-architecture.md
[RFC-0007: Cognitive Economy](#rfc-0007-cognitive-economy) - rfcs/RFC-0007-cognitive-economy.md
[QCOS Manifesto](#qcos-manifesto) - vision/000_qcos_manifesto.md
[Cognitive Primitives](#cognitive-primitives) - vision/001_cognitive_primitives.md
[Cognitive Cells](#cognitive-cells) - vision/002_cognitive_cells.md
[Meta Cognition](#meta-cognition) - vision/003_meta_cognition.md
[Self Improvement](#self-improvement) - vision/004_self_improvement.md
[Governance](#governance) - vision/005_governance.md
[Ethics](#ethics) - vision/006_ethics.md
[World Model](#world-model) - vision/007_world_model.md
[Simulation Engine](#simulation-engine) - vision/008_simulation_engine.md
[Evolution](#evolution) - vision/009_evolution.md
[Reference Architecture](#reference-architecture) - vision/010_reference_architecture.md
[Research Agenda](#research-agenda) - vision/011_research_agenda.md
[Roadmap 2050](#roadmap-2050) - vision/012_roadmap_2050.md
[QCOS Design Reviews](#qcos-design-reviews) - vision/013_qcos_design_reviews.md
[QCOS Vision](#qcos-vision) - vision/README.md
[Future of Cognition](#future-of-cognition) - research/000_future_of_cognition.md
[Post-Agent Architecture](#post-agent-architecture) - research/001_post_agent_architecture.md
[Digital Organisms](#digital-organisms) - research/002_digital_organisms.md
[Cognitive Operating Systems](#cognitive-operating-systems) - research/003_cognitive_operating_systems.md
[Enterprise Cognition](#enterprise-cognition) - research/004_enterprise_cognition.md
[Machine Reflection](#machine-reflection) - research/005_machine_reflection.md
[World Models](#world-models) - research/006_world_models.md
[Collective Intelligence](#collective-intelligence) - research/007_collective_intelligence.md
[Human-AI Symbiosis](#human-ai-symbiosis) - research/008_human_ai_symbiosis.md
[QCOS Research](#qcos-research) - research/README.md

Qubit Jarvis Documentation

Purpose

This folder is the documentation source for Qubit Jarvis, the venture studio operating system used to build, operate, and improve revenue-generating systems.

Current Status

Initial source structure created for architecture, business, builder, crypto, operations, roadmap, QCOS vision, and QCOS research documentation.

QCOS Sections

[QCOS Development OS](../development/README.md)
[QCOS Benchmarks](../benchmarks/qcos/README.md)
[QCOS Knowledge Base](../qkb/README.md)
[QCOS Kernel Version](../qcos/KERNEL_VERSION.md)
[QCOS RFCs](../rfcs/README.md)
[QCOS Vision](../vision/README.md)
[QCOS Design Reviews](../vision/013_qcos_design_reviews.md)
[QCOS Research](../research/README.md)

QCOS Alpha

[QCOS Runtime](../qcos/README.md)
[QCOS Kernel](../qcos/kernel/README.md)
[QCOS Identity](../qcos/kernel/identity/README.md)
[QCOS Goal Engine](../qcos/kernel/goals/README.md)
[QCOS Attention Engine](../qcos/kernel/attention/README.md)

Key Notes

Documentation should stay close to the operating reality of Qubit Jarvis.
Business value, revenue impact, and operational clarity should guide future updates.
API, Docker, Nginx, environment, and site files are intentionally out of scope for this documentation structure.
Every new QCOS kernel primitive must pass a design review before implementation.
Major QCOS architectural proposals and kernel primitives should begin as RFCs.
Cognition is allocated by attention; not every observation deserves equal processing.
Every major architectural decision must leave behind reusable knowledge.
QCOS must measure cognitive effectiveness, attention quality, and cognitive economy.
Every new capability must preserve or improve architectural coherence.

Next Steps

Fill each document with current implementation details.
Link documents together as the source of truth matures.
Add review cadence for keeping documentation current.
Expand QCOS vision and research placeholders into owner-reviewed doctrine.
Register first QCOS Alpha identity records for active agents and engines.
Register measurable goals for each QCOS identity.
Use attention scoring to decide which observations deserve memory, reasoning, planning, or action.
Apply the QCOS design review checklist before new kernel primitive implementation.
Use the RFC process for major QCOS architecture and kernel proposals.
Preserve architectural decisions, tradeoffs, and lessons in the QKB.
Use QCOS benchmarks to guide Memory and later kernel primitives.
Use the Development OS to plan, review, validate, release, and learn from QCOS changes.

API

Purpose

Document Qubit Jarvis API responsibilities, endpoint groups, request and response contracts, and integration boundaries.

Conversation Endpoints

`POST /chat`

The existing request remains compatible with:

`json

{"message": "Hello"}

Optional isolation metadata is supported through conversation_id, tenant_id, user_id, and agent_id. Omitting conversation_id selects the stable default conversation. The response remains:

`json

{"response": "..."}

`GET /memory`

Returns the original memory_key and items response shape. The optional conversation_id query parameter selects a conversation; omission selects default.

`DELETE /memory`

Clears messages only for the selected conversation and preserves its metadata. The optional conversation_id query parameter defaults to default.

See [Conversation Architecture](conversations.md) for identity, storage, lifecycle, compatibility, and security boundaries.

Key Notes

API implementation details should be verified from source before documenting exact endpoints.
Endpoint documentation should include method, path, request body, response shape, and failure modes.
API docs should distinguish stable contracts from internal or experimental endpoints.
Conversation metadata does not provide authorization; callers must not treat it as verified identity.

Next Steps

Inventory current FastAPI routes.
Document authentication and authorization assumptions.
Add endpoint examples after verification.

Conversation Architecture

Purpose

Define how Jarvis identifies conversations, isolates chat history, stores conversation metadata, and preserves compatibility with the original single-conversation API.

Conversation history is separate from the structured Jarvis knowledge store and from QCOS cognitive memory.

Identity

The target identity hierarchy is:

`text

tenant_id

-> user_id

-> agent_id

-> conversation_id

-> messages

conversation_id is the current storage isolation boundary. tenant_id, user_id, and agent_id are optional conversation metadata until authentication and authorization establish trusted identities.

Conversation IDs must be 1-128 characters and may contain letters, numbers, ., _, and -. Redis separators, paths, whitespace, and control characters are rejected instead of being embedded in keys.

Default Conversation

Clients that omit conversation_id use the stable ID:

`text

default

Jarvis never creates a new conversation ID for a legacy request. This preserves the original single-user behavior while allowing newer callers to select an isolated conversation.

Redis Keys

Conversation metadata is stored as JSON values in a Redis hash:

`text

jarvis:conversations

The hash field is conversation_id. Each record contains:

conversation_id
tenant_id
user_id
agent_id
title
status
created_at
updated_at
metadata

Messages are JSON values in one Redis list per conversation:

`text

jarvis:conversation:{conversation_id}:messages

Each message contains:

message_id
conversation_id
role
content
created_at
metadata

Only user and assistant messages are accepted for conversational history. Malformed records and unsupported roles are ignored when context is constructed. Lists retain the most recent 20 messages, matching the original memory limit. Normal request paths do not scan Redis keys.

Chat Lifecycle

For POST /chat, Jarvis:

1. validates or defaults the conversation ID;

2. lazily ensures conversation metadata;

3. loads only the selected conversation's messages;

4. loads structured knowledge separately;

5. adds the current user input once to the model request;

6. calls the model;

7. after a successful model response, appends the user message and assistant response to the selected conversation.

If the model call fails, neither the user message nor an assistant message is appended. An empty conversation metadata record may still exist because the conversation is ensured before the call.

System prompts, credentials, and internal configuration are not written to conversation messages.

Lifecycle

The conversation service supports:

lazy creation with active status;
metadata lookup and listing;
isolated message append and loading;
message clearing without deleting conversation metadata;
archival using archived status.

Supported statuses are active, archived, and closed. The current API exposes existing chat and memory operations; broader conversation-management routes are deferred until identity and authorization rules exist.

Backward Compatibility

Legacy requests containing only message continue to use the default conversation and receive the unchanged ChatResponse shape.

GET /memory and DELETE /memory continue to target the default conversation when no query parameter is supplied. Both accept an optional conversation_id query parameter. The response retains the original memory_key and items fields, and items retain role, content, and time.

The old Redis list remains:

`text

jarvis:memory:default

When the new default-conversation list is empty, Jarvis reads this old list as a temporary, read-only history fallback. It is never read for another conversation and is not copied automatically. Once the new default list contains messages, it becomes authoritative. Explicitly clearing default memory clears both default lists so the old history cannot reappear.

Isolation Guarantees

A conversation loads only its own message-list key.
The legacy global list is eligible only for the default conversation.
Unsupported stored roles cannot become model conversation history.
Structured knowledge is supplied separately and is never persisted as a conversation message.
Clearing one conversation does not clear another conversation.

Current Limitations

Authentication and authorization do not yet verify tenant, user, agent, or conversation ownership.
Conversation IDs are globally addressed; callers must not reuse an ID across security boundaries.
Metadata and message writes are separate Redis operations and may require transactions or Lua scripts under high concurrency.
Retention, deletion, export, legal hold, and privacy policies are not yet defined.
Migration or retirement of jarvis:memory:default remains a separately approved operational task.

Infrastructure

Purpose

Document the infrastructure that runs Qubit Jarvis, including host environment, containers, reverse proxy, runtime services, and operational dependencies.

Current Status

Placeholder documentation created. Infrastructure details need to be expanded from verified deployment state.

Key Notes

Known infrastructure includes Ubuntu, Docker Compose, Nginx, FastAPI, Redis, and n8n.
Infrastructure changes require explicit owner approval.
Secrets, certificates, DNS, firewall rules, and environment files must not be modified without approval.

Next Steps

Inventory services and container names.
Document network boundaries and public entry points.
Add backup, restore, and deployment expectations.

Architecture Overview

Purpose

Describe the high-level architecture of Qubit Jarvis and how its infrastructure, APIs, data stores, agents, and business systems fit together.

Current Status

Placeholder documentation created. Detailed architecture content still needs to be captured from the running system.

Key Notes

Qubit Jarvis runs as a venture studio operating system.
Current known components include Ubuntu, Docker Compose, Nginx, FastAPI, Redis, and n8n.
Core systems include opportunity, product, revenue, and experiment workflows.
Chat history is isolated by conversation ID; see [Conversation Architecture](conversations.md).

Next Steps

Document major services and their responsibilities.
Add system context and component diagrams.
Identify ownership boundaries between infrastructure, API, agents, and business workflows.

Redis Schema

Purpose

Document Redis keys, data models, expiration policies, ownership, and operational risks for Qubit Jarvis.

Conversation Keys

| Key | Type | Purpose |

| --- | --- | --- |

| jarvis:conversations | Hash | Conversation metadata keyed by validated conversation_id. |

| jarvis:conversation:{conversation_id}:messages | List | JSON conversation messages, capped at the latest 20 entries. |

| jarvis:memory:default | List | Legacy default history; temporary default-only fallback. |

Conversation IDs are validated before key construction. Request paths address a known key directly and do not use Redis key scans.

No automatic production migration copies or deletes the legacy list. See [Conversation Architecture](conversations.md) for fallback and removal considerations.

Key Notes

Redis keys should be documented with purpose, producer, consumer, and expected data shape.
Expiration and retention behavior should be explicit.
Data deletion or migration requires owner approval when production data may be affected.
Conversation metadata and message lists currently have no TTL.

Next Steps

Inventory Redis key prefixes from source.
Document value formats and lifecycle rules.
Add migration notes for any future schema changes.

AI App Factory

Purpose

Document the AI App Factory business line, including offer, target customer, delivery model, revenue assumptions, and operating workflow.

Current Status

Placeholder documentation created. Existing deployment notes indicate a static AI App Factory landing page has been deployed.

Key Notes

AI App Factory should be documented as a revenue-generating productized service.
Documentation should connect the public offer to internal delivery, proposal, and build workflows.
Revenue evidence should be tracked separately from assumptions.

Next Steps

Capture offer positioning, pricing, and target customer profile.
Document lead intake and fulfillment workflow.
Link deployment and operational notes from the operations docs.

CRM Pipeline

Purpose

Document how Qubit Jarvis tracks leads, prospects, opportunities, customers, and revenue movement through the business pipeline.

Current Status

Placeholder documentation created. CRM pipeline implementation details need to be captured.

Key Notes

Pipeline stages should reflect actual selling and delivery behavior.
Customer, opportunity, and revenue records should have clear ownership.
Automation should reduce manual follow-up while preserving evidence.

Next Steps

Define pipeline stages and required fields.
Document lead sources and qualification rules.
Add reporting needs for revenue forecasting.

Proposal Engine

Purpose

Document the system for generating, tracking, and improving business proposals for Qubit Jarvis opportunities.

Current Status

Placeholder documentation created. Proposal generation workflows need to be documented from current practice.

Key Notes

Proposals should be tied to specific customer problems, scope, pricing, and expected revenue.
Generated content should remain reviewable before customer delivery.
Proposal outcomes should feed back into business learning.

Next Steps

Define proposal inputs, templates, and approval steps.
Document pricing and scope assumptions.
Track proposal status and win or loss reasons.

Revenue Engine

Purpose

Document how Qubit Jarvis identifies, tracks, validates, and grows revenue across products, services, and experiments.

Current Status

Placeholder documentation created. Revenue engine details need to be expanded.

Key Notes

Revenue beats novelty in Qubit Jarvis decision-making.
Business documentation should separate confirmed revenue from hypotheses.
Revenue systems should connect opportunities, proposals, delivery, invoices, and follow-up.

Next Steps

Define revenue metrics and reporting cadence.
Document active revenue streams and target segments.
Add links to CRM, proposal, and product delivery workflows.

Codex Execution

Purpose

Document how Codex should execute work inside Qubit Jarvis, including constraints, validation expectations, and handoff format.

Current Status

Placeholder documentation created using repository constitution guidance. No code changes were made.

Key Notes

Codex must not commit unless explicitly instructed by Dc.
Codex must avoid modifying API, Docker, Nginx, environment, or site files unless the task explicitly authorizes it.
Validation, git status, and clear change summaries are required before stopping.

Next Steps

Capture standard execution checklists for common task types.
Add examples for documentation-only, API, infrastructure, and deployment tasks.
Link this document to repository-level operating rules.

Builder Projects

Purpose

Document active and historical build projects managed by Qubit Jarvis, including business rationale, scope, status, and delivery outcomes.

Current Status

Placeholder documentation created. Project inventory needs to be added.

Key Notes

Projects should connect technical work to business value.
Project status should be clear enough to support prioritization.
Completed projects should capture outcomes and reusable lessons.

Next Steps

Inventory active projects.
Define project status categories.
Link project records to specifications, tasks, and deployment notes.

Builder Specifications

Purpose

Document product and technical specifications used by the Qubit Jarvis builder workflow.

Current Status

Placeholder documentation created. Specification format and current specs need to be added.

Key Notes

Specifications should be small, testable, and tied to outcomes.
Requirements should distinguish business goals from implementation details.
Specs should define validation before build work begins.

Next Steps

Define a standard specification template.
Add current product and feature specifications.
Link specifications to implementation tasks and validation results.

Builder Tasks

Purpose

Document how Qubit Jarvis tracks builder tasks, execution state, validation, and completion criteria.

Current Status

Placeholder documentation created. Task tracking conventions need to be documented.

Key Notes

Tasks should be narrow, reversible, and testable.
Completion should include validation evidence.
Task records should preserve decisions and constraints that affect implementation.

Next Steps

Define task states and required fields.
Document task intake and prioritization flow.
Link tasks to projects, specifications, and Codex execution records.

PnL Engine

Purpose

Document crypto profit and loss tracking, including realized PnL, unrealized PnL, cost basis, and reporting behavior.

Current Status

Placeholder documentation created. PnL implementation details need verification.

Key Notes

PnL calculations should be auditable.
Cost basis rules must be explicit.
Trading, deletion, or mutation of production financial data requires owner approval.

Next Steps

Document PnL formulas and data dependencies.
Add example calculations.
Define reconciliation and reporting cadence.

Portfolio Engine

Purpose

Document the crypto portfolio engine, including portfolio tracking, asset allocation, valuation inputs, and risk controls.

Current Status

Placeholder documentation created. Crypto implementation details need verification before expansion.

Key Notes

Codex must not execute trades.
Crypto trading requires explicit owner approval.
Portfolio documentation should separate observation, valuation, and action.

Next Steps

Inventory current portfolio data sources and models.
Document allocation and risk assumptions.
Add owner approval flow for any trading-related workflow.

Valuation V2

Purpose

Document the second version of crypto valuation logic, including inputs, methodology, assumptions, and output format.

Current Status

Placeholder documentation created. Valuation V2 details need to be captured from source or design notes.

Key Notes

Valuation logic should make assumptions explicit.
Market data freshness and source reliability should be documented.
Outputs should distinguish estimates from verified balances or realized profit and loss.

Next Steps

Define valuation inputs and calculation flow.
Document supported assets and data providers.
Add validation cases for valuation output.

Deployment Log

Purpose

Track production and public deployment events for Qubit Jarvis, including dates, scope, URLs, source paths, infrastructure touched, and verification results.

Current Status

Existing deployment log content moved from docs/deployment-log.md into this operations document.

Key Notes

Deployment entries should be factual and date-stamped.
Public URLs, source paths, and verification status should be recorded.
Production deployments require owner approval.

Existing Entries

2026-06-22 - AI App Factory Deployment

Deployed static AI App Factory landing page.

Public URL:

https://appfactory.qubit.co.bw

Source path:

sites/ai-app-factory

Nginx site:

appfactory.qubit.co.bw

Status:

HTTP redirects to HTTPS
HTTPS returns 200 OK

Next Steps

Add owner approval references for future deployments.
Record validation commands and outputs for each deployment.
Link deployments to business and builder documentation.

2026-06-25 — Documentation Website Deployment

Deployed Qubit Jarvis documentation website.

Public URL:

https://docs.qubit.co.bw

Source path:

docs/generated/site

Nginx site:

docs.qubit.co.bw

Status:

HTTP redirects to HTTPS
HTTPS returns 200 OK

Incident Log

Purpose

Track operational incidents, outages, degraded behavior, root causes, remediation, and follow-up work for Qubit Jarvis.

Current Status

Placeholder documentation created. No incidents were added as part of this task.

Key Notes

Incident records should include date, impact, detection, response, resolution, and prevention.
Action items should be linked to builder tasks or roadmap items.
Sensitive operational details should not expose secrets.

Next Steps

Define incident entry format.
Backfill known incidents if appropriate.
Add review cadence for unresolved follow-up items.

Runbook

Purpose

Document operational procedures for running, checking, recovering, and safely changing Qubit Jarvis.

Current Status

Placeholder documentation created. Operational commands and procedures need to be captured and verified.

Key Notes

Runbook instructions should avoid exposing secrets.
Destructive actions, production data deletion, firewall changes, DNS changes, and certificate changes require owner approval.
Procedures should include expected outputs and rollback notes where possible.

Next Steps

Document health checks and service inspection commands.
Add deployment and rollback procedures.
Add incident response steps and escalation rules.

Current Roadmap

Purpose

Document the current roadmap for Qubit Jarvis, including near-term priorities, business goals, technical work, and validation milestones.

Current Status

Placeholder documentation created. Roadmap content needs owner-reviewed prioritization.

Key Notes

Roadmap items should be tied to revenue, evidence, automation, or infrastructure reliability.
Near-term work should favor small working systems.
Roadmap changes should preserve clear rationale.

Next Steps

Add current quarterly and monthly priorities.
Separate committed work from candidate ideas.
Link roadmap items to business systems and builder projects.

Self-Improving Jarvis

Purpose

Document the roadmap and operating model for making Qubit Jarvis improve its own systems, documentation, workflows, and business outcomes over time.

Current Status

Placeholder documentation created. Self-improvement loops need to be defined.

Key Notes

Self-improvement should prioritize measurable business and operational value.
Automation should reduce repeated manual work.
Changes must remain small, testable, and reversible.

Next Steps

Define feedback loops from incidents, deployments, revenue, and experiments.
Identify safe automation candidates.
Add metrics for measuring improvement over time.

Benchmarks

Purpose

Define measurement frameworks for determining whether Qubit Jarvis and QCOS are becoming more effective, not just larger.

Current Status

Initial benchmark foundation created for QCOS Kernel Alpha.

Benchmark Areas

[QCOS Benchmarks](qcos/README.md)

Principles

Benchmarks should measure cognitive quality, economy, and progress.
Benchmarks should expose false positives and false negatives.
Benchmarks should be tied to business value, owner review, and kernel evolution.

Next Steps

Convert benchmark definitions into executable evaluation datasets.
Link benchmark results to QKB lessons and release notes.
Use benchmark failures to guide Memory, Reasoning, Planning, and Simulation work.

QCOS Benchmarks

Purpose

Track whether the QCOS kernel is improving cognitive effectiveness across identity, goals, observations, attention, and future primitives.

Current Status

Initial benchmark structure created before Memory implementation.

Benchmark Documents

[Attention Benchmarks](attention_benchmarks.md)
[Cognitive Economy](cognitive_economy.md)
[Kernel Alpha Metrics](kernel_alpha_metrics.md)

Measurement Focus

Attention quality
Cognitive cost control
Kernel primitive progress
Human escalation quality
Goal-aligned decision support

Next Steps

Add baseline examples for attention scoring.
Define benchmark input and expected output formats.
Record results after each QCOS kernel alpha release.

Attention Benchmarks

Purpose

Measure whether the QCOS Attention Engine prioritizes observations in a way that improves cognition, reduces waste, and protects high-impact decisions.

Current Status

Initial benchmark definitions for Alpha 0.4.

Metrics

Attention Prioritization Accuracy

Measures how often attention scores and priority queues match owner-reviewed priority labels.

High-Value Observation Recall

Measures how often observations later judged valuable were routed to remember, reason, plan, simulate, act, or human_review.

Ignored Critical Observation Rate

Measures how often observations later judged critical were incorrectly routed to ignore or low-priority archival handling.

Human Escalation Appropriateness

Measures whether human_review recommendations are triggered for genuinely high-risk or high-impact observations without overwhelming the owner.

Goal Alignment Accuracy

Measures whether attention scores correctly reflect active identity and business goals.

Recommendation Quality

Measures how often recommendations produce the right next cognitive step: ignore, archive, remember, reason, plan, simulate, act, or human review.

Next Steps

Create labeled attention benchmark cases.
Add expected score ranges and priority queues.
Track errors by false positive, false negative, and escalation mismatch.

Cognitive Economy

Purpose

Measure whether QCOS uses cognitive resources efficiently by avoiding unnecessary processing while preserving high-value cognition.

Current Status

Initial benchmark definitions for attention-driven cognitive allocation.

Metrics

Cognitive Cost Saved

Measures the processing effort avoided when low-value observations are ignored, archived, or deferred.

Processing Cost Versus Expected Value

Compares estimated cognitive processing cost against expected business, operational, or learning value.

Reasoning Avoided Through Filtering

Measures how much reasoning work is avoided because attention filters noisy or low-value observations.

Simulation Avoided Through Filtering

Measures how much simulation work is avoided because attention prevents low-value observations from entering simulation workflows.

Cost of False Positives

Measures wasted processing caused by treating low-value observations as important.

Cost of False Negatives

Measures lost value or increased risk caused by ignoring or under-prioritizing important observations.

Next Steps

Define cost units for reasoning, planning, simulation, memory writes, and human review.
Track economy outcomes after Memory is introduced.
Connect benchmark results to kernel release notes.

Kernel Alpha Metrics

Purpose

Track QCOS Kernel Alpha primitive progress before the first complete cognitive kernel.

Current Status

Alpha 0.5 includes Identity, Goals, Observation, Attention, and Memory.

Primitive Status

Identity implemented
Goals implemented
Observation implemented
Attention implemented
Memory implemented
Reasoning pending
Planning pending
Simulation pending
Reflection pending
Learning pending
Evolution pending
Governance pending
Trust pending

Next Steps

Add release dates and validation links for each primitive.
Track benchmark coverage per primitive.
Use metrics to decide readiness for the first complete cognitive kernel.

Development OS Changelog

1.0

Initial QCOS Development Operating System created.

Notes

Future entries should record changes to workflow, standards, prompt templates, epics, milestones, and release process.
Kernel release notes remain in qkb/0008_kernel_release_notes.md.

Codex Instructions

Required Reading

Always read root CODEX.md first.
Read relevant files in development/ before making changes.
Use repository files as the source of truth over memory or assumptions.

Engineering Rules

Make small, testable changes.
Preserve existing endpoint behavior unless the task explicitly changes it.
Prefer existing project patterns over new abstractions.
Never modify .env.
Never commit secrets.
Never execute trades.
Never run destructive commands without explicit approval.

Validation Rules

Always run the validation requested by the task.
Run python3 -m pytest when changes affect Python code, docs export tests, routes, or shared behavior.
Run python3 scripts/export_docs.py when documentation sources change.
Always show git diff or git diff --stat as requested.
Always show git status.

Git Rules

Stop before commit unless explicitly told to commit.
Do not revert user changes unless explicitly instructed.
Do not modify Docker, Nginx, deployment, or infrastructure files unless the task explicitly requires it.

Contributing

Purpose

Define how contributors and agents should work inside QCOS.

Required Process

1. Read CODEX.md.

2. Read relevant development/ files.

3. Identify the epic and milestone.

4. Keep changes small and scoped.

5. Preserve endpoint behavior unless explicitly changing it.

6. Update docs, QKB, RFCs, or benchmarks when architecture changes.

7. Run validation.

8. Show diff and status.

9. Stop before commit unless explicitly approved.

Do Not Modify Without Explicit Scope

.env
Docker files
Nginx files
Deployment configuration
Production data
Secrets

Development Decisions

Purpose

Record development-system decisions that affect how QCOS work is planned, reviewed, tested, released, and learned from.

Current Decisions

QCOS work should move through research, RFCs, design reviews, QKB updates, epics, milestones, tasks, validation, documentation, benchmarks, release, and post-release review.
Codex work must stop before commit unless explicitly instructed.
Documentation changes should run the docs exporter and include generated documentation when required.

Next Decisions

Define required benchmark thresholds for kernel primitive promotion.
Define when RFCs are mandatory versus optional for non-kernel changes.
Define review ownership for cognitive cell migrations.

Epic 000 - Development OS

Purpose

Govern how QCOS is built.

Scope

Workflow
Standards
Prompt templates
Review checklists
Task and release process

Non-scope

Runtime API features
Kernel primitive implementation
Deployment changes

Current Status

Initialized as Development Operating System 1.0.

Relevant Folders

development/
docs/
qkb/

Success Criteria

Work has a repeatable lifecycle.
Tasks include validation and stop-before-commit instructions.
Reviews check architecture, tests, benchmarks, docs, governance, and compatibility.

Risks

Process docs may drift from actual practice.
Excess process may slow small fixes.

Next Milestones

Add real task records in development/TASKS/.
Add post-release review records in development/REVIEWS/.

Epic 001 - QCOS Kernel

Purpose

Implement QCOS kernel primitives.

Scope

Identity
Goals
Observation
Attention
Memory
Reasoning
Planning
Simulation
Reflection
Learning
Evolution
Governance
Trust

Non-scope

Cognitive cell migration
Deployment infrastructure
Non-kernel business features

Current Status

Alpha 0.5 Memory is complete. Alpha 0.6 Reasoning is next.

Relevant Folders

qcos/kernel/
agents/api/routes/
tests/
rfcs/
qkb/
benchmarks/qcos/

Success Criteria

Each primitive has model, service, route, tests, docs, RFC/QKB context, and benchmark consideration.
Kernel laws are preserved.
Existing primitives remain coherent.

Risks

Primitive coupling may grow without clear interfaces.
Storage contracts may drift without migration planning.

Next Milestones

Alpha 0.6 Reasoning
Alpha 0.7 Planning
Alpha 0.8 Simulation

Epic 002 - Cognitive Cells

Purpose

Convert existing engines and agents into QCOS-native cognitive cells.

Scope

Business
Builder
Crypto
Documentation
Architecture
Research
Compliance
Finance
Operations

Non-scope

Kernel primitive definition
Infrastructure rewrites
Deployment changes

Current Status

Planned.

Relevant Folders

agents/api/services/
agents/api/routes/
qcos/
docs/
qkb/

Success Criteria

Each cell has identity, goals, observations, attention, memory references, and documented interfaces.
Cell behavior remains backward compatible.
Business value and cognitive role are explicit.

Risks

Existing services may be wrapped without meaningful cognitive capability.
Cell contracts may diverge without standards.

Next Milestones

Define cognitive cell identity template.
Map current services to candidate cell records.
Design first cell migration review.

Epic 003 - Platform Engineering

Purpose

Maintain API, Redis, CI, testing, docs generation, deployment, monitoring, security, and reliability.

Scope

FastAPI structure
Redis access patterns
Tests
Documentation export
Operational reliability
Security posture
Deployment hygiene

Non-scope

Kernel primitive theory
Research doctrine
Product strategy

Current Status

Active maintenance.

Relevant Folders

agents/api/
tests/
scripts/
docs/
development/STANDARDS/

Success Criteria

Validation remains fast and reliable.
Docs export remains reproducible.
Runtime contracts stay stable.
Security constraints are followed.

Risks

Generated docs may drift if export is skipped.
Infrastructure changes may exceed task scope.

Next Milestones

Strengthen route behavior tests.
Add platform health and reliability standards.
Review Redis indexing patterns.

Epic 004 - Research and Knowledge

Purpose

Maintain Vision, Research, RFCs, QKB, Benchmarks, standards, and future scientific work.

Scope

Vision documents
Research documents
RFC process
QKB records
Benchmarks
Development standards
Lessons learned

Non-scope

Runtime implementation without approved tasks
Deployment configuration
Unreviewed doctrine changes

Current Status

Active foundation.

Relevant Folders

vision/
research/
rfcs/
qkb/
benchmarks/
development/

Success Criteria

Major decisions leave reusable knowledge.
Benchmarks measure cognitive quality and economy.
Research informs kernel and cell milestones.

Risks

Knowledge may become aspirational instead of operational.
Benchmarks may lag behind implementation.

Next Milestones

Add QKB decision entries for Alpha 0.1 through Alpha 0.5.
Define benchmark thresholds for Reasoning readiness.
Add post-release review records.

Epics

Epic 000 - Development OS

Purpose: govern how QCOS is built.

Epic 001 - QCOS Kernel

Purpose: implement kernel primitives: Identity, Goals, Observation, Attention, Memory, Reasoning, Planning, Simulation, Reflection, Learning, Evolution, Governance, Trust.

Epic 002 - Cognitive Cells

Purpose: convert Business, Builder, Crypto, Documentation, Architecture, Research, Compliance, Finance, and Operations into QCOS-native cognitive cells.

Epic 003 - Platform Engineering

Purpose: maintain API, Redis, CI, testing, docs generation, deployment, monitoring, security, and reliability.

Epic 004 - Research and Knowledge

Purpose: maintain Vision, Research, RFCs, QKB, Benchmarks, standards, and future scientific work.

Epic Records

[Epic 000](EPICS/epic-000-development-os.md)
[Epic 001](EPICS/epic-001-qcos-kernel.md)
[Epic 002](EPICS/epic-002-cognitive-cells.md)
[Epic 003](EPICS/epic-003-platform-engineering.md)
[Epic 004](EPICS/epic-004-research-and-knowledge.md)

Alpha 0.1 - Identity

Kernel Version

Alpha 0.1

Purpose

Create structured identity records for cognitive cells, plugins, subsystems, and engines.

Primitive Added

Identity

Key Files

qcos/kernel/identity/
agents/api/routes/qcos_identity.py
tests/test_qcos_identity.py

Tests

Import tests for model and route.

Documentation

qcos/kernel/identity/README.md
qcos/kernel/README.md
docs/README.md

RFC/QKB Links

rfcs/RFC-0002-kernel-primitives.md
qkb/0008_kernel_release_notes.md

Known Limitations

Identity lifecycle and governance rules remain early.

Next Milestone

Alpha 0.2 Goals

Alpha 0.2 - Goals

Kernel Version

Alpha 0.2

Purpose

Attach measurable intent and progress to identities.

Primitive Added

Goals

Key Files

qcos/kernel/goals/
agents/api/routes/qcos_goals.py
tests/test_qcos_goals.py

Tests

Import tests for model and route.

Documentation

qcos/kernel/goals/README.md
qcos/kernel/README.md
docs/README.md

RFC/QKB Links

rfcs/RFC-0002-kernel-primitives.md
qkb/0008_kernel_release_notes.md

Known Limitations

Goal hierarchy and outcome evaluation need deeper behavior tests.

Next Milestone

Alpha 0.3 Observation

Alpha 0.3 - Observation

Kernel Version

Alpha 0.3

Purpose

Record immutable QCOS perceptions of reality.

Primitive Added

Observation

Key Files

qcos/kernel/observation/
agents/api/routes/qcos_observation.py
tests/test_qcos_observation.py

Tests

Import tests for model and route.

Documentation

qcos/kernel/observation/README.md
vision/001_cognitive_primitives.md
qcos/kernel/README.md

RFC/QKB Links

rfcs/RFC-0003-observation-immutability.md
qkb/0008_kernel_release_notes.md

Known Limitations

Observation provenance and correlation behavior need future benchmarks.

Next Milestone

Alpha 0.4 Attention / Cognitive Scheduler

Alpha 0.4 - Attention

Kernel Version

Alpha 0.4

Purpose

Allocate cognitive resources across observations.

Primitive Added

Attention / Cognitive Scheduler

Key Files

qcos/kernel/attention/
agents/api/routes/qcos_attention.py
tests/test_qcos_attention.py
benchmarks/qcos/attention_benchmarks.md
benchmarks/qcos/cognitive_economy.md

Tests

Import tests for model and route.

Documentation

qcos/kernel/attention/README.md
rfcs/RFC-0005-attention-engine.md
vision/001_cognitive_primitives.md

RFC/QKB Links

rfcs/RFC-0005-attention-engine.md
qkb/0008_kernel_release_notes.md

Known Limitations

Thresholds are code-configurable and need outcome feedback.
Recommendation quality requires benchmark datasets.

Next Milestone

Alpha 0.5 Memory

Alpha 0.5 - Memory

Kernel Version

Alpha 0.5

Purpose

Preserve attended experience for future reasoning, planning, simulation, reflection, and learning.

Primitive Added

Memory

Key Files

qcos/kernel/memory/
agents/api/routes/qcos_memory.py
tests/test_qcos_memory.py
benchmarks/qcos/kernel_alpha_metrics.md

Tests

Import tests for model and route.

Documentation

qcos/kernel/memory/README.md
rfcs/RFC-0006-memory-architecture.md
vision/001_cognitive_primitives.md

RFC/QKB Links

rfcs/RFC-0006-memory-architecture.md
qkb/0008_kernel_release_notes.md

Known Limitations

Retrieval quality and memory usefulness need executable benchmarks.
Long-term storage strategy is not finalized.

Next Milestone

Alpha 0.6 Reasoning

Kernel Roadmap

Completed

Alpha 0.1 - Identity
Alpha 0.2 - Goals
Alpha 0.3 - Observation
Alpha 0.4 - Attention / Cognitive Scheduler
Alpha 0.5 - Memory

Planned

Alpha 0.6 - Reasoning
Alpha 0.7 - Planning
Alpha 0.8 - Simulation
Alpha 0.9 - Reflection
Alpha 0.10 - Learning
Alpha 0.11 - Evolution
Alpha 0.12 - Governance
Alpha 0.13 - Trust
1.0 - First Complete Cognitive Kernel

Release Rule

Each milestone should update kernel docs, release notes, RFC/QKB references, benchmarks, tests, and generated docs.

Milestones

Completed Kernel Milestones

Alpha 0.1 - Identity
Alpha 0.2 - Goals
Alpha 0.3 - Observation
Alpha 0.4 - Attention / Cognitive Scheduler
Alpha 0.5 - Memory

Planned Kernel Milestones

Alpha 0.6 - Reasoning
Alpha 0.7 - Planning
Alpha 0.8 - Simulation
Alpha 0.9 - Reflection
Alpha 0.10 - Learning
Alpha 0.11 - Evolution
Alpha 0.12 - Governance
Alpha 0.13 - Trust
1.0 - First Complete Cognitive Kernel

Milestone Records

[Alpha 0.1 Identity](MILESTONES/alpha-0.1-identity.md)
[Alpha 0.2 Goals](MILESTONES/alpha-0.2-goals.md)
[Alpha 0.3 Observation](MILESTONES/alpha-0.3-observation.md)
[Alpha 0.4 Attention](MILESTONES/alpha-0.4-attention.md)
[Alpha 0.5 Memory](MILESTONES/alpha-0.5-memory.md)
[Roadmap](MILESTONES/roadmap.md)

Benchmark Prompt Template

Read CODEX.md first.

Task:

Add or update QCOS benchmark coverage for <capability>.

Requirements:

1. Define measurable capability.

2. Include false positive and false negative costs.

3. Link benchmarks to relevant primitive, RFC, QKB, and milestone.

4. Update docs export patterns if needed.

5. Run python3 scripts/export_docs.py.

6. Run python3 -m pytest.

7. Show git diff --stat and git status.

8. Stop before commit.

Bugfix Prompt Template

Read CODEX.md first.

Task:

Fix <bug summary>.

Context:

Describe observed behavior, expected behavior, affected files, and reproduction steps.

Requirements:

1. Reproduce or inspect the failure.

2. Patch the smallest responsible surface.

3. Add or update focused tests when useful.

4. Avoid unrelated refactors.

5. Run validation.

6. Show git diff --stat and git status.

7. Stop before commit.

Documentation Prompt Template

Read CODEX.md first.

Task:

Update documentation for <topic>.

Requirements:

1. Update source docs only in scoped folders.

2. Preserve runtime code and endpoint behavior.

3. Update indexes and cross-links.

4. Run python3 scripts/export_docs.py.

5. Run python3 -m pytest.

6. Show git diff --stat and git status.

7. Stop before commit.

Feature Prompt Template

Read CODEX.md first.

Task:

Implement <feature name>.

Purpose:

Explain the user or system capability this feature adds.

Context files:

development/WORKFLOW.md
development/REVIEW_CHECKLIST.md
<feature files>

Requirements:

1. Keep changes small and testable.

2. Preserve existing endpoint behavior unless explicitly changed.

3. Update docs and tests.

4. Run validation.

5. Show git diff --stat and git status.

6. Stop before commit.

Kernel Primitive Prompt Template

Read CODEX.md first.

Task:

Initialize QCOS <primitive> Engine.

Context files:

qcos/KERNEL_VERSION.md
qcos/kernel/README.md
vision/001_cognitive_primitives.md
rfcs/
qkb/
benchmarks/qcos/
development/REVIEW_CHECKLIST.md

Requirements:

1. Define model, service, route, tests, docs, RFC/QKB updates, and benchmarks.

2. Preserve existing primitives unless explicit changes are required.

3. Add Redis keys only when documented.

4. Update kernel version and release notes.

5. Run compile, tests, docs export.

6. Show git diff --stat and git status.

7. Stop before commit.

Refactor Prompt Template

Read CODEX.md first.

Task:

Refactor <area> without changing behavior.

Requirements:

1. Identify current behavior and response shapes.

2. Keep external contracts stable.

3. Prefer existing patterns.

4. Add tests only where risk warrants it.

5. Run validation.

6. Show git diff --stat and git status.

7. Stop before commit.

Release Prompt Template

Read CODEX.md first.

Task:

Prepare release <version>.

Requirements:

1. Confirm milestone scope.

2. Update version, release notes, RFC/QKB links, benchmarks, and docs.

3. Run required validation.

4. Show generated docs changes.

5. Show git diff --stat and git status.

6. Stop before commit unless explicitly approved.

QCOS Development Operating System

Purpose

This folder is the Development Operating System for QCOS. It governs how work moves from idea to implementation to review to release.

Scope

The Development OS defines planning, review, implementation, testing, documentation, benchmarking, release, and learning workflows for QCOS and Qubit Jarvis engineering work.

Core Files

[CODEX Instructions](CODEX.md)
[Workflow](WORKFLOW.md)
[Epics](EPICS.md)
[Milestones](MILESTONES.md)
[Release Process](RELEASE_PROCESS.md)
[Review Checklist](REVIEW_CHECKLIST.md)
[Task Template](TASK_TEMPLATE.md)
[Changelog](CHANGELOG.md)
[Decisions](DECISIONS.md)
[Contributing](CONTRIBUTING.md)

Supporting Folders

[Prompt Library](PROMPT_LIBRARY/)
[Standards](STANDARDS/)
[Epic Records](EPICS/)
[Milestone Records](MILESTONES/)
[Tasks](TASKS/)
[Reviews](REVIEWS/)

Operating Principle

Every capability should preserve or improve the coherence of the cognitive architecture while remaining small, testable, documented, benchmark-aware, and reversible.

Release Process

Purpose

Define how QCOS changes become versioned, documented, validated releases.

Release Steps

1. Confirm milestone scope.

2. Review relevant RFCs, design reviews, QKB entries, and benchmark definitions.

3. Complete implementation and focused tests.

4. Run requested validation commands.

5. Update source documentation and generated docs.

6. Update kernel version and release notes when applicable.

7. Record known limitations and follow-up work.

8. Show git diff --stat and git status.

9. Stop before commit unless explicitly approved.

Release Evidence

Tests run
Docs export result
Benchmark coverage
Runtime behavior affected
Redis keys added or changed
Endpoint changes
Open risks

QCOS Core Repository Extraction Plan

Purpose

Prepare a non-destructive split between the current Jarvis repository and a future qcos-core repository.

The goal is to let QCOS mature as a reusable Cognitive Operating System while Jarvis remains the first production application built on top of it.

Target Repository Structure

qcos-core

`text

qcos-core/

qcos/

vision/

research/

rfcs/

qkb/

benchmarks/

development/

tests/

pyproject.toml

README.md

jarvis

`text

jarvis/

agents/

docs/

docker/

nginx/

n8n/

scripts/

site/

tests/

qcos/

During early phases, jarvis/qcos/ remains in place. It is removed only after qcos-core is packaged, validated, versioned, and consumed successfully by Jarvis.

What Belongs In qcos-core

QCOS kernel primitives in qcos/
Kernel version records in qcos/KERNEL_VERSION.md
Vision documents in vision/
Research documents in research/
RFCs in rfcs/
QCOS Knowledge Base in qkb/
Cognitive benchmarks in benchmarks/
Development Operating System in development/
Import and behavior tests for core primitives
Packaging metadata for the reusable core

What Stays In jarvis

FastAPI application code in agents/api/
Business engine
Builder engine
Crypto engine
Documentation and Architecture application services
Jarvis-specific API routes
Integrations and automation
Deployment, Docker, Nginx, and infrastructure configuration
n8n workflows
Sites and deployment artifacts
Jarvis-specific documentation in docs/
Application tests that validate Jarvis behavior

Migration Phases

Phase 1 — Non-destructive extraction

Create qcos-core as a separate repository.
Copy files first from Jarvis into qcos-core.
Validate tests in both repositories.
Do not remove from Jarvis until qcos-core is stable.
Keep Jarvis runtime behavior unchanged during this phase.
Track every copied path and any divergence between repositories.

Phase 2 — Package qcos-core

Add pyproject.toml.
Expose qcos as an importable package.
Add tests for package imports, models, services, kernel docs, and benchmark docs.
Version qcos-core independently from Jarvis.
Define release notes and compatibility rules for each qcos-core version.
Publish or install from a controlled source before Jarvis depends on it.

Phase 3 — Jarvis consumes qcos-core

Install qcos-core as a dependency.
Update imports in Jarvis to consume qcos-core.
Test Jarvis end to end.
Validate FastAPI startup, route imports, service behavior, docs tests, and any endpoint contracts.
Only then remove duplicated qcos files from Jarvis.
Keep rollback simple by preserving the last Jarvis commit with local qcos files intact.

Dependency Strategy

qcos-core should minimize application dependencies.
Core models and services should remain importable without starting FastAPI.
Redis integration should remain behind explicit service boundaries.
Jarvis should depend on a pinned qcos-core version.
Breaking qcos-core changes require version bumps, release notes, migration notes, and Jarvis compatibility tests.

How Jarvis Will Use qcos-core

Jarvis imports kernel models and services from qcos-core.
Jarvis owns FastAPI route wiring, Redis connections, deployment, and application-specific behavior.
Jarvis may add adapter layers where runtime integration differs from pure core behavior.
Jarvis remains the production proving ground for QCOS primitives.
Feedback from Jarvis should flow back into QKB, benchmarks, RFCs, and core releases.

Testing Requirements

qcos-core

Package import tests
Kernel primitive model tests
Kernel primitive service tests where behavior is deterministic
Documentation export or documentation integrity tests
Benchmark document integrity tests
Version and release note checks

jarvis

FastAPI import and startup tests
Route import tests
Existing endpoint contract tests
Redis-backed behavior tests where available
Docs export tests
Integration smoke tests after dependency installation

Risks

Duplicated files may diverge during the transition.
Jarvis may rely on implicit local imports that fail after packaging.
Core services may carry application assumptions that belong in Jarvis.
Redis behavior may be harder to test cleanly across repository boundaries.
Generated documentation may split incorrectly if source ownership is unclear.
Versioning mistakes may make Jarvis depend on incompatible core behavior.

Rollback Plan

Do not remove local Jarvis qcos files in Phase 1 or Phase 2.
Keep all extraction work copy-only until Jarvis passes tests with packaged qcos-core.
If dependency installation or imports fail, revert Jarvis import changes and continue using local qcos.
If qcos-core behavior is wrong, patch and release a new core version before retrying Jarvis migration.
Preserve a known-good Jarvis commit before removing duplicated core files.

Long-term QCOS Maturity

This split supports long-term QCOS maturity by separating reusable cognitive architecture from the first production application.

qcos-core can evolve as a stable, versioned kernel with its own laws, RFCs, benchmarks, QKB, and development process. Jarvis can move faster as an application while still validating QCOS in production-like workflows.

The split also makes architectural boundaries clearer:

QCOS defines primitives and cognitive contracts.
Jarvis composes those primitives into business operations.
Benchmarks measure whether the core is becoming more effective.
QKB preserves why decisions were made.
Versioned releases prevent hidden coupling from becoming permanent architecture.

Reviews

Purpose

Store design reviews, post-release reviews, and architectural integrity reviews.

Current Status

No review records have been added yet.

Review Checklist

Architectural Fit

Does the change preserve the QCOS architecture?
Does it align with current kernel version and roadmap?
Does it avoid long-term architectural entropy or document mitigation?

Kernel Primitive Interaction

Which primitives does it read from or write to?
Does it preserve immutable observation records?
Does it maintain clear references between Identity, Goals, Observation, Attention, Memory, and future primitives?

Data Model Stability

Are fields explicit and documented?
Are Redis keys preserved or clearly introduced?
Are response shapes preserved when required?

Runtime Behavior

Are endpoint behaviors unchanged unless explicitly requested?
Are side effects scoped and auditable?
Are failure modes clear?

Tests

Are import tests present for new routes and models?
Are behavior tests added when risk warrants them?
Do tests avoid requiring Redis when only import safety is required?

Benchmarks

Does the change improve or preserve measurable cognitive capability?
Are false positives, false negatives, and cognitive cost considered?
Are benchmark updates linked to relevant milestone or RFC records?

Documentation

Are source docs updated?
Was python3 scripts/export_docs.py run when docs changed?
Are generated docs included when required?

Governance and Safety

Does the change avoid secrets, trades, destructive actions, and deployment changes?
Are human review paths documented for high-impact cognitive decisions?
Is owner approval required for any sensitive action?

Backward Compatibility

Are existing endpoints, Redis keys, and response shapes preserved?
Are migration risks documented?
Are callers protected from unnecessary breaking changes?

API Standards

Principles

Preserve existing endpoint behavior unless explicitly changing it.
Keep response shapes stable for existing endpoints.
Register routes explicitly in agents/api/main.py.
Keep route handlers thin and delegate behavior to services.
Return clear 404 errors for missing records.

Validation

Compile changed route and service files.
Add import tests for new route modules.
Add behavior tests when endpoint semantics change.

Documentation Standards

Principles

Keep docs close to operating reality.
Update indexes when adding folders or source documents.
Preserve architectural rationale in QKB.
Use RFCs for major kernel or architecture proposals.
Run docs export after source docs change.

Generated Docs

Generated Markdown, DOCX, and static site outputs should be refreshed when source docs change and the task requires export.

Naming Standards

Principles

Use clear domain names over abbreviations.
Kernel primitive folders should be singular capability names.
QCOS route modules should use qcos_<primitive>.py.
Redis keys should use stable namespace prefixes such as qcos:<domain>.
Markdown filenames should be lowercase with separators that match the folder convention.

Version Names

Kernel alpha milestones use Alpha X.Y.
RFC files use RFC-0000-short-name.md.

Redis Standards

Principles

Document every new Redis key.
Preserve existing Redis keys unless migration is explicitly approved.
Keep repository or service access scoped to the owning domain.
Store structured JSON payloads for hash values.
Avoid mutating immutable source records.

Indexing

Use separate index keys when retrieval requires derived lookup structure.
Preserve provenance fields such as IDs and source references.

Security Standards

Required Constraints

Never commit secrets.
Never print secrets.
Never modify .env.
Never execute trades.
Never run destructive commands without explicit owner approval.
Never change deployment, Docker, Nginx, firewall, DNS, or SSL configuration unless explicitly scoped.

Review Questions

Does the change expose sensitive data?
Does the change enable high-impact actions without human review?
Does the change modify persistence, access, or automation boundaries?

Testing Standards

Principles

Tests should match risk and blast radius.
Import tests should not require Redis.
Behavior tests should cover new calculations, state changes, and response contracts.
Full validation should include python3 -m pytest.

Documentation Changes

Run python3 scripts/export_docs.py.
Run pytest because docs export is covered by tests.

Tasks

Purpose

Store task records created from development/TASK_TEMPLATE.md.

Current Status

No task records have been added yet.

Task Template

Title

<short task title>

Epic

<epic id and name>

Milestone

<kernel or platform milestone>

Purpose

Explain why the task matters.

Context Files To Read

CODEX.md
development/README.md
development/WORKFLOW.md
<relevant source files>

Requirements

Requirement 1
Requirement 2
Requirement 3

Files Expected To Change

<path>
<path>

Validation Commands

`bash

python3 -m pytest

python3 scripts/export_docs.py

Risks

Runtime behavior risk
Data model risk
Documentation drift risk
Benchmark gap risk

Stop Before Commit

Show git diff, validation results, and git status, then stop before commit unless explicitly instructed to commit.

Development Workflow

Lifecycle

Idea

-> Research

-> RFC

-> Design Review

-> QKB update

-> Epic

-> Milestone

-> Task

-> Implementation

-> Tests

-> Benchmarks

-> Documentation

-> Release

-> Post-release Review

Stage Definitions

Idea: A capability, improvement, concern, or opportunity is identified.
Research: Existing docs, code, benchmarks, and external constraints are reviewed.
RFC: Major architecture and kernel changes are proposed formally.
Design Review: Architectural fit, risks, data contracts, benchmarks, and safety are reviewed.
QKB update: Durable rationale, tradeoffs, patterns, or lessons are preserved.
Epic: Work is grouped under a long-lived objective.
Milestone: A concrete release target is defined.
Task: A bounded implementation unit is written with validation commands.
Implementation: Files are changed in small, reversible patches.
Tests: Imports, routes, services, and behavior are validated.
Benchmarks: Cognitive quality, economy, and progress are measured when relevant.
Documentation: Source docs and generated docs are updated.
Release: Version, release notes, and validation evidence are recorded.
Post-release Review: Outcomes, failures, and lessons are fed back into QKB.

QCOS Kernel Version

Current Kernel Version

Alpha 0.5

Completed Primitives

Alpha 0.1 Identity
Alpha 0.2 Goals
Alpha 0.3 Observation
Alpha 0.4 Attention
Alpha 0.5 Memory

Next Primitive

Alpha 0.6 Reasoning

Future Primitives

Alpha 0.7 Planning
Alpha 0.8 Simulation
Alpha 0.9 Reflection
Alpha 0.10 Learning
Alpha 0.11 Evolution
Alpha 0.12 Governance
Alpha 0.13 Trust
1.0 First Complete Cognitive Kernel

Notes

Kernel versioning records the intended evolution path before each primitive is implemented.

Qubit Cognitive Operating System

Purpose

Define the runtime and constitutional home for QCOS-native primitives, kernels, plugins, and cognitive subsystems.

Current Status

QCOS Alpha is initialized with the first kernel primitives: Identity and Goals.

Key Notes

QCOS primitives should be small, inspectable, and composable.
Identity records should eventually describe every cognitive cell, plugin, subsystem, and engine.
Goals should attach measurable intent to each identity.
Runtime primitives should connect implementation behavior to vision, research, and architecture references.

Next Steps

Register initial identities for existing Qubit Jarvis agents and engines.
Register initial goals for active identities.
Define plugin identity requirements.
Link identity records to memory, documentation, and architecture references.

QCOS Kernel

Purpose

Define core QCOS primitives that support cognitive cells, plugins, subsystems, engines, perception records, cognitive allocation, and memory.

Current Status

The kernel starts with the Identity, Goal, Observation, Attention, and Memory primitives.

Kernel Primitives

[Identity](identity/README.md)
[Goal Engine](goals/README.md)
[Observation Engine](observation/README.md)
[Attention Engine](attention/README.md)
[Memory Engine](memory/README.md)

Attention Scheduler

Attention allocates cognitive resources across observations by calculating an attention score and assigning a priority queue. High-risk or high-impact recommendations are escalated to human review.

Memory Engine

Memory preserves attended experience by storing meaning, retrieval structure, and references back to immutable observations and attention decisions.

Kernel Acceptance Rule

Every new QCOS kernel primitive must answer:

1. How does it interact with the other kernel primitives?

2. What measurable cognitive capability does it add?

3. How can it improve itself over time?

Design Review Standard

Every new QCOS kernel primitive must pass a design review before implementation.

Every new QCOS kernel primitive should begin as an RFC before implementation.

Design reviews must cover:

Architectural Fit
Kernel Interactions
Data Model
Evolution Path
Safety & Governance
Testing
Documentation

QCOS Law 002

Observations are immutable and append-only.

QCOS Law 003

Cognition is allocated by attention. Not every observation deserves equal processing.

QCOS Law 004

Every major architectural decision must leave behind reusable knowledge. No important decision should exist only in code or in a developer's memory.

QCOS Law 005

Memory preserves attended experience. Observations remain immutable; memory stores meaning and retrieval structure.

QCOS Law 006

Every new capability must improve or preserve the coherence of the cognitive architecture. No feature may be accepted if it increases long-term architectural entropy without a documented rationale and mitigation strategy.

Kernel Version

[QCOS Kernel Version](../KERNEL_VERSION.md)

Next Steps

Stabilize identity storage and route behavior.
Attach goals to identities and business outcomes.
Capture observations from active identities.
Allocate cognition with attention scoring.
Preserve attended observations as memory.
Preserve major architectural decisions in the QKB.
Add owner-reviewed primitive lifecycle rules.
Define how future primitives depend on identity records.
Apply the QCOS design review standard before implementing new primitives.
Use RFCs for major kernel primitive proposals and architectural changes.

QCOS Cognitive Scheduler

Purpose

Allocate cognitive resources based on expected value, goal alignment, confidence, risk, and processing cost.

Current Status

Initial runtime model and service created as the fourth QCOS Kernel primitive.

Redis Storage

qcos:attention

Supported Fields

attention_id
observation_id
identity_id
importance
urgency
novelty
risk
opportunity
goal_alignment
confidence
processing_cost
attention_score
priority_queue
recommendation
requires_human_review
rationale
created_at

Scoring

Attention score is calculated as:

importance + urgency + novelty + risk + opportunity + goal_alignment + confidence - processing_cost

Priority Queues

immediate
high
medium
low
archive

Recommendations

ignore
archive
remember
reason
plan
simulate
act
human_review

Human Review

The scheduler recommends human_review when risk exceeds the configured risk threshold or the computed recommendation implies a high-impact action.

QCOS Law 003

Cognition is allocated by attention. Not every observation deserves equal processing.

Next Steps

Connect attention records to observations and goals.
Define default scoring guidance for identities.
Tune human review thresholds with real outcomes.
Track whether recommendations lead to valuable outcomes.

QCOS Goal Engine

Purpose

Provide measurable intent for QCOS identities, cognitive cells, plugins, subsystems, and engines.

Current Status

Initial runtime model and service created as the second QCOS Kernel primitive.

Redis Storage

qcos:goals

Supported Fields

goal_id
identity_id
name
description
parent_goal_id
priority
status
target_value
current_value
unit
progress
confidence
deadline
owner
evidence
dependencies
created_at
updated_at

Progress Calculation

Progress is automatically calculated when target_value and current_value are numeric.

Next Steps

Attach goals to existing QCOS identities.
Define accepted status and priority values.
Link goals to evidence, metrics, and business outcomes.

QCOS Identity

Purpose

Provide structured identity records for QCOS cognitive cells, plugins, subsystems, and engines.

Current Status

Initial runtime model and service created for QCOS Alpha.

Redis Storage

qcos:identity:cells

Supported Fields

id
name
type
mission
purpose
owner
status
goals
responsibilities
dependencies
interfaces
metrics
memory_refs
documentation_refs
architecture_refs
confidence
created_at
updated_at

Next Steps

Register identities for existing Jarvis agents.
Define identity status values and confidence scoring.
Link identity records to documentation and architecture references.

QCOS Memory Engine

Purpose

Store and index observations that Attention has judged worth preserving for future reasoning, planning, simulation, reflection, and learning.

Current Status

Initial runtime model and service created as the fifth QCOS Kernel primitive.

Redis Storage

qcos:memory
qcos:memory:index

Supported Fields

memory_id
identity_id
observation_id
attention_id
memory_type
summary
content
importance
confidence
tags
source
related_memory_ids
created_at
updated_at

Memory Types

episodic
semantic
procedural
strategic
operational
risk
research

Reference Preservation

Memory stores meaning and retrieval structure while preserving references to immutable observation records and attention decisions through observation_id and attention_id.

QCOS Law 005

Memory preserves attended experience. Observations remain immutable; memory stores meaning and retrieval structure.

Next Steps

Add benchmark datasets for memory retrieval quality.
Connect memory records to reasoning and planning.
Track which memories improve downstream cognitive outcomes.

QCOS Observation Engine

Purpose

Record immutable QCOS perceptions of reality from identities, cognitive cells, plugins, subsystems, and engines.

Current Status

Initial runtime model and service created as the third QCOS Kernel primitive.

Redis Storage

qcos:observations

Supported Fields

observation_id
identity_id
source
category
type
timestamp
payload
confidence
evidence
tags
correlation_id
immutable

QCOS Law 002

Observations are immutable and append-only.

Next Steps

Capture observations from existing QCOS identities.
Link observations to goals, evidence, and world model records.
Define category and type conventions.

QCOS Plugins

Purpose

Reserve a home for future QCOS-native plugins.

Current Status

Placeholder folder initialized for QCOS Alpha.

Next Steps

Define plugin identity requirements.
Document plugin lifecycle and governance.
Link plugin records to the Identity primitive.

Design Decisions

Purpose

Record major QCOS design decisions and their reusable rationale.

Current Status

Initial placeholder for decision records.

Entry Format

Decision
Date
Context
Options Considered
Chosen Direction
Rationale
Consequences
Reuse Notes

Initial Notes

Kernel primitives should be introduced through RFCs and design reviews.
Observations are immutable and append-only.
Attention allocates cognition across observations.

Next Steps

Add records for existing kernel primitive decisions.
Link decisions to RFC and design review documents.
Capture rejected alternatives, not only final choices.

Engineering Principles

Purpose

Define reusable engineering principles for QCOS implementation work.

Current Status

Initial placeholder for QCOS engineering doctrine.

Principles

Keep kernel primitives small and composable.
Prefer explicit data models and Redis keys.
Preserve import safety with Redis-free tests.
Keep runtime behavior auditable.
Make generated documentation part of the validation loop.
Make cognitive scheduling decisions inspectable through scores, queues, recommendations, and human review flags.
Measure cognitive effectiveness with benchmarks before expanding kernel complexity.
Preserve continuous architectural integrity.

QCOS Law 006

Attention Scheduling

The Attention Engine should expose enough scoring context to explain why an observation was ignored, archived, remembered, reasoned about, planned, simulated, acted on, or escalated.

Benchmark Discipline

Every major kernel primitive should define how it improves measurable cognitive effectiveness, cognitive economy, or decision quality.

Next Steps

Add examples from Identity, Goals, Observation, and Attention.
Convert repeated engineering patterns into templates.
Connect principles to tests and validation commands.
Link engineering principles to benchmark outcomes.

Architectural Tradeoffs

Purpose

Document architectural tradeoffs so future QCOS work can reuse past reasoning.

Current Status

Initial placeholder for tradeoff records.

Tradeoff Areas

Kernel primitive versus service boundary.
Redis hash storage versus future durable storage.
Immutable records versus mutable operational state.
Generated documentation versus hand-maintained summaries.
Import-only tests versus deeper service integration tests.

Next Steps

Record tradeoffs for Observation immutability.
Record tradeoffs for Attention scoring thresholds.
Link tradeoffs to RFCs and design review outcomes.

Failed Experiments

Purpose

Preserve failed experiments and rejected paths so QCOS does not repeat avoidable mistakes.

Current Status

Initial placeholder. No failed QCOS experiments have been recorded yet.

Entry Format

Experiment
Hypothesis
Method
Result
Failure Mode
Lesson
Future Constraint

Next Steps

Add entries when a design, implementation, or workflow fails validation.
Link failures to corrective RFCs or design review updates.
Distinguish true failures from deferred ideas.

Patterns

Purpose

Capture reusable QCOS implementation and documentation patterns.

Current Status

Initial placeholder for reusable patterns.

Current Patterns

Kernel primitive folder: README.md, __init__.py, models.py, service.py.
Route folder pattern: agents/api/routes/qcos_<primitive>.py.
Import tests should not require Redis.
Runtime services should receive Redis through router configuration.
Documentation export should include kernel, RFC, vision, research, and QKB material.

Next Steps

Create a kernel primitive scaffold checklist.
Add route and service examples.
Link patterns to design review checklist items.

Lessons Learned

Purpose

Record lessons from QCOS implementation, validation, and documentation work.

Current Status

Initial placeholder for reusable lessons.

Initial Lessons

Kernel primitives need clear interaction rules before implementation.
Immutable observations create a stable evidence layer.
Attention should prevent equal processing of unequal signals.
RFCs and design reviews reduce architectural drift.

Next Steps

Add lessons after each kernel release.
Link lessons to failed experiments and tradeoffs.
Promote durable lessons into laws or acceptance rules when justified.

Glossary

Purpose

Define QCOS terminology for consistent research, design, implementation, and review.

Current Status

Initial glossary placeholder.

Terms

Attention: The mechanism for allocating cognitive processing across observations.
Goal: A measurable intent attached to an identity.
Identity: A structured record describing a cognitive cell, plugin, subsystem, or engine.
Kernel Primitive: A core QCOS capability that other cognitive systems compose around.
Observation: An immutable, append-only perception record.
QKB: QCOS Knowledge Base.
RFC: A formal request for comments for major architecture proposals.

Next Steps

Add terms for Memory, Reasoning, Planning, Simulation, Reflection, Learning, and Evolution.
Link glossary terms to source documents.
Keep definitions stable and concise.

Kernel Release Notes

Purpose

Track QCOS kernel evolution and summarize changes by alpha release.

Current Status

Release notes updated through Alpha 0.5.

Alpha Releases

Alpha 0.1: Identity primitive initialized.
Alpha 0.2: Goals primitive initialized.
Alpha 0.3: Observation primitive initialized.
Alpha 0.4: Attention primitive initialized as the QCOS Cognitive Scheduler.
Alpha 0.5: Memory primitive initialized for attended experience preservation.

Upcoming Releases

Alpha 0.6: Reasoning primitive.
Alpha 1.0: First complete cognitive kernel.

Benchmark Notes

QCOS benchmark foundations now track attention quality, cognitive economy, and kernel alpha progress.
Memory implementation should use benchmark results to validate whether stored knowledge improves cognition.
Memory benchmarks should track retrieval quality, provenance preservation, and usefulness for future reasoning.

Next Steps

Add release notes after each kernel primitive lands.
Link each release to RFCs, design reviews, tests, and generated docs.
Capture migration notes when kernel contracts change.
Record benchmark coverage and results for each future primitive.

QCOS Knowledge Base

Purpose

Preserve reusable institutional knowledge for QCOS architecture, engineering, tradeoffs, patterns, failures, and lessons.

Current Status

Initial QKB structure created for the QCOS Alpha kernel.

QCOS Law 004

Every major architectural decision must leave behind reusable knowledge. No important decision should exist only in code or in a developer's memory.

Sections

[Design Decisions](0001_design_decisions.md)
[Engineering Principles](0002_engineering_principles.md)
[Architectural Tradeoffs](0003_architectural_tradeoffs.md)
[Failed Experiments](0004_failed_experiments.md)
[Patterns](0005_patterns.md)
[Lessons Learned](0006_lessons_learned.md)
[Glossary](0007_glossary.md)
[Kernel Release Notes](0008_kernel_release_notes.md)

Next Steps

Backfill knowledge records for Identity, Goals, Observation, and Attention.
Link RFCs and design reviews to reusable QKB entries.
Review QKB entries during future kernel releases.

QCOS RFCs

Purpose

Track formal proposals for major QCOS architecture changes, kernel primitives, and governance decisions.

Process

Every major QCOS architectural proposal and every new QCOS kernel primitive should begin as an RFC before implementation.

Accepted RFCs should produce reusable QKB entries when they introduce durable rationale, tradeoffs, patterns, or lessons.

RFC Index

[RFC-0001: QCOS Constitution](RFC-0001-qcos-constitution.md)
[RFC-0002: Kernel Primitives](RFC-0002-kernel-primitives.md)
[RFC-0003: Observation Immutability](RFC-0003-observation-immutability.md)
[RFC-0004: Design Review Process](RFC-0004-design-review-process.md)
[RFC-0005: Attention Engine](RFC-0005-attention-engine.md)
[RFC-0006: Memory Architecture](RFC-0006-memory-architecture.md)
[RFC-0007: Cognitive Economy](RFC-0007-cognitive-economy.md)

Knowledge References

[QCOS Knowledge Base](../qkb/README.md)
[QCOS Kernel Version](../qcos/KERNEL_VERSION.md)

Required Sections

Status
Context
Proposal
Rationale
Consequences
Open Questions

RFC-0001: QCOS Constitution

Status

Draft.

Context

QCOS needs a formal constitutional layer that defines purpose, authority, safety boundaries, design standards, and long-term operating doctrine.

Proposal

Establish the QCOS constitution as the governing source for kernel primitives, cognitive cells, design reviews, RFCs, and self-improvement rules.

Rationale

A constitutional layer prevents ad hoc architectural drift and keeps QCOS aligned with owner authority, business value, safety, and measurable cognitive capability.

Consequences

Kernel primitives must align with constitutional rules.
Major changes require documentation before implementation.
Governance decisions become easier to audit and improve.

Open Questions

Which rules should be immutable constitutional laws?
How often should constitutional documents be reviewed?
What changes require explicit owner approval?

RFC-0002: Kernel Primitives

Status

Draft.

Context

QCOS kernel primitives define the core building blocks used by identities, goals, observations, future memory systems, and cognitive cells.

Proposal

Formalize kernel primitives as small, composable runtime capabilities that must pass design review and define their interactions with existing primitives.

Rationale

Kernel primitives should remain few, durable, measurable, and understandable. This keeps QCOS extensible without turning the kernel into a loose collection of unrelated services.

Consequences

New primitives require RFC and design review.
Each primitive must define data models, Redis keys, endpoint behavior, tests, and documentation.
Primitive interactions become first-class architecture concerns.

Open Questions

What is the threshold for promoting a capability into the kernel?
Which primitives should be built after Observation?
How should primitives be versioned over time?

RFC-0003: Observation Immutability

Status

Draft.

Context

Observations represent QCOS perceptions of reality. If observations can be rewritten, the system loses auditability and cannot reliably learn from past perception.

Proposal

Adopt QCOS Law 002: Observations are immutable and append-only.

Rationale

Immutable observations preserve evidence, support traceable learning, and let later systems compare belief, action, and outcome against the original perception record.

Consequences

Observation routes must not expose update or delete endpoints.
Corrections should be represented by new observations or derived records.
Storage and retention policy become important as observation volume grows.

Open Questions

What retention policy should apply to low-value observations?
How should sensitive observations be handled?
What derived records should summarize or supersede raw observations?

RFC-0004: Design Review Process

Status

Draft.

Context

QCOS needs a repeatable way to evaluate kernel primitives and major architecture proposals before implementation.

Proposal

Require every new QCOS kernel primitive to pass a design review covering architectural fit, kernel interactions, data model, evolution path, safety and governance, testing, and documentation.

Rationale

Design reviews reduce architectural mistakes, clarify tradeoffs early, and ensure implementation work remains small, testable, reversible, and aligned with the QCOS constitution.

Consequences

Kernel implementation work should not begin until design review questions are answered.
Review artifacts become part of the QCOS knowledge base.
Repeated review findings can become future acceptance rules.

Open Questions

Where should completed design review records live?
Who can approve a design review?
What level of review is required for non-kernel QCOS changes?

RFC-0005: Attention Engine

Status

Accepted for Alpha 0.4.

Context

QCOS will need a way to prioritize observations, goals, tasks, risks, opportunities, and cognitive work across identities and cells.

Proposal

Introduce the Attention Engine as the fourth QCOS kernel primitive. It scores observations with importance, urgency, novelty, risk, opportunity, goal alignment, confidence, and processing cost, then routes cognitive work into priority queues and recommendations.

Scoring Model

Initial score:

importance + urgency + novelty + risk + opportunity + goal_alignment + confidence - processing_cost

Priority Queues

immediate
high
medium
low
archive

Recommendations

ignore
archive
remember
reason
plan
simulate
act
human_review

Human Escalation

The initial implementation recommends human_review when risk exceeds a configurable code threshold or when the recommendation implies a high-impact action.

Rationale

Without attention, QCOS may collect records without knowing what deserves action. Attention converts raw state into prioritized cognitive work.

Attention must also be benchmarked. QCOS should measure prioritization accuracy, critical observation misses, human escalation quality, goal alignment, recommendation quality, and cognitive cost saved.

Consequences

Attention must interact with Identity, Goals, Observations, and future Memory.
Scoring criteria must be inspectable and tied to business value, urgency, risk, confidence, and owner priorities.
Human escalation creates a governance hook before high-impact cognitive action.
Benchmarking creates feedback loops for improving attention quality before Memory, Reasoning, Planning, and Simulation depend on it.
Poor attention logic could amplify noise or miss important signals.

Open Questions

How should attention learn from outcomes over time?
What thresholds should be owner-configurable at runtime instead of in code?
Which recommendations should count as high-impact as QCOS gains more agency?
What benchmark thresholds are required before Attention can drive autonomous downstream workflows?

RFC-0006: Memory Architecture

Status

Accepted for Alpha 0.5.

Context

QCOS needs memory that can preserve facts, observations, decisions, goals, evidence, and lessons across time.

Proposal

Define a memory architecture that preserves attended observations as retrievable memory without modifying immutable observation or attention records.

Memory records must retain observation_id and attention_id references, classify memory by type, and provide searchable summaries, tags, content, related memory links, importance, confidence, and source metadata.

Memory Types

episodic
semantic
procedural
strategic
operational
risk
research

Retrieval Interfaces

Create memory from attended observations.
List memories by recency.
Retrieve memory by ID.
Search memories by query, identity, memory type, or tag.
Link related memories without changing source observations.

Rationale

Memory must support cognition without becoming an unstructured log. Clear memory layers allow QCOS to retrieve context, learn from outcomes, and maintain evidence quality.

QCOS Law 005: Memory preserves attended experience. Observations remain immutable; memory stores meaning and retrieval structure.

Consequences

Memory must define retention, summarization, and provenance rules.
Identity, Goals, Observations, and Attention will depend on memory interfaces.
Memory must preserve provenance through observation and attention references.
Incorrect memory design can create drift, duplication, or stale reasoning.

Open Questions

What belongs in Redis versus future long-term storage?
How should memory confidence and freshness be represented?
What memory APIs should cognitive cells use?
What retrieval benchmarks prove that memory improves reasoning, planning, simulation, reflection, and learning?

RFC-0007: Cognitive Economy

Status

Draft.

Context

QCOS will eventually coordinate many identities, goals, observations, memory records, and cognitive cells. It needs a way to allocate cognitive effort and measure value created.

Proposal

Explore a cognitive economy model where cognitive work has cost, priority, value, evidence, and outcome feedback.

Rationale

A cognitive economy can help QCOS spend attention and compute on work that improves revenue, reliability, learning speed, and strategic advantage.

Consequences

Goals and observations may need economic metadata.
Attention and memory systems may use value signals to prioritize work.
Governance is needed to prevent local optimization from harming long-term objectives.

Open Questions

What units should represent cognitive cost and value?
How should business outcomes feed back into cognitive prioritization?
Should cognitive economy rules be centralized or identity-specific?

QCOS Manifesto

Purpose

Define the founding intent of the Qubit Cognitive Operating System.

Current Status

Placeholder constitutional document. Core claims, commitments, and operating principles need owner review.

Key Notes

QCOS should describe cognition as an operating system, not a single agent.
The manifesto should connect intelligence, business value, safety, and long-term compounding capability.
Future revisions should separate aspiration from verified implementation.

Next Steps

Draft the core thesis.
Define non-negotiable principles.
Link the manifesto to governance, ethics, and reference architecture.

Cognitive Primitives

Purpose

Define the smallest reusable units of cognition in QCOS.

Current Status

Placeholder document. Primitive definitions need research, examples, and implementation mapping.

Key Notes

Candidate primitives include memory, perception, planning, reflection, action, evaluation, and simulation.
Each primitive should have inputs, outputs, constraints, and success measures.
Primitives should compose into higher-order cognitive workflows.

QCOS Law 002

Observations are immutable and append-only.

QCOS Law 003

Cognition is allocated by attention. Not every observation deserves equal processing.

Attention Primitive

Attention is the QCOS cognitive scheduler. It ranks observations by importance, urgency, novelty, risk, opportunity, goal alignment, confidence, and processing cost so downstream primitives can decide what to remember, reason about, plan, simulate, act on, or escalate for human review.

QCOS Law 004

Every major architectural decision must leave behind reusable knowledge. No important decision should exist only in code or in a developer's memory.

QCOS Law 005

Memory preserves attended experience. Observations remain immutable; memory stores meaning and retrieval structure.

QCOS Law 006

Memory Primitive

Memory stores meaning, summaries, retrieval tags, and links for observations that Attention has judged worth preserving. It must preserve observation_id and attention_id references instead of mutating immutable observation records.

Kernel Acceptance Rule

Every new QCOS kernel primitive must answer:

1. How does it interact with the other kernel primitives?

2. What measurable cognitive capability does it add?

3. How can it improve itself over time?

Next Steps

Inventory candidate primitives.
Define primitive interfaces.
Map primitives to existing Qubit Jarvis agents and services.

Cognitive Cells

Purpose

Describe how cognitive primitives combine into autonomous, reusable cognitive cells.

Current Status

Placeholder document. Cell lifecycle, boundaries, and coordination rules need definition.

Key Notes

Cognitive cells should encapsulate a specific capability or business function.
Cells should expose clear contracts for memory, tools, evaluation, and escalation.
Cell behavior should remain inspectable and reversible.

Next Steps

Define the cognitive cell model.
Specify inputs, outputs, state, and governance hooks.
Identify first candidate cells for implementation.

Meta Cognition

Purpose

Define how QCOS observes, evaluates, and improves its own cognition.

Current Status

Placeholder document. Reflection loops and evaluation criteria need formal design.

Key Notes

Meta cognition should detect uncertainty, drift, failure, duplication, and opportunity.
Reflection should produce actionable improvements, not abstract commentary.
Self-observation must preserve auditability.

Next Steps

Define reflection events.
Specify quality signals and error classes.
Link meta cognition to self-improvement and governance.

Self Improvement

Purpose

Describe how QCOS can improve its workflows, models, tools, and knowledge over time.

Current Status

Placeholder document. Improvement loops need measurable objectives and safety limits.

Key Notes

Self-improvement should prioritize revenue impact, reliability, and learning speed.
Changes should be small, testable, reversible, and reviewable.
Automated improvement must respect owner authority and operational constraints.

Next Steps

Define improvement loop stages.
Establish validation gates.
Identify safe automation candidates.

Governance

Purpose

Define the decision rights, review processes, and control boundaries for QCOS.

Current Status

Placeholder constitutional document. Governance rules need owner approval before operational use.

Key Notes

Governance should make authority, escalation, and approval boundaries explicit.
Production, financial, infrastructure, and destructive actions require strong controls.
Governance should support speed without sacrificing accountability.

Next Steps

Define approval tiers.
Specify audit and review cadence.
Link governance to ethics and self-improvement.

Ethics

Purpose

Define ethical constraints and operating commitments for QCOS.

Current Status

Placeholder document. Ethical principles need concrete examples and enforcement mechanisms.

Key Notes

QCOS should preserve human agency, transparency, and accountability.
Systems should avoid hidden manipulation, unsafe autonomy, and unreviewable decisions.
Ethical guidance should be practical enough to shape product and infrastructure choices.

Next Steps

Draft ethical principles.
Define prohibited behaviors.
Link ethical checks to governance and evaluation.

World Model

Purpose

Describe how QCOS represents businesses, markets, users, infrastructure, risks, and opportunities.

Current Status

Placeholder document. World model scope and data contracts need design.

Key Notes

The world model should separate facts, assumptions, forecasts, and decisions.
Evidence quality and freshness should be tracked.
Business outcomes should be first-class entities.

Next Steps

Define core entities.
Specify evidence and confidence fields.
Map current Redis and API data into the model.

Simulation Engine

Purpose

Define how QCOS simulates decisions, strategies, experiments, and future operating states.

Current Status

Placeholder document. Simulation inputs, methods, and validation rules need research.

Key Notes

Simulations should make assumptions explicit.
Outputs should be treated as decision support, not certainty.
Business experiments should feed simulation calibration.

Next Steps

Define simulation scenarios.
Identify required world model data.
Establish validation against real outcomes.

Evolution

Purpose

Describe how QCOS evolves across versions, capabilities, and operating environments.

Current Status

Placeholder document. Evolution strategy needs milestones and safety constraints.

Key Notes

Evolution should preserve continuity, auditability, and business alignment.
New capabilities should graduate from research to controlled operation.
Architecture should support replacement of weak components without system collapse.

Next Steps

Define maturity stages.
Specify capability graduation criteria.
Link evolution to the 2050 roadmap.

Reference Architecture

Purpose

Define the high-level architecture of QCOS as a cognitive operating system.

Current Status

Placeholder document. Component boundaries, data flows, and deployment assumptions need design.

Key Notes

Reference architecture should include primitives, cells, memory, tools, governance, and evaluation.
Architecture should distinguish current Qubit Jarvis implementation from future QCOS design.
Interfaces should be explicit enough to guide build decisions.

Next Steps

Draft system context and component diagrams.
Define core interfaces.
Map implementation phases to the roadmap.

Research Agenda

Purpose

Define the research questions that must be answered to build QCOS responsibly.

Current Status

Placeholder document. Research priorities need ranking by business value, feasibility, and risk.

Key Notes

Research should connect theory to implementation and measurable outcomes.
Each research question should have an owner, evidence standard, and decision impact.
Unproven assumptions should remain visible.

Next Steps

Prioritize research themes.
Define evidence requirements.
Link research documents to architecture and roadmap decisions.

Roadmap 2050

Purpose

Describe the long-range path from Qubit Jarvis to a mature Qubit Cognitive Operating System.

Current Status

Placeholder roadmap. Milestones require owner review and staged validation.

Key Notes

The roadmap should separate near-term commitments from long-term possibilities.
Revenue, defensibility, and operational reliability should shape sequencing.
Each phase should identify capabilities, risks, and proof points.

Next Steps

Define roadmap horizons.
Identify milestones from 2026 through 2050.
Link milestones to research agenda and reference architecture.

QCOS Design Reviews

Purpose

Define the design review standard for new QCOS kernel primitives and major QCOS runtime changes.

Current Status

Initial design review checklist created for QCOS kernel governance.

Design Review Requirement

Every new QCOS kernel primitive must pass a design review before implementation.

Checklist

Architectural Fit

Explain why the primitive belongs in the QCOS kernel.
Identify the cognitive cell, plugin, subsystem, or engine use cases it enables.
Confirm the primitive is small, composable, and not duplicating an existing primitive.

Kernel Interactions

Describe how the primitive interacts with Identity, Goals, Observations, and future kernel primitives.
Define required inputs, outputs, lifecycle events, and ownership boundaries.
Identify dependencies and any ordering constraints between primitives.

Data Model

Define every field, type, default value, and required value.
Specify Redis keys, persistence rules, immutability rules, and retention assumptions.
Explain how records will be queried, linked, and referenced by other primitives.

Evolution Path

Describe how the primitive can improve itself over time.
Define versioning, migration, and backward-compatibility expectations.
Identify what evidence would justify expanding, replacing, or retiring the primitive.

Safety & Governance

Identify approval boundaries, owner authority requirements, and operational risks.
Document destructive actions, privacy risks, financial risks, and infrastructure risks.
Confirm governance hooks, auditability, and failure handling.

Testing

Define import, unit, service, route, and integration test expectations.
Specify validation commands and expected outcomes.
Identify Redis-free tests required for import safety.

Documentation

List required documentation updates before implementation.
Link vision, kernel, API, and generated documentation requirements.
Confirm the docs export will include the new primitive.

Next Steps

Apply this checklist to the next QCOS kernel primitive before writing runtime code.
Add design review records for existing Identity, Goal, and Observation primitives.
Convert recurring checklist findings into kernel acceptance rules.

QCOS Vision

Purpose

Collect the constitutional vision documents for the Qubit Cognitive Operating System.

Current Status

Initial placeholder structure created for manifesto, primitives, cells, meta cognition, self-improvement, governance, ethics, world modeling, simulation, evolution, architecture, research, roadmap, and design reviews.

Documents

[QCOS Manifesto](000_qcos_manifesto.md)
[Cognitive Primitives](001_cognitive_primitives.md)
[Cognitive Cells](002_cognitive_cells.md)
[Meta Cognition](003_meta_cognition.md)
[Self Improvement](004_self_improvement.md)
[Governance](005_governance.md)
[Ethics](006_ethics.md)
[World Model](007_world_model.md)
[Simulation Engine](008_simulation_engine.md)
[Evolution](009_evolution.md)
[Reference Architecture](010_reference_architecture.md)
[Research Agenda](011_research_agenda.md)
[Roadmap 2050](012_roadmap_2050.md)
[QCOS Design Reviews](013_qcos_design_reviews.md)

Governance Standard

Every new QCOS kernel primitive must pass a design review before implementation.

Major QCOS architectural proposals and kernel primitives should begin as RFCs before implementation.

Major architectural decisions should leave reusable knowledge in the QKB.

Knowledge References

[QCOS Knowledge Base](../qkb/README.md)
[QCOS Kernel Version](../qcos/KERNEL_VERSION.md)

Next Steps

Expand each placeholder into a reviewed constitutional document.
Connect vision documents to implementation plans.
Establish a review cadence for QCOS doctrine.
Apply the design review checklist before new QCOS kernel primitives are implemented.
Link future constitutional decisions to RFC records.
Preserve reusable rationale in the QKB.

Future of Cognition

Purpose

Explore how artificial, human, and organizational cognition may evolve.

Current Status

Placeholder research note. Claims require evidence and source review.

Research Questions

What changes when cognition becomes programmable infrastructure?
Which cognitive capabilities create durable business advantage?
How should cognition be measured across humans, agents, and organizations?

Next Steps

Collect foundational sources.
Define working hypotheses.
Link findings to QCOS primitives and roadmap.

Post-Agent Architecture

Purpose

Research architectures that move beyond isolated agents toward operating systems of cognition.

Current Status

Placeholder research note. Architecture patterns need comparison and validation.

Research Questions

What are the limits of single-agent and multi-agent designs?
Which coordination patterns support durable cognition?
How should memory, tools, governance, and evaluation be shared?

Next Steps

Compare agent, swarm, cell, and operating-system models.
Identify failure modes in current agent architectures.
Feed conclusions into QCOS reference architecture.

Digital Organisms

Purpose

Research whether persistent software systems can use organism-like structures for adaptation and survival.

Current Status

Placeholder research note. Concepts need careful definition to avoid metaphor-driven design.

Research Questions

Which organism concepts are useful for software cognition?
How should reproduction, mutation, selection, and metabolism translate into systems?
What safety constraints are required for adaptive digital systems?

Next Steps

Define terms precisely.
Separate useful analogies from implementation requirements.
Link findings to evolution and self-improvement.

Cognitive Operating Systems

Purpose

Research the design space for operating systems that coordinate cognitive capabilities.

Current Status

Placeholder research note. Prior art and design principles need review.

Research Questions

What services should a cognitive operating system provide?
How should applications, agents, tools, and memory run on top of it?
What makes a cognitive OS reliable, inspectable, and economically useful?

Next Steps

Survey related systems and terminology.
Define QCOS differentiators.
Link research outputs to the reference architecture.

Enterprise Cognition

Purpose

Research how organizations can use cognitive systems to improve strategy, operations, and revenue.

Current Status

Placeholder research note. Enterprise use cases and constraints need evidence.

Research Questions

Which enterprise workflows benefit most from cognitive infrastructure?
How should cognitive systems integrate with existing business operations?
What governance is required for enterprise adoption?

Next Steps

Identify high-value workflows.
Document adoption risks.
Connect findings to Qubit Jarvis business systems.

Machine Reflection

Purpose

Research how machine systems can inspect, critique, and improve their own reasoning and behavior.

Current Status

Placeholder research note. Reflection methods need testing against real outcomes.

Research Questions

What makes reflection useful instead of performative?
How should systems detect uncertainty, contradiction, and failure?
Which reflection outputs should trigger automated action or human review?

Next Steps

Define reflection quality metrics.
Compare reflection patterns.
Link findings to meta cognition and self-improvement.

World Models

Purpose

Research representations that allow cognitive systems to reason about reality, business, and change.

Current Status

Placeholder research note. Model structure and evidence handling need design.

Research Questions

How should facts, assumptions, predictions, and decisions be represented?
How should uncertainty and freshness influence action?
What data is required for useful business world models?

Next Steps

Survey representation strategies.
Define evidence standards.
Link findings to the QCOS world model.

Collective Intelligence

Purpose

Research how groups of humans, agents, tools, and organizations can think and act together.

Current Status

Placeholder research note. Coordination mechanisms and evaluation methods need study.

Research Questions

What makes collective cognition better than individual cognition?
How should authority, specialization, and feedback be structured?
How can collective systems avoid noise, drift, and group failure?

Next Steps

Compare coordination models.
Define collective performance metrics.
Link findings to cognitive cells and governance.

Human-AI Symbiosis

Purpose

Research operating models where humans and AI systems amplify each other over time.

Current Status

Placeholder research note. Human workflows, trust boundaries, and adoption patterns need evidence.

Research Questions

Which decisions should remain human-led?
How can AI systems increase human agency instead of replacing judgment blindly?
What interfaces support trust, speed, and accountability?

Next Steps

Define collaboration patterns.
Identify risks to autonomy and accountability.
Link findings to ethics and governance.

QCOS Research

Purpose

Collect research notes that inform the Qubit Cognitive Operating System.

Current Status

Initial placeholder structure created for future cognition, post-agent architecture, digital organisms, cognitive operating systems, enterprise cognition, machine reflection, world models, collective intelligence, and human-AI symbiosis.

Knowledge References

[QCOS Knowledge Base](../qkb/README.md)
[QCOS Kernel Version](../qcos/KERNEL_VERSION.md)

Documents

[Future of Cognition](000_future_of_cognition.md)
[Post-Agent Architecture](001_post_agent_architecture.md)
[Digital Organisms](002_digital_organisms.md)
[Cognitive Operating Systems](003_cognitive_operating_systems.md)
[Enterprise Cognition](004_enterprise_cognition.md)
[Machine Reflection](005_machine_reflection.md)
[World Models](006_world_models.md)
[Collective Intelligence](007_collective_intelligence.md)
[Human-AI Symbiosis](008_human_ai_symbiosis.md)

Next Steps

Expand each placeholder with sources, hypotheses, and implications.
Promote validated findings into the Vision documents.
Maintain research notes separately from operating doctrine.
Preserve reusable research conclusions and failed assumptions in the QKB.

Qubit Jarvis Enterprise Documentation

Table of Contents

Qubit Jarvis Documentation

Purpose

Current Status

QCOS Sections

QCOS Alpha

Key Notes

Next Steps

API

Purpose

Conversation Endpoints

POST /chat

GET /memory

DELETE /memory

Key Notes

Next Steps

Conversation Architecture

Purpose

Identity

Default Conversation

Redis Keys

Chat Lifecycle

Lifecycle

Backward Compatibility

Isolation Guarantees

Current Limitations

Infrastructure

Purpose

Current Status

Key Notes

Next Steps

Architecture Overview

Purpose

Current Status

Key Notes

Next Steps

Redis Schema

Purpose

Conversation Keys

Key Notes

Next Steps

AI App Factory

Purpose

Current Status

Key Notes

Next Steps

CRM Pipeline

Purpose

Current Status

Key Notes

Next Steps

Proposal Engine

Purpose

Current Status

Key Notes

Next Steps

Revenue Engine

Purpose

Current Status

Key Notes

Next Steps

Codex Execution

Purpose

Current Status

Key Notes

Next Steps

Builder Projects

Purpose

Current Status

Key Notes

Next Steps

Builder Specifications

Purpose

Current Status

Key Notes

Next Steps

Builder Tasks

Purpose

Current Status

`POST /chat`

`GET /memory`

`DELETE /memory`