Memory and control plane · RP2350 platform

Artifact Contracts Turn Files into Controlled Operating State

Durable interfaces connect human intent, agent execution, governance, evidence, and shipping. They preserve exactly what an artifact means, who authorized it, what it proves, where it applies, and what may happen next.

Status · ExplorationVersion · 0.1Example · Sock RescuePlatform · Feather RP2350 HSTXUpdated · August 7, 2026

Declare meaning

Purpose, identity, authority, and applicability.

Bind inputs

Exact upstream artifacts and versions.

Authorize action

Define bounded downstream permission.

Attach evidence

Support precise, scoped claims.

Control validity

Track freshness, conditions, and invalidation.

Preserve history

Supersede—never silently rewrite.

01 · Operating idea

Documentation explains. Contracts govern.

An artifact contract defines not only what a file contains, but the operational meaning and consequences that other humans, agents, and automations may safely rely on.

The durable interface

Every consequential artifact declares what it represents, who may create and approve it, which inputs authorize it, what downstream work it permits, how its claims are verified, and what makes it stale.

This lets agents enter and leave without losing the project’s trusted state.

Meaning — the exact outcome, behavior, decision, or claim.

Authority — who may create, validate, approve, and act.

Lineage — immutable inputs, versions, commits, and runs.

Effect — what is authorized, blocked, or obligated.

Validity — applicability, freshness, conditions, and invalidation.

An artifact contract turns repository content into controlled operating state.

02 · Core distinctions

A schema validates shape; a contract defines consequence

Structural correctness is necessary, but it does not establish legitimacy, authority, applicability, or permission.

Schema

Is the structure valid?

Required fields, data types, allowed values, and syntax.

status is an allowed enum
Required identifiers exist
YAML parses correctly

Contract

What does it mean?

Purpose, authority, lifecycle, obligations, consumers, and consequences.

Who may approve
What approval authorizes
When approval expires

Operating system

Can it be trusted now?

Instance, validator, policy, and registry combine to answer operational questions.

Exact artifact instance
Semantic validation
Registry and lineage

03 · Universal envelope

Every governed artifact carries the same control envelope

The envelope stays consistent across specifications, work packages, evidence bundles, decisions, handoffs, and releases. Each artifact type adds its own body beneath it.

Common control surface

The universal envelope makes every artifact independently understandable to a cold agent and mechanically traceable by the Orchestrator.

Stable identity and type
Lifecycle state and immutability
Human and agent authority
Provenance and relationships
Applicability and validity
Integrity and classification

artifact:
  contract: artifact-envelope
  contract_version: 1.0
  identity:
    id: SPEC-GAME-LIFECYCLE-001
    type: specification
    version: 0.4
    title: Game Lifecycle Behavior
  project:
    id: RP2350-GAME-PLATFORM
    capability: game-lifecycle
  lifecycle:
    state: approved
    created_at: 2026-08-07T14:30:00Z
    updated_at: 2026-08-07T17:10:00Z
    immutable_after_approval: true
  authority:
    created_by: {actor: agent-run-041, role: specification-agent}
    approved_by: {actor: product-owner, role: product-owner}
    technical_approval: {actor: chief-architect, role: chief-architect}
  provenance:
    source_commit: 8f31c2a
    generated_by_run: RUN-2026-08-07-041
    derived_from: [CHANGE-GAME-LIFECYCLE-001@0.3, ADR-LIFECYCLE-002@1.0]
  relationships:
    supersedes: SPEC-GAME-LIFECYCLE-001@0.3
    depends_on: [CONTRACT-INPUT-EVENTS@1.1]
    authorizes: [WP-LIFECYCLE-CORE-003@1.2]
  applicability:
    hardware_profiles: [feather-rp2350-hstx-rev-b-non-psram]
    release_range: ">=0.5.0 <1.0.0"
  validity:
    effective_from: 2026-08-07
    expires_at: null
    invalidated_by: [lifecycle-public-api-change, pause-semantics-change]
  integrity:
    content_digest: sha256:...
    schema_validation: pass
  classification:
    authority_level: approved-specification
    confidentiality: internal

04 · Contract anatomy

Eleven questions define every artifact-type contract

Together, these dimensions specify the artifact’s full lifecycle—from prerequisite through authorized use and downstream obligation.

1Purpose

