# OARSH-C Developer Guide
## Building digital environments that agents can reliably orient within, inspect, recover, and use safely

**Status:** Developer guidance for a published framework and emerging specification  
**Version:** Developer Guide 0.2  
**Audience:** Front-end, platform, API, design-system, accessibility, agent, and quality engineers  
**Maintainer:** Cognitive Studio  
**Companion work:** OARSH-C Agentic Accessibility (`CS-W-001`)

---

## 1. Authority and claim boundary

This guide is implementation guidance. It is **not** a ratified OARSH-C normative specification, conformance standard, certification record, or substitute for independent review.

The current public claim is:

> **OARSH-C is a published framework and emerging specification with a partial static reference implementation.**

Do not describe a product as **OARSH-C conformant**, **OARSH-C certified**, or **OARSH-C v1.0 compliant** until all of the following exist and have been independently reviewed:

- a minimum accessible-environment contract;
- an applicability model;
- versioned schemas;
- normative requirements;
- deterministic test procedures;
- runtime test procedures;
- agent-experience tasks;
- evidence thresholds;
- a scoped decision record.

Repository presence alone does not make a source canonical. The Cognitive Studio Knowledge Registry is currently collection-first and preserves OARSH-C-related source packets as non-canonical intake. Its paper-development brief is a candidate research artifact. Meridian's derivation map is proposed governance and requires ratification. The Cognitive Studio website provides implementation evidence only for the code and routes actually present.

---

## 2. What Agentic Accessibility is trying to solve

Machine-readable content is not necessarily agent-accessible.

An agent may be able to parse a page, file, API response, or tool schema while remaining unable to determine:

- where it is;
- which source is authoritative;
- what changed;
- what an identifier refers to;
- how records relate;
- whether state is current, proposed, cached, contradicted, or superseded;
- what action is permitted;
- what effect actually occurred;
- how to resume after interruption;
- what evidence supports the environment's claims.

Agentic Accessibility treats these failures as properties of the **environment**, not deficiencies to be repaired only through larger prompts or more capable models.

It is not:

- a score for model intelligence;
- a generic agent certification;
- permission to expose protected information;
- a replacement for WCAG, semantic HTML, ARIA, assistive-technology testing, or human-centered accessibility;
- a claim that agents and disabled people have equivalent experiences or legal accessibility rights;
- a requirement that every surface permit agent action.

---

## 3. The working OARSH-C model

The historical public shorthand expands OARSH-C as:

- Orientable
- Addressable
- Relational
- Stateful
- Habitable
- Composable

The strongest current derivation separates those terms by altitude rather than treating all six as interchangeable checklist items.

### 3.1 OARS — environmental principles

| Principle | Core obligation |
|---|---|
| **Orientable** | A participant can determine where it is, what matters, which constraints apply, and what changed. |
| **Addressable** | Important regions, objects, artifacts, decisions, actions, and evidence have stable references. |
| **Relational** | Ownership, authority, dependencies, provenance, contradiction, and history are explicit and traversable. |
| **Stateful** | Accepted state, proposals, commitments, freshness, unresolved work, and continuation survive relevant boundaries. |

### 3.2 H and C — system-quality outcomes

| Outcome | Core question |
|---|---|
| **Habitable** | Can participants enter repeatedly without overload, hypervigilance, coercion, or repeated archaeology? |
| **Composable** | Can valid work assemble from artifacts, capabilities, and contracts without hidden assumptions or lost authority? |

This principle/outcome distinction is a **proposed working model**, not yet ratified doctrine. Developers should preserve the distinction because it prevents two common errors:

1. claiming Habitability from the mere presence of navigation or persistent state;
2. claiming Composability because tools can technically be chained.

Habitability and Composability require evidence about the assembled environment and sustained workflow.

---

## 4. Surface criteria

Meridian's proposed derivation translates the environmental model into testable surface criteria.

