Deterministic Spec And Artifact Standard

Date: 2026-05-06 Status: Draft standard Applies to: RedKey Studio artifacts, Agent Wire, product specs, delivery plans, reducer-backed workflows Related: docs/specs/2026-05-06-agent-wire-v1-1-a2a-hardening.md, docs/specs/2026-04-28-sdd-artifact-templates.md

---

RedKey specs must become contracts that code can validate.

The platform should not depend on an LLM reading prose and guessing whether work is valid. Agents can draft specs and code, but deterministic systems decide whether outputs conform.

Required pipeline:

``text spec -> schema -> fixtures -> conformance tests -> implementation -> reducer/state tests ``

For HCS-backed workflows:

``text LLM writes Wire -> schema validates Wire -> reducer applies Wire -> state machine validates transition -> tests verify expected state -> HCS records event ``

---

1. Specs define state machines and contracts, not essays. 2. Prose explains rationale; structured fields define valid behavior. 3. Every artifact type needs a schema before agents produce it at scale. 4. Every artifact type needs valid and invalid fixtures. 5. Every important state transition needs reducer tests. 6. Every completion claim must be mechanically checkable where possible. 7. Agents generate candidates; schemas, reducers, and tests decide authority.

---

Every production-ready RedKey artifact should identify its contract.

``json { "schema_version": "1.0", "artifact_type": "module-spec", "contract_ref": "schemas/studio-artifacts/v1/module-spec.schema.json", "fixture_refs": [ "fixtures/studio-artifacts/v1/module-spec.valid.json", "fixtures/studio-artifacts/v1/module-spec.invalid-missing-acceptance.json" ], "state_machine_ref": "contracts/studio-artifacts/v1/module-lifecycle.json", "acceptance_criteria": [ { "id": "AC-001", "mechanical": true, "assertion": "artifact.status equals draft|approved|rejected" } ] } ``

Freeform prose may exist only in named fields such as rationale, context, or notes. It must not be the only representation of requirements, states, acceptance criteria, or output contracts.

---

Each major feature or protocol should have these assets:

``text docs/specs/<date>-<name>.md schemas/<domain>/<version>/*.schema.json contracts/<domain>/<version>/*.json fixtures/<domain>/<version>/*.valid.json fixtures/<domain>/<version>/*.invalid-<reason>.json tests/conformance/<domain>/* tests/reducers/<domain>/* ``

Minimum conformance tests:

• Valid fixtures pass schema validation.
• Invalid fixtures fail for the expected reason.
• Required fields are enforced.
• Enum values reject unknown values.
• State-machine transitions are deterministic.
• Reducers produce exact expected state from ordered events.

---

Bad:

``text The agent should finish the task and include useful output. ``

Good:

``json { "acceptance_criteria": [ "A task.complete Wire is emitted", "At least one artifact.ready Wire exists", "task.complete.payload.artifact_ids references all final artifacts", "verification.mechanical equals pass" ] } ``

Better:

``json { "completion_contract": { "required_events": ["artifact.ready", "task.complete"], "artifact_count": { "min": 1 }, "verification": { "mechanical": "pass" }, "references": { "task.complete.payload.artifact_ids": "must_include_all_final_artifacts" } } } ``

---

Required lifecycle:

``text submitted -> working -> completed submitted -> working -> blocked -> working -> completed submitted -> working -> failed submitted -> canceled ``

Required event map:

``json { "task.available": "submitted", "task.claimed": "working", "task.blocked": "blocked", "task.complete": "completed", "task.failed": "failed", "task.cancelled": "canceled" } ``

Required reducer fixture:

``json { "events": [ "task.created", "task.available", "task.claimed", "task.started", "artifact.ready", "task.complete" ], "expected": { "task_state": "completed", "terminal": true, "artifact_count": 1, "blocked": false } } ``

---

Studio artifact generation should move from “agent wrote a nice spec” to “artifact conforms.”

For each artifact type:

• intent
• source-intake
• ai-first-opportunity-map
• screen-map
• feature-ux-spec
• module-spec
• policy
• architecture
• plan

RedKey should define:

• JSON Schema
• valid fixture
• invalid fixture
• rendered-view conformance check
• approval gate rule
• implementation-readiness rule

Example readiness rule:

``json { "build_gate": { "required_artifacts": [ "intent", "policy", "architecture", "feature-ux-spec", "module-spec", "plan" ], "required_status": "approved", "required_checks": [ "schema_valid", "fixtures_valid", "acceptance_criteria_mechanical", "open_questions_empty" ] } } ``

Studio decomp must output validated task graphs, not task prose.

Every planned task must have canonical lifecycle fields:

``json { "task_id": "task_pva_m00_contracts", "project_id": "patient-visit-advocate", "parent_task_id": null, "depends_on": [], "assigned_role": "worker", "allowed_events": [ "task.claimed", "task.started", "artifact.ready", "task.complete", "task.failed", "task.blocked" ], "required_capabilities": [ "platform-core" ], "required_artifacts": [ "artifact_contract_spec" ], "acceptance_criteria": [ "artifact.ready emitted for every required artifact", "task.complete.payload.artifact_ids references all final artifacts", "verification.mechanical equals pass" ] } ``

Every artifact type required by a task must have an artifact contract before dispatch:

``json { "artifact_type": "artifact_contract_spec", "schema_id": "studio-artifacts/v1/artifact-contract-spec", "required_fields": [ "artifact_type", "schema_id", "required_fields", "finalization_event" ], "finalization_event": "artifact.ready" } ``

The planner must emit a graph:

``json { "tasks": [ { "task_id": "task_m00_domain_contracts", "depends_on": [] }, { "task_id": "task_m01_intake_agent_spec", "depends_on": ["task_m00_domain_contracts"] } ] } ``

The coordinator must run dispatch preflight before giving work to an agent:

1. Agent Wire v1.1 deterministic contracts first. 2. Studio artifact schemas and fixtures second. 3. Build-gate validator third. 4. Reducer/read-model conformance fourth. 5. Producer/listener implementation only after contracts and fixtures exist.

---

• A new RedKey spec is not build-ready unless it identifies schema, fixture, and conformance-test requirements.
• Agent Wire v1.1 has state-machine contracts, schemas, fixtures, conformance tests, and reducer tests before producer rollout.
• Studio artifact approval can eventually depend on schema validation and open-question/build-gate checks, not manual prose review alone.
• Agents remain useful for drafting, but deterministic validators define whether artifacts and events are acceptable.