Contracts

Example from HELIX’s own docs. This generated page comes from docs/helix/. Use it to see the method in practice; start with the artifact-type catalog for reusable templates. Historical plans and reports may describe retired architecture.

Contracts

contracts is restored as the canonical design-activity artifact for normative interface and schema specifications that another team can implement against directly.

Decision

This artifact is restored rather than retired.

Current HELIX already depends on contract-shaped documents in live repo state:

CONTRACT-001 defines the DDx / HELIX ownership boundary
CONTRACT-002 defines HELIX execution-document conventions
API-001 defines the tracker mutation surface

Those documents carry a distinct responsibility that is not replaced cleanly by ADRs, solution designs, or technical designs.

Why It Exists

ADRs record why an architectural decision was made.
Solution designs explain the feature-level approach.
Technical designs scope one bounded slice of implementation work.
Contracts define the authoritative interface, schema, and error semantics that another team, tool, or service can implement against directly.

Canonical Scope

Use a contract for normative specifications such as:

CLI and library mutation surfaces
HTTP or RPC request/response interfaces
protocol or event payload schemas
data exchange formats and validation rules
precedence, ordering, and conflict semantics
error codes, retry behavior, and recovery expectations

Naming Guidance

CONTRACT-XXX is the canonical prefix for general interface, protocol, schema, and boundary contracts.

API-XXX remains an allowed subtype when the contract is specifically centered on an API surface. Both prefixes must meet the same completeness bar and live in the same docs/helix/02-design/contracts/ directory.

Minimum Prompt Bar

Start from the governing requirement, design, or ADR rather than inventing a parallel design narrative.
Specify exact keys, fields, types, units, enums, ranges, and requiredness where relevant.
Define precedence, ordering, versioning, and compatibility rules explicitly.
Define error semantics, failure modes, and recovery expectations.
Include concrete examples and validation hooks that tests can execute.
Keep the document implementation-independent enough that another team could build against it without inheriting feature-level or code-level baggage.

Minimum Template Bar

purpose and scope
related governing artifacts
normative surface definitions
precedence or compatibility rules
error semantics
worked examples
validation checklist

Canonical Replacement Status

contracts is not replaced by ADRs, solution designs, or technical designs. Those artifacts govern why a contract exists and where it applies, but the contract remains the canonical normative specification.

Innsigle seal: model-primary by HELIX

The signature covers the markdown source of this page, not these HTML bytes. This page quotes that seal; verify it against the source file.

Composition: model-primary
Issuer: HELIX helix
Signing key: ed25519:b0865d76d834a52c48506414d16f4e5a (build key)
Signed source: artifacts/contracts/README.md
Signed: 2026-09-23T14:11:58Z
Content digest: sha256:85718253…42118f53

This build key is endorsed by the human key for build signing; the signature is not a detector and not a truth guarantee.

Raw attestation JSON

{
  "payload": {
    "innsigle": "1",
    "type": "https://innsigle.dev/claim/colophon/v1",
    "issued_at": "2026-09-23T14:11:58Z",
    "issuer": {
      "id": "helix",
      "name": "HELIX",
      "key_id": "ed25519:b0865d76d834a52c48506414d16f4e5a",
      "key_url": "https://documentdrivendx.github.io/helix/.well-known/innsigle/keys.json"
    },
    "subjects": [
      {
        "uri": "https://documentdrivendx.github.io/helix/artifacts/contracts/README/",
        "digest": {
          "alg": "sha256",
          "value": "857182535c43155f5a2c8b3a1d0ec64266082f1e8a85f54b5ca1586242118f53"
        }
      }
    ],
    "colophon": {
      "schema_version": "1",
      "composition": "model-primary",
      "ingredients": [
        {
          "kind": "model",
          "name": "Claude",
          "role": "draft"
        },
        {
          "kind": "tool",
          "name": "sloptimizer",
          "role": "rewrite"
        },
        {
          "kind": "human",
          "name": "operator",
          "role": "structure-edit"
        }
      ],
      "notes": null
    }
  },
  "payload_encoding": "json",
  "signatures": [
    {
      "key_id": "ed25519:b0865d76d834a52c48506414d16f4e5a",
      "alg": "ed25519",
      "sig": "yy372mkbqokkqU-u6rJ33mqMFRq_tkdhSiAU_Q4BFP_h5OUaXNTIl6KHSY0OfJlNBk0SzCU1G4rvND-8cSntCw",
      "signed_at": "2026-09-23T14:11:58Z"
    }
  ]
}

attestation file · issuer keys