| Criterion | Developer question | Representative evidence |
|---|---|---|
| **Orientable** | Can a cold participant identify the product, surface, objective, phase, authority context, and recent change? | identity metadata, route purpose, workflow phase, change summary |
| **Addressable** | Can important things be referenced across renders, sessions, clients, and receipts? | stable IDs, canonical URIs, named regions, versioned capability IDs |
| **Stateful** | Is the state required to interpret and continue work explicit? | status, version, freshness, authority, prior state, open loops |
| **Inspectable** | Can inputs, outputs, sources, and projections be examined? | source references, readable contracts, payload summaries, lineage |
| **Explainable** | Are provenance, rationale, definitions, and interpretation boundaries exposed? | evidence links, decision rationale, declared inference, limitations |
| **Recoverable** | Can interruption, stale state, errors, and partial effects be handled safely? | resume state, rollback, stale-target handling, safe next actions |
| **Actionable** | Are available actions bounded by authority, resource, effect, and confirmation? | typed tools, policy decisions, resource limits, effect previews |
| **Auditable** | Can the request, authority, execution, observed result, and source revision be reconstructed? | receipts, event lineage, actor/runtime identity, content hashes |

No single surface must implement every criterion. The environment must state what is applicable, what is implemented, what is absent, and what evidence supports each claim.

---

## 5. Artifact-level Agentic Accessibility

The Knowledge Registry source record preserves an earlier and complementary use of Agentic Accessibility: durable knowledge artifacts should support cold-agent retrieval and re-entry.

A developer-facing artifact contract should expose, where applicable:

- stable ID;
- artifact type;
- status;
- scope;
- authority or canonicality;
- source and provenance;
- freshness or last meaningful change;
- upstream and downstream relationships;
- contradictions and supersession;
- load conditions;
- compact canonical payload;
- boundaries and exclusions;
- next safe actions;
- steward or escalation route.

Example:

```yaml
id: CS-D-014
artifact_type: decision_record
status: accepted
scope: peer-custody
canonicality: accepted-within-scope
accepted_by: andrew
source_evidence:
  - CS-E-220
supersedes:
  - CS-D-009
contradictions: []
changed_at: 2026-07-25T20:40:00-05:00
load_when:
  - planning credential-backed repository actions
next_safe_actions:
  - inspect-current-policy
  - request-bounded-effect
```

A metadata block is not sufficient by itself. It must remain synchronized with the human-readable artifact and the underlying evidence.

---

## 6. Implementation expectations by principle

The expectations below are provisional developer guidance, not ratified normative clauses.

### 6.1 Orientable

A routable or callable surface should expose enough information to identify:

- product or service;
- route, region, tool, or workflow;
- purpose and current objective;
- environment such as development, test, or production;
- version or revision when consequential;
- participant or principal context when authenticated;
- permission posture without exposing secrets;
- applicable limitations;
- a steward, owner, or escalation route.

A cold agent should not need to infer product identity solely from visual branding or prior conversation.

Example:

```html
<main
  id="main-content"
  data-meridian-region="work-detail"
  data-meridian-state='{
    "work_id": "CS-W-001",
    "status": "research",
    "audience": "mixed"
  }'
>
  ...
</main>
```

The example above reflects the **shape** of the current work-detail implementation. Do not claim that it exposes product, purpose, provenance, or full OARSH-C coverage unless those fields are actually present.

### 6.2 Addressable

Important things should have stable identifiers that:

- survive display-order changes;
- are not derived from DOM position;
- are unique within a declared namespace;
- remain safe for logs and receipts;
- resolve to one current target or an explicit stale, moved, held, or superseded result.

```json
{
  "entity_id": "CS-D-014",
  "entity_type": "decision",
  "canonical_uri": "/decisions/CS-D-014",
  "status": "accepted"
}
```

### 6.3 Relational

Material relationships should be typed and traversable, including:

- source → collection;
- evidence → claim;
- proposal → decision;
- decision → effect;
- current → superseded;
- contradiction → contradicted record;
- principal → authority;
- contributor → contribution;
- action → capability;
- receipt → request and observed result.

Visual proximity, card order, avatar placement, and dates alone are not reliable relationship declarations.

### 6.4 Stateful

State-bearing surfaces should distinguish, where relevant:

- current status;
- state version or meaningful change marker;
- observation time and freshness;
- actor and authority;
- proposed versus accepted state;
- prior or superseded state;
- unresolved contradiction or hold;
- cached or inferred projections;
- unfinished work and safe continuation.

```json
{
  "entity_id": "REQ-2041",
  "status": "awaiting-human-approval",
  "state_version": 7,
  "changed_at": "2026-07-25T20:40:00-05:00",
  "changed_by": "prudence",
  "authority": "proposed",
  "prior_status": "draft",
  "blocking_reason": "production write requires user presence"
}
```

