---
id: ARTIFACT-STORE-WP-0005
type: workplan
title: "Guide-Board Pilot Ingestion"
repo: artifact-store
domain: stack
status: active
owner: codex
topic_slug: stack
planning_priority: high
planning_order: 5
created: "2026-05-15"
updated: "2026-05-16"
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: blocked
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.

Blocked 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 needs to be fixed in the producer/extension before the documented
fresh-run procedure can be marked complete.

## 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).