Skip to content

Delivery Record schema — v1

This page is the human-readable face of the Delivery Record schema. It is the target of the predicate_type identifier:

predicate_type: https://kanopi.github.io/cms-cultivator/spec/delivery-record/v1

The machine-readable schema is canonical in the repository at spec/delivery-record/v1/. The narrative rationale lives in kanopi/ai-workflows → The Delivery Record.

AI drafts, a named human signs

A passive "AI was used" disclosure is not enough. Every Delivery Record names the human who reviewed and signed it.

What a record is

One schema-typed, human-signed markdown file per significant AI-assisted output — a code change, a deliverable, an audit, or a client-facing communication. The front-matter is validated; the prose body is unstructured by design.

A record is required whenever the output is client-facing or load-bearing internal (an FRD, IA, audit, architecture decision, or design-to-dev handoff that downstream work depends on). It is not required for ephemeral chat, meeting prep, status notes, throwaway spikes, or brainstorming.

Front-matter fields

Field Required Notes
predicate_type yes Must match https://kanopi.github.io/cms-cultivator/spec/delivery-record/v<n>.
activity_type yes One of code, frd, audit, discovery, design-handoff, strategy, client-comm.
subject yes Object with kind (pr/document/report/figma/message) and title; optional ref, sha.
ticket no Project ticket reference.
scope no One of feature, fix, chore, milestone, launch, deliverable.
assisted_by yes Object with models (non-empty array) and optional skills.
checks yes Object of check groups; required keys depend on activity_type.
sign_off yes Requires produced_by and reviewed_by; approved_by is required when scope is launch or deliverable.

Per-activity check templates

The checks: block adapts to the activity type — same record shape, different evidence. Each activity requires exactly these keys:

Activity type Subject kind Required checks keys Sign-off roles
code pr standards, tests, audits, review Developer, Tech Lead
frd document sow_alignment, hour_total_vs_cap, completeness, stakeholder_review Tech Lead, PM
audit report methodology, sample_size, findings_verified, severity_rubric Specialist, Tech Lead
discovery document sources_cited, sample_size, bias_check, stakeholder_review Strategist, PM
design-handoff document goals_kpis, audiences, journeys, figma_urls, cd_review Strategist, Designer, Tech Lead
strategy document sources_grounded, recommendations_defensible, alternatives_considered Strategist, Account
client-comm message facts_verified, tone_reviewed, no_unauthorized_commitments PM, Account

Each check group is an object. Leaf values are a status (pass / fail / n/a) or an evidence string such as a CI run URL or a reviewer note.

The threshold rule

The status semantics are enforced by the verifier, not the schema:

  • A fail cannot be signed off without an explicit ## Waiver heading in the body.
  • An n/a must be justified in one line near the top of the body — silence is not an answer.

/delivery-record-verify surfaces these as warnings by default, and as hard failures under --strict.

Validating a record

# All records under docs/delivery-records/, or pass explicit paths
python3 scripts/delivery_record_verify.py spec/delivery-record/v1/examples/*.md
python3 scripts/delivery_record_verify.py --strict path/to/record.md

Any JSON Schema 2020-12 validator works against schema.json directly.

Versioning

v1 is the floor. Additive, backward-compatible changes land in place; breaking changes ship as a new v2/ directory so old records keep validating. See the versioning policy.