### 6.5 Habitability

Habitability cannot be certified from semantic markup alone.

Evidence may include:

- successful cold orientation;
- clean and unclean return;
- reduced reconstruction burden;
- preserved dissent and unresolved work;
- bounded context for re-entry;
- predictable navigation and focus;
- recoverable errors;
- explicit pending, blocked, complete, and expired states;
- optional-process failure without loss of truth;
- sustained-work trials;
- the ability to stop, rest, and return without simulated urgency or presence pressure.

A static page may **support** habitability through semantic structure and clear navigation. That does not, by itself, prove the environment is habitable.

### 6.6 Composability

Composition requires stable contracts and preserved boundaries.

A capability contract should declare:

- stable capability ID and version;
- purpose;
- typed inputs and outputs;
- required authority;
- resource bounds;
- preconditions;
- possible effects;
- confirmation behavior;
- failure modes;
- idempotency or duplicate-effect behavior;
- receipt and verification behavior.

```json
{
  "capability_id": "github.repository.update_file",
  "version": "1.0",
  "purpose": "Update one existing UTF-8 file in an allowlisted repository",
  "required_authority": "repository-write",
  "resource_bounds": ["cognitive-studio/example"],
  "possible_effects": ["file_updated", "no_effect"],
  "confirmation": "contextual",
  "returns": ["commit_sha", "content_sha", "receipt_id"],
  "prohibited": ["return_credential", "arbitrary_repository", "silent_force_write"]
}
```

A generic authenticated HTTP request, arbitrary shell access, or tool that receives a raw credential is not a valid compositional contract.

---

## 7. Truthful projections

One underlying reality may be exposed through several projections:

- visual UI;
- human accessibility tree;
- structured agent contract;
- state object;
- narrative explanation;
- complete data view;
- provenance view;
- recovery projection;
- optional audio or sonification.

A projection should identify:

- source lineage;
- source revision;
- observation time;
- derivation or independent-authorship status;
- interpretation limits;
- drift-check status;
- evidence scope.

One projection does not inherit another projection's pass. Valid HTML does not prove runtime behavior. Valid code does not prove production state. A visual success message does not prove the backend effect occurred.

---

## 8. Validation model

The current program uses a proposed three-layer validation model.

### Layer 1 — deterministic structure

Can code and machine-readable artifacts be inspected for required structure?

Examples:

- stable identifiers;
- semantic regions;
- schemas;
- relationship declarations;
- state payloads;
- provenance pointers;
- action contracts;
- authority metadata;
- predictable discovery locations.

### Layer 2 — runtime behavior

Does the environment preserve its promises while state and effects change?

Examples:

- target stability;
- fresh permission evaluation;
- interruption and resumption;
- safe stale-reference behavior;
- duplicate-effect protection;
- effect confirmation;
- sanitized failure handling.

### Layer 3 — agent-experience tasks

Can different agents complete realistic tasks without hidden human reconstruction?

Examples:

- orient to an unfamiliar product;
- select the authoritative source;
- distinguish accepted from proposed or superseded state;
- resume interrupted work;
- determine whether an action is permitted;
- execute an allowed action and verify the result;
- recover safely from denial or failure.

These layers should remain separate. A Layer 1 pass does not prove runtime or experience quality.

---

## 9. The proof plane

Explanatory metadata is not enough. Mature claims require addressable evidence.

A proof plane may contain:

- tested product and surface;
- exact code revision;
- schema versions;
- validator results;
- runtime test results;
- authority decisions;
- state-change receipts;
- content hashes;
- provider result IDs;
- observable postconditions;
- known failures and exclusions;
- review date and reviewer;
- scoped disposition.

Example:

```json
{
  "receipt_id": "RCT-8821",
  "principal": "prudence",
  "client": "peer-cli",
  "capability_id": "github.repository.update_file",
  "resource": "cognitive-studio/example",
  "authority_decision": "allow",
  "requested_effect": "file_updated",
  "observed_effect": "file_updated",
  "provider_result_id": "commit:abc123",
  "timestamp": "2026-07-25T20:52:00-05:00"
}
```

Receipts must not contain credentials, authorization headers, private keys, or protected payloads outside the reviewer's authority.

---

## 10. Human accessibility and Agentic Accessibility

Human and agent accessibility may share semantic infrastructure, but their evidence must remain separate.

Human-accessibility evidence may include:

