docs(cockpit): add operational snapshot fixtures #142

Merged

pdurlej merged 1 commit from codex/operational-snapshot-fixtures into main

2026-06-03 21:30:41 +02:00

codex commented

2026-06-03 09:11:18 +02:00

Collaborator

Canary status: missing — fire 3+3 review before merge

Summary

Fixes #130 by adding a reusable operational snapshot fixture and a dependency-free fixture hygiene checker.

While doing that, this also aligns docs/contracts/operational-snapshot.v0.schema.json with the current runtime/API shape for the cockpit snapshot contract:

scope.workspace instead of the stale scope.operator/workspacePublicId shape,
freshness.stale as required runtime field,
runtime evidence kinds: file, api, log, command, derived,
evidence.redacted as the documented privacy marker,
risk narrowed to low | medium | high.

Scope

Adds docs/fixtures/operational-snapshot.v0.sample.json covering ok, watch, warn, blocked, and unknown.
Adds scripts/check-operational-snapshot-fixtures.mjs with no external dependencies.
Documents the fixture and validation command in docs/operational-cockpit-contract.md.
Updates the JSON schema to match the current Zod/runtime contract used by submitOperationalSnapshot and the Cockpit UI.

Non-goals

No production deploy.
No runtime/API code changes.
No DB schema or migration.
No new dependencies.
No OpenClaw scraping or private local file references.

Spec sources read

#130
docs/operational-cockpit-contract.md
docs/contracts/operational-snapshot.v0.schema.json
packages/api/src/routers/agent.ts operational snapshot Zod schema
apps/web/src/views/settings/OperationalCockpitSettings.tsx

Tests / smoke

node scripts/check-operational-snapshot-fixtures.mjs — passed.
pnpm exec prettier --check docs/contracts/operational-snapshot.v0.schema.json docs/fixtures/operational-snapshot.v0.sample.json docs/operational-cockpit-contract.md scripts/check-operational-snapshot-fixtures.mjs — passed.

Rollback

Revert 9a28bc48. This is docs/fixture/script only; no data or runtime migration.

Owner gates

No production-impacting action taken. Merge decision remains with Piotr.

Canary status: missing — fire 3+3 review before merge ## Summary Fixes #130 by adding a reusable operational snapshot fixture and a dependency-free fixture hygiene checker. While doing that, this also aligns `docs/contracts/operational-snapshot.v0.schema.json` with the current runtime/API shape for the cockpit snapshot contract: - `scope.workspace` instead of the stale `scope.operator/workspacePublicId` shape, - `freshness.stale` as required runtime field, - runtime evidence kinds: `file`, `api`, `log`, `command`, `derived`, - `evidence.redacted` as the documented privacy marker, - `risk` narrowed to `low | medium | high`. ## Scope - Adds `docs/fixtures/operational-snapshot.v0.sample.json` covering `ok`, `watch`, `warn`, `blocked`, and `unknown`. - Adds `scripts/check-operational-snapshot-fixtures.mjs` with no external dependencies. - Documents the fixture and validation command in `docs/operational-cockpit-contract.md`. - Updates the JSON schema to match the current Zod/runtime contract used by `submitOperationalSnapshot` and the Cockpit UI. ## Non-goals - No production deploy. - No runtime/API code changes. - No DB schema or migration. - No new dependencies. - No OpenClaw scraping or private local file references. ## Spec sources read - #130 - `docs/operational-cockpit-contract.md` - `docs/contracts/operational-snapshot.v0.schema.json` - `packages/api/src/routers/agent.ts` operational snapshot Zod schema - `apps/web/src/views/settings/OperationalCockpitSettings.tsx` ## Tests / smoke - `node scripts/check-operational-snapshot-fixtures.mjs` — passed. - `pnpm exec prettier --check docs/contracts/operational-snapshot.v0.schema.json docs/fixtures/operational-snapshot.v0.sample.json docs/operational-cockpit-contract.md scripts/check-operational-snapshot-fixtures.mjs` — passed. ## Rollback Revert `9a28bc48`. This is docs/fixture/script only; no data or runtime migration. ## Owner gates No production-impacting action taken. Merge decision remains with Piotr.

Rows
Columns