ARDS v5.2 — August 2026

What's new in ARDS v5.2

SurfDoc is now the native format of the standard. CONTEXT.surf is the canonical root context, every .context/ document is a typed SurfDoc, and Markdown remains a fully conformant alias for any project that declares it.

Read the Full SpecQuick Start
2,842Spec lines
45Sections
10New since v4
7Doc types
6+Platforms
3Conformance tiers

SurfDoc-native context

v3.1 added .surf as an option. v5.2 makes it the format of the standard and demotes Markdown to a declared alias. Nothing is removed, and no existing project is invalidated.

Canonical root

CONTEXT.surf is the canonical root context filename. A project may keep CONTEXT.md by declaring the .md format — it stays conformant at every tier.

Native .context/ tree

Knowledge docs, guides, agent configs, skills, plans and checkpoints are typed SurfDoc files with validated frontmatter.

Alias resolution

Tooling resolves .surf first and falls back to .md. A tool that reads only one of the two extensions is non-conformant.

Exactly one root

Two root context files are two edit surfaces with no merge rule. Carrying both is a lint failure, not a style preference.

Version-aware defaults

An omitted format field resolves by manifest version — .surf at 5.2 and above, .md below it. Upgrade nothing and nothing breaks.

New lint rule

A manifest declaring the .surf format while carrying a Markdown root now warns: the declared format and the file on disk disagree.

Why the format is the standard's business

ARDS has always specified structure and left rendering to the reader. SurfDoc is not a rendering choice — it is a typed format with validated frontmatter, which is what makes relevance hooks, version stamps and a reliable block-level parse enforceable rather than conventional. Declaring the native format is how the standard stops specifying a contract it cannot check.

CapabilitySurfDoc rootMarkdown root
Root context✓✓
Core injection with hash stamp✓✓
Generated harness files✓✓
Validated frontmatter✓—
Relevance hooks scored by the rubric✓partial
Block-level parse a generator can rely on✓—

7 document types

Each type has a distinct purpose, mutability pattern, and read frequency. Agents load them at different times to manage context window usage.

TypeLocationMutabilityRead Frequency
Root ContextCONTEXT.surfUpdated weeklyEvery turn
Agent Config.context/agents/*.surfStableOn dispatch
Skill Config.context/skills/*/SKILL.surfStableOn invocation
Knowledge Doc.context/docs/*.surfUpdated on changeOn demand
Guide.context/guides/*.surfLiving (grows)On demand
Plan Docplans/*/.surfImmutableOn demand
Research Docresearch/*/VersionedOn demand

The v5 line

v5.2 is the third release in the guaranteed-context line. The guarantees below carry forward unchanged.

Core Injection Contract

A root file that merely points at the context is non-conformant. The rules live in the file the harness actually loads, stamped so drift is detectable.

Harness Binding Profiles

Generate enforcement configuration — hooks, always-apply rules, launcher prompt composition — not merely documents.

Write-Path Contract

No durable fact may be recoverable only from agent-local memory. Memory is a pointer; the tree is the source.

Relevance Hooks

answers: frontmatter moves connections from inference to lookup, and propagates into generated index views.

Conformance Linting

Three tiers — guaranteed, injected, discovered — with CI exit codes. A project's tier is the minimum across its platform matrix.

Workspace Push Channel

The workspace Core rides the MCP server instructions field, reaching connected agents regardless of vendor, machine, or file layout.

Fully backward-compatible

A valid v5.1 project is a valid v5.2 project. A Markdown-rooted project stays conformant for as long as it declares the .md format.

  1. 1

    Bump the version30 sec

    Change version in surfcontext.json from "5.1" to "5.2"

  2. 2

    Choose a format30 sec

    Set "format": ".surf" to adopt the native format, or ".md" to pin the alias explicitly

  3. 3

    Rename the root2 min

    Rename CONTEXT.md to CONTEXT.surf with SurfDoc frontmatter and the ## Core section intact

  4. 4

    Rename the .context/ tree10 min

    Move docs, guides, agents, skills and plans to the .surf extension

  5. 5

    Re-run sync1 min

    Generated harness root files pick up the new source path and re-stamp the Core

  6. 6

    Lint30 sec

    Confirm no both-roots failure and no format-mismatch warning

Ready to upgrade to v5.2?

Backward-compatible by design. Declare a format, rename the root, re-run sync.

Get Started Full Specification