Spec / ovs-node-integration-checklist
Open Values Node Integration Checklist v0.1
The checklist for wiring the generated node and search files into the app: the phases of the work, the commands to run, and what must be true before each kind of page goes public. The data build writes it for the people doing that work. It is an internal file used while building the site.
- Test data and building contracts
- Status: dev-contract
- Version: 0.1
- Format name in the file:
ovs-node-integration-checklist
Used while building the sites. Not meant for other apps. Data kept for tests, not for use.
Who writes it and who reads it
Written by pipeline/build_nodes.js. Read by app-lane integration, handoff review.
Fields
| Field | What it means | Type |
|---|---|---|
format required | Names this file's format, so a reader can check it before reading the rest of the file. | always "ovs-node-integration-checklist" |
version required | The version of the format this file follows, such as "0.1". | see version |
built required | The date of the source data this file was built from, as YYYY-MM-DD. | see date |
source required | The script and files this file was built from, as paths in the repository. | see source |
purpose required | One sentence on what this file is for. | see nonEmptyString |
appLaneNote required | A note on which choices this file leaves to the app code that reads it, such as fetching, layout and wording. | see nonEmptyString |
readinessTargets required | Byte budgets and the lists of files that load at startup, when a page needs them, only for product search, or only in testing. | object |
counts required | Counts of generated nodes, Ask index entries and test cases, by name. | object |
smokeCommands required | Commands to run before checking the app, such as "node research/node_index_audit.js". | list |
publicGates required | The conditions each kind of generated page must meet before it moves out of the private workbench and goes public. | see publicGates |
h4DrainContract required | The steps the app must show evidence for before handoff item H4 in docs/CONTENT-HANDOFF.md can be closed. H4 is the work of wiring the generated node and Ask files into the app. | see h4DrainContract |
phases required | The phases of the integration work, each with what it must achieve. | list |
A reader MUST ignore fields it does not know, so a file can carry more than this list and still be read. A writer MUST NOT change what a listed field means.
A file that passes
Integration checklists keep app/design ownership, smoke commands, counts, targets, and pending phases together.
{
"format": "ovs-node-integration-checklist",
"version": "0.1",
"built": "2026-07-07",
"source": [
"pipeline/build_nodes.js"
],
"purpose": "Acceptance checklist for app-owned node and Ask integration.",
"appLaneNote": "Checklist only.",
"readinessTargets": {
"startupBudgetBytes": 780000
},
"counts": {
"brands": 1
},
"smokeCommands": [
"node research/node_index_audit.js"
],
"phases": [
{
"id": "startup-ask",
"label": "Startup Ask",
"owner": "app/design",
"status": "pending-app-integration",
"sourceFiles": [
"ask-core.json"
],
"acceptanceCriteria": [
"Render startup Ask results."
],
"risk": "Startup latency."
}
],
"publicGates": {
"status": "ready-for-app-public-gates",
"namedConsumer": "App I5 workbench graduation",
"voiceSource": "BUILD-PLAN.md#c8-voice-pass-status",
"rule": "Move one surface public at a time after app-owned rendering consumes generated files.",
"appOwnedBeforePublic": [
"Render from generated data.",
"Keep app-added copy in the signed voice."
],
"releaseContract": {
"purpose": "App-owned public release contract.",
"status": "ready-for-app-public-gates",
"namedConsumer": "App I5 workbench graduation",
"releaseRule": "Release one surface at a time after app-owned evidence.",
"voiceSource": "BUILD-PLAN.md#c8-voice-pass-status",
"releaseOrder": [
{
"step": 1,
"surfaceId": "company-pages",
"label": "Company pages",
"voiceStatus": "signed",
"sourceFiles": [
"app/data/nodes/companies.json",
"BUILD-PLAN.md"
],
"evidenceRequired": [
"Rendering evidence."
],
"releaseWhen": [
"Gate passes."
],
"mustNot": [
"Do not overclaim coverage."
]
}
],
"sharedEvidenceRequired": [
"Smoke commands pass."
],
"rollbackRule": "Rollback only the failed surface.",
"coverage": {
"surfaces": 1,
"releaseSteps": 1,
"allSurfacesCovered": true,
"minimalGeneratedCopy": [],
"signedSurfaces": [
"company-pages"
]
}
},
"surfaces": [
{
"id": "company-pages",
"label": "Company pages",
"owner": "app/design",
"status": "voice-signed-app-gate",
"proseClass": "company-reads",
"sourceFiles": [
"app/data/nodes/companies.json",
"BUILD-PLAN.md"
],
"voice": {
"status": "signed",
"signedAt": "2026-07-08",
"signoffBlock": "BUILD-PLAN.md#c8-voice-pass-status",
"pilotSamples": 5
},
"generatedCount": 1,
"appOwnedGate": "Render signed reads with receipts before public release.",
"mustNot": [
"Do not overclaim coverage."
]
}
]
},
"h4DrainContract": {
"purpose": "App-owned H4 drain contract.",
"status": "pending-app-integration",
"activeHandoff": "H4",
"namedConsumer": "App H4 generated-node integration drain pass",
"h4DrainableFromDataAlone": false,
"drainRule": "H4 drains only after app-owned implementation evidence; generated data alone is insufficient.",
"steps": [
{
"step": 1,
"id": "startup-ask",
"label": "Startup Ask",
"phaseIds": [
"startup-ask"
],
"sourceFiles": [
"ask-core.json"
],
"contractPointer": "ask-core.json#startupContract",
"appOwnedEvidence": [
"Running app note."
],
"passWhen": [
"App behavior passes."
],
"mustNot": [
"Do not drain from data alone."
]
}
],
"finalDecision": {
"expectedStatusBeforeAppWork": "pending-app-integration",
"dataAlo
…
A file that must be rejected
Integration checklist phases must stay app/design owned until explicitly reassigned.
{
"format": "ovs-node-integration-checklist",
"version": "0.1",
"built": "2026-07-07",
"source": [
"pipeline/build_nodes.js"
],
"purpose": "Acceptance checklist for node and Ask integration.",
"appLaneNote": "Checklist only.",
"readinessTargets": {
"startupBudgetBytes": 780000
},
"counts": {
"brands": 1
},
"smokeCommands": [
"node research/node_index_audit.js"
],
"phases": [
{
"id": "startup-ask",
"label": "Startup Ask",
"owner": "data-lane",
"status": "pending-app-integration",
"sourceFiles": [
"ask-core.json"
],
"acceptanceCriteria": [
"Render startup Ask results."
],
"risk": "Startup latency."
}
],
"publicGates": {
"status": "ready-for-app-public-gates",
"namedConsumer": "App I5 workbench graduation",
"voiceSource": "BUILD-PLAN.md#c8-voice-pass-status",
"rule": "Move one surface public at a time after app-owned rendering consumes generated files.",
"appOwnedBeforePublic": [
"Render from generated data.",
"Keep app-added copy in the signed voice."
],
"releaseContract": {
"purpose": "App-owned public release contract.",
"status": "ready-for-app-public-gates",
"namedConsumer": "App I5 workbench graduation",
"releaseRule": "Release one surface at a time after app-owned evidence.",
"voiceSource": "BUILD-PLAN.md#c8-voice-pass-status",
"releaseOrder": [
{
"step": 1,
"surfaceId": "company-pages",
"label": "Company pages",
"voiceStatus": "signed",
"sourceFiles": [
"app/data/nodes/companies.json",
"BUILD-PLAN.md"
],
"evidenceRequired": [
"Rendering evidence."
],
"releaseWhen": [
"Gate passes."
],
"mustNot": [
"Do not overclaim coverage."
]
}
],
"sharedEvidenceRequired": [
"Smoke commands pass."
],
"rollbackRule": "Rollback only the failed surface.",
"coverage": {
"surfaces": 1,
"releaseSteps": 1,
"allSurfacesCovered": true,
"minimalGeneratedCopy": [],
"signedSurfaces": [
"company-pages"
]
}
},
"surfaces": [
{
"id": "company-pages",
"label": "Company pages",
"owner": "app/design",
"status": "voice-signed-app-gate",
"proseClass": "company-reads",
"sourceFiles": [
"app/data/nodes/companies.json",
"BUILD-PLAN.md"
],
"voice": {
"status": "signed",
"signedAt": "2026-07-08",
"signoffBlock": "BUILD-PLAN.md#c8-voice-pass-status",
"pilotSamples": 5
},
"generatedCount": 1,
"appOwnedGate": "Render signed reads with receipts before public release.",
"mustNot": [
"Do not overclaim coverage."
]
}
]
},
"h4DrainContract": {
"purpose": "App-owned H4 drain contract.",
"status": "pending-app-integration",
"activeHandoff": "H4",
"namedConsumer": "App H4 generated-node integration drain pass",
"h4DrainableFromDataAlone": false,
"drainRule": "H4 drains only after app-owned implementation evidence; generated data alone is insufficient.",
"steps": [
{
"step": 1,
"id": "startup-ask",
"label": "Startup Ask",
"phaseIds": [
"startup-ask"
],
"sourceFiles": [
"ask-core.json"
],
"contractPointer": "ask-core.json#startupContract",
"appOwnedEvidence": [
"Running app note."
],
"passWhen": [
"App behavior passes."
],
"mustNot": [
"Do not drain from data alone."
]
}
],
"finalDecision": {
"expectedStatusBeforeAppWork": "pending-app-integration",
"dataAloneIsInsuffi
…
The schema
Its address is https://openvaluesstandard.org/schema/node-integration-checklist-v0.1.schema.json. Validators can fetch it there; the file is also in the repository at app/data/standard/schemas/node-integration-checklist.schema.json.
The key words MUST, MUST NOT, SHOULD, SHOULD NOT and MAY are used as described in RFC 2119 and RFC 8174 when, and only when, they appear in capitals.
Whether this format fits your app is your call. The spec says what a file MUST hold. Which formats you read and write, and what your app does with them, is yours to decide.