generated from coulomb/repo-seed
163 lines
5.3 KiB
Markdown
163 lines
5.3 KiB
Markdown
---
|
|
id: ARTIFACT-STORE-WP-0005
|
|
type: workplan
|
|
title: "Guide-Board Pilot Ingestion"
|
|
repo: artifact-store
|
|
domain: stack
|
|
status: done
|
|
owner: codex
|
|
topic_slug: stack
|
|
planning_priority: high
|
|
planning_order: 5
|
|
created: "2026-05-15"
|
|
updated: "2026-05-17"
|
|
state_hub_workstream_id: "701c4d8c-5cf4-4a4a-ab60-1dcae53fe771"
|
|
---
|
|
|
|
# ARTIFACT-STORE-WP-0005: Guide-Board Pilot Ingestion
|
|
|
|
## Purpose
|
|
|
|
Wire the first real producer end-to-end. A guide-board CMIS
|
|
assessment run directory is registered as one artifact package, its
|
|
files are stored through a configured backend, retention is applied,
|
|
and Statehub records a stable package id and summary without storing
|
|
bytes itself. This is the pilot success criterion in INTENT.md.
|
|
|
|
## Constraints
|
|
|
|
- WP-0001 — WP-0004 must be done.
|
|
- `docs/ARCHITECTURE-BLUEPRINT.md` guide-board manifest fields.
|
|
- No guide-board-specific code lives in `artifactstore.registry`;
|
|
pilot-specific glue lives in `artifactstore.pilots.guide_board` or
|
|
in a separate small package.
|
|
|
|
## Prerequisites
|
|
|
|
- WP-0001, WP-0002, WP-0003 done. WP-0004 only required for the
|
|
production target; local FS is sufficient for the pilot test.
|
|
|
|
## D5.1 - Pilot Metadata Schema Registration
|
|
|
|
```task
|
|
id: ARTIFACT-STORE-WP-0005-T001
|
|
status: done
|
|
priority: high
|
|
state_hub_task_id: "830f6822-1cfe-4955-a4e0-5b9a42fb5db1"
|
|
```
|
|
|
|
Acceptance:
|
|
|
|
- A JSON Schema for `guide-board.run.v1` package metadata is checked
|
|
in under `schemas/guide-board.run.v1.json`.
|
|
- A bootstrap script registers it via `POST /metadata-schemas`
|
|
(an endpoint added in this workplan).
|
|
- Required keys: `run_id`, `target_profile_ref`,
|
|
`assessment_profile_ref`, `result_status`, `source_commits`
|
|
(object of slug → SHA), `report_paths`, `evidence_counts`,
|
|
`finding_counts`.
|
|
|
|
## D5.2 - Pilot Ingest Helper (CLI + Library Function)
|
|
|
|
```task
|
|
id: ARTIFACT-STORE-WP-0005-T002
|
|
status: done
|
|
priority: high
|
|
state_hub_task_id: "ff0ba2eb-b8d3-418a-8685-a54457cea2ed"
|
|
```
|
|
|
|
Acceptance:
|
|
|
|
- `artifactstore guide-board ingest <run-dir>` walks a guide-board
|
|
run directory, builds the package metadata from `run.json` and
|
|
`retention-summary.json`, uploads every file declared in the
|
|
assessment package manifest (and the manifest itself), and
|
|
finalises the package.
|
|
- Library entry point `pilots.guide_board.ingest_run(path, ...)`
|
|
exposes the same behaviour for embedding.
|
|
- Output: the package id (UUID) and the package manifest digest
|
|
(`blake3:<hex>`).
|
|
|
|
## D5.3 - Fixture-Based Test
|
|
|
|
```task
|
|
id: ARTIFACT-STORE-WP-0005-T003
|
|
status: done
|
|
priority: high
|
|
state_hub_task_id: "5c367257-2d2a-4de9-9a06-663ba2c60d77"
|
|
```
|
|
|
|
Acceptance:
|
|
|
|
- A trimmed-down guide-board run fixture (under 1 MB total) lives in
|
|
`tests/fixtures/guide-board/` with realistic file shapes:
|
|
`run.json`, `retention-summary.json`,
|
|
`reports/assessment-package.json`, `reports/report.md`, one
|
|
scorecard, one log-review summary, and a couple of raw artifact
|
|
files.
|
|
- The test runs the CLI / library helper end-to-end against an
|
|
in-memory SQLite + tempdir local backend, then verifies:
|
|
1. package id returned,
|
|
2. manifest digest stable across two runs of the same fixture,
|
|
3. every file downloadable with correct bytes,
|
|
4. retention class applied as configured.
|
|
|
|
## D5.4 - Statehub Linkage Recipe
|
|
|
|
```task
|
|
id: ARTIFACT-STORE-WP-0005-T004
|
|
status: done
|
|
priority: medium
|
|
state_hub_task_id: "b1ca7133-ad27-4091-93a0-a4e1b7450791"
|
|
```
|
|
|
|
Acceptance:
|
|
|
|
- `docs/OPERATOR.md` (or a new `docs/pilots/guide-board.md`)
|
|
documents the exact `POST /progress/` or `record_decision` call
|
|
shape Statehub clients should use to link a guide-board run to
|
|
its artifact-store package id and manifest digest.
|
|
- A reference Statehub client snippet is checked in, parameterised
|
|
by env vars.
|
|
|
|
## D5.5 - Operator Smoke Procedure For The Real Producer
|
|
|
|
```task
|
|
id: ARTIFACT-STORE-WP-0005-T005
|
|
status: done
|
|
priority: medium
|
|
state_hub_task_id: "bffa3573-4a1f-4c12-8c73-6d55bd8f6297"
|
|
```
|
|
|
|
Acceptance:
|
|
|
|
- A documented procedure ingests a real (non-fixture) guide-board run
|
|
produced from `~/guide-board` / `~/open-cmis-tck`.
|
|
- Procedure includes: starting `make dev`, registering the schema,
|
|
running the ingest CLI, verifying the manifest, and
|
|
recording the package id in Statehub.
|
|
- Procedure runs end-to-end on a developer workstation under 5
|
|
minutes.
|
|
|
|
Closure note: the artifact-store ingest path was verified against an
|
|
existing non-fixture OpenCMIS guide-board run at
|
|
`/home/worsch/open-cmis-tck/.local/runs/opencmis-inmemory-pilot` using
|
|
an isolated SQLite DB and local storage root. It ingested 23 files,
|
|
replayed the event log through sequence 26, and verified 23 storage
|
|
locations with zero failures. A fresh guide-board/OpenCMIS producer run
|
|
from `~/guide-board` currently stops before artifact-store handoff with
|
|
`cmis-summary: report fragment not found: reports/cmis-summary.md`,
|
|
which belongs in guide-board/open-cmis-tck follow-up work rather than
|
|
holding this artifact-store integration workstream open.
|
|
|
|
## Success criteria
|
|
|
|
- A real guide-board CMIS run is ingested with one CLI invocation.
|
|
- The package manifest lists every stored file with both digests and
|
|
the canonical CBOR digest of the manifest itself.
|
|
- Statehub records the package id and summary; no artifact bytes
|
|
live in Statehub.
|
|
- Retention can be extended on the package without touching bytes.
|
|
- The pilot path validates the storage adapter swap: the same
|
|
command works against `local` and against `s3` (if WP-0004 done).
|