Why does the artifact exist?

2Required inputs

What must exist first?

3Producer

Which role may create it?

4Required content

Which assertions and fields?

5Validator

How is correctness checked?

6Authority

Who may approve or activate?

7Transitions

Which state changes are legal?

8Consumer

Who may safely rely on it?

9Authorization

What does it permit?

10Invalidation

What makes it unusable?

11Outputs

What obligations follow?

Work-package contract type

A contract definition governs all work-package instances. It limits execution authority as explicitly as it defines the desired result.

Approved intent required
One bounded owner
Verification planned first
Shipping authority capped
Source changes invalidate

artifact_contract:
  id: CONTRACT-WORK-PACKAGE
  version: 1.0
  artifact_type: work-package
  purpose: Authorize one actor to deliver a bounded, verifiable outcome.
  requires:
    - approved-change
    - approved-specification
    - identified-owner
    - verification-plan
  produced_by:
    allowed_roles: [orchestrator, technical-lead]
  approved_by:
    allowed_roles: [package-owner]
  authorizes:
    - discovery-within-context-boundary
    - modification-within-file-boundary
    - specified-verification
    - shipment-through-declared-level
  must_not_authorize:
    - unapproved-public-contract-change
    - release-beyond-package-authority
    - unrelated-repository-cleanup
  produces:
    - readiness-declaration
    - implementation-result
    - evidence-bundle
    - agent-handoff
  invalidated_by:
    - source-specification-change
    - authorized-base-commit-mismatch
    - package-scope-change

05 · Artifact classes

Different artifacts perform different jobs

Classes should not be blurred. A test report proves behavior; it does not authorize release. A proposal expresses intent; it is not an approved requirement.

Intent

Why the outcome matters.

Project charter
Experience brief
Change proposal
Success measures

Authority

Consequential decisions.

Charter authorization
OpenSpec approval
Architecture decision
Risk acceptance

Execution

Bounded work and its status.

Work package
Agent bootstrap
Readiness declaration
Handoff

Technical

Supported system behavior.

API contract
Hardware profile
Resource budget
Compatibility matrix

Evidence

Support for completion claims.

Test result
Build manifest
Hardware measurement
Evidence bundle

Shipping

Integration and distribution control.

Integration candidate
Release gate
Release manifest
Rollback record

Learning

What changes future behavior.

Finding
Retrospective
Adopted learning
Supersession record

06 · Dependency graph

Artifacts form an authorization and evidence graph

Every edge has one exact meaning. Relationships use immutable artifact IDs and versions—not filenames alone.

Charter + change

Approved specification

Work package

Implementation + evidence

Human acceptance

Release authorization

Published release

Observed results

Adopted learning

Future intent

derived_from developed fromdepends_on validity requiresauthorizes permits actionsatisfies supplies evidenceimplements realizes behaviorverifies evaluates a claimapproves grants authoritysupersedes replaces versioninvalidates makes unusableobserved_in binds to candidatepromotes_to creates platform status

07 · Identity and authority

Trust is explicit, versioned, and role-bound

Stable identity preserves lineage. Separate authority dimensions prevent a creator, validator, or recommender from silently becoming the decision owner.

Identity and versioning

<TYPE>-<SUBJECT>-<SEQUENCE>@<VERSION>

CHARTER-RP2350-001@1.0
SPEC-GAME-LIFECYCLE-001@0.4
WP-LIFECYCLE-CORE-003@1.2
EVID-LIFECYCLE-CORE-003@1.0
REL-SOCK-RESCUE-0.5.0@rc2

Four forms of authority

Creation — may draft the artifact.
Validation — may confirm technical correctness.
Approval — may authorize the represented decision.
Execution — may act on the approved artifact.

An agent may draft and validate an OpenSpec proposal, yet cannot approve product intent.

Version rule	Operating effect
Draft edits	May increment draft versions while remaining unapproved.
Approval	Freezes the exact approved instance.
Material change	Creates a new version; never silently edits the approved one.
Supersession	Preserves older versions for lineage and audit.
Downstream use	Records the exact upstream version consumed.
Spec revision	Triggers reaffirm, revise, pause, or invalidate for dependent work.

Authority policy

Separation of authority is encoded so orchestration cannot substitute technical confidence for human legitimacy.

