MD-OS

Codex Natural Language Operator Model

Natural language is the command interface for MD-OS operation. It is not the stable memory of the system by itself.

The stable form is:

natural language intent
-> bounded task frame
-> provenance and before/after semantic delta
-> semantic commitment gate when canonical state may change
-> repository artifact
-> schema or test
-> command readback
-> replay
-> runtime compiler rebuild
-> final report

This model applies when a coding host such as Codex operates the repository. The host may receive natural-language instructions, read the codebase, edit files, and run commands, but the work is complete only when the repository contains the durable artifacts that preserve and verify the result.

Operating Formula

Natural language = command surface
AGENTS.md = operating constitution
schemas = grammar
tests = externalized reality checks
replay = verified memory
compiler = cognitive runtime readback

The operator should not leave important rules in conversational context. Security policy, claim status, skill promotion rules, command contracts, episode format, eval criteria, and identity gates must be stored in the repository.

Context Sufficiency

A coherent controller is not enough if it receives a fragmentary context. Every natural-language turn therefore starts with a bounded invariant baseline: identity, cognitive bootstrap, compact core, conceptual orientation, active work, continuity, and the generated catalog of context packs.

Task-specific lexical matches are only hints. They may save reads, but they do not establish meaning, relevance, or completeness. The turn frame must carry a hash-bound context sufficiency contract with two separate states:

baseline = ready | degraded
task context = pending turn resolution

The distinction matters. Baseline ready means that the stable orientation was loaded; it does not mean that every dependency of the current task is known. Inside the same ordinary model call, a simple answer may use the human request and baseline directly. Before a nontrivial project claim or action, the operator must identify the task’s dependency edges, route through the compact context-pack catalog, inspect the required canonical sources and current readback, then act or report insufficiency. Loading every repository file is neither required nor equivalent to cognitive unity.

For nontrivial repository navigation, Graphify is the default first-pass graph orientation layer. The operator should prefer:

cortex graphify orient "<question>"

before broad file reads when a current graph exists, and should refresh the graph with:

cortex graphify build .

when the graph needs to evolve with current files, connectors, schemas, audit artifacts, or knowledge nodes.

Task Frame

A well-formed natural-language task should be converted into:

goal
scope
forbidden paths
required outputs
acceptance criteria
master closure frame when the task is complex
epistemic rules
execution rules
verification commands
final readback

If the user gives an underspecified task, the host should infer a conservative scope from the current repository contracts. If the missing information would make the task unsafe or identity-changing, the host should ask a short clarifying question before editing.

Hard Rules

• Never introduce autonomous continuous execution unless explicitly requested and separately gated.
• Never report closure progress on a complex task unless a named master-closure dependency edge closed with readback; use md-os/kb/MASTER_CLOSURE_DISCIPLINE_MODEL.md when a task risks target proliferation.
• Never modify host-local, unsafe, secret, credential, publication-sensitive, or append-only audit files unless explicitly requested.
• Never promote a claim, skill, capability, identity element, connector, or permission expansion without verifier readback.
• Every new runtime artifact must be schema-valid when a schema exists, or must be accompanied by a schema/proposal when it creates a new runtime class.
• Every operation must produce readback.
• Every learning cycle must write an episode.
• Every promoted skill must have an eval.
• Every build-relevant change must be covered by a focused test or an explicit verification command.
• Runtime generated outputs should be rebuilt by builders, not edited by hand.
• A host-native edit primitive is optional. If it fails before mutation, route the same unified diff through cortex workspace patch, which is confined to the active workspace and returns before/after hashes; do not weaken host security policy or grant broader permissions to recover local edit ability.
• Challenge remains admissible and must retain its source and non-canonical status; replacement requires the authority appropriate to the affected claim.
• No critique, inference, or editorial proposal becomes an authorized project interpretation without provenance, before/after semantic readback, invariant comparison, and the required approval.
• Classify an edit by its effective semantic delta, not by its stated editorial intention. Added, removed, negated, broadened, or narrowed propositions must be routed as semantic revisions.
• Treat editorial correction as reasoned semantic work. Editorial means that the verified before/after delta preserves or clarifies the supported thesis; it does not mean unreasoned or merely mechanical wording work.
• Do not constrain exploration, criticism, hypotheses, or drafts merely because they conflict with a canonical thesis. Constrain their promotion into memory, canonical knowledge, decision, action, identity, or publication.

Verification Ladder

Use the smallest sufficient verification first, then broaden based on risk.

For JavaScript, runtime logic, schemas, or build-output contracts:

