# Cognitive Substrate Specification

Version: 1.0.0
Status: Draft

## 0. Purpose

This document defines the canonical classes of authored cognitive assets in cnos-style systems.
It answers four questions:

1. What class of thing is this?
2. Where does it live?
3. What structure must it follow?
4. How does the runtime treat it?

This spec governs authored substrate assets.
It does not redefine runtime state machines, transport, or projection layers.

---

## 1. Scope

This spec classifies authored assets into five canonical classes:

- Identity
- Doctrine
- Mindset
- Skill
- Reflection

It also names three runtime/context classes that are not authored substrate assets:

- Capability
- Conversation
- Inbound message

Conversation history, queue entries, and runtime-generated capability declarations are context strata, not cognitive assets.

---

## 2. Canonical Classes

### 2.1 Identity

Identity defines who the agent is and who the user is.
Identity is local to a hub and loaded at every wake-up.
Identity is not doctrine, mindset, or skill.

Typical location:

- `spec/SOUL.md`
- `spec/USER.md`

### 2.2 Doctrine

Doctrine is always-on, constitutive, and non-competitive.

A doctrine artifact defines a global invariant, obligation, prohibition, trust boundary, or runtime grammar.
If removing it changes what the system is allowed to be or do everywhere, it is doctrine.

### 2.3 Mindset

A mindset is always-on, orienting, deterministic, and non-competitive.

A mindset artifact defines a cross-domain framing habit, craft default, or cognitive stance.
If removing it changes how the system habitually interprets many tasks, but does not change its constitutive boundaries, it is a mindset.

### 2.4 Skill

A skill is bounded, selected, and instrumental.

A skill artifact defines a reusable method for a task class.
If it has triggers, preconditions, bounded applicability, or observable effects, and may or may not be loaded depending on current demand, it is a skill.

### 2.5 Reflection

A reflection is dated, revisable, and local.

A reflection records what was learned from recent operation.
Reflections are memory inputs.
They are not stable substrate classes until explicitly promoted.

### 2.6 Capability

A capability is runtime-generated.
It describes what the body can currently observe or do.
Capabilities are not authored doctrine, mindsets, or skills.

---

## 3. Distinction Rule

Use these tests in order.

### 3.1 Identity test

If the artifact defines the agent's self-description or the user's standing context required at wake-up, it is Identity.

### 3.2 Capability test

If the artifact is generated by the runtime to describe currently available observation or effect affordances, it is Capability, not authored substrate.

### 3.3 Reflection test

If the artifact is dated, episodic, recent, or revisable local learning, it is Reflection.

### 3.4 Doctrine test

If the artifact defines a global invariant, obligation, prohibition, trust boundary, or grammar that must apply everywhere, it is Doctrine.

### 3.5 Mindset test

If the artifact defines an always-on cross-domain orientation or interpretive default, but not a constitutive boundary, it is a Mindset.

### 3.6 Skill test

If the artifact defines a reusable bounded method with triggers, preconditions, or effects for a task class, it is a Skill.

### 3.7 Split rule

If one artifact contains constitutive law, always-on orientation, and task procedure mixed together, it MUST be split until each part fits one class.
A single file MUST NOT silently mix doctrine, mindset, and skill semantics.

---

## 4. Placement Algorithm

Given new knowledge K:

1. If K is wake-required self or user context, place it in Identity.
2. Else if K is runtime-generated affordance information, place it in Capability.
3. Else if K is dated or recent learning, place it in Reflection.
4. Else if K defines a global invariant, obligation, prohibition, trust boundary, or runtime grammar, place it in Doctrine.
5. Else if K defines an always-on cross-domain framing default, place it in Mindset.
6. Else if K defines a bounded reusable method with inputs, rules, and effects, place it in Skill.
7. Else decompose K until every part fits one class.

---

## 5. Canonical Locations

### 5.1 Identity

- `spec/SOUL.md`
- `spec/USER.md`

### 5.2 Doctrine

Package source:

- `doctrine/*.md`

Hub-local override:

- `agent/doctrine/<package>/...`

### 5.3 Mindsets

Package source:

- `mindsets/*.md`

Hub-local override:

- `agent/mindsets/<package>/...`

### 5.4 Skills

Package source:

- `skills/<domain>/<name>/SKILL.md`

Optional companions:

- `skills/<domain>/<name>/kata.md`
- references
- scripts
- examples

Hub-local override:

- `agent/skills/<package>/...`

### 5.5 Reflections

- `threads/reflections/...`

### 5.6 Capabilities

Runtime-declared only.

### 5.7 Conversation / Inbound message

Runtime state only. Not authored substrate.

---

## 6. Runtime Treatment

At wake-up or context packing, the runtime MUST treat the classes as follows:

1. Identity — always loaded
2. Doctrine — always loaded, never scored, never bounded by task-slot competition
3. Mindsets — always loaded, never scored, never bounded by task-slot competition
4. Reflections — recent N only
5. Skills — relevance-scored, bounded to top N
6. **Runtime Contract** — always emitted by runtime (see §6.1)
7. Conversation — recent N turns
8. Inbound message — current demand only