Drafting is not approval
Validation is not risk acceptance
Recommendation is not authorization
Self-approval can be prohibited

authority:
  create:
    roles: [specification-agent]
  validate:
    roles: [requirements-reviewer, chief-architect]
  approve:
    required: [product-owner, chief-architect]
  consume:
    roles: [orchestrator, implementation-agent, qa-agent]
  prohibited_self_approval:
    - creator_cannot_supply_product_approval

08 · Lifecycle and claims

State and evidence must be precise enough to automate safely

Shared base states make orchestration deterministic. Claim contracts prevent vague completion language and keep evidence bound to a declared configuration.

draftvalidatinginvalidready-for-reviewawaiting-authorityapprovedapproved-with-conditionsactivesatisfiedrejectedreturned-for-refinementsupersededexpiredinvalidatedwithdrawnarchived

Controlled claims

Evidence supports a precise statement for a precise build and target—not every conceivable environment.

asserted
supported
partially-supported
contradicted
not-evaluated
obsolete

claims:
  - id: CLAIM-LIFECYCLE-PAUSE-001
    statement: Simulation state does not mutate while paused.
    claim_type: behavioral
    requirement: REQ-LIFECYCLE-PAUSE-003
    applicability:
      build: rp2350-sock-rescue-0.5.0-rc2
      hardware: feather-rp2350-hstx-rev-b-non-psram
    evidence:
      - TEST-LIFECYCLE-IMMUTABILITY-034
      - TARGET-RUN-2026-08-07-008
    status: supported
    limitations: []

09 · Provenance and validity

A valid artifact may still be inapplicable or stale

Every consequential artifact records how it was produced and the precise configurations for which it may be trusted.

Minimum provenance

Producing actor or agent run
Timestamp, repository, base and result commit
Toolchain, compiler, flags, dependencies
Input artifact versions
Measurement method and configuration
Hardware profile and content digest

Validity ≠ applicability

PSRAM evidence does not prove non-PSRAM behavior.
rc1 tests do not authorize rc2.
A 1.x architecture approval may not apply to 2.0.
An invalidated playtest can inform learning but not release.

Applicability and freshness

The evaluator can determine when a result must be repeated, without discarding valid historical evidence.

Project and capability
Software version range
Board and revision
PSRAM profile
Re-evaluation triggers

applicability:
  project: rp2350-game-platform
  capability: game-lifecycle
  software_range: ">=0.5.0 <0.6.0"
  hardware:
    board: feather-rp2350-hstx
    revisions: [rev-b]
    psram: false
freshness:
  evaluated_at: 2026-08-07T18:00:00Z
  reevaluate_on:
    - firmware-change
    - controller-driver-change
    - hardware-revision-change

10 · Invalidation

Source changes propagate through the dependency graph

Old artifacts remain historically intact, but their operational state changes. The Orchestrator identifies the precise downstream impact and required action.

Specification 0.4 invalidated

Work-package readiness re-evaluated

Evidence becomes obsolete

Release candidate invalidated

Explicit propagation event

A Pause semantics revision does not erase prior work. It records what is affected and determines the correct response for each dependent artifact.

Pause and reissue work
Retain obsolete evidence
Re-evaluate experience
Invalidate exact candidate

artifact_event:
  type: source-invalidated
  source:
    artifact: SPEC-GAME-LIFECYCLE-001@0.4
    reason: pause-semantics-revised
  affected:
    - artifact: WP-LIFECYCLE-CORE-003@1.2
      action: pause-and-reissue
    - artifact: EVID-LIFECYCLE-CORE-003@1.0
      action: retain-but-mark-obsolete
    - artifact: CP-EXPERIENCE-009@1.0
      action: reevaluate
    - artifact: REL-SOCK-RESCUE-0.5.0@rc2
      action: invalidate-candidate
  recorded_by: orchestrator

11 · Conditions and records

Conditional approval creates machine-readable obligations

Every condition names its owner, deadline, verification method, and blocking effect. “Approved with conditions” can never collapse into unconditional approval.

Conditions contract

Conditions can block all work, one package, integration, release—or create a non-blocking tracked obligation.

Exact obligation
Named owner
Due-before milestone
Verification method
Open/closed status

decision:
  outcome: approved-with-conditions