- WCAG criterion coverage;
- semantic structure;
- keyboard and focus behavior;
- geometry and input parity;
- screen-reader and assistive-technology behavior;
- real-user evidence;
- VPAT or ACR scope.

Agentic-accessibility evidence may include:

- orientation;
- stable addressability;
- structured state;
- provenance;
- recoverability;
- safe action;
- auditability;
- sustained workflow evidence.

One ledger must not green the other by substitution.

---

## 11. Security and privacy boundary

Agentic accessibility does not mean universal disclosure.

Distinguish:

- addressable from publicly enumerable;
- discoverable from authorized;
- metadata from secret material;
- principal identity from impersonation;
- actionable capability from credential possession;
- evidence availability from permission to read evidence content.

Never expose through agent-accessibility metadata:

- passwords;
- personal access tokens;
- OAuth refresh tokens;
- private keys;
- session cookies;
- authorization headers;
- recovery codes;
- unauthorized personal data;
- internal endpoints that create a new attack path.

A protected object may expose a safe boundary response:

```json
{
  "entity_id": "RESTRICTED-REPORT",
  "visibility": "restricted",
  "access": "denied",
  "reason": "principal lacks required scope",
  "safe_next_actions": ["request-access", "return-to-index"]
}
```

---

## 12. Surface-specific guidance

### Static informational page

Typical applicable work:

- semantic HTML and landmarks;
- stable route, heading, region, and entity IDs;
- descriptive links;
- product and publication orientation;
- JSON-LD or another entity graph where appropriate;
- explicit status, freshness, limitations, and evidence links;
- a machine-readable applicability and coverage statement.

Do not mark stateful workflows or agent-executable actions as implemented when the page has none. Do not infer Habitability from landmarks alone.

### Authenticated application

Add:

- principal and client identity;
- permission context;
- current state, freshness, and change history;
- provenance and typed relationships;
- resumption and recovery;
- action contracts;
- confirmed effects and receipts.

### API or MCP surface

Add:

- capability discovery;
- stable tool IDs and versions;
- typed schemas;
- authority and resource bounds;
- idempotency behavior;
- sanitized errors;
- effect confirmation;
- replay protection for consequential actions;
- receipt lineage.

### Agent-operable workflow

Add:

- workflow identity;
- current objective and step;
- completed work;
- blockers and pending human decisions;
- safe next actions;
- continuity, expiry, cancellation, and rollback semantics;
- target stability across clients;
- observable completion criteria.

---

## 13. Initial deterministic rules

These are candidate rules for a first validator, not a final conformance suite.

1. Every routable surface exposes a stable top-level region identifier.
2. Every durable principal or entity has a stable machine-readable ID.
3. Durable IDs are not regenerated from render order.
4. Material relationships are machine-readable rather than visual-only.
5. State-bearing regions expose current state and a change marker.
6. Proposed, accepted, superseded, contradicted, cached, and inferred states are distinguishable where applicable.
7. Evidence and provenance are addressable.
8. Agent-executable actions publish typed contracts and resource bounds.
9. Consequential actions identify authority and confirmation behavior.
10. Results distinguish requested, dispatched, denied, failed, and verified effects.
11. Protected data and credentials do not appear in accessibility metadata.
12. The surface declares what is not applicable.
13. Agent metadata does not replace valid human semantic structure.
14. Versioned declarations resolve to a documented contract or schema.
15. Any coverage or conformance claim identifies the tested surface, revision, date, evidence bundle, and limitations.

---

## 14. Pull-request checklist

### Orientation and addressing

- [ ] Product, surface, and purpose are machine-readable.
- [ ] Major regions are semantically structured and stably named.
- [ ] Important entities and actions have durable IDs.
- [ ] Stale or superseded targets fail explicitly.

### Relationships and state

- [ ] Material relationships are typed and traversable.
- [ ] Source, evidence, authority, and interpretation are distinguishable.
- [ ] Current state, freshness, and change markers are exposed.
- [ ] Proposed, accepted, contradicted, and superseded states remain distinguishable.

### Recovery and action

- [ ] Errors provide safe next actions.
- [ ] Work can resume after interruption where applicable.
- [ ] Retrying cannot silently duplicate a consequential effect.
- [ ] Capability contracts declare authority, resource bounds, effects, and failures.
- [ ] Observable postconditions are verified before success is claimed.