npm run check
npm test
npm run build:all
npm run replay
npm run replay

For runtime compiler changes:

node --test test/runtime_compiler.test.js

For verified learning-loop changes:

node --test test/agi_loop.test.js

For documentation and knowledge-base changes that affect semantic or operating state:

node md-os/os/build_semantic_commitment_gate.js status
node md-os/os/build_markdown_graph.js
node md-os/os/mdos.js graphify build . --no-viz
node md-os/os/build_runtime_lifecycle_index.js
node md-os/os/build_semantic_knowledge_graph.js
node md-os/os/agi_loop.js eval
node md-os/os/build_runtime_compiler.js
node md-os/os/build_global_index.js
node md-os/os/build_health_dashboard.js

Output Discipline

The final report should state:

files changed
commands run
tests passed or failed
runtime outputs changed
health status
unresolved risks

The report should be short, concrete, and grounded in generated readback.

Prompt Template

Goal:
[desired result]

Scope:
[allowed files or directories]

Do not modify:
[forbidden paths or state classes]

Required outputs:
[files, schemas, tests, runtime artifacts]

Acceptance criteria:
[commands and readback that must pass]

Semantic commitment frame when meaning may change:
- provenance class
- claim class
- transition from possibility space to commitment space
- propositions before and after
- added, removed, negated, broadened, or narrowed propositions
- affected and superseded invariants
- authority and approval evidence
- challenge status when no canonical effect is requested

Epistemic rules:
- every claim must have status
- complex tasks use a master closure frame
- progress is counted only when a master edge closes
- every operation must have readback
- every promoted skill must have eval
- no identity update without explicit gate

Execution rules:
- make the smallest sufficient change
- run targeted checks first
- then run full checks when risk or scope requires it
- report exact commands and results

MD-OS Specific Rule

For MD-OS, the correct operating path is:

prompt
-> diff
-> focused test
-> full test when needed
-> build
-> replay
-> health/readback
-> compiler rebuild

The host should never ask the user to trust a conversational answer when the repository can produce a stronger artifact, test, replay, or generated readback.

Unified Agentic Shell Path

The public cortex command can fuse a real host shell with the native Codex agent loop without reducing either layer:

human input
├── valid native command
│   -> host shell
│   -> bounded observation
└── natural language
    -> current workspace
    -> fresh thread by default, live same-workspace reuse, explicit /resume
    -> AGENTS.md discovery
    -> APFC turn frame -> reason -> plan -> explore -> bounded tool -> APFC gate
    -> observe -> correct -> verify -> report

The layers have distinct responsibilities:

shell = continuous interaction, cwd, commands, pipes, processes
Codex = plastic reasoning, planning, repository exploration, and tool use
MD-OS = identity, method, persistent operational context, semantic gates,
        policy, bounded authority, executors, sensors, verifiers, and ledger

On POSIX interactive hosts, all cortex entrypoints for the same Git workspace attach to one stable tmux session. A local terminal, ordinary SSH login, and WebSSH can therefore continue the same live Cortex process and Codex thread. Workspace identity selects the shared session; the current directory alone is only the fallback outside Git. If an external process already owns the latest thread, Cortex must fail with explicit attach guidance instead of silently starting a divergent conversation.

MD-OS must preserve Codex’s native agent cycle on this path. It may orient, constrain, observe, verify, and persist commitments, but it must not replace the cycle with a classifier whose final output is executed as one unrestricted host command. Direct human commands retain host-shell authority. Agent-selected actions run inside the workspace sandbox and APFC action gate. Final assistant text is never itself an executable capability.

Codex-native thread history remains outside the repository and is not consulted during ordinary Cortex boot. Shared interactive sessions preserve their already-live thread across terminal transports. Workspace changes start fresh threads. The operator must issue /resume to import the latest matching provider-stored conversation.

A separate private chronology lives at md-os/ops/local/cortex/conversation.ndjson. Cortex records successful human inputs and final assistant responses there, verifies its hash chain, and gives a bounded recent tail to a new thread. A physical folder copy carries the file; Git ignores it, so push and clone do not. It is local working context, never canonical MD-OS memory or publication input. The selected excerpt is still sent to the configured model provider during inference.

Clone-carried working continuity is instead read from the verified md-os/continuity/portable_state.json artifact. The snapshot is non-canonical, excludes raw transcripts and host/model/thread identifiers, and must fail closed on any self-hash, identity-source, or evidence mismatch. Host-local last_turn.md and last_summary.md artifacts are likewise excluded from implicit turn context and require an explicit historical-diagnostic task.

This site is open source. Improve this page.