Skip to content
Agent OS
AOS-META-004 Normative foundation

Repository Layout

Repository Layout: scope, decisions, requirements, evidence, risks, and traceability for the Agent OS programme.

Edit on GitHub →

Repository Layout

This document defines the machine-readable conventions that keep specifications, tasks, sources, claims, experiments, and Wiki output consistent.

Table of Contents

Purpose and Scope

Area: Documentation System.

This document defines the machine-readable conventions that keep specifications, tasks, sources, claims, experiments, and Wiki output consistent.

This document owns the semantics implied by Repository Layout. It does not assert that every described subsystem already exists. It defines the target model, constraints, evidence needed to trust an implementation, and the boundary with adjacent documents.

Normative Position

  1. Use stable document, task, source, claim, experiment, decision, and evidence IDs.
  2. Use explicit anchors and machine xrefs that render to repository and GitHub Wiki links.
  3. Keep Markdown narrative and CSV registries generated from one canonical relationship model where possible.

Operating Model

The operating model is contract-first and evidence-driven. A component declares its authority, resources, lifecycle, error model, cancellation and timeout behavior, observability, version, and compatibility promise. Backends are replaceable only when the same conformance suite passes and no forbidden platform type leaks into portable layers.

Implementation proceeds through a reference model or mock, deterministic QEMU evidence where relevant, documentation-first physical hardware, and quality-hardware evidence. Pixel 9 adapters remain quarantined according to ADR-0004.

Requirements

  • R01. Use stable document, task, source, claim, experiment, decision, and evidence IDs.
  • R02. Use explicit anchors and machine xrefs that render to repository and GitHub Wiki links.
  • R03. Keep Markdown narrative and CSV registries generated from one canonical relationship model where possible.
  • R04. Specify normal, partial, denied, timeout, cancellation, restart, upgrade, and permanent-failure behavior.
  • R05. Expose structured diagnostics without leaking secrets or vendor-specific implementation details.
  • R06. Link material unknowns to a claim and, when testable, an experiment with an owner and gate.
  • R07. Update affected documentation and task data when evidence changes the model.

Failure and Degradation

Degradation must be explicit rather than accidental. The system reports capability absence, reduced quality, unavailable provider, stale data, or unsafe condition through typed states. It must not silently fall back to broader authority, unrestricted legacy execution, unverified firmware, lossy data migration, or irreversible agent action.

Recovery defines what state is retained, reconstructed, re-enrolled, compensated, or intentionally discarded. Unsupported hardware or providers are rejected at binding time where possible.

Evidence and Acceptance

  • Cross-reference crawler.
  • Frontmatter schema validation.
  • Manifest/hash generation and duplicate-view checks.
  • Evidence records target identity, hardware revision, firmware, source commit, toolchain, configuration, seed, timestamps, artifacts, expected result, actual result, and reviewer.
  • Acceptance requires the referenced tasks to meet their own criteria; prose completion is not implementation completion.

Implementation Obligations

Task Obligation Priority Gate/Milestone Verification
AOS-DOCS-001 Create repository and document topology P0 M0 fresh-clone structure and ownership review
AOS-DOCS-011 Generate and review Wiki publication preview P2 M0 crawl all generated pages and compare xref targets to source
AOS-COMM-010 Build documentation site and Wiki publication pipeline P1 M2 build from clean source, crawl links, test mobile/accessibility/search/versioned anchors

Risks and Open Questions

  • Duplicated Wiki copies can drift.
  • Renamed headings can break deep links.
  • Machine-generated volume can obscure review status.
  • Open-question rule: an unanswered high-impact question becomes a claim/experiment record and cannot be hidden in meeting notes.
  • Stop rule: work stops or changes track when legal rights, recovery, debug access, safety, or the required evidence path is unavailable.

Related Documents

Planning Reference Anchors

Generated Artifacts

AOS-DOCS-011 — Generate and review Wiki publication preview; AOS-COMM-010 — Build documentation site and Wiki publication pipeline

Target Layout

AOS-DOCS-001 — Create repository and document topology