{
  "id": "2026-05-06-deterministic-spec-artifact-standard-3944bdce8e",
  "scope": "redkey",
  "source_of_truth": "repo",
  "source_path": "docs/specs/2026-05-06-deterministic-spec-artifact-standard.md",
  "source_kind": "markdown",
  "visibility": "internal",
  "renderer_id": "design_doc.dreamborn-forge.generated.v1",
  "design_system": "dreamborn-design-system:forge",
  "generated_at": "2026-05-09T13:00:55.720Z",
  "artifact_type": "design_doc",
  "schema_version": "design_doc.generated.v1",
  "title": "Deterministic Spec And Artifact Standard",
  "summary": "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 Purpose RedKey specs must become contracts that code can vali...",
  "format_source": "markdown",
  "sections": [
    {
      "title": "Deterministic Spec And Artifact Standard",
      "level": 1,
      "body": "**Date:** 2026-05-06\n**Status:** Draft standard\n**Applies to:** RedKey Studio artifacts, Agent Wire, product specs, delivery plans, reducer-backed workflows\n**Related:** `docs/specs/2026-05-06-agent-wire-v1-1-a2a-hardening.md`, `docs/specs/2026-04-28-sdd-artifact-templates.md`\n\n---"
    },
    {
      "title": "Purpose",
      "level": 2,
      "body": "RedKey specs must become contracts that code can validate.\n\nThe 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.\n\nRequired pipeline:\n\n```text\nspec\n  -> schema\n  -> fixtures\n  -> conformance tests\n  -> implementation\n  -> reducer/state tests\n```\n\nFor HCS-backed workflows:\n\n```text\nLLM writes Wire\n  -> schema validates Wire\n  -> reducer applies Wire\n  -> state machine validates transition\n  -> tests verify expected state\n  -> HCS records event\n```\n\n---"
    },
    {
      "title": "Core Rules",
      "level": 2,
      "body": "1. Specs define state machines and contracts, not essays.\n2. Prose explains rationale; structured fields define valid behavior.\n3. Every artifact type needs a schema before agents produce it at scale.\n4. Every artifact type needs valid and invalid fixtures.\n5. Every important state transition needs reducer tests.\n6. Every completion claim must be mechanically checkable where possible.\n7. Agents generate candidates; schemas, reducers, and tests decide authority.\n\n---"
    },
    {
      "title": "Required Artifact Shape",
      "level": 2,
      "body": "Every production-ready RedKey artifact should identify its contract.\n\n```json\n{\n  \"schema_version\": \"1.0\",\n  \"artifact_type\": \"module-spec\",\n  \"contract_ref\": \"schemas/studio-artifacts/v1/module-spec.schema.json\",\n  \"fixture_refs\": [\n    \"fixtures/studio-artifacts/v1/module-spec.valid.json\",\n    \"fixtures/studio-artifacts/v1/module-spec.invalid-missing-acceptance.json\"\n  ],\n  \"state_machine_ref\": \"contracts/studio-artifacts/v1/module-lifecycle.json\",\n  \"acceptance_criteria\": [\n    {\n      \"id\": \"AC-001\",\n      \"mechanical\": true,\n      \"assertion\": \"artifact.status equals draft|approved|rejected\"\n    }\n  ]\n}\n```\n\nFreeform 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.\n\n---"
    },
    {
      "title": "Spec-To-Code Contract Pattern",
      "level": 2,
      "body": "Each major feature or protocol should have these assets:\n\n```text\ndocs/specs/<date>-<name>.md\nschemas/<domain>/<version>/*.schema.json\ncontracts/<domain>/<version>/*.json\nfixtures/<domain>/<version>/*.valid.json\nfixtures/<domain>/<version>/*.invalid-<reason>.json\ntests/conformance/<domain>/*\ntests/reducers/<domain>/*\n```\n\nMinimum conformance tests:\n\n- Valid fixtures pass schema validation.\n- Invalid fixtures fail for the expected reason.\n- Required fields are enforced.\n- Enum values reject unknown values.\n- State-machine transitions are deterministic.\n- Reducers produce exact expected state from ordered events.\n\n---"
    },
    {
      "title": "State Machines Over Prose",
      "level": 2,
      "body": "Bad:\n\n```text\nThe agent should finish the task and include useful output.\n```\n\nGood:\n\n```json\n{\n  \"acceptance_criteria\": [\n    \"A task.complete Wire is emitted\",\n    \"At least one artifact.ready Wire exists\",\n    \"task.complete.payload.artifact_ids references all final artifacts\",\n    \"verification.mechanical equals pass\"\n  ]\n}\n```\n\nBetter:\n\n```json\n{\n  \"completion_contract\": {\n    \"required_events\": [\"artifact.ready\", \"task.complete\"],\n    \"artifact_count\": { \"min\": 1 },\n    \"verification\": {\n      \"mechanical\": \"pass\"\n    },\n    \"references\": {\n      \"task.complete.payload.artifact_ids\": \"must_include_all_final_artifacts\"\n    }\n  }\n}\n```\n\n---"
    },
    {
      "title": "Agent Wire Example",
      "level": 2,
      "body": "Required lifecycle:\n\n```text\nsubmitted -> working -> completed\nsubmitted -> working -> blocked -> working -> completed\nsubmitted -> working -> failed\nsubmitted -> canceled\n```\n\nRequired event map:\n\n```json\n{\n  \"task.available\": \"submitted\",\n  \"task.claimed\": \"working\",\n  \"task.blocked\": \"blocked\",\n  \"task.complete\": \"completed\",\n  \"task.failed\": \"failed\",\n  \"task.cancelled\": \"canceled\"\n}\n```\n\nRequired reducer fixture:\n\n```json\n{\n  \"events\": [\n    \"task.created\",\n    \"task.available\",\n    \"task.claimed\",\n    \"task.started\",\n    \"artifact.ready\",\n    \"task.complete\"\n  ],\n  \"expected\": {\n    \"task_state\": \"completed\",\n    \"terminal\": true,\n    \"artifact_count\": 1,\n    \"blocked\": false\n  }\n}\n```\n\n---"
    },
    {
      "title": "Studio Artifact Implications",
      "level": 2,
      "body": "Studio artifact generation should move from “agent wrote a nice spec” to “artifact conforms.”\n\nFor each artifact type:\n\n- `intent`\n- `source-intake`\n- `ai-first-opportunity-map`\n- `screen-map`\n- `feature-ux-spec`\n- `module-spec`\n- `policy`\n- `architecture`\n- `plan`\n\nRedKey should define:\n\n- JSON Schema\n- valid fixture\n- invalid fixture\n- rendered-view conformance check\n- approval gate rule\n- implementation-readiness rule\n\nExample readiness rule:\n\n```json\n{\n  \"build_gate\": {\n    \"required_artifacts\": [\n      \"intent\",\n      \"policy\",\n      \"architecture\",\n      \"feature-ux-spec\",\n      \"module-spec\",\n      \"plan\"\n    ],\n    \"required_status\": \"approved\",\n    \"required_checks\": [\n      \"schema_valid\",\n      \"fixtures_valid\",\n      \"acceptance_criteria_mechanical\",\n      \"open_questions_empty\"\n    ]\n  }\n}\n```"
    },
    {
      "title": "Studio Task Planning And Decomp",
      "level": 2,
      "body": "Studio decomp must output validated task graphs, not task prose.\n\nEvery planned task must have canonical lifecycle fields:\n\n```json\n{\n  \"task_id\": \"task_pva_m00_contracts\",\n  \"project_id\": \"patient-visit-advocate\",\n  \"parent_task_id\": null,\n  \"depends_on\": [],\n  \"assigned_role\": \"worker\",\n  \"allowed_events\": [\n    \"task.claimed\",\n    \"task.started\",\n    \"artifact.ready\",\n    \"task.complete\",\n    \"task.failed\",\n    \"task.blocked\"\n  ],\n  \"required_capabilities\": [\n    \"platform-core\"\n  ],\n  \"required_artifacts\": [\n    \"artifact_contract_spec\"\n  ],\n  \"acceptance_criteria\": [\n    \"artifact.ready emitted for every required artifact\",\n    \"task.complete.payload.artifact_ids references all final artifacts\",\n    \"verification.mechanical equals pass\"\n  ]\n}\n```\n\nEvery artifact type required by a task must have an artifact contract before dispatch:\n\n```json\n{\n  \"artifact_type\": \"artifact_contract_spec\",\n  \"schema_id\": \"studio-artifacts/v1/artifact-contract-spec\",\n  \"required_fields\": [\n    \"artifact_type\",\n    \"schema_id\",\n    \"required_fields\",\n    \"finalization_event\"\n  ],\n  \"finalization_event\": \"artifact.ready\"\n}\n```\n\nThe planner must emit a graph:\n\n```json\n{\n  \"tasks\": [\n    {\n      \"task_id\": \"task_m00_domain_contracts\",\n      \"depends_on\": []\n    },\n    {\n      \"task_id\": \"task_m01_intake_agent_spec\",\n      \"depends_on\": [\"task_m00_domain_contracts\"]\n    }\n  ]\n}\n```\n\nThe coordinator must run dispatch preflight before giving work to an agent:\n\n- task spec validates\n- dependencies are completed\n- required artifact specs exist\n- required artifact schemas exist\n- allowed lifecycle events are known\n- required capability IDs exist in `scripts/capabilities.json`\n- required capabilities are `agent_safe=true` unless explicitly approved\n\nThe coordinator must run completion preflight before accepting completion:\n\n- required artifact IDs are referenced\n- artifact payloads validate against artifact schemas\n- `terminal` equals `true`\n- `verification.mechanical` equals `pass`\n\nValidated Studio task graphs can now be converted into Agent Wire v1.1 lifecycle events:\n\n```text\nvalidated Studio task graph\n  -> task.created for every task\n  -> task.available only for dependency-ready tasks\n  -> required_capabilities and required_artifacts carried in extensions.redkey\n  -> dry-run stream adapter validates schemas and reducer state before persistence\n```\n\nThe planner bridge lives at:\n\n```text\nscripts/lib/studio-agent-wire-planner.js\nscripts/lib/agent-wire-v1-1-stream.js\ntests/conformance/studio/studio-agent-wire-planner.test.js\ntests/conformance/agent-wire/v1-1-stream-adapter.test.js\n```\n\nImplemented contract paths:\n\n```text\ncontracts/studio/v1/task-spec.schema.json\ncontracts/studio/v1/artifact-spec.schema.json\ncontracts/studio/v1/task-graph.schema.json\nfixtures/studio/v1/task-spec.valid.json\nfixtures/studio/v1/artifact-spec.valid.json\nfixtures/studio/v1/task-graph.valid.json\nfixtures/studio/v1/task-complete.valid.json\nfixtures/studio/v1/task-complete.invalid-missing-artifact.json\nscripts/lib/studio-task-planner-validator.js\ntests/conformance/studio/\n```\n\n---"
    },
    {
      "title": "Implementation Order",
      "level": 2,
      "body": "1. Agent Wire v1.1 deterministic contracts first.\n2. Studio artifact schemas and fixtures second.\n3. Build-gate validator third.\n4. Reducer/read-model conformance fourth.\n5. Producer/listener implementation only after contracts and fixtures exist.\n\n---"
    },
    {
      "title": "Acceptance Criteria",
      "level": 2,
      "body": "- A new RedKey spec is not build-ready unless it identifies schema, fixture, and conformance-test requirements.\n- Agent Wire v1.1 has state-machine contracts, schemas, fixtures, conformance tests, and reducer tests before producer rollout.\n- Studio artifact approval can eventually depend on schema validation and open-question/build-gate checks, not manual prose review alone.\n- Agents remain useful for drafting, but deterministic validators define whether artifacts and events are acceptable."
    }
  ],
  "html_path": "artifacts/2026-05-06-deterministic-spec-artifact-standard-3944bdce8e.html",
  "json_path": "artifacts/2026-05-06-deterministic-spec-artifact-standard-3944bdce8e.json"
}