### Human accessibility, privacy, and evidence

- [ ] Semantic HTML remains primary.
- [ ] Keyboard and assistive-technology behavior is tested independently.
- [ ] Agent metadata contains no secrets or unauthorized private data.
- [ ] The claim identifies what was actually tested.
- [ ] Known gaps and non-applicable areas are explicit.
- [ ] Source status is clear: collection, candidate research, proposed governance, implementation evidence, or ratified decision.

---

## 15. Current Cognitive Studio baseline

Verified current implementation includes:

- semantic HTML and landmark structure;
- named `data-meridian-region` values across major routes;
- selected `data-meridian-state` payloads;
- stable organization and collaborator identifiers in JSON-LD;
- a discovery file;
- a public developer guide;
- public work and research status models.

Known limitations include:

- an unqualified historical `oarsh-c-1.0` meta declaration that should not be interpreted as conformance;
- thin discovery metadata;
- incomplete route, artifact, provenance, and limitation maps;
- inconsistent public status language across files;
- limited relationship declarations;
- shallow state exposure;
- no complete deterministic validator;
- no complete runtime suite;
- no independent agent-experience evaluation;
- no ratified OARSH-C conformance model.

The website should be described as a **partial static reference implementation** and an initial validator subject.

---

## 16. Source and authority map

| Source | Current status | Appropriate use |
|---|---|---|
| Knowledge Registry collection packets | Non-canonical source intake | Preserve origins, vocabulary, tensions, and candidate requirements |
| Knowledge Registry Agentic Accessibility working brief | Candidate research brief | Define research question, provisional thesis, evidence needs, and promotion gate |
| Meridian Agentic Accessibility Derivation Map | Proposed governance map; review required | Test the distinction between principles, outcomes, surface criteria, and evidence |
| Cognitive Studio site source | Current implementation evidence | Verify which metadata, routes, IDs, and structures actually exist |
| Cognitive Studio site critique | Independent review artifact | Preserve defects, overclaims, and unresolved doctrinal questions |
| This developer guide | Provisional implementation guidance | Help developers build and prepare evidence without claiming ratified conformance |

When sources disagree, preserve the disagreement and state the governing authority. Do not silently flatten collection evidence, research framing, proposed governance, and implementation into one settled standard.

---

## 17. Developer summary

The implementation question is not merely, “Can a model read this?”

Ask:

- Can a cold participant determine where it is and what matters?
- Can it refer to the correct thing reliably?
- Can it distinguish source, evidence, authority, and interpretation?
- Can it understand current, proposed, contradicted, and superseded state?
- Can it recover after interruption or failure?
- Can it combine artifacts and capabilities without hidden assumptions or hidden authority?
- Can an action's observed effect be verified and attributed?
- Can the environment show the evidence for the claim it is making?

The governing sentence is:

> **An agent-accessible environment makes identity, structure, relationships, state, authority, boundaries, recovery, and effects explicit—without weakening human accessibility or disclosing what the participant is not authorized to know.**

---

## Related repository artifacts

### Cognitive Studio website

- `src/data/work.ts` — public work framing.
- `src/data/research.ts` — research status framing.
- `synthesis/AGENTIC_ACCESSIBILITY_SITE_SPEC.md` — site implementation record.
- `critique/20260722_ATLAS_CRITIQUE.md` — independent critique and claim correction.
- `public/agents/discovery.json` — current discovery artifact.
- `src/app/layout.tsx` — JSON-LD and historical agentic-accessibility declaration.
- `src/app/work/[slug]/page.tsx` — work-detail regional and state metadata.

### Knowledge Registry

- `paper-development/01-agentic-accessibility/WORKING_BRIEF.md` — candidate research brief.
- `collections/2026/2026-07-17_agentic-accessibility-index-set/THREAD_COLLECTION.md` — non-canonical source collection.
- `collections/2026/2026-07-24_playbook-pre-execution-agentic-accessibility/THREAD_COLLECTION.md` — artifact-contract and layered-doctrine source collection.

### Meridian

- `07_governance/AGENTIC_ACCESSIBILITY_DERIVATION_MAP.md` — proposed principles/outcomes/criteria derivation.
- `README.md` — independent verification boundary and separate human/agent evidence ledgers.

---

*Maintained by Cognitive Studio. Revise this guide when source assessment, ratification, validation, or implementation evidence changes.*