Doctrine and mindsets MUST NOT compete for skill slots.
If doctrine or mindsets are handled as task skills, the substrate is misclassified.

### 6.1 Runtime Contract (normative)

The runtime MUST emit a structured **Runtime Contract** at every wake. The contract uses a vertical four-layer self-model (issue #62, replacing the flat three-block v1):

**Identity** — who am I?
- `cn_version`: runtime binary version
- `hub_name`: hub directory name (hub-relative, not absolute path)
- `profile`: effective runtime role from config (derived from package profile, not parsed from SOUL.md)

**Cognition** — what shapes my thinking?
- `installed_packages`: list with per-package doctrine/mindset/skill counts
- `active_overrides`: hub-local overrides by category (doctrine, mindsets, skills)

**Body** — what can my body do?
- observe/effect op kinds, apply_mode, exec_enabled, budgets
- max_passes, max_total_ops
- known peers

**Medium** — what world do I inhabit?
- `constitutive_self`: identity substrate (spec/SOUL.md, spec/USER.md, installed doctrine/mindsets)
- `memory`: temporal record (threads/reflections/, state/conversation.json)
- `private_body`: runtime internals (.cn/, state/, logs/)
- `work_medium`: legitimate work surfaces (src/, docs/, agent/)
- `projection_surface`: communication channels (threads/outbox/)

#### Invariant

After wake, the agent MUST be able to answer from packed context alone:
- Who am I? → identity
- What shapes my thinking? → cognition
- What can my body do? → body
- What world do I inhabit? → medium
- What is my memory vs. my work surface vs. my private internals? → medium zones

If the agent must probe the filesystem for any of these, the Runtime Contract is incomplete.

#### Persistence

The same contract is persisted to `state/runtime-contract.json` for:
- operator inspection
- `cn doctor` validation
- traceability reference

See [`RUNTIME-CONTRACT-v2.md`](../agent-runtime/RUNTIME-CONTRACT-v2.md) for full design.

---

## 7. Canonical File Contracts

### 7.1 Doctrine Contract

A doctrine file MUST contain:

- `# <NAME>`
- `## Claim` — the constitutive law or invariant in one sentence
- `## Scope` — why it applies globally
- `## Rules` — required and forbidden behaviors
- `## Review` — how to self-check or apply the doctrine in practice

A doctrine file MUST be global, not trigger-based.
A doctrine file MUST NOT depend on task selection.
A doctrine file MUST NOT read like a productivity trick.

### 7.2 Mindset Contract

A mindset file MUST contain:

- `# <NAME>`
- `## Core Principle` — the orienting stance in one sentence
- one or more sections that express the persistent interpretive, stylistic, or craft defaults the mindset installs
- one or more sections that show how the mindset changes behavior through rules, examples, anti-patterns, contrast pairs, red flags, lenses, or levels

These sections MAY be named `## Defaults` and `## Rules`, but equivalent structures are valid.

A mindset MAY be organized as levels, lenses, principles, biases, anti-patterns, exemplars, or thematic sections, provided the file remains:

- always-on
- cross-domain
- non-triggered
- non-competitive with task skills

A mindset file MUST NOT define task gating or top-N selection.
A mindset file MUST NOT encode constitutive prohibitions that belong in doctrine.

### 7.3 Skill Contract

A skill file MUST name the domain-specific coherence formula for the task.

The canonical skill contract is:

- optional frontmatter:
  - name
  - description
  - triggers or equivalent applicability hints
- `# <NAME>`
- `## Core Principle` — what coherence looks like in this task domain
- `## 1. Define` — identify the parts, how they fit, name the failure mode (with ❌/✅ pairs)
- `## 2. Unfold` — expand each part into its domain-specific structure (with ❌/✅ pairs)
- `## 3. Rules` — numbered, stable-ID rules with ❌/✅ pairs showing incoherent/coherent behavior

A skill's Core Principle MUST be specific to the domain.
Generic principles such as "follow best practices" are invalid.

A skill MUST use numbered rules with stable IDs.
A skill MUST show incoherent/coherent examples (❌/✅ pairs) when examples increase clarity.

A skill MAY include additional sections (Checklist, Output Format, etc.) after the core contract.
A skill MAY include `kata.md`, references, scripts, or case studies.

### 7.4 Kata Contract

A kata file is an optional companion to a skill.
A kata MUST contain:

- A practice scenario with concrete inputs
- Exit criteria — what "done" looks like
- Expected outputs or behaviors to verify

A kata is a bounded exercise, not a skill definition.

### 7.5 Reflection Contract

A reflection MUST be dated or period-bounded.

A reflection SHOULD state:

- what was observed
- what changed in the model
- what should be promoted, if anything

A reflection MUST NOT silently become doctrine, mindset, or skill without explicit promotion.

---

## 8. Promotion and Splitting Rules

Promotion is allowed only when repeated use proves that a lower class was misclassified.

### 8.1 Reflection → Skill

Promote when:

- the lesson recurs
- the method is reusable
- triggers or preconditions can be named
- success has observable effects

### 8.2 Reflection → Mindset

Promote when:

- the lesson should orient many tasks continuously
- it changes default framing rather than prescribing a bounded method

### 8.3 Reflection or Mindset → Doctrine

Promote when:

- the content is globally binding
- violating it is a breach of the system, not merely weaker craft

### 8.4 Split rule

Split an artifact when:

- one part is globally binding and another part is procedural
- one part is always-on orientation and another part is task-gated method
- a file requires both "always load" and "score top N" semantics

---

## 9. Precedence

Normative precedence for authored substrates is:

Doctrine → Mindset → Skill → Reflection

Identity is loaded first but is not a general override layer.
It localizes the subject and user context to which doctrine, mindsets, and skills apply.

Capabilities describe affordance, not permission.
Runtime policy and doctrine still govern which capabilities may be used.

### 9.1 Runtime Contract Authority (normative)

The Runtime Contract (§6.1) is authoritative over conversation history for all fields it declares: version, packages, overrides, workspace layout, and capabilities.

Conversation history is a temporal record — it may contain probe results, version references, or workspace claims from prior sessions that are no longer true. When the Runtime Contract contradicts conversation history, the contract wins.

Conversation entries SHOULD carry a `cn_version` stamp. Entries from a prior version are stale and MUST NOT be treated as current truth for any field the Runtime Contract covers.

---

## 10. Validation Checks

### 10.1 Doctrine is invalid if

- it is optional or task-scoped
- it depends on triggers
- it can be outscored by another artifact
- it is merely advice

### 10.2 Mindset is invalid if

- it is procedural rather than orienting
- it is only relevant to one task family
- it must compete for loading
- it contains constitutive law better expressed as doctrine

### 10.3 Skill is invalid if

- it lacks bounded applicability
- it lacks Define/Unfold/Rules structure or equivalent inputs, rules, and effects
- it is actually a worldview or identity statement
- it claims always-on global authority
- it cannot say what changed when the skill succeeds

### 10.4 Reflection is invalid if

- it pretends to be timeless
- it contains no concrete observation or update
- it silently changes always-on substrate without explicit promotion

### 10.5 Known misclassifications

- COHERENCE.md is doctrine per this spec. Any runtime or document treating it as a mindset is misclassified and MUST be aligned.

---

## 11. Builder Guidance

Use doctrine for: "this must always hold."
Use mindset for: "always look this way."
Use skill for: "do this when the task calls for it."
Use reflection for: "we learned this recently."
Use capability for: "the runtime can currently do this."

Examples:

- "Never fabricate evidence." → Doctrine
- "Write so nothing can be removed without loss." → Mindset
- "Review code so unintended behavior is unrepresentable." → Skill
- "This week, branch pushes returned success without landing remotely." → Reflection

---

## 12. Compatibility and Migration

This spec is normative for new substrate work.

Legacy skill files that expose only Core Principle + Rules remain readable, but new and revised skills SHOULD migrate to the canonical skill contract in §7.3 so that placement, loading, and authorship rules are explicit in one place.

Any document that explains doctrine, mindsets, or skills MUST defer to this spec for classification and file contract.

---

## Coherence Contract for This Document

**Gap:** cnos has doctrine (CAP, COHERENCE, CBP, CA-CONDUCT), architecture (CAA, CAR, AGENT-RUNTIME), and skill-writing guides (skill/SKILL.md, WRITE-A-SKILL.md), but no single normative document for classifying, placing, and structuring cognitive substrate assets. Classification rules were scattered across THESIS, CAA, CAR, and COHERENCE-SYSTEM.

**Mode:** MCI — unify existing concepts into one normative spec.

**Scope:** System spec layer.

**Expected effect:**

- α: one classifier, one placement algorithm, one file contract per class
- β: docs that reference substrate classes now defer to one spec
- γ: new assets have a clear placement path; promotion rules prevent class drift

**Failure if skipped:** Classification remains implicit and taste-based. Mindsets look like skills, skills look like mindsets, reflections silently become doctrine. The COHERENCE-as-mindset drift persists.

**CLP:**

- **TERMS:** The ontology already exists: THESIS defines the semantic distinctions, CAA defines the wake-up strata, CAR defines load behavior. The MCP is "unify classification, placement, and schema into one normative document."
- **POINTER:** Weakest axis before patch is β. The concepts are present but their relations are broken across documents. The sharpest break is the skill contract: skill/SKILL.md teaches Define/Unfold/Rules while skills/README.md frames skills as TERMS/INPUTS/EFFECTS.
- **EXIT:** MCI applied. The draft installs one classifier, one placement algorithm, canonical locations, explicit runtime treatment, a unified skill contract (Define/Unfold/Rules as canonical form), promotion/splitting rules, and validation checks. Remaining MCA: align CAR, AGENT-RUNTIME, WHITEPAPER, and skills/README.md to this spec.