conditions:
  - id: CONDITION-GOLDEN-SOCK-CONTRAST
    obligation: Increase golden-sock silhouette contrast.
    owner: technical-artist
    due_before: integration-acceptance
    verification: {type: human-creative-review}
    status: open
  - id: CONDITION-PAUSE-OVERLAY
    obligation: Set pause-overlay opacity to 65 percent.
    owner: graphics-engineer
    due_before: next-integration-build
    verification: {type: automated-asset-check}
    status: open

Usually mutable

Current orchestration state
Assignment and package progress
Checkpoint queue
Active blockers
Artifact registry

Immutable after issuance

Approved specification version
Human checkpoint decision
Test result and build manifest
Evidence bundle
Risk and release authorization

12 · Operational contracts

Four contracts carry work from intent to release

The work package bounds discretion, evidence supports exact claims, the human decision records legitimate judgment, and the release contract fails closed.

Work package

Authorizes bounded implementation and caps shipping authority.

artifact:
  id: WP-LIFECYCLE-CORE-003
  type: work-package
  version: 1.2
  state: authorized
objective:
  outcome: Implement reusable Start, Pause, Resume.
authority_basis:
  - CHANGE-GAME-LIFECYCLE-001@0.4
  - SPEC-GAME-LIFECYCLE-001@0.4
  - CP-SPEC-004@1.0
scope:
  allowed_paths: [platform/lifecycle/**, tests/platform/lifecycle/**]
  protected_paths: [games/sock-rescue/scoring/**, platform/audio/public/**]
prohibited_decisions:
  - public lifecycle API changes
  - pause semantics changes
  - memory-budget increases
shipping:
  maximum_level: S1
  may_commit: true
  may_merge: false
  may_release: false
required_outputs:
  - readiness-declaration
  - implementation-commit
  - evidence-bundle
  - resumable-handoff

Evidence bundle

Supports only the claims demonstrated by one exact result.

artifact:
  id: EVID-LIFECYCLE-CORE-003
  type: evidence-bundle
  version: 1.0
  state: complete
subject:
  work_package: WP-LIFECYCLE-CORE-003@1.2
  result_commit: 42db7e1
  build: rp2350-sock-rescue-0.5.0-dev17
scope_verification:
  modified_files: 6
  outside_allowed_paths: 0
  public_contract_changed: false
results:
  - {check: lifecycle-unit-tests, outcome: pass, cases: 34}
  - {check: lifecycle-conformance, outcome: pass}
  - check: static-memory-budget
    outcome: pass
    measured_bytes: 2816
    budget_bytes: 4096
limitations:
  - target-board behavior not evaluated
  - human experience acceptance not included
claims:
  achieved_ship_level: S1
  recommended_next_level: S2

Human checkpoint decision

Preserves judgment without reconstructing it from meeting notes.

artifact:
  id: CP-EXPERIENCE-009
  type: checkpoint-decision
  version: 1.0
  state: active
checkpoint:
  type: experience-acceptance
  authority_role: product-owner
subject:
  build: rp2350-sock-rescue-0.5.0-rc2
  commit: 6e08a4c
  artifact_digest: sha256:abc123
  hardware: feather-rp2350-hstx-rev-b-non-psram
decision:
  outcome: returned-for-refinement
  accepted: [pause clarity, state preservation]
  rejected: [combo-loss feedback]
effects:
  blocks: [product-acceptance, release-authorization]
  permits: [documentation-preparation, endurance-testing]
invalidation:
  invalidated_by: [candidate-build-change, scoring-feedback-change]

Release candidate

Assembles the evidence chain and fails closed.

artifact:
  id: REL-SOCK-RESCUE-0.5.0-RC3
  type: release-candidate
  state: authorized-for-release
candidate:
  version: 0.5.0
  commit: 7bd219f
  artifact_digest: sha256:def456
  hardware_profile: feather-rp2350-hstx-rev-b-non-psram
requirements:
  specification: {artifact: SPEC-SOCK-RESCUE-MVP@1.0, status: satisfied}
  package_evidence:
    - EVID-LIFECYCLE-CORE-003@1.0
    - EVID-SCORING-COMBO-004@1.1
    - EVID-GOLDEN-SOCK-002@1.0
  target_validation: {artifact: TARGET-VALIDATION-RC3@1.0, status: pass}
  experience: {artifact: CP-EXPERIENCE-010@1.0, status: accepted}
exceptions: [EXC-AUDIO-003@1.0]
authorization:
  product_owner: approved
  technical_owner: approved
  release_owner: approved
rollback: {artifact: ROLLBACK-SOCK-RESCUE-0.5.0@1.0}

13 · Validation and tooling

Validation proceeds from syntax to policy

A release gate is trustworthy only when the artifact graph is structurally valid, referentially complete, authority-correct, applicable, fresh, intact, and semantically supported.

Syntax

YAML parses.

Schema

Fields and enums.

Referential

IDs exist.

Authority

Role is permitted.

State

Transition is legal.

Applicability

Build and target match.

Freshness

Sources unchanged.

Integrity

Digest matches.

Semantic

Evidence supports claim.

Policy

Approvals and conditions.

contracts/
├── base/
│   ├── artifact-envelope.schema.yaml
│   ├── identity-policy.md
│   ├── authority-policy.md
│   ├── lifecycle-policy.md
│   └── invalidation-policy.md
├── intent/
├── execution/
├── decisions/
├── evidence/
├── shipping/
└── learning/

artifacts/
├── registry.yaml
├── active/
├── awaiting-decision/
├── invalidated/
├── superseded/
└── archived/

tools/
├── artifact
├── validate-contracts
├── trace-lineage
└── evaluate-impact

Operator commands

./tools/artifact validate WP-LIFECYCLE-CORE-003@1.2./tools/artifact explain REL-SOCK-RESCUE-0.5.0-RC3./tools/artifact impact SPEC-GAME-LIFECYCLE-001@0.4./tools/artifact lineage EVID-LIFECYCLE-CORE-003@1.0

Explain should report why the artifact is valid or invalid, its authorities, what it permits and blocks, downstream dependents, and invalidating changes.

14 · Minimum viable system

Build the control foundation, then operational contracts, then automation

The RP2350 project does not need every possible artifact on day one. This sequence is enough for a cold agent to move from approved intent through controlled release.

PHASE 01

Foundation

Universal Artifact Envelope
Identity and Versioning Policy
Authority and Role Policy
Artifact Lifecycle Policy
Relationship and Invalidation Policy
Artifact Registry

PHASE 02

Operational contracts

Approved Specification
Work Package
Agent Readiness
Evidence Bundle
Human Checkpoint Decision
Resumable Handoff
Release Gate

PHASE 03

Automation

Structural validator
Reference validator
Authority validator
Invalidation-impact evaluator
Artifact-lineage viewer
Release-gate evaluator

15 · RP2350 example

Start / Pause / Resume, end to end

The chain lets a cold agent understand why the feature exists, what was approved, what may change, which decisions humans made, what evidence applies, and what action is permitted next.

IntentCHANGE-GAME-LIFECYCLE-001@0.4Proposes the outcome.

SpecificationSPEC-GAME-LIFECYCLE-001@0.4Defines required behavior.

Human decisionCP-SPEC-004@1.0Authorizes implementation planning.

ExecutionWP-LIFECYCLE-CORE-003@1.2Authorizes bounded agent work.

ReadinessREADY-RUN-041@1.0Confirms agent understanding.

Implementationcommit 42db7e1Produces the change.

EvidenceEVID-LIFECYCLE-CORE-003@1.0Supports S1 completion.

ReviewVERIFY-LIFECYCLE-003@1.0Supports independent S2 verification.

IntegrationEVID-INTEGRATION-RC3@1.0Supports S3 integration.

ExperienceCP-EXPERIENCE-010@1.0Supplies human S4 acceptance.

PlatformCP-PLATFORM-003@1.0Determines reusable support status.

ReleaseREL-SOCK-RESCUE-0.5.0-RC3Authorizes the exact candidate.

ObservationFIELD-SOCK-RESCUE-0.5.0@1.0Records behavior in use.

LearningLEARN-LIFECYCLE-CONTROL-002@1.0Updates future standards.

No proposal becomes an approved requirement.

No test pass becomes product acceptance.

No recommendation becomes a human decision.

No local build becomes a release candidate.

No evidence moves across unmatched builds.

No game code becomes an accidental platform promise.

No stale approval survives a material subject change.

No actor may rely on an artifact beyond the authority, applicability, evidence, version, lifecycle state, and shipping effect explicitly declared